Azure Cosmos DB .NET Standard SDK for SQL API: Download and release notes

SDK download NuGet
API documentation .NET API reference documentation
Samples .NET code samples
Get started Get started with the Azure Cosmos DB .NET SDK
Web app tutorial Web application development with Azure Cosmos DB
Current supported framework Microsoft .NET Standard 2.0


Preview features are treated as a separate branch and will not be included in the official release until the feature is ready. Each preview release lists all the additional features that are enabled.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.




3.6.0 - 2020-01-23


  • #1097 Add GeospatialConfig to ContainerProperties, BoundingBoxProperties to SpatialPath
  • #1061 Add Stream payload to ExecuteStoredProcedureStreamAsync
  • #1062 Add additional diagnostic information including the ability to track time through the different SDK layers
  • #1107 Add Source Link support
  • #1121 StandByFeedIterator breath-first read strategy


  • #1105 Custom serializer no longer calls SDK owned types that would cause serialization exceptions
  • #1112 Fixed SDK properties like DatabaseProperties to have same JSON attributes
  • #1116 Fixed a deadlock on scenarios with SynchronizationContext while executing async query operations
  • #1143 Fixed permission resource link and authorization issue when doing a query with resource token for a specific partition key
  • #1150 Fixed NullReferenceException when using a non-existent Lease Container.

3.5.1 - 2019-12-11


  • #1060 Fixed unicode encoding bug in DISTINCT queries.
  • #1070 CreateItem will only retry for auto-extracted partition key in-case of collection re-creation
  • #1075 Including header size details for BadRequest with large headers
  • #1078 Fixed a deadlock on scenarios with SynchronizationContext while executing async SDK API
  • #1081 Fixed race condition in serializer caused null reference exception.
  • #1086 Fix possible NullReferenceException on a TransactionalBatch code path
  • #1091 Fixed a bug in query when a partition split occurs that causes a NotImplementedException to be thrown.
  • #1089 Fixes a NullReferenceException when using Bulk with items with no PK

3.5.0 - 2019-12-03


  • #979 Make SessionToken on QueryRequestOptions public.
  • #995 Included session token in diagnostics.
  • #1000 Add PortReuseMode to CosmosClientOptions.
  • #1017 Adding ClientSideRequestStatistics to gateway calls and making endtime nullable
  • #1038 Add Selflink to resource properties


  • #921 Fixed error handling to preserve stack trace in certain scenarios
  • #944 Change Feed Processor won't use user serializer for internal operations
  • #988 Fixed query mutating due to retry of gone / name cache is stale.
  • #954 Support "Start from Beginning" for Change Feed Processor in multi master accounts
  • #999 Fixed grabbing extra page, updated continuation token on exception path, and non ascii character in order by continuation token.
  • #1013 Gateway OperationCanceledException are now returned as request timeouts
  • #1020 Direct package update removes debug statements
  • #1023 Fixed ThroughputResponse.IsReplacePending header mapping
  • #1036 Fixed query responses to return null Content if it is a failure
  • #1045 Added stack trace and innner exception to CosmosException
  • #1050 Add mocking constructors to TransactionalBatchOperationResult

3.4.1 - 2019-11-06


  • #978 Fixed mocking for FeedIterator and Response classes

3.4.0 - 2019-11-04


  • #853 ORDER BY Arrays and Object support.
  • #877 Query diagnostics now contains client side request diagnostics information
  • #923 Bulk Support is now public
  • #922 Included information of bulk support usage in user agent
  • #934 Preserved the ordering of projections in a GROUP BY query.
  • #952 ORDER BY Undefined and Mixed Type ORDER BY support
  • #965 Batch API is now public


  • #901 Fixed a bug causing query response to create a new stream for each content call
  • #918 Fixed serializer being used for Scripts, Permissions, and Conflict related iterators
  • #936 Fixed bulk requests with large resources to have natural exception

3.3.3 - 2019-10-30

  • #837 Fixed group by bug for non-Windows platforms
  • #927 Fixed query returning partial results instead of error

3.3.2 - 2019-10-16


  • #905 Fixed linq camel case bug

3.3.1 - 2019-10-11


  • #895 Fixed user agent bug that caused format exceptions on non-Windows platforms

3.3.0 - 2019-10-09


  • #801 Enabled LINQ ThenBy operator after OrderBy
  • #814 Ability to limit to configured endpoint only
  • #822 GROUP BY query support.
  • #844 Added PartitionKeyDefinitionVersion to container builder


  • #835 Fixed a bug that caused sortedRanges exceptions
  • #846 Statistics not getting populated correctly on CosmosException.
  • #857 Fixed reusability of the Bulk support across Container instances
  • #860 Fixed base user agent string
  • #876 Default connection timeout reduced from 60s to 10s

