Azure Cosmos DB .NET SDK v3 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.13.0-preview - 2020-08-12

Added

  • #1725 ChangeFeed : Adds ChangeFeedStartFrom to support StartTimes x FeedRanges. WARNING: This is breaking change for preview SDK
  • #1764 Performance: Adds compiler optimize flag
  • #1768 SessionToken: Adds optimization to reduce header size by removing session token for CRUD on stored procedure, triggers, and UDFs

Fixed

  • #1757 Batch API: Fixes the size limit to reduce timeouts
  • #1758 Connectivity: Fixes address resolution calls when using EnableTcpConnectionEndpointRediscovery

3.12.0 - 2020-08-06

Added

  • #1548 Transport: Adds an optimization to unify HttpClient usage across Gateway classes
  • #1569 Batch API: Adds support of request options for transactional batch
  • #1693 Performance: Reduces lock contention on GlobalAddress Resolver
  • #1712 Performance: Adds optimization to reduce AuthorizationHelper memory allocations
  • #1715 Availability: Adds cross-region retry mechanism on transient connectivity issues
  • #1721 LINQ : Adds support for case-insensitive searches (Thanks to jeffpardy)
  • #1733 Change Feed Processor: Adds backward compatibility of lease store

Fixed

  • #1720 Gateway Trace: Fixes a bug where the ActivityId is being set to Guid.Empty
  • #1728 Diagnostics: Fixes ActivityScope by moving it to operation level
  • #1740 Connection limits: Fixes .NET core to honor gateway connection limit
  • #1744 Transport: Fixes use of PortReuseMode and other Direct configuration settings

3.11.0 - 2020-07-07

Added

  • #1587 & 1643 & 1667 Diagnostics: Adds synchronization context tracing to all request
  • #1617 Performance: Fixes Object Model hierarchy to use strings for relative paths instead of URI
  • #1639 CosmosClient: Adds argument check for empty key to prevent ambiguous 401 not authorized exception
  • #1640 Bulk: Adds TimerWheel to Bulk to improve latency
  • #1678 Autoscale: Adds to container builder

Fixed

  • #1638 Documentation : Fixes all examples to add using statement to FeedIterator
  • #1666 CosmosOperationCanceledException: Fixes handler to catch all operation cancelled exceptions
  • #1682 Performance: Fixes high CPU consumption caused by EnableTcpConnectionEndpointRediscovery

3.10.1 - 2020-06-18

  • #1637 TransportHandler : Removes stack trace print. Introduced in 3.10.0 PR 1587

3.10.0 - 2020-06-18

Added

  • #1613 Query FeedIterator: Adds IDisposable to fix memory leak. WARNING: This will require changes to fix static anlysis tools checking for dispose.
  • #1550 CosmosOperationCanceledException: This enables users to access the diagnsotics when an operation is canceled via the cancellation token. The new type extends OperationCanceledException so it does not break current exception handling and includes the CosmosDiagnostic in the ToString().
  • #1578 Query: Adds memory optimization to prevent coping the buffer
  • #1578 Query: Adds support for ignore case for Contains and StartsWith functions.
  • #1602 Diagnostics: Adds CPU usage to all operations
  • #1603 Documentation: Adds new exception handling documentation

Fixed

  • #1530 ContainerDefinition : Fixes WithDefaultTimeToLive argument spelling (Thanks to tony-xia)
  • #1547 & #1582 Query and Readfeed: Fix exceptions caused by not properly handling splits
  • #1578 ApplicationRegion: Fixes ApplicationRegion to ensure the correct order is being used for failover scenarios
  • #1585 Query : Fixes Multi- ORDER BY continuation token support with QueryExecutionInfo response headers

3.9.1 - 2020-05-19

3.9.1-preview - 2020-05-19

Fixed

  • #1539 CosmosException and Diagnostics: Fixes ToString() to not grow exponentially with retries. Introduced in 3.7.0 in PR #1189.

3.9.0 - 2020-05-18

Added

  • #1356 & #1407 & #1428 & #1407 Adds autoscale support.
  • #1398 Diagnostics: Adds CPU monitoring for .NET Core.
  • #1441 Transport: Adds HttpClientFactory support on CosmosClientOptions.
  • #1457 Container: Adds database reference to the container.
  • #1455 Serializer: Adds SDK serializer to Client.ClientOptions.Serializer.
  • #1397 CosmosClientBuilder: Adds preferred regions and WithConnectionModeDirect().
  • #1439 No content on Response: Adds the ability to have operations return no content from Azure Cosmos DB.
  • #1398 & #1516 Read feed and change feed: Adds serialization optimization to reduce memory and CPU utilization up to 90%. Objects are now passed as an array to the serializer.
  • #1516 Query: Adds serialization optimization to reduce memory up to %50 and CPU utilization up to 25%. Objects are now passed as an array to the serializer.

