Harnessing Azure Cosmos DB with .NET: A Developer’s Guide

Sardar Mudassar Ali Khan
3 min readJan 26, 2024

Azure Cosmos DB is a globally distributed, multi-model database service provided by Microsoft Azure. It offers unparalleled scalability, performance, and flexibility for building modern, cloud-native applications. In this article, we’ll explore how Azure Cosmos DB seamlessly integrates with .NET, empowering developers to leverage its capabilities to their fullest extent.

Overview of Azure Cosmos DB:

Azure Cosmos DB is a fully managed NoSQL database service designed to handle globally distributed, high-throughput applications with ease. It supports multiple data models including document, key-value, graph, and column-family, providing developers with the flexibility to choose the right data model for their application needs.

Key Features of Azure Cosmos DB:

  1. Global Distribution: Azure Cosmos DB offers global distribution with turnkey multi-region replication, enabling low-latency access to data from any region around the world.
  2. Elastic Scalability: With Azure Cosmos DB, developers can scale throughput and storage independently based on application demand, ensuring optimal performance and cost-effectiveness.
  3. Multi-model Support: Azure Cosmos DB supports multiple data models including document, key-value, graph, and column family, allowing developers to use the most appropriate model for their data.
  4. Consistency Levels: Azure Cosmos DB offers configurable consistency levels, allowing developers to choose between strong, bounded staleness, session, or eventual consistency based on their application requirements.
  5. Enterprise-grade Security: Azure Cosmos DB integrates with Azure Active Directory for seamless authentication and supports encryption at rest and in transit to ensure data security.

.NET Integration with Azure Cosmos DB:

Integrating Azure Cosmos DB with .NET applications is straightforward, thanks to the Azure Cosmos DB .NET SDK provided by Microsoft. This SDK abstracts the complexity of interacting with Azure Cosmos DB and provides a rich set of APIs for CRUD operations, query execution, and more.

Step 1: Install the Azure Cosmos DB .NET SDK

In your .NET application, install the Azure Cosmos DB .NET SDK using the following NuGet package:

dotnet add package Microsoft.Azure.Cosmos

Step 2: Connect to Azure Cosmos DB

Create an instance of the CosmosClient class by passing the connection string and database name:

using Microsoft.Azure.Cosmos;
CosmosClient cosmosClient = new CosmosClient("connectionString");

Step 3: Create or Retrieve Databases and Containers

Use the Database and Container classes to create or retrieve databases and containers within Azure Cosmos DB:

Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync("DatabaseName");
Container container = await database.CreateContainerIfNotExistsAsync("ContainerName", "/PartitionKey");

Step 4: Perform CRUD Operations

Use the Container class to perform CRUD operations on documents within containers:

// Create a document
var item = new { id = Guid.NewGuid().ToString(), name = "John Doe", age = 30 };
await container.CreateItemAsync(item);
// Read a document
ItemResponse<dynamic> response = await container.ReadItemAsync<dynamic>(item.id, new PartitionKey(item.id));// Update a document
item.age = 31;
await container.ReplaceItemAsync(item, item.id, new PartitionKey(item.id));
// Delete a document
await container.DeleteItemAsync<dynamic>(item.id, new PartitionKey(item.id));

Step 5: Query Data

Execute SQL queries against Azure Cosmos DB using the Container class:

var query = "SELECT * FROM c WHERE c.age > @age";
var parameters = new SqlParameterCollection() { new SqlParameter("@age", 25) };QueryDefinition queryDefinition = new QueryDefinition(query).WithParameters(parameters);
FeedIterator<dynamic> resultSetIterator = container.GetItemQueryIterator<dynamic>(queryDefinition);while (resultSetIterator.HasMoreResults)
FeedResponse<dynamic> response = await resultSetIterator.ReadNextAsync();
foreach (var item in response)

Step 6: Handle Throughput and Performance

Azure Cosmos DB offers provisioned throughput and autoscale options for handling throughput requirements. Adjust throughput settings based on your application’s needs to ensure optimal performance and cost-efficiency.


Azure Cosmos DB, coupled with .NET integration, empowers developers to build highly scalable and globally distributed applications with ease. The Azure Cosmos DB .NET SDK simplifies interactions with Azure Cosmos DB, providing a rich set of APIs for CRUD operations, querying, and performance optimization. By leveraging Azure Cosmos DB in .NET applications, developers can unlock the full potential of modern, cloud-native architectures, delivering robust and scalable solutions to meet the demands of today’s data-intensive applications.



Sardar Mudassar Ali Khan

8x-Microsoft Certified Senior Software Engineer | MCT|MCT |Microsoft Certified Cloud Solution Architect | Microsoft Certified Cloud Developer | Technical Author