3.2.0 - 2019-09-17


  • #100 Configurable Tcp settings to CosmosClientOptions
  • #615, #775 Added request diagnostics to Response's
  • #622 Added CRUD and query operations for Users and Permissions which enables ResourceToken support
  • #716 Added camel case serialization on LINQ query generation
  • #729, #776 Added aggregate(CountAsync/SumAsync etc.) extensions for LINQ query
  • #743 Added WebProxy to CosmosClientOptions


  • #726 Query iterator HasMoreResults now returns false if an exception is hit
  • #705 User agent suffix gets truncated
  • #753 Reason was not being propagated for Conflict exceptions
  • #756 Change Feed Processor with WithStartTime would execute the delegate the first time with no items.
  • #761 CosmosClient deadlocks when using a custom Task Scheduler like Orleans (Thanks to jkonecki)
  • #769 Session Consistency + Gateway mode session-token bug fix: Under few rare non-success cases session token might be in-correct
  • #772 Fixed Throughput throwing when custom serializer used or offer doesn't exists
  • #785 Incorrect key to throw CosmosExceptions with HttpStatusCode.Unauthorized status code

3.2.0-preview2 - 2019-09-10

  • #585, #741 Bulk execution support
  • #427 Transactional batch support (Item CRUD)

3.2.0-preview - 2019-08-09

  • #427 Transactional batch support (Item CRUD)

3.1.1 - 2019-08-12


  • #650 CosmosSerializerOptions to customize serialization


  • #612 Bug fix for ReadFeed with partition-key
  • #614 Fixed SpatialPath serialization and compatibility with older index versions
  • #619 Fixed PInvokeStackImbalance exception for .NET Framework
  • #626 FeedResponse status code now return OK for success instead of the invalid status code 0 or Accepted
  • #629 Fixed CreateContainerIfNotExistsAsync validation to limited to partitionKeyPath only
  • #630 Fixed User Agent to contain environment and package information

3.1.0 - 2019-07-29 - Unlisted


  • #541 Added consistency level to client and query options
  • #544 Added continuation token support for LINQ
  • #557 Added trigger options to item request options
  • #572 Added partition key validation on CreateContainerIfNotExistsAsync
  • #581 Added LINQ to QueryDefinition API
  • #592 Added CreateIfNotExistsAsync to container builder
  • #597 Added continuation token property to ResponseMessage
  • #604 Added LINQ ToStreamIterator extension method


  • #548 Fixed mis-typed message in CosmosException.ToString();
  • #558 LocationCache ConcurrentDict lock contention fix
  • #561 GetItemLinqQueryable now works with null query
  • #567 Query correctly handles different language cultures
  • #574 Fixed empty error message if query parsing fails from unexpected exception
  • #576 Query correctly serializes the input into a stream

3.0.0 - 2019-07-15

  • General availability of Version 3.0.0 of the .NET SDK
  • Targets .NET Standard 2.0, which supports .NET framework 4.6.1+ and .NET Core 2.0+
  • New object model, with top-level CosmosClient and methods split across relevant Database and Container classes
  • New highly performant stream APIs
  • Built-in support for Change Feed processor APIs
  • Fluent builder APIs for CosmosClient, Container, and Change Feed processor
  • Idiomatic throughput management APIs
  • Granular RequestOptions and ResponseTypes for database, container, item, query and throughput requests
  • Ability to scale non-partitioned containers
  • Extensible and customizable serializer
  • Extensible request pipeline with support for custom handlers

Release & Retirement dates

Microsoft provides notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version.

New features and functionality and optimizations are only added to the current SDK, as such it is recommended that you always upgrade to the latest SDK version as early as possible.

Any requests to Azure Cosmos DB using a retired SDK are rejected by the service.

Version Release Date Retirement Date
3.6.0 January 23, 2020 ---
3.5.1 December 11, 2019 ---
3.5.0 December 03, 2019 ---
3.4.1 November 06, 2019 ---
3.4.0 November 04, 2019 ---
3.3.3 October 30, 2019 ---
3.3.2 October 16, 2019 ---
3.3.1 October 11, 2019 ---
3.3.0 October 8, 2019 ---
3.2.0 September 18, 2019 ---
3.1.1 August 12, 2019 ---
3.1.0 July 29, 2019 ---
3.0.0 July 15, 2019 ---


1. How will customers be notified of the retiring SDK?

Microsoft will provide 12 month advance notification to the end of support of the retiring SDK in order to facilitate a smooth transition to a supported SDK. Further, customers will be notified through various communication channels – Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

Yes, customers will have full access to author, deploy and modify applications using the "to-be" retired Azure Cosmos DB SDK during the 12 month grace period. During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

After the 12 month notification period, the SDK will be retired. Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. Further, Microsoft will not provide customer support on the retired SDK.

4. What happens to Customer’s running applications that are using unsupported Azure Cosmos DB SDK version?

Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5. Will new features and functionality be applied to all non-retired SDKs?

New features and functionality will only be added to new versions. If you are using an old, non-retired, version of the SDK your requests to Azure Cosmos DB will still function as previous but you will not have access to any new capabilities.

6. What should I do if I cannot update my application before a cut-off date?

We recommend that you upgrade to the latest SDK as early as possible. Once an SDK has been tagged for retirement you will have 12 months to update your application. If, for whatever reason, you cannot complete your application update within this timeframe then please contact the Cosmos DB Team and request their assistance before the cutoff date.

See also

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