Connect to a multi-region write account with the Azure Cosmos DB for NoSQL SDK

The CosmosClientBuilder class is a fluent class designed to build the SDK client to connect to your container and perform operations. Using the builder, you can configure a preferred application region for write operations if your Azure Cosmos DB for NoSQL account is already configured for multi-region writes.

In this lab, you will configure an Azure Cosmos DB for NoSQL account with multiple regions and enable multi-region writes. You will then use the SDK to perform operations against a specific region.

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 Getting Started documentation
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

📝 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 Replicate data globally pane.
In the Replicate data globally pane, add at least one extra region to the account.
Still within the Replicate data globally pane, enable Multi-region writes and then Save your changes.
Wait for the replication task to complete before continuing with this task.

📝 This operation can take approximately 5-10 minutes.
Notice at least one of the extra regions you created. You will use this region value later in this exercise.
In the resource blade, navigate to the Data Explorer pane.
In the Data Explorer pane, select New Container.

In the New Container popup, enter the following values for each setting, and then select OK:

Setting	Value
Database id	Create new \| `cosmicworks`
Share throughput across containers	Do not select
Container id	`products`
Partition key	`/categoryId`
Container throughput	Manual \| 400

Back in the Data Explorer pane, expand the cosmicworks database node and then observe the products container node within the hierarchy.
In the resource blade, 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.
Return to Visual Studio Code.

Connect to the Azure Cosmos DB for NoSQL account from the SDK

Using the credentials from the newly created account, you will connect with the SDK classes and create a new database and container instance. Then, you will use the Data Explorer to validate that the instances exist in the Azure portal.

In the Explorer pane, browse to the 22-sdk-multi-region folder.
Open the context menu for the 22-sdk-multi-region 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 22-sdk-multi-region folder.
Build the project using the dotnet build command:
```
 dotnet build
```
📝 You may see a compiler warning that the endpoint and key variables are current unused. You can safely ignore this warning as you will use these variable in this task.
Close the integrated terminal.
Open the product.cs code file.
Observe the Product record and its corresponding properties. Specifically, this lab will use the id, name, and categoryId properties.
Back in the Explorer pane of Visual Studio Code, open the script.cs code file.

📝 The [Microsoft.Azure.Cosmos][nuget.org/packages/microsoft.azure.cosmos/3.22.1] library has already been pre-imported from NuGet.
Locate the string variable named endpoint. Set its value 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/”;.
Locate the string variable named key. Set its value 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==”;.
Save the script.cs code file.

Configure write region for the SDK

The fluent WithApplicationRegion method is used to configure the preferred region for the subsequent operations using the builder class.

Create a new instance of the CosmosClientBuilder class named builder passing in the endpoint and key variables as constructor parameters:
```
 CosmosClientBuilder builder = new (endpoint, key);
```
Create a new variable named region of type string with the name of the extra region you created earlier in the lab. For example, if you created your Azure Cosmos DB for NoSQL account in the East US region, and then added Brazil South; then your string variable would contain:
```
 string region = "Brazil South"; 
```
💡 Alternatively; you can use the Microsoft.Azure.Cosmos.Regions static class which includes built-in string properties for various Azure regions.
Invoke the WithApplicationRegion method with a parameter of region and the Build method fluently on the builder variable storing the result in a variable named client of type CosmosClient that is encapsulated within a using statement:
```
 using CosmosClient client = builder
     .WithApplicationRegion(region)
     .Build();
```
Use the GetContainer method of the client variable to retrieve the existing container using the name of the database (cosmicworks) and the name of the container (products):
```
 Container container = client.GetContainer("cosmicworks", "products");
```
Create two string variables named id and categoryId by generating a new Guid value and then storing the result as a string:
```
 string id = $"{Guid.NewGuid()}";
 string categoryId = $"{Guid.NewGuid()}";
```
Create a new variable named item of type Product passing in the id variable, a string value of Polished Bike Frame, and the categoryId variable as constructor parameters:
```
 Product item = new (id, "Polished Bike Frame", categoryId);
```
Asynchronously invoke the CreateItemAsync<> method of the container variable passing in the item variable as a parameter and storing the result in a variable named response:
```
 var response = await container.CreateItemAsync<Product>(item);
```

Invoke the static Console.WriteLine method to print the response’s HTTP status code and request charge (in request units):

 Console.WriteLine($"Status Code:\t{response.StatusCode}");
 Console.WriteLine($"Charge (RU):\t{response.RequestCharge:0.00}");

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

 using Microsoft.Azure.Cosmos;
 using Microsoft.Azure.Cosmos.Fluent;

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

 CosmosClientBuilder builder = new (endpoint, key);            
    
 string region = "West Europe";
    
 using CosmosClient client = builder
     .WithApplicationRegion(region)
     .Build();
    
 Container container = client.GetContainer("cosmicworks", "products");
    
 string id = $"{Guid.NewGuid()}";
 string categoryId = $"{Guid.NewGuid()}";
 Product item = new (id, "Polished Bike Frame", categoryId);
    
 var response = await container.CreateItemAsync<Product>(item);
    
 Console.WriteLine($"Status Code:\t{response.StatusCode}");
 Console.WriteLine($"Charge (RU):\t{response.RequestCharge:0.00}");

Save the script.cs code file.
In Visual Studio Code, open the context menu for the 22-sdk-multi-region 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
```
Observe the output from the terminal. The HTTP status code and request charge (in RUs) should be printed to the console.
Close the integrated terminal.
Close Visual Studio Code.