Azure Cosmos DB: .NET examples for the SQL API

Latest sample solutions that perform CRUD operations and other common operations on Azure Cosmos DB resources are included in the azure-cosmos-dotnet-v2 GitHub repository. This article provides:

  • Links to the tasks in each of the example C# project files.
  • Links to the related API reference content.

For code samples for the .NET SDK Version 3.0 (Preview), see the latest samples in the azure-cosmos-dotnet-v3 GitHub repository.


If you don't have an Azure subscription, create a free account before you begin.

You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. The Primary Key is provided in Authenticating requests.

You also need the Microsoft.Azure.DocumentDB NuGet package.


Each sample is self-contained, it sets itself up and cleans up after itself. As such, the samples issue multiple calls to CreateDocumentCollectionAsync(). Each time this is done your subscription is billed for 1 hour of usage per the performance tier of the collection being created.

Database examples

The RunDatabaseDemo method of the sample of the DatabaseManagement project shows how to perform the following tasks.

Task API reference
Create a database DocumentClient.CreateDatabaseAsync
Query a database DocumentQueryable.CreateDatabaseQuery
Read a database by Id DocumentClient.ReadDatabaseAsync
Read all the databases DocumentClient.ReadDatabaseFeedAsync
Delete a database DocumentClient.DeleteDatabaseAsync

Collection examples

The RunCollectionDemo method of the sample CollectionManagement project shows how to do the following tasks.

Task API reference
Create a collection DocumentClient.CreateDocumentCollectionAsync
Get configured performance of a collection DocumentQueryable.CreateOfferQuery
Change configured performance of a collection DocumentClient.ReplaceOfferAsync
Get a collection by Id DocumentClient.ReadDocumentCollectionAsync
Read all the collections in a database DocumentClient.ReadDocumentCollectionFeedAsync
Delete a collection DocumentClient.DeleteDocumentCollectionAsync

Document examples

The RunDocumentsDemo method of the sample DocumentManagement project shows how to do the following tasks.

Task API reference
Create a document DocumentClient.CreateDocumentAsync
Read a document by Id DocumentClient.ReadDocumentAsync
Read all the documents in a collection DocumentClient.ReadDocumentFeedAsync
Query for documents DocumentClient.CreateDocumentQuery
Replace a document DocumentClient.ReplaceDocumentAsync
Upsert a document DocumentClient.UpsertDocumentAsync
Delete document DocumentClient.DeleteDocumentAsync
Working with .NET dynamic objects DocumentClient.CreateDocumentAsync
Replace document with conditional ETag check DocumentClient.AccessCondition
Read document only if document has changed DocumentClient.AccessCondition

Indexing examples

The RunIndexDemo method of the sample IndexManagement project shows how to perform the following tasks.

Task API reference
Exclude a document from the index IndexingDirective.Exclude
Use manual (instead of automatic) indexing IndexingPolicy.Automatic
Use lazy (instead of consistent) indexing IndexingMode.Lazy
Exclude specified document paths from the index IndexingPolicy.ExcludedPaths
Force a range scan operation on a hash indexed path FeedOptions.EnableScanInQuery
Use range indexes on strings IndexingPolicy.IncludedPaths
Perform an index transform ReplaceDocumentCollectionAsync

For more information about indexing, see Azure Cosmos DB indexing policies.

Geospatial examples

The geospatial sample file, azure-documentdb-dotnet/samples/code-samples/Geospatial/Program.cs, shows how to do the following tasks.

Task API reference
Enable geospatial indexing on a new collection IndexingPolicy
Insert documents with GeoJSON points DocumentClient.CreateDocumentAsync
Find points within a specified distance ST_DISTANCE
Find points within a polygon ST_WITHIN
GeometryOperationExtensions.Within and
Enable geospatial indexing on an existing collection DocumentClient.ReplaceDocumentCollectionAsync
Validate point and polygon data ST_ISVALID

For more information about working with Geospatial data, see Working with Geospatial data in Azure Cosmos DB.

Query examples

The query document file, azure-documentdb-dotnet/samples/code-samples/Queries/Program.cs, shows how to do each of the following tasks using the SQL query grammar, the LINQ provider with query, and with Lambda.

Task API reference
Query for all documents DocumentQueryable.CreateDocumentQuery
Query for equality using == DocumentQueryable.CreateDocumentQuery
Query for inequality using != and NOT DocumentQueryable.CreateDocumentQuery
Query using range operators like >, <, >=, <= DocumentQueryable.CreateDocumentQuery
Query using range operators against strings DocumentQueryable.CreateDocumentQuery
Query with Order by DocumentQueryable.CreateDocumentQuery
Query with Aggregate Functions DocumentQueryable.CreateDocumentQuery
Work with subdocuments DocumentQueryable.CreateDocumentQuery
Query with intra-document Joins DocumentQueryable.CreateDocumentQuery
Query with string, math and array operators DocumentQueryable.CreateDocumentQuery
Query with parameterized SQL using SqlQuerySpec DocumentQueryable.CreateDocumentQuery
Query with explicit paging DocumentQueryable.CreateDocumentQuery
Query partitioned collections in parallel DocumentQueryable.CreateDocumentQuery
Query with Order by for partitioned collections DocumentQueryable.CreateDocumentQuery

For more information about writing queries, see SQL query within Azure Cosmos DB.

Change feed examples

The change feed sample, azure-documentdb-dotnet/samples/code-samples/ChangeFeed/Program.cs shows how to do the following tasks.

Task API reference
Read change feed DocumentClient.CreateDocumentChangeFeedQuery
Read partition key ranges DocumentClient.ReadPartitionKeyRangeFeedAsync

The change feed processor sample: Change Feed Migration Tool demonstrates how to use change feed processor library to replicate data to another Cosmos DB collection.

Server-side programming examples

The server-side programming file, azure-documentdb-dotnet/samples/code-samples/ServerSideScripts/Program.cs, shows how to do the following tasks.

Task API reference
Create a stored procedure DocumentClient.CreateStoredProcedureAsync
Execute a stored procedure DocumentClient.ExecuteStoredProcedureAsync
Read a document feed for a stored procedure DocumentClient.ReadDocumentFeedAsync
Create a stored procedure with Order by DocumentClient.CreateStoredProcedureAsync
Create a pre-trigger DocumentClient.CreateTriggerAsync
Create a post-trigger DocumentClient.CreateTriggerAsync
Create a User Defined Function (UDF) DocumentClient.CreateUserDefinedFunctionAsync

For more information about server-side programming, see Azure Cosmos DB server-side programming: Stored procedures, database triggers, and UDFs.

User management examples

The user management file, azure-documentdb-dotnet/samples/code-samples/UserManagement/Program.cs, shows how to do the following tasks.

Task API reference
Create a user DocumentClient.CreateUserAsync
Set permissions on a collection or document DocumentClient.CreatePermissionAsync
Get a list of a user's permissions DocumentClient.ReadUserAsync