Fixed

  • #1401 & #1437: Response type: Fix deadlock on scenarios with SynchronizationContext when using Response.Container.
  • #1445 Transport: Fix ServicePoint for WebAssembly.
  • #1462 UserAgent: Fix feature usage tracking.
  • #1469 Diagnostics: Fix InvalidOperationException and converts elapsed time to millisecond.
  • #1512 PartitionRoutingHelper: Fix ReadFeed ArgumentNullException due to container cache miss.
  • #1530 CosmosClientBuilder: Fix WithDefaultTimeToLive parameter spelling.

3.9.0-preview3 - 2020-05-11

Added

  • #1356 & #1407 & #1428 Autoscale preview release.
  • #1407 Autoscale: Adds CreateDatabaseIfNotExistsAsync and CreateContainerIfNotExistsAsync methods.
  • #1410 FeedRange: Adds Json serialization support.
  • #1398 Diagnostics: Adds CPU monitoring for .NET Core.
  • #1441 Transport: Adds HttpClientFactory support on CosmosClientOptions.
  • #1457 Container: Adds database reference to the container.
  • #1453 Response factory: Adds a response factory to the public API.
  • #1455 Serializer: Adds SDK serializer to Client.ClientOptions.Serializer.
  • #1397 CosmosClientBuilder: Adds preferred regions and public internal func WithConnectionModeDirect().
  • #1439 No content on response: Adds the ability to have operation return no content from Azure Cosmos DB.
  • #1469 Diagnostics: Fixes the InvalidOperationException and converts elapsed time to millisecond.

Fixed

  • #1398 Reduced memory allocations on query deserialization.
  • #1401 & #1437: Response type: Fixes deadlock on scenarios with SynchronizationContext when using Response.Container.
  • #1445 Transport: Fixes ServicePoint for WebAssembly.
  • #1462 UserAgent: Fixes feature usage tracking.

3.9.0-preview - 2020-04-17

Added

  • #1356 Autoscale: Adds to public preview release

3.8.0-preview - 2020-04-16

Added

  • #1331 Enabled client encryption / decryption for transactional batch requests

Fixed

  • #1369 Fixes decryption for 'order by' query results

3.8.0 - 2020-04-07

Added

  • #1314 Adds configuration for proactive TCP end-of-connection detection.
  • #1305 Adds support for preferred region customization.

Fixed

  • #1312 Fixes null reference when using default(PartitionKey).
  • #1296 Decrypts the encrypted properties before returning query result.
  • #1345 Fixes get query plan diagnostics.

3.7.1-preview - 2020-03-30

  • #1210 Adds change feed pull model.
  • #1242 Client encryption - fixes bug in read path without encrypted properties.
  • #1314 Adds configuration for proactive TCP end-of-connection detection.
  • #1312 Fixes null reference when using default(PartitionKey).
  • #1296 Decrypts the encrypted properties before returning query result.

3.7.0 - 2020-03-26

Added

  • #1268 Adds GetElapsedClientLatency to CosmosDiagnostics.
  • #1239 Made MultiPolygon and PolygonCoordinates classes public.
  • #1233 Partition key now supports operators ==, != for equality comparison.
  • #1285 Add query plan retrieval to diagnostics.
  • #1289 Query ORDER BY resume optimization.
  • #1074 Bulk API congestion control.

Fixed

  • #1213 CosmosException now returns the original stack trace.
  • #1213 ResponseMessage.ErrorMessage is now always correctly populated. There was bug in some scenarios where the error message was left in the content stream.
  • #1298 CosmosException.Message contains the same information as CosmosException.ToString() to ensure all the information is being tracked.
  • #1242 Client encryption - Fixes bug in read path without encrypted properties.
  • #1189 Query diagnostics shows correct overall time.
  • #1189 Fixes a bug that caused duplicate information in diagnostic context.
  • #1263 Fixes a bug where retry after interval did not get set on query stream responses.
  • #1198 Fixes null reference exception when calling a disposed CosmosClient.
  • #1274 ObjectDisposedException is thrown when calling all SDK objects like Database and Container that reference a disposed client.
  • #1268 Fixes bug where Request Options was getting lost for Database.ReadStreamAsync and Database.DeleteStreamAsync methods.
  • #1304 Fixes XML documentation so it now is visible in Visual Studio.

