Azure Cosmos DB .NET Core SDK for SQL API: Release notes and resources

SDK downloadNuGet
API documentation.NET API reference documentation
Samples.NET code samples
Get startedGet started with the Azure Cosmos DB .NET Core SDK
Web app tutorialWeb application development with Azure Cosmos DB
Current supported framework.NET Standard 1.6 and .NET Standard 1.5

Release Notes

The Azure Cosmos DB .NET Core SDK has feature parity with the latest version of the Azure Cosmos DB .NET SDK.


  • Added ConsistencyLevel Property to FeedOptions.
  • Added JsonSerializerSettings to RequestOptions and FeedOptions.
  • Added EnableReadRequestsFallback to ConnectionPolicy.


  • Fixed KeyNotFoundException for cross partition order by queries in corner cases.
  • Fixed bug where JsonPropery attribute in select clause for LINQ queries was not being honored.


  • Fixed bug that is hit under certain race conditions, that results in intermittent “Microsoft.Azure.Documents.NotFoundException: The read session is not available for the input session token” errors when using Session consistency level.


  • Fixed regression where FeedOptions.MaxItemCount = -1 threw an System.ArithmeticException: page size is negative.
  • Added a new ToString() function to QueryMetrics.
  • Exposed partition statistics on reading collections.
  • Added PartitionKey property to ChangeFeedOptions.
  • Minor bug fixes.


  • Adds the ability to specify unique indexes for the documents by using UniqueKeyPolicy property on the DocumentCollection.
  • Fixed a bug in which the custom JsonSerializer settings were not being honored for some queries and stored procedure execution.


  • Branding change from Azure DocumentDB to Azure Cosmos DB in the API Reference documentation, metadata information in assemblies, and the NuGet package.
  • Expose diagnostic information and latency from the response of requests sent with direct connectivity mode. The property names are RequestDiagnosticsString and RequestLatency on ResourceResponse class.
  • This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from


  • Added several reliability fixes and improvements.



  • Added support for PartitionKeyRangeId as a FeedOption for scoping query results to a specific partition key range value.
  • Added support for StartTime as a ChangeFeedOption to start looking for the changes after that time.


  • Fixed an issue in the JsonSerializable class that may cause a stack overflow exception.


  • Added support for specifying custom JsonSerializerSettings while instantiating a DocumentClient instance.


  • Supporting .NET Standard 1.5 as one of the target frameworks.


  • Fixed an issue that affected x64 machines that don’t support SSE4 instruction and throw SEHException when running Azure Cosmos DB queries.


  • Added support for a new consistency level called ConsistentPrefix.
  • Added support for query metrics for individual partitions.
  • Added support for limiting the size of the continuation token for queries.
  • Added support for more detailed tracing for failed requests.
  • Made some performance improvements in the SDK.


  • Fixed an issue that ignored the PartitionKey value provided in FeedOptions for aggregate queries.
  • Fixed an issue in transparent handling of partition management during mid-flight cross-partition Order By query execution.


  • Fixed an issue which caused deadlocks in some of the async APIs when used inside ASP.NET context.


  • Fixes to make SDK more resilient to automatic failover under certain conditions.


  • Fix for an issue that occasionally causes a WebException: The remote name could not be resolved.
  • Added the support for directly reading a typed document by adding new overloads to ReadDocumentAsync API.


  • Added LINQ support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
  • Fix for a memory leak issue for the ConnectionPolicy object caused by the use of event handler.
  • Fix for an issue wherein UpsertAttachmentAsync was not working when ETag was used.
  • Fix for an issue wherein cross partition order-by query continuation was not working when sorting on string field.


  • Added support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG). See Aggregation support.
  • Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.


The Azure Cosmos DB .NET Core SDK enables you to build fast, cross-platform ASP.NET Core and .NET Core apps to run on Windows, Mac, and Linux. The latest release of the Azure Cosmos DB .NET Core SDK is fully Xamarin compatible and be used to build applications that target iOS, Android, and Mono (Linux).


The Azure Cosmos DB .NET Core Preview SDK enables you to build fast, cross-platform ASP.NET Core and .NET Core apps to run on Windows, Mac, and Linux.

The Azure Cosmos DB .NET Core Preview SDK has feature parity with the latest version of the Azure Cosmos DB .NET SDK and supports the following:

If you have questions related to this SDK, post to StackOverflow, or file an issue in the github repository.

Release & Retirement Dates

Version Release Date Retirement Date
1.9.1 March 09, 2018 ---
1.8.2 February 21, 2018 ---
1.8.1 February 05, 2018 ---
1.7.1 November 16, 2017 ---
1.7.0 November 10, 2017 ---
1.6.0 October 17, 2017 ---
1.5.1 October 02, 2017 ---
1.5.0 August 10, 2017 ---
1.4.1 August 07, 2017 ---
1.4.0 August 02, 2017 ---
1.3.2 June 12, 2017 ---
1.3.1 May 23, 2017 ---
1.3.0 May 10, 2017 ---
1.2.2 April 19, 2017 ---
1.2.1 March 29, 2017 ---
1.2.0 March 25, 2017 ---
1.1.2 March 20, 2017 ---
1.1.1 March 14, 2017 ---
1.1.0 February 16, 2017 ---
1.0.0 December 21, 2016 ---
0.1.0-preview November 15, 2016 December 31, 2016

See Also

To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.