Previous

Next

Prepare

Completed

You're building a .NET application that imports and queries data in an Azure Cosmos DB for NoSQL container. Here, we discuss the overall goals of the project and how you implement the import and query functionality. Additionally, we cover how to set up the API for NoSQL account that you need.

Project overview

This project's goal is to build and validate a .NET console application that uploads and queries items in an API for NoSQL container. The .NET application uses the .NET SDK for Azure Cosmos DB for NoSQL to interact with a service instance in Azure. The project code uses transactional batches to create multiple related items simultaneously. The project code also uses queries, represented as strings, to validate that the items were successfully uploaded.

The following flowchart shows the business logic the app needs to perform:

Diagram of a flowchart showing steps to authenticate the client. The flowchart then shows a batch creation step that combines the creation of four individual items. Finally, the flow chart shows the sequence to create, execute, and observe the results of a query.

The key tasks you need to do are:

1. Create an Azure Cosmos DB account and retrieve the connection string.
2. Create a .NET console application and add a package reference to the Microsoft.Azure.Cosmos SDK.
3. Create database and container resources.
4. Add a single item as a simple operation.
5. Create a transactional batch to add four items.
6. Execute and observe the results of a query.

Setup

To complete this project, you need an API for NoSQL account.

Create Azure Cosmos DB for NoSQL account

The API for NoSQL account is used to store the data you create in this project and to execute queries. This section guides you through the steps to creating a new account using the Azure CLI directly in the Azure Cloud Shell terminal.

1. Create a new shell variable named suffix with a random number. Create a new API for NoSQL account within the [sandbox resource group name] resource group.

   let suffix=$RANDOM*$RANDOM
   
   az cosmosdb create \
       --resource-group "<rgn>[sandbox resource group name]</rgn>" \
       --name "mslearn-$suffix" \
       --locations "regionName=westus"
   

   Important

   This resource group was already created by the sandbox.

2. Wait for the command to complete once the new account is created. Creating a new account can take a couple of minutes.

   Tip

   You can navigate to your new API for NoSQL account using the Azure portal.

Get account connection string

Now that you have an API for NoSQL account, you can use the az cosmosdb keys list command from the Azure CLI to get the account's credentials. In this section, you filter the output of the command to only return a single connection string.

1. First, get the name of the most recently created API for NoSQL accounts.

   let resourceGroup="<rgn>[sandbox resource group name]</rgn>"
   
   az cosmosdb list \
       --resource-group $resourceGroup \
       --query "sort_by([].{name:name,created:systemData.createdAt}, &created)" \
       --output table
   

2. Now, get the Primary SQL Connection String credential for the first account from the list of recently created accounts.

   let resourceGroup="<rgn>[sandbox resource group name]</rgn>"
   
   az cosmosdb keys list \
       --resource-group $resourceGroup \
       --name $(az cosmosdb list \
           --resource-group $resourceGroup \
           --query "sort_by([].{name:name,created:systemData.createdAt}, &created)[0].name" \
           --output tsv) \
       --type connection-strings \
       --query "connectionStrings[?description=='Primary SQL Connection String'].connectionString" \
       --output tsv
   

3. Record the value of this connection string. You use the connection string later in this project to connect to this account.

Configure dev environment

A development container environment is available with all dependencies required to complete every exercise in this project. You can run the development container in GitHub Codespaces or locally using Visual Studio Code.

Develop in browser

GitHub Codespaces runs a development container managed by GitHub with Visual Studio Code for the Web as the browser-based user interface. For the most straightforward development environment, use GitHub Codespaces so that you have the correct developer tools and dependencies preinstalled to complete this training module.

Important

All GitHub accounts can use Codespaces for up to 60 hours free each month with 2 core instances.

1. Create a new GitHub Codespace using the azure-samples/cosmos-db-dotnet template.

   

2. On the Create codespace page, review the codespace configuration settings, and then select Create new codespace.

3. Wait for the codespace to start. This startup process can take a few minutes.

4. Open a new terminal in the codespace.

5. Validate that .NET 8 is installed in your environment:

   dotnet --list-sdks
   

6. Close the terminal.

The remaining exercises in this project take place in the context of this development container.

Develop locally

The Dev Containers extension for Visual Studio Code requires Docker to be installed on your local machine. The extension hosts the development container locally using the Docker host with the correct developer tools and dependencies preinstalled to complete this training module.

1. Open the azure-samples/cosmos-db-dotnet template repository from GitHub within Visual Studio Code.

   

2. Open a new terminal.

3. Validate that .NET 8 is installed in your environment:

   dotnet --list-sdks
   

4. Close the terminal.

The remaining exercises in this project take place in the context of this development container.

Continue