Working With Microsoft NET SDK for Azure Cosmos DB

Working with the Microsoft .NET SDK for Azure Cosmos DB This guide demonstrates common patterns for working with Azure Cosmos DB using the Microsoft .NET SDK: initializing a client, accessing a container, creating/upserting items, reading a single item, and querying multiple items. Each code snippet shows the typical sequence of operations and is accompanied by notes and portal screenshots for context. Quick overview — common steps:

Initialize a CosmosClient with your account endpoint and key.
Get a Container reference for the target database and container.
Create or upsert items (CreateItemAsync, UpsertItemAsync).
Read a single item by id and partition key (ReadItemAsync<T>).
Query items with SQL-like queries via GetItemQueryIterator<T> (returns a FeedIterator<T>).

Table: common SDK operations

Operation	Purpose	Example method
Initialize client	Connect to Cosmos DB account	`new CosmosClient(endpoint, key)`
Get container	Reference DB and container	`client.GetContainer(databaseName, containerName)`
Create item	Insert a new document	`container.CreateItemAsync(item)`
Upsert item	Insert or update (idempotent write)	`container.UpsertItemAsync(item)`
Read item	Fetch by id and partition key	`container.ReadItemAsync<T>(id, partitionKey)`
Query items	Execute SQL-like queries with paging	`container.GetItemQueryIterator<T>(query)`

References:

Create items

Start by creating a CosmosClient and obtaining the Container object for the database and container where you’ll store documents. The following example shows:

Initializing the client and container.
Defining a simple Employee POCO.
Creating an item with CreateItemAsync.
Demonstrating UpsertItemAsync (insert-or-update).

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

public class Employee
{
    public string id { get; set; }
    public string name { get; set; }
    public string department { get; set; }
    public bool isFullTime { get; set; }
    public int salary { get; set; }
    public int yearsOfExperience { get; set; }
}

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        string key = "<your-cosmosdb-account-key>";
        string databaseName = "<your-database-name>";
        string containerName = "<your-container-name>";

        CosmosClient client = new CosmosClient(endpoint, key);
        Container container = client.GetContainer(databaseName, containerName);

        Employee employeeRecord = new Employee
        {
            id = "123e4567-e89b-12d3-a456-426614174000",
            name = "John Doe",
            department = "Human Resources",
            isFullTime = true,
            salary = 4500,
            yearsOfExperience = 5
        };

        try
        {
            // Create a new item
            ItemResponse<Employee> createResponse = await container.CreateItemAsync(employeeRecord);
            Console.WriteLine($"Created item with RU charge: {createResponse.RequestCharge}");

            // Upsert (insert or update)
            ItemResponse<Employee> upsertResponse = await container.UpsertItemAsync(employeeRecord);
            Console.WriteLine($"Upserted item with RU charge: {upsertResponse.RequestCharge}");
        }
        catch (CosmosException ex)
        {
            Console.WriteLine($"Cosmos DB error: {ex.StatusCode} - {ex.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"General error: {ex.Message}");
        }
    }
}

If your container uses a partition key other than id, include it when creating or upserting items so the SDK routes the write correctly. Example: await container.CreateItemAsync(employeeRecord, new PartitionKey(employeeRecord.department));

Notes:

UpsertItemAsync is useful for idempotent writes — it inserts if the id is new, or replaces the existing item if the id exists.
Monitor RequestCharge from responses to understand RU consumption and tune throughput.

Read a single item

Reading an item requires the item’s id and its partition key value (if the container uses one). Use ReadItemAsync<T> to fetch a single document and access the resource via ItemResponse<T>.Resource.

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        string key = "<your-cosmosdb-account-key>";
        string databaseName = "<your-database-name>";
        string containerName = "<your-container-name>";

        CosmosClient client = new CosmosClient(endpoint, key);
        Container container = client.GetContainer(databaseName, containerName);

        string id = "123e4567-e89b-12d3-a456-426614174000";
        PartitionKey partitionKey = new PartitionKey("Human Resources");

        try
        {
            ItemResponse<Employee> response = await container.ReadItemAsync<Employee>(id, partitionKey);
            Employee item = response.Resource;
            Console.WriteLine($"Employee name: {item.name}, Department: {item.department}");
        }
        catch (CosmosException ex) when (ex.StatusCode == System.Net.HttpStatusCode.NotFound)
        {
            Console.WriteLine("Item not found.");
        }
        catch (CosmosException ex)
        {
            Console.WriteLine($"Cosmos DB error: {ex.StatusCode} - {ex.Message}");
        }
    }
}

Query multiple items (paged queries with FeedIterator)