3.7.0-preview2 - 2020-03-09

  • #1210 Change feed pull model.
  • #1242 Client encryption - fixes bug in read path without encrypted properties.

3.7.0-preview - 2020-02-25

  • #1074 Bulk API congestion control.
  • #1210 Change feed pull model.

3.6.0 - 2020-01-23

  • #1105 CosmosClient Immutability + Disposable Fixes

Added

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

Fixed

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

3.5.1 - 2019-12-11

Fixed

  • #1060 Fixes 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 bad request with large headers.
  • #1078 Fixes a deadlock on scenarios with SynchronizationContext while executing async SDK API.
  • #1081 Fixes race condition in serializer caused by null reference exception.
  • #1086 Fix possible NullReferenceException on a TransactionalBatch code path.
  • #1091 Fixes 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 without partition key.

3.5.0 - 2019-12-03

Added

  • #979 Make SessionToken on QueryRequestOptions public.
  • #995 Included session token in diagnostics.
  • #1000 Adds PortReuseMode to CosmosClientOptions.
  • #1017 Adds ClientSideRequestStatistics to gateway calls and making end time nullable.
  • #1038 Adds self-link to resource properties.

Fixed

  • #921 Fixes error handling to preserve stack trace in certain scenarios.
  • #944 Change feed processor won't use user serializer for internal operations.
  • #988 Fixes 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 Fixes grabbing extra page, updated continuation token on exception path, and non-Ascii character in order by continuation token.
  • #1013 Gateway OperationCanceledExceptions are now returned as request timeouts.
  • #1020 Direct package update removes debug statements.
  • #1023 Fixes ThroughputResponse.IsReplacePending header mapping.
  • #1036 Fixes query responses to return null Content if it is a failure.
  • #1045 Adds stack trace and inner exception to CosmosException.
  • #1050 Adds mocking constructors to TransactionalBatchOperationResult.

3.4.1 - 2019-11-06

Fixed

  • #978 Fixes mocking for FeedIterator and response classes.

3.4.0 - 2019-11-04

Added

  • #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.

Fixed

  • #901 Fixes a bug causing query response to create a new stream for each content call.
  • #918 Fixes serializer being used for scripts, permissions, and conflict-related iterators.
  • #936 Fixes bulk requests with large resources to have natural exception.

3.3.3 - 2019-10-30

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

3.3.2 - 2019-10-16

Fixed

  • #905 Fixes lINQ camel case bug.

3.3.1 - 2019-10-11

Fixed

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

3.3.0 - 2019-10-09

Added

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

Fixed

  • #835 Fixes a bug that caused sorted ranges exceptions.
  • #846 Statistics not getting populated correctly on CosmosException.
  • #857 Fixes reusability of the bulk support across container instances.
  • #860 Fixes base user agent string.
  • #876 Default connection time out reduced from 60 s to 10 s.

3.2.0 - 2019-09-17

Added

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

Fixed

  • #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.
  • #769 Session consistency and gateway mode session-token bug fix- under few rare non-success cases session token might be in-correct.
  • #772 Fixes 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

Added

  • #650 CosmosSerializerOptions to customize serialization.

Fixed

  • #612 Bug fix for ReadFeed with partition key.
  • #614 Fixes spatial path serialization and compatibility with older index versions.
  • #619 Fixes PInvokeStackImbalance exception for .NET framework.
  • #626 FeedResponse<T> status codes now return OK for success instead of the invalid status code 0 or Accepted.
  • #629 Fixes CreateContainerIfNotExistsAsync validation to limited to partition key path only.
  • #630 Fixes user agent to contain environment and package information.

3.1.0 - 2019-07-29 - Unlisted

Added

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

Fixed

  • #548 Fixes mis-typed message in CosmosException.ToString().
  • #558 Location cache ConcurrentDict lock contentions fix.
  • #561 GetItemLinqQueryable now works with null query.
  • #567 Query correctly handles different language cultures.
  • #574 Fixes 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 stream APIs that have high performance.
  • 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.

After 31 August 2022, Azure Cosmos DB will no longer make bug fixes, add new features, and provide support for versions 1.x of the Azure Cosmos DB .NET or .NET Core SDK for SQL API. If you prefer not to upgrade, requests sent from version 1.x of the SDK will continue to be served by the Azure Cosmos DB 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 ---

FAQ

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.