Azure Cosmos DB: .NET examples for the SQL API

The azure-cosmos-dotnet-v2 GitHub repository includes the latest .NET sample solutions to perform CRUD and other common operations on Azure Cosmos DB resources. This article provides:

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

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

Prerequisites

Visual Studio 2019 with the Azure development workflow installed

The Microsoft.Azure.DocumentDB NuGet package

An Azure subscription or free Cosmos DB trial account

Note

The samples are self-contained, and set up and clean up after themselves with multiple calls to CreateDocumentCollectionAsync(). Each occurrence bills your subscription for one hour of usage in your collection's performance tier.

Database examples

The RunDatabaseDemo method of the sample DatabaseManagement project shows how to do the following tasks. To learn about Azure Cosmos databases before you run the following samples, see Work with databases, containers, and items.

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. To learn about Azure Cosmos collections before you run the following samples, see Work with databases, containers, and items.

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. To learn about Azure Cosmos documents before you run the following samples, see Work with databases, containers, and items.

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 a document DocumentClient.DeleteDocumentAsync
Working with .NET dynamic objects DocumentClient.CreateDocumentAsync
DocumentClient.ReadDocumentAsync
DocumentClient.ReplaceDocumentAsync
Replace document with conditional ETag check DocumentClient.AccessCondition
Documents.Client.AccessConditionType
Read document only if document has changed DocumentClient.AccessCondition
Documents.Client.AccessConditionType

Indexing examples

The RunIndexDemo method of the sample IndexManagement project shows how to do the following tasks. To learn about indexing in Azure Cosmos DB before you run the following samples, see index policies, index types, and index paths.

Task API reference
Exclude a document from the index IndexingDirective.Exclude
Use manual (instead of automatic) indexing IndexingPolicy.Automatic
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
RangeIndex
Perform an index transform ReplaceDocumentCollectionAsync

Geospatial examples

The geospatial sample file, azure-documentdb-dotnet/samples/code-samples/Geospatial/Program.cs, shows how to do the following tasks. To learn about GeoJSON and geospatial data before you run the following samples, see Use geospatial and GeoJSON location data.

Task API reference
Enable geospatial indexing on a new collection IndexingPolicy
IndexKind.Spatial
DataType.Point
Insert documents with GeoJSON points DocumentClient.CreateDocumentAsync
DataType.Point
Find points within a specified distance ST_DISTANCE
GeometryOperationExtensions.Distance
Find points within a polygon ST_WITHIN
GeometryOperationExtensions.Within
Polygon
Enable geospatial indexing on an existing collection DocumentClient.ReplaceDocumentCollectionAsync
DocumentCollection.IndexingPolicy
Validate point and polygon data ST_ISVALID
ST_ISVALIDDETAILED
GeometryOperationExtensions.IsValid
GeometryOperationExtensions.IsValidDetailed

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 Lambda. To learn about the SQL query reference in Azure Cosmos DB before you run the following samples, see SQL query examples for Azure Cosmos DB.

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
SqlQuerySpec
Query with explicit paging DocumentQueryable.CreateDocumentQuery
Query partitioned collections in parallel DocumentQueryable.CreateDocumentQuery
Query with ORDER BY for partitioned collections DocumentQueryable.CreateDocumentQuery

Change feed examples

The change feed sample, azure-documentdb-dotnet/samples/code-samples/ChangeFeed/Program.cs, shows how to do the following tasks. To learn about change feed in Azure Cosmos DB before you run the following samples, see Read Azure Cosmos DB change feed and Change feed processor.

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

The change feed processor sample, ChangeFeedMigrationTool, shows how to use the 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. To learn about server-side programming in Azure Cosmos DB before you run the following samples, see Stored procedures, triggers, and user-defined functions.

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

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
DocumentClient.ReadPermissionFeedAsync