To query many documents, use SQL-like syntax with GetItemQueryIterator<T>. The method returns a FeedIterator<T> that yields FeedResponse<T> batches — which enables efficient paging through large result sets.

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        string key = "<your-cosmosdb-account-key>";
        string databaseName = "<your-database-name>";
        string containerName = "<your-container-name>";

        CosmosClient client = new CosmosClient(endpoint, key);
        Container container = client.GetContainer(databaseName, containerName);

        FeedIterator<dynamic> iterator = container.GetItemQueryIterator<dynamic>(
            "SELECT * FROM c WHERE c.isFullTime = true"
        );

        while (iterator.HasMoreResults)
        {
            FeedResponse<dynamic> batch = await iterator.ReadNextAsync();
            foreach (var item in batch)
            {
                Console.WriteLine($"{item.name} - {item.department}");
            }
        }
    }
}

This approach scales because the SDK retrieves pages of results from the service and you can process each page independently.

Creating a database and container in the Azure portal

If you don’t yet have a database and container, use the Azure portal Data Explorer to create them. The portal’s Overview page shows account essentials and quick access to Data Explorer.

A screenshot of the Microsoft Azure portal showing the Overview page for an Azure Cosmos DB account named "az204cosmosdb01." The page displays account essentials (status, read/write locations, throughput), monitoring charts, and a left-hand navigation menu with options like Activity log, Tags, and Data Explorer.

When creating a new container in the portal you configure:

Database id (create new or use existing).
Provisioned throughput (RU/s) or serverless/free options.
Container id and partition key path (for scale and routing).
Indexing policy and any unique keys.

Below is the New Container dialog in the Data Explorer.

A screenshot of the Azure Cosmos DB web portal showing the "Welcome to Azure Cosmos" home page with tiles like "Launch quick start" and "New Container." A right-side pane is open to the "New Container" creation form, showing fields for Container id, indexing, and partition key.

Bulk loading sample data (Data Migration Tool)

For test datasets or bulk imports, use the Cosmos DB Data Migration Tool (DMT). It supports sources such as JSON files, Amazon S3, and Azure Blob Storage and sinks including Cosmos DB (NoSQL). See the GitHub repository: https://github.com/Azure/azure-documentdb-datamigrationtool. Sample migration settings for a JSON source to a Cosmos DB sink:

{
  "Source": "JSON",
  "Sink": "Cosmos-nosql",
  "SourceSettings": {
    "FilePath": "/Users/yourusername/Downloads/airports.json"
  },
  "SinkSettings": {
    "ConnectionString": "AccountEndpoint=https://<your-cosmosdb-account>.documents.azure.com:443/;AccountKey=<your-account-key>",
    "Database": "datamigration",
    "Container": "btcdata",
    "PartitionKeyPath": "/id",
    "RecreateContainer": false,
    "IncludeMetadataFields": false
  }
}

Example terminal steps to prepare and run the tool:

# Navigate to the Data Migration Tool folder
cd ~/Documents/Cosmos\ DB\ DMT

# List files
ls -l

# Clear or replace migrationsettings.json
echo "" > migrationsettings.json

# Edit migrationsettings.json and run the Data Migration Tool with your settings

Sample logs from a successful import (example output):

info: JsonFileSource[0]
      Reading file '/Users/yourusername/Downloads/airports.json'
info: CosmosDataSinkExtension[0]
      500 records added after 4.95s (100 records/s)
info: CosmosDataSinkExtension[0]
      1000 records added after 8.11s (123 records/s)
info: CosmosDataSinkExtension[0]
      Added 1000 total records in 8.11s (123 records/s)
info: Cosmos.DataTransfer.Core.RunCommand.CommandHandler[0]
      Data transfer complete

A sample document ingested into the container might look like:

{
  "id": "60886968-4e2b-463d-924d-574c72e9be91",
  "airport_code": "AIM",
  "airport_name": "Ailuk Airport",
  "country_code": "Philippines",
  "_rid": "MncmAImgwm4BAAAAAAAAA==",
  "_self": "dbs/MncmAA==/colls/MncmAImgwm4=/docs/MncmAImgwm4=/",
  "_etag": "\"6b007d9b-0000-0300-0000-66ddde2c0000\"",
  "_attachments": "attachments/",
  "_ts": 1725816364
}

After import, validate and query documents from Data Explorer using SQL queries.

Visual Studio: adding, reading, and querying items from .NET

Create a Console application and add the Microsoft.Azure.Cosmos NuGet package. Use the account URI and primary key from the Azure portal Keys blade to configure CosmosClient. Do not hard-code secrets in production—use managed identities and Azure Key Vault.

