Azure Cosmos DB: .NET examples for the SQL API

Tip

The Azure Cosmos DB DocumentDB API or SQL (DocumentDB) API is now known as Azure Cosmos DB SQL API. You don't need to change anything to continue running your apps built with DocumentDB API. The functionality remains the same.

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

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

Prerequisites

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

Alternatively, 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 for this tutorial with a URI of https://localhost:8081 and a key of

C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

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

Note

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
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 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
RangeIndex
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
IndexKind.Spatial
DataType.Point
Insert documents with GeoJSON points DocumentClient.CreateDocumentAsync
DataType.Point
Find points within a specified distance ST_DISTANCE
[GeometryOperationExtensions.Distance](https://msdn.microsoft.com/library/azure/microsoft.azure.documents.spatial.geometryoperationextensions.distance.aspx#M:Microsoft.Azure.Documents.Spatial.GeometryOperationExtensions.Distance(Microsoft.Azure.Documents.Spatial.Geometry,Microsoft.Azure.Documents.Spatial.Geometry)
Find points within a polygon ST_WITHIN
[GeometryOperationExtensions.Within](https://msdn.microsoft.com/library/azure/microsoft.azure.documents.spatial.geometryoperationextensions.within.aspx#M:Microsoft.Azure.Documents.Spatial.GeometryOperationExtensions.Within(Microsoft.Azure.Documents.Spatial.Geometry,Microsoft.Azure.Documents.Spatial.Geometry) and
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

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