You are currently viewing Using .NET Client SDK with Azure Cosmos DB

Using .NET Client SDK with Azure Cosmos DB

In this article, let’s try to see how can we use .NET client SDK with Cosmos DB. We will have look at important APIs to manage the database. In this article, we will use Azure.Cosmos NuGet package.

Client SDK .NET

The Cosmos DB has 4 important entities, Cosmos DB account, Database, Container, Item. To learn more about these 4 entities, please have a look at one of my previous blogs. Below are important Classes and APIs which are used very frequently:

  • CosmosClient, client side representation of Cosmos DB service. You will use this object for performing Cosmos DB operations.
  • CreateDatabaseIfNotExistsAsync, creates or gets the reference of database 
  • CreateContainerIfNotExistsAsync, creates a container if it does not exists OR gets reference to the container if it already exists. 
  • CreateItemAsync, creates an item in the container 
  • UpsertItemAsync, creates the item if it does not exit OR updates an existing item 
  • GetItemQueryIterator, creates a query for items under a container using SQL statement with parameterized values
  • DeleteAsync , deletes the specified database.

Before We Begin

When we create the new project, we will have to add few settings which are shown in below code snippet.

// Endpoint of Cosmos DB Account
private const string EndpointUrl = "https:
//<your-account>.documents.azure.com:443/";

// Primary Key for Cosmos DB account
private const string AuthorizationKey = "<your-account-key>";

// The name of database
private const string DatabaseId = "SampleDatabase";

// The name of container
private const string ContainerId = "SampleContainer";

Then we can create an instance of CosmosClient. As stated earlier, CosmosClient is the client side representation of Cosmos DB account. All the API methods are available of CosmosClient.

// Cosmos Client instance for next interactions
CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);

Create Database

Below code calls Create Database method. It takes database name as parameter. 

// Create a new database
Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync(DatabaseId);

Create Container

Below code tries to get reference to the database using CosmosClient. Then the database reference is used to create the container. It takes two parameters container name and partition key. In below example, created date is the partition key.

// Create a new container
Container container = await cosmosClient.GetDatabase(DatabaseId).CreateContainerIfNotExistsAsync(ContainerId, "/CreatedDate");

Add Items to Container

Below code snippet shows how to check if an item exists. The first line will throw an exception if the item is not found. The second line creates the instance.

// Get reference to container
Container container = cosmosClient.GetContainer(DatabaseId, ContainerId);

// To check if item exists 
ItemResponse<Item> checkExistResponse = await container.ReadItemAsync<Item>(item.Id, new PartitionKey(item.CreatedDate));

// To create new item 
ItemResponse<Item> itemResponse = await container.CreateItemAsync<Item>(todoItem, new PartitionKey(todoItem.CreatedDate));

// To create new or update existing
ItemResponse<Item> upsertResponse = await container.UpsertItemAsync<Item>(todoItem, new PartitionKey(todoItem.CreatedDate));

Delete Items

Below code shows how the items can be deleted.

// Get reference to container
Container container = cosmosClient.GetContainer(DatabaseId, ContainerId);

// ItemID and partionkey values
ItemResponse<Item> deleteResponse = await container.DeleteItemAsync<Item>(itemId, new PartitionKey(partitionKeyValue));

Delete Database

Below code gets reference to the database and deletes it. 

Database database = cosmosClient.GetDatabase(DatabaseId);
DatabaseResponse databaseResourceResponse = await database.DeleteAsync();

I hope this article provides you enough information to get started on .NET Client SDK. Let me know your thoughts.

Tags: , , , , ,