A screenshot of the Microsoft Azure portal showing the Keys page for an Azure Cosmos DB account named "az204cosmosdb01," with the account URI, primary/secondary keys, and connection strings displayed (keys masked). The portal's left navigation and account settings are visible.

Do not store keys or secrets in source code for production. Use managed identities with Key Vault or other secure secret storage.

Example: inserting an airport record using an anonymous object that matches your JSON schema:

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        string key = "<your-cosmosdb-account-key>";
        string databaseName = "flightDetails";
        string containerName = "airportCodes";

        CosmosClient client = new CosmosClient(endpoint, key);
        Container container = client.GetContainer(databaseName, containerName);

        var airportRecord = new
        {
            id = Guid.NewGuid().ToString(),
            airport_code = "DXB",
            airport_name = "Dubai International Airport",
            country_code = "AE"
        };

        try
        {
            ItemResponse<dynamic> response = await container.CreateItemAsync(airportRecord);
            Console.WriteLine($"Inserted airport {airportRecord.airport_code}. RU charge: {response.RequestCharge}");
        }
        catch (CosmosException ex)
        {
            Console.WriteLine($"Cosmos DB error: {ex.StatusCode} - {ex.Message}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"General error: {ex.Message}");
        }
    }
}

Validate the inserted record in Data Explorer with a SQL query such as:

SELECT * FROM c WHERE c.country_code = 'AE'

Querying by country_code (example)

If your documents use a country_code property, filter by that property in your SQL query. The sample below shows querying airports by country_code and printing each airport name.

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos;

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://<your-cosmosdb-account>.documents.azure.com:443/";
        string key = "<your-cosmosdb-account-key>";
        string databaseName = "flightDetails";
        string containerName = "airportCodes";

        CosmosClient client = new CosmosClient(endpoint, key);
        Container container = client.GetContainer(databaseName, containerName);

        FeedIterator<dynamic> iterator = container.GetItemQueryIterator<dynamic>(
            "SELECT * FROM c WHERE c.country_code = 'United States'"
        );

        while (iterator.HasMoreResults)
        {
            FeedResponse<dynamic> batch = await iterator.ReadNextAsync();
            foreach (var airport in batch)
            {
                Console.WriteLine($"{airport.airport_name}");
            }
        }
    }
}

Sample console output (truncated):

Burgos Airport
Gregorio Luperon International Airport
Zvartnots International Airport
Caye Caulker Airport
Parry Sound Area Municipal Airport
Pompano Beach Airport
Akron Canton Regional Airport
Susanville Municipal Airport
Mogilev Airport

This lesson covered the essential CRUD and query patterns for using the Microsoft .NET SDK with Azure Cosmos DB. From here you can expand into partition key design, throughput tuning (RU/s), bulk imports, change feed processing, and server-side programming (stored procedures, triggers, and UDFs). Further reading and resources:

Introduction

Exploring Azure App Service

Configuring Web App Settings

Scaling Apps in Azure App Service

Exploring App Service Deployment Slots

Exploring Azure Functions

Developing Azure Functions

Exploring Azure Blob Storage

Managing Azure Blob Storage Lifecycle

Working With Azure Blob Storage

Exploring Azure Cosmos DB

Working With Azure Cosmos DB

Managing Container Images in Azure Container Registry

Running Container Images in Azure Container Instances

Implementing Azure Container Apps

Exploring the Microsoft Identity Platform

Implementing Authentication Using MSAL

Implementing Shared Access Signatures

Exploring Microsoft Graph

Implementing Azure Key Vault

Implementing Managed Identities

Implementing Azure App Configuration

Exploring API Management

Exploring Azure Event Grid

Exploring Azure Event Hubs

Discovering Azure Message Queues

Monitoring App Performance

Developing Azure Cache for Redis

Developing for storage on CDNs

Working With Microsoft NET SDK for Azure Cosmos DB

Create items

Read a single item

Query multiple items (paged queries with FeedIterator)

Creating a database and container in the Azure portal

Bulk loading sample data (Data Migration Tool)

Visual Studio: adding, reading, and querying items from .NET

Querying by country_code (example)

Watch Video

​Create items

​Read a single item

​Query multiple items (paged queries with FeedIterator)

​Creating a database and container in the Azure portal

​Bulk loading sample data (Data Migration Tool)

​Visual Studio: adding, reading, and querying items from .NET

​Querying by country_code (example)

Watch Video

Create items

Read a single item

Query multiple items (paged queries with FeedIterator)

Creating a database and container in the Azure portal

Bulk loading sample data (Data Migration Tool)

Visual Studio: adding, reading, and querying items from .NET

Querying by country_code (example)