Connect to Azure Cosmos DB for NoSQL with the SDK

The Azure SDK for .NET is a suite of libraries that provides a consistent developer interface to interact with many Azure services. The Azure SDK for .NET is built to the .NET Standard 2.0 specification ensuring that it can be used in .NET Framework (4.6.1 or above), .NET Core (2.1 or above), and .NET (5 or above) applications.

In this lab, you’ll connect to an Azure Cosmos DB for NoSQL account using the Azure SDK for .NET.

Prepare your development environment

If you have not already cloned the lab code repository for DP-420 to the environment where you’re working on this lab, follow these steps to do so. Otherwise, open the previously cloned folder in Visual Studio Code.

Start Visual Studio Code.

📝 If you are not already familiar with the Visual Studio Code interface, review the Get Started guide for Visual Studio Code
Open the command palette and run Git: Clone to clone the https://github.com/microsoftlearning/dp-420-cosmos-db-dev GitHub repository in a local folder of your choice.

💡 You can use the CTRL+SHIFT+P keyboard shortcut to open the command palette.
Once the repository has been cloned, open the local folder you selected in Visual Studio Code.

Create an Azure Cosmos DB for NoSQL account

Azure Cosmos DB is a cloud-based NoSQL database service that supports multiple APIs. When provisioning an Azure Cosmos DB account for the first time, you will select which of the APIs you want the account to support (for example, Mongo API or NoSQL API). Once the Azure Cosmos DB for NoSQL account is done provisioning, you can retrieve the endpoint and key and use them to connect to the Azure Cosmos DB for NoSQL account using the Azure SDK for .NET or any other SDK of your choice.

In a new web browser window or tab, navigate to the Azure portal (portal.azure.com).
Sign into the portal using the Microsoft credentials associated with your subscription.

Select + Create a resource, search for Cosmos DB, and then create a new Azure Cosmos DB for NoSQL account resource with the following settings, leaving all remaining settings to their default values:

Setting	Value
Subscription	Your existing Azure subscription
Resource group	Select an existing or create a new resource group
Account Name	Enter a globally unique name
Location	Choose any available region
Capacity mode	Provisioned throughput
Apply Free Tier Discount	Do Not Apply
Limit the total amount of throughput that can be provisioned on this account	Unchecked

📝 Your lab environments may have restrictions preventing you from creating a new resource group. If that is the case, use the existing pre-created resource group.

Wait for the deployment task to complete before continuing with this task.
Go to the newly created Azure Cosmos DB account resource and navigate to the Keys pane.
This pane contains the connection details and credentials necessary to connect to the account from the SDK. Specifically:
1. Notice the URI field. You will use this endpoint value later in this exercise.
2. Notice the PRIMARY KEY field. You will use this key value later in this exercise.
Keep the browser tab open, as we will return to it later.

View the Microsoft.Azure.Cosmos library on NuGet

The NuGet website contains a searchable index of packages that are available to import into your .NET applications. To import prerelease packages such as Microsoft.Azure.Cosmos, you can use the NuGet website to get the appropriate versions and commands to import the package into your applications.

In new browser tab, navigate to the NuGet website (nuget.org).
Review the description of NuGet, the package manager for .NET, and its capabilities.
Search for the Microsoft.Azure.Cosmos library on NuGet.org.
Select the .NET CLI tab to observe the command required to import the latest version of this library into a .NET project.

💡 No need to record this command. You will use a specific version of the library later in this exercise.
Close your web browser window or tab.

Import the Microsoft.Azure.Cosmos library into a .NET project

The .NET CLI includes an add package command to import packages from a pre-configured package feed. A .NET installation uses NuGet as its default package feed.

In Visual Studio Code, in the Explorer pane, browse to the 04-sdk-connect folder.
Open the context menu for the 04-sdk-connect folder and then select Open in Integrated Terminal to open a new terminal instance.

📝 This command will open the terminal with the starting directory already set to the 04-sdk-connect folder.
Add the Microsoft.Azure.Cosmos package from NuGet using the following command:
```
 dotnet add package Microsoft.Azure.Cosmos --version 3.*
```
Close the integrated terminal.

Use the Microsoft.Azure.Cosmos library

Once the Azure Cosmos DB library from the Azure SDK for .NET has been imported, you can immediately use its classes within the Microsoft.Azure.Cosmos namespace to connect to an Azure Cosmos DB for NoSQL account. The CosmosClient class is the core class that is used to make the initial connection to an Azure Cosmos DB for NoSQL account.

In Visual Studio Code, in the Explorer pane, browse to the 04-sdk-connect folder.
Open the empty script.cs code file.
Add using blocks for the built-in System and System.Linq namespaces:
```
 using System;
 using System.Linq;
```
Add a using block for the Microsoft.Azure.Cosmos namespace:
```
 using Microsoft.Azure.Cosmos;
```
Add a string variable named endpoint with its value set to the endpoint of the Azure Cosmos DB account you created earlier.
```
 string endpoint = "<cosmos-endpoint>";
```
📝 For example, if your endpoint is: https://dp420.documents.azure.com:443/, then the C# statement would be: string endpoint = “https://dp420.documents.azure.com:443/”;.
Add a string variable named key with its value set to the key of the Azure Cosmos DB account you created earlier.
```
 string key = "<cosmos-key>";
```
📝 For example, if your key is: fDR2ci9QgkdkvERTQ==, then the C# statement would be: string key = “fDR2ci9QgkdkvERTQ==”;.
Add a new variable named client of type CosmosClient using the endpoint and key variables in the constructor:
```
 CosmosClient client = new (endpoint, key);
```
Add a new variable named account of type AccountProperties using the asynchronous result of invoking the ReadAccountAsync method of the client variable:
```
 AccountProperties account = await client.ReadAccountAsync();
```
Use the built-in Console.WriteLine static method to print the Id property of the AccountProperties class with a header titled Account Name:
```
 Console.WriteLine($"Account Name:\t{account.Id}");
```
Use the built-in Console.WriteLine static method to query the WritableRegions property of the AccountProperties class and then print the Name property of the first result with a header titled Primary Region:
```
 Console.WriteLine($"Primary Region:\t{account.WritableRegions.FirstOrDefault()?.Name}");
```

Once you are done, your code file should now include:

 using System;
 using System.Linq;
    
 using Microsoft.Azure.Cosmos;

 string endpoint = "<cosmos-endpoint>";
 string key = "<cosmos-key>";

 CosmosClient client = new (endpoint, key);

 AccountProperties account = await client.ReadAccountAsync();

 Console.WriteLine($"Account Name:\t{account.Id}");
 Console.WriteLine($"Primary Region:\t{account.WritableRegions.FirstOrDefault()?.Name}");

Save the script.cs code file.

Test the script

Now that the .NET code to connect to the Azure Cosmos DB for NoSQL account is complete, you can test the script. This script will print the name of the account, and the name of the first writable region. When you created the account, you specified a location and you should expect to see that same location value printed as the result of this script.

In Visual Studio Code, open the context menu for the 04-sdk-connect folder and then select Open in Integrated Terminal to open a new terminal instance.
Build and run the project using the dotnet run command:
```
 dotnet run
```
The script will now output the name of the account, and the first writable region. For example, if you named the account dp420, and the first writable region was West US 2, the script would output:
```
 Account Name:   dp420
 Primary Region: West US 2
```
Close the integrated terminal.
Close Visual Studio Code.