You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/cosmos-db/nosql/quickstart-dotnet.md
+109-3Lines changed: 109 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -107,13 +107,43 @@ You'll use the following .NET classes to interact with these resources:
107
107
-[Get an item](#get-an-item)
108
108
-[Query items](#query-items)
109
109
110
-
The sample code described in this article creates a database named ``adventureworks`` with a container named ``products``. The ``products`` table is designed to contain product details such as name, category, quantity, and a sale indicator. Each product also contains a unique identifier.
110
+
The sample code described in this article creates a database named ``cosmicworks`` with a container named ``products``. The ``products`` table is designed to contain product details such as name, category, quantity, and a sale indicator. Each product also contains a unique identifier.
111
111
112
112
For this sample code, the container will use the category as a logical partition key.
113
113
114
114
### Authenticate the client
115
115
116
-
From the project directory, open the *Program.cs* file. In your editor, add a using directive for ``Microsoft.Azure.Cosmos``.
You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the `Azure.Identity` NuGet package to your application. `DefaultAzureCredential` will automatically discover and use the account you signed-in with in the previous step.
129
+
130
+
```dotnetcli
131
+
dotnet add package Azure.Identity
132
+
```
133
+
134
+
From the project directory, open the `Program.cs` file. In your editor, add using directives for the ``Microsoft.Azure.Cosmos`` and `Azure.Identity` namespaces.
Define a new instance of the ``CosmosClient`` class using the constructor, and [``Environment.GetEnvironmentVariable``](/dotnet/api/system.environment.getenvironmentvariable) to read the `COSMOS_ENDPOINT` environment variable you created earlier.
For more information on different ways to create a ``CosmosClient`` instance, see [Get started with Azure Cosmos DB for NoSQL and .NET](how-to-dotnet-get-started.md#connect-to-azure-cosmos-db-sql-api).
143
+
144
+
## [Connection String](#tab/connection-string)
145
+
146
+
From the project directory, open the `Program.cs` file. In your editor, add a using directive for ``Microsoft.Azure.Cosmos``.
@@ -123,11 +153,85 @@ Define a new instance of the ``CosmosClient`` class using the constructor, and [
123
153
124
154
For more information on different ways to create a ``CosmosClient`` instance, see [Get started with Azure Cosmos DB for NoSQL and .NET](how-to-dotnet-get-started.md#connect-to-azure-cosmos-db-sql-api).
125
155
156
+
---
157
+
158
+
### Create and query the database
159
+
160
+
Next you'll create a database and container to store products, and perform queries to insert and read those items.
161
+
162
+
## [Passwordless](#tab/passwordless)
163
+
164
+
The `Microsoft.Azure.Cosmos` client libraries enable you to perform *data* operations using [Azure RBAC](../role-based-access-control.md). However, to authenticate *management* operations such as creating and deleting databases you must use RBAC through one of the following options:
The Azure CLI approach is used in this example. Use the [`az cosmosdb sql database create`](/azure/cosmosdb/sql/database#az-cosmosdb-sql-database-create) and [`az cosmosdb sql container create`](/azure/cosmosdb/sql/container#az-cosmosdb-sql-container-create) commands to create a Cosmos DB NoSQL database and container.
172
+
173
+
```azurecli
174
+
# Create a SQL API database
175
+
az cosmosdb sql database create
176
+
--account-name msdocs-cosmos-nosql
177
+
--resource-group msdocs
178
+
--name cosmicworks
179
+
180
+
# Create a SQL API container
181
+
az cosmosdb sql container create
182
+
--account-name msdocs-cosmos-nosql
183
+
--resource-group msdocs
184
+
--database-name cosmicworks
185
+
--name products
186
+
```
187
+
188
+
After the resources have been created, use classes from the `Microsoft.Azure.Cosmos` client libraries to connect to and query the database.
189
+
190
+
### Get the database
191
+
192
+
Use the [``CosmosClient.GetDatabase``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.getdatabase) method will return a reference to the specified database.
The easiest way to create a new item in a container is to first build a C# [class](/dotnet/csharp/language-reference/keywords/class) or [record](/dotnet/csharp/language-reference/builtin-types/record) type with all of the members you want to serialize into JSON. In this example, the C# record has a unique identifier, a *categoryId* field for the partition key, and extra *categoryName*, *name*, *quantity*, and *sale* fields.
For more information on creating, upserting, or replacing items, see [Create an item in Azure Cosmos DB for NoSQL using .NET](how-to-dotnet-create-item.md).
213
+
214
+
### Get an item
215
+
216
+
In Azure Cosmos DB, you can perform a point read operation by using both the unique identifier (``id``) and partition key fields. In the SDK, call [``Container.ReadItemAsync<>``](/dotnet/api/microsoft.azure.cosmos.container.readitemasync) passing in both values to return a deserialized instance of your C# type.
For more information about reading items and parsing the response, see [Read an item in Azure Cosmos DB for NoSQL using .NET](how-to-dotnet-read-item.md).
221
+
222
+
### Query items
223
+
224
+
After you insert an item, you can run a query to get all items that match a specific filter. This example runs the SQL query: ``SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79"``. This example uses the **QueryDefinition** type and a parameterized query expression for the partition key filter. Once the query is defined, call [``Container.GetItemQueryIterator<>``](/dotnet/api/microsoft.azure.cosmos.container.getitemqueryiterator) to get a result iterator that will manage the pages of results. Then, use a combination of ``while`` and ``foreach`` loops to retrieve pages of results and then iterate over the individual items.
Use the [``CosmosClient.CreateDatabaseIfNotExistsAsync``](/dotnet/api/microsoft.azure.cosmos.cosmosclient.createdatabaseifnotexistsasync) method to create a new database if it doesn't already exist. This method will return a reference to the existing or newly created database.
This app creates an API for NoSQL database and container. The example then creates an item and then reads the exact same item back. Finally, the example issues a query that should only return that single item. With each step, the example outputs metadata to the console about the steps it has performed.
When developing locally with Passwordless authentication, make sure the user account that connects to Cosmos DB is assigned a role with the correct permissions to perform data operations. Currently, Azure Cosmos DB for NoSQL does not include built-in roles for data operations, but you can create your own using the Azure CLI or PowerShell.
14
+
15
+
Roles consist of a collection of permissions or actions that a user is allowed to perform, such as read, write, and delete. You can read more about [configuring role based access control (RBAC)](/azure/cosmos-db/how-to-setup-rbac) in the cosmos security configuration documentation.
16
+
17
+
## Create the custom role
18
+
19
+
Create roles using the `az role definition create` command. Pass in the Cosmos DB account name and resource group, followed by a body of JSON that defines the custom role. The following example creates a role named `PasswordlessReadWrite` with permissions to read and write items in Cosmos DB containers. The role is also scoped to the account level using `/`.
When the command completes, copy the ID value from the `name` field and paste it somewhere for later use.
40
+
41
+
Next, assign the role you created to the user account or service principal that will connect to Cosmos DB. During local development, this will generally be your own account that is logged into Visual Studio or the Azure CLI.
42
+
43
+
Retrieve the details of your account using the `az ad user` command.
44
+
45
+
```azurecli
46
+
az ad user --id "<your-email-address>"
47
+
```
48
+
49
+
Copy the value of the `id` property out of the results and paste it somewhere for later use.
50
+
51
+
Finally, assign the custom role you created to your user account using the `az cosmosdb sql role assignment create` command and the IDs you copied previously.
0 commit comments