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

APPLIES TO: SQL API

Links
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
Entity Framework Core tutorial Entity Framework Core with Azure Cosmos DB Provider
Current supported framework Microsoft .NET Standard 2.0

The minimum recommended version is 3.20.1.

Make sure that your applications, when using the .NET V3 SDK, are using at least the version described here to have all the critical fixes.

Any known issues detected on that version are listed in the known issues section.

Release notes

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.20.1 - 2021-06-29

3.20.1-preview - 2021-06-29

Fixed

  • #2450 Query: Fixes c# parser grammar for recognizing string literal which will avoid falling back to gateway to get the query plan.
  • #2574 UserAgent: Fixes race condition in user agent string creation and limits client id to 10. Introduced in 3.20.0 PR 2552
  • #2580 LINQ : Fixes ArgumentNullException while calling ToQueryDefinition() when no filters are applied.

3.20.0 - 2021-06-21

Added

  • #2509 Change Feed: Adds change feed iterator APIs on containers
  • #2558 Diagnostics: Adds Duration field to HttpResponseStatistics in Diagnostics
  • #2502 Diagnostics: Adds Direct TransportRequestStats for tracking transport request timeline
  • #2491 Change Feed Processor: Adds support for Graph API accounts. Graph API accounts can now create lease containers with /partitionKey instead of /id.

Fixed

  • #2567 ReadMany: Fixes AddRequestHeaders request option and missing headers and message on failure scenarios
  • #2510 Query: Fixes InvalidOperationException when partitions are merged. Introduced in 3.17.0 PR #2084.
  • #2510 Query: Fixes handling of pipeline execution on partition merge. Introduced in 3.17.0 PR #2084.
  • #2547 Query: Fixes incorrect order by query when the field is an object or array
  • #2511 Availability: Fixes get account info retry logic to not go to secondary regions on 403(Forbidden)
  • #2512 Caches: Fixes the cache to remove values if generator throws an exception. Thanks @johngallardo.
  • #2516 Diagnostics: Fixes a race condition causing InvalidOperationException. Introduced in 3.17.0 PR #2097
  • #2530 Gateway: Fixes container recreate scenarios for Gateway Mode in session consistency. Introduced in 3.18.0 PR #2165
  • #2552 UserAgent: Fixes UserAgent to have the correct number of clients
  • #2562 Diagnostics: Fixes NullReferenceException in service unavailable scenarios. Introduced in 3.18.0 PR #2312
  • #2502 Tracing: Removes noisy trace in direct mode

3.20.0-preview - 2021-06-21

Added

  • #2509 Change Feed: Adds change feed iterator APIs on containers
  • #2558 Diagnostics: Adds Duration field to HttpResponseStatistics in Diagnostics
  • #2502 Diagnostics: Adds Direct TransportRequestStats for tracking transport request timeline
  • #2491 Change Feed Processor: Adds support for Graph API accounts. Graph API accounts can now create lease containers with /partitionKey instead of /id.
  • #2488 Change Feed Processor: Refactors checkpoint API to throw exception. Introduced in #2331. This is considered a breaking change on the preview API as it evolves into GA.

Fixed

  • #2567 ReadMany: Fixes AddRequestHeaders request option and missing headers and message on failure scenarios
  • #2510 Query: Fixes InvalidOperationException when partitions are merged. Introduced in 3.17.0 PR #2084.
  • #2510 Query: Fixes handling of pipeline execution on partition merge. Introduced in 3.17.0 PR #2084.
  • #2547 Query: Fixes incorrect order by query when the field is an object or array
  • #2511 Availability: Fixes get account info retry logic to not go to secondary regions on 403(Forbidden)
  • #2512 Caches: Fixes the cache to remove values if generator throws an exception. Thanks @johngallardo.
  • #2516 Diagnostics: Fixes a race condition causing InvalidOperationException. Introduced in 3.17.0 PR #2097
  • #2530 Gateway: Fixes container recreate scenarios for Gateway Mode in session consistency. Introduced in 3.18.0 PR #2165
  • #2552 UserAgent: Fixes UserAgent to have the correct number of clients
  • #2562 Diagnostics: Fixes NullReferenceException in service unavailable scenarios. Introduced in 3.18.0 PR #2312
  • #2502 Tracing: Removes noisy trace in direct mode

3.19.0 - 2021-05-25

Added

  • #2482 Azure Active Directory: Adds CosmosClient TokenCredential APIs
  • #2440 Performance: Adds Bulk optimizations to reduce allocations and improves async task handling
  • #2447 Availability: Adds account refresh logic on gateway outage instead of waiting on 5min background refresh
  • #2493 NullReferenceException: Adds logic to append the CosmosDiagnostics to NullReferenceExceptions
  • #2465 ObjectDisposedException: Adds logic to append the CosmosDiagnostics to ObjectDisposedException
  • #2390 Bulk: Adds retry for patch operations when request is to large
  • #2487 UserAgent: Adds flag to user agent to show if region failover is configured

Fixed

  • #2451 Query: Fixes native c# parser not recognizing query with multiple IN statements. Introduced in 3.13.0 PR #1743
  • #2451 Bulk: Fixes diagnostic traces by removing redundant info and adding correct retry context. Introduced in 3.17.0 PR #2097
  • #2460 Permission: Fixes documentation on resource token range limit. (Thanks to arorainms)
  • #2490 Change Feed: Fixes CancellationToken to be honored. Introduced in 3.15.0 PR #1933
  • #2483 Availability: Fixes the get account information to stop the background refresh after CosmosClient is disposed. Introduced in 3.18.0 PR #2355
  • #2481 Azure Active Directory: Fixes token refresh interval, exception handling, and retry logic
  • #2474 Change Feed: Fixes exceptions generating "Change Feed should always have a next page". Introduced in 3.15.0 PR #1933
  • #2498 Diagnostics: Fixes default setting in Consistency Config Serialization. Introduced in 3.18.0 PR #2250

3.19.0-preview1 - 2021-05-17

Added

  • #2398 Patch : Adds TrySerializeValueParameter method for PatchOperation
  • #2440 Performance: Adds Bulk optimizations to reduce allocations and improves async task handling
  • #2447 Availability: Adds account refresh logic on gateway outage instead of waiting on 5min background refresh
  • #2449 Client encryption: Adds PolicyFormatVersion and validation that partition key paths are not encrypted

Fixed

  • #2451 Query: Fixes native c# parser not recognizing query with multiple IN statements. Introduced in 3.13.0 PR #1743
  • #2451 Bulk: Fixes diagnostic traces by removing redundant info and adding correct retry context. Introduced in 3.17.0 PR #2097
  • #2460 Permission: Fixes documentation on resource token range limit. (Thanks to arorainms)

3.19.0-preview - 2021-04-27

Added

  • #2308 & #2425 Dedicated Gateway: Adds MaxIntegratedCacheStaleness to Item and Query Request Options
  • #2371 Request Options : Adds delegate on request options to access and add headers
  • #2398 Patch : Adds TrySerializeValueParameter and makes PatchOperation<T> internal since it is not used in any public API
  • #2331 ChangeFeedProcessor: Adds support for manual checkpoint, context, and stream

3.18.1-preview - 2021-06-14

Fixed

  • #2510 Query: Fixes InvalidOperationException on merge to a single partition
  • #2531 Query: Fixes invalid query results on partition merge

3.18.0 - 2021-04-26

Added

  • #2324 Diagnostics: Adds all http requests to diagnostics
  • #2400 Performance: Adds optimizations to reduce allocations for Direct + TCP operations
  • #2353 Query: Adds support to c# query parser for LIKE statement and INT system functions to avoid gateway query plan call when service interop is not available
  • #2397 Diagnostics: Adds optimizations and BELatency which is the Cosmos DB Backend Request Latency In Milliseconds
  • #2355 Availability: Adds concurrent requests to secondary region if the initial get account information takes longer than 5 seconds which reduces SDK startup time if primary region is down.
  • #2352 ReadManyApi: Adds new API designed to efficiently read a list of items using the item id and partition key value
  • #2250 Diagnostics: Adds client configuration information needed to root cause issues
  • #2241 ContainerBuilder: Adds public constructor to create ContainerBuilder instance
  • #2222 Query: Adds WithParameterStream to QueryDefinition to pass in serialized values
  • #2165 & #2408 Performance: Adds optimization to reduce header size for gateway mode with session consistency. It now only send specific partition session token like direct mode.

Fixed

  • #2282 Query: Fixes COUNT(DISTINCT) to always compute correct value. Any query with more than 1 page of results could produce incorrect values.
  • #2405 Change Feed: Fixes pull model to avoid additional NotModified call
  • #2368 Query: Fixes BadRequest with "Failed to parse ... as ResourceId" for gateway mode on splits. Introduced in 3.14.0 PR #1812
  • #2357 Query: Fixes incorrect RequestCharge and missing headers in FeedResponse for ordered cross-partition queries. Introduced in 3.14.0 PR #1812 (Thanks to ccurrens)
  • #2409 Query: Fixes race condition in diagnostics causes missing information and Index out of bound exceptions. Introduced in 3.17.0 PR #2097
  • #2400 Availability: Fixes race condition in direct + tcp mode causing SDK generated internal server errors and invalid operation exceptions
  • #2400 Availability: Fixes race condition in direct + tcp mode causing unnecessary connections to be created by concurrent requests
  • #2392 Change Feed Estimator: Fixes exception propagation to throw on StartAsync for container/lease not found scenarios. Introduced in 3.17.0 PR #1830
  • #2383 Availability: Fixes CancellationToken evaluation during failover which could prevent necessary SDK refreshes to occur
  • #2376 Diagnostics: Fixes invalid nesting and handler names in ITrace. Introduced in 3.17.0 PR #2097
  • #2286 Diagnostics: Fixes regression in ITrace where direct operation diagnostics were not included in exception scenarios. Introduced in 3.17.0 PR #2097
  • #2424 Query: Fixes TaskCanceledException being converted to InternalServerError and not including diagnostics on most exceptions. Introduced in 3.14.0 PR #1812

3.18.0-preview - 2021-03-18

Added

  • #2308 Patch: Adds preview support for Patch API
  • #2312 Diagnostics: Adds Api for getting all regions contacted by a request

Fixed

  • #2314 Diagnostics: Fixes InvalidOperationException caused by concurrently modifing a dictionary in TraceWriter. Introduced in 3.17.0 PR #2242
  • #2303 CosmosException : Fixes exception messages to remove JSON formatting
  • #2311 Spatial: Fixes deserialization when Json does not represent a Spatial type
  • #2284 Diagnostics: Adds traces for cache operations. Introduced in 3.17.0 PR #2097
  • #2278 Documentation: Fixes typos in comment examples (Thanks to paulomorgado)
  • #2279 Availability: Fixes region failover logic on control plane hot path when gateway hangs. Introduced in 3.16.0 PR #1954
  • #2286 Diagnostics: Fixes regression which caused ActivityId to not get included. Introduced in 3.17.0 PR #2097

3.17.1 - 2021-03-19

Fixed

  • #2314 Diagnostics: Fixes InvalidOperationException caused by concurrently modifying a dictionary in TraceWriter. Introduced in 3.17.0 PR #2242
  • #2303 CosmosException : Fixes exception messages to remove JSON formatting
  • #2311 Spatial: Fixes deserialization when Json does not represent a Spatial type
  • #2284 Diagnostics: Adds traces for cache operations. Introduced in 3.17.0 PR #2097
  • #2278 Documentation: Fixes typos in comment examples (Thanks to paulomorgado)
  • #2279 Availability: Fixes region failover logic on control plane hot path when gateway hangs. Introduced in 3.16.0 PR #1954
  • #2286 Diagnostics: Fixes regression which caused ActivityId to not get included. Introduced in 3.17.0 PR #2097

3.17.0 - 2021-03-02

Added

  • #1870 Batch API: Adds Session token support
  • #2145 EnableContentResponseOnWrite: Adds client level support via CosmosClientOptions and CosmosClientBuilder
  • #2166 QueryRequestOption: Adds optimization to avoid duplicating QueryRequestOption
  • #1830 & #2170 Change Feed Estimator: Adds support for detailed estimation per lease
  • #2097 & #2204 & #2213 & #2235 & #2236 & #2242 & #2246 CosmosDiagnostics: Refactored to use ITrace as the default implementation
  • #2206 LINQ : Adds User Defined Function Translation Support (Thanks to dpiessens)
  • #2210 QueryDefinition: Adds API to get query parameters (Thanks to thomaslevesque)
  • #2197 CosmosClient: Adds CreateAndInitializeAsync method which can be used to avoid latency of warming caches on first operation.
  • #2220 LINQ: Adds camelCase support to GetItemLinqQueryable() as optional parameter
  • #2249 Performance: Adds HTTP optimization to disable Nagle Algorithm for .NET Framework applications

Fixed

  • #2168 Query: Fixes a regression in Take operator where it drains the entire query instead of stopping a the take count. Introduced in 3.14.0 PR #1812 and reported in issue #1979
  • #2129 CosmosDiagnostics: Fixes memory leak caused by pagination library holding on to all diagnostics. Introduced in 3.14.0 PR #1812 and reported in issue #2087
  • #2103 Query: Fixes ORDER BY undefined (and mixed type primitives) continuation token support. Introduced in 3.14.0 PR #1812
  • #2124 Bulk: Fixes retry logic to handle RequestEntityTooLarge exceptions caused by the underlying batch request being to large. Introduced in #741
  • #2198 CosmosClientOptions: Fixes a bug causing ConsistentPrefix to be convert to BoundedStaleness. Introduced in 3.1.0 PR #541 and reported in issue #2196
  • #2262 CosmosException: Fixes the headers not matching CosmosException property values and incorrect SubStatusCode values on client initialization failures
  • #2269 PermissionProperties: Fixes PermissionProperties to not take dependency on internal type to fix mocking
  • #2097 Diagnostics: Fixes regression in query, change feed, and read feed that causes diagnostics to be empty after first page. Introduced in 3.14.0 PR #1812

3.17.0-preview1 - 2021-03-02

Added

  • #2197 CosmosClient: Adds CreateAndInitializeAsync Method

Fixed

  • #2235 CosmosDiagnostics: Fixes ITrace JsonTraceWriter to include address resolution and store response stats. Introduced in 3.17.0-preview in PR #2097
  • #2236 CosmosDiagnostics: Fixes missing POCO deserialization for query operations.
  • #2218 (Preview) ChangeFeed pull model: Fixes missing headers on failure path. Introduced in 3.15.0 in PR #1933

3.17.0-preview - 2021-02-15

Added

  • #1870 Batch API: Adds Session token support
  • #1952 & #1648 (Preview) Subpartitioning: Adds support for subpartitioning
  • #2122 (Preview) Change Feed: Adds Full Fidelity support
  • #2145 EnableContentResponseOnWrite: Adds client level support via CosmosClientOptions and CosmosClientBuilder
  • #2166 QueryRequestOption: Adds optimization to avoid duplicating QueryRequestOption
  • #2097 & #2204 & #2213 CosmosDiagnostics: Refactored to use ITrace as the default implementation
  • #2206 LINQ : Adds User Defined Function Translation Support (Thanks to dpiessens)
  • #2210 QueryDefinition: Adds API to get query parameters (Thanks to thomaslevesque)

Fixed

  • #2168 Query: Fixes a regression in Take operator where it drains the entire query instead of stopping a the take count. Introduced in 3.14.0 PR #1812 and reported in issue #1979
  • #2129 CosmosDiagnostics: Fixes memory leak caused by pagination library holding on to all diagnostics. Introduced in 3.14.0 PR #1812 and reported in issue #2087
  • #2103 Query: Fixes ORDER BY undefined (and mixed type primitives) continuation token support. Introduced in 3.14.0 PR #1812
  • #2124 Bulk: Fixes retry logic to handle RequestEntityTooLarge exceptions caused by the underlying batch request being to large. Introduced in #741
  • #2198 CosmosClientOptions: Fixes a bug causing ConsistentPrefix to be convert to BoundedStaleness. Introduced in 3.1.0 PR #541 and reported in issue #2196

3.16.0 - 2021-01-12

Added

  • #2098 Performance: Adds gateway header optimization
  • #1954 & #2094 Control Plane Hot Path: Adds more aggressive timeout and retry logic for getting caches and query plan from gateway
  • #2013 Change Feed Processor: Adds support for EPK leases
  • #2016 Performance: Fixes lock contentions and reduce allocations on TCP requests
  • #2000 Performance: Adds Authorization Helper improvements

Fixed

  • #2110 CosmosException: Fixes substatuscode to get the correct value instead of 0 when it is not in the enum
  • #2092 Query: Fixes cancellation token support for the lazy + buffering path
  • #2099 & #2116 CosmosDiagnostics: Fixes IndexOutOfRangeException by adding concurrent operation support
  • #2096 AggregateException: Fixes some cache calls to throw original exception instead of AggregateException
  • #2044 Query: Fixes Equals method on SqlParameter class
  • #2077 Availability: Fixes retry behavior on HttpException where SDK will retry on same region instead of secondary region
  • #2056 Performance: Fixes encoded strings performance for query operations
  • #2060 Query: Fixes high CPU usage caused by FeedRange comparison used in LINQ order by operation. Introduced in 3.14.0 PR #1812
  • #2041 Request Charge: Fixes request charges for offers and CreateIfNotExists APIs

3.15.1 - 2020-12-16

Fixed

  • #2069 Bulk: Fixes incorrect routing on split
  • #2047 Diagnostics: Adds operation name to summary
  • #2042 Change Feed Processor: Fixes StartTime not being correctly applied. Introduced in 3.13.0-preview PR #1725
  • #2071 Diagnostics: Fixes substatuscode when recording internal DocumentClientException

3.15.0 - 2020-11-17

Added

  • #1926 Query: Adds multiple arguments in IN clause support to c# query parser when service interop is not available.
  • #1933 ChangeFeed: Adds adoption of pagination library
  • #1943 Performance: Adds query optimization by LazyCosmosElement Cache Improvements
  • #1944 Performance: Adds direct version to get response header improvement
  • #1947 ReadFeed: Adds pagination library adoption
  • #1949 Performance: Adds optimized request headers
  • #1974 Performance: Adds Bulk optimization by reducing lock contention in TimerWheel
  • #1977 Performance diagnostics: Adds static timer and caches handler name

Fixed

  • #1930 Change Feed: Fixes estimator diagnostics
  • #1939 LINQ: Fixes ArgumentNullException with StringComparison sensitive case (Thanks to ylabade)
  • #1940 LINQ: Fixes CancellationToken bug in CosmosLinqQuery.AggregateResultAsync (Thanks to ylabade)
  • #1960 CosmosClientOptions and ClientBuilder: Fixes ArgumentException when setting null value on HttpClientFactory or WebProxy
  • #1961 RequestOption.Properties: Fixes RequestOption.Properties for CreateContainerIfNotExistsAsync
  • #1967 Query: Fixes CancellationToken logic in pagination library
  • #1988 Query: Fixes split proofing logic for queries with logical partition key
  • #1999 Performance: Fixes exception serialization when tracing is not enabled
  • #2004 Query: Fixes SplitHandling bug caused by caches not getting refreshed. Introduced in 3.14.0 PR #1812

3.15.2-preview - 2020-11-17

Fixed

  • #2004 Query: Fixes SplitHandling bug caused by caches not getting refreshed. Introduced in 3.14.0 PR #1812

Unlisted see #2004 - 3.15.1-preview - 2020-11-05

Fixed

  • #1972 Private preview Azure Active Directory: Fixes TokenCredentialCache timeout logic and ports tests from master
  • #1984 Private preview Azure Active Directory: Fixes issue with using wrong scope value

Unlisted see #2004 - 3.15.0-preview - 2020-10-21

Added

  • #1944 Performance: Adds direct version to get response header improvement
  • #1933 Change Feed: Adds new continuation token format which can be migrated via new EmitOldContinuationToken.
  • #1933 Change Feed: Adds the ability to retry on 304s and no longer modifies HasMoreResults
  • #1926 Query: Adds multiple arguments in IN clause support to c# query parser when service interop is not available.
  • #1798 Private Preview Azure Active Directory: Adds Azure Active Directory support to the SDK

Fixed

  • #1933 Change Feed: Fixes StartFrom bug where the value was not honored

Unlisted see #2004 - 3.14.0-preview - 2020-10-09

Added

  • #1830 Change Feed Estimator: Adds support for detailed estimation per lease

Unlisted see #2004 - 3.14.0 - 2020-10-09

Added

  • #1876 Performance: Adds session token optimization
  • #1879 Performance: Adds AuthorizationHelper improvements
  • #1882 Performance: Adds SessionContainer optimizations and style fixes
  • #1812 Query: Adds adoption of pagination library
  • #1920 Query: Adds RegexMatch system function support

Fixed

  • #1875 HttpClient: Fixes HttpResponseMessage.RequestMessage is null in WASM
  • #1886 Change Feed Processor: Fixes failures during initialization
  • #1892 GatewayAddressCache: Fixes high CPU from HashSet usage on Address refresh path
  • #1909 Authorization: Fixes DocumentClientException being thrown on write operations
  • #1812 Query: Fixes MalformedContinuationTokenException. Introduced in 3.7.0 PR #1260 and reported in issue #1364

3.13.0 - 2020-09-21

Added

  • #1743 Query Performance: Adds skipping getting query plan for non-aggregate single partition queries on non-Windows x64 systems when FeedOptions.PartitionKey is set
  • #1768 Performance: Adds SessionToken optimization to reduce header size by removing session token for CRUD on stored procedure, triggers, and UDFs
  • #1781 Performance: Adds headers optimization which can reduce response allocation by 10 KB per a request.
  • #1825 RequestOptions.Properties: Adds the ability for applications to specify request context
  • #1835 Performance: Add HttpClient optimization to avoid double buffering gateway responses
  • #1837 Query SystemFunctions : Adds DateTime System Functions
  • #1842 Query Performance: Adds Singleton QueryPartitionProvider. Helps when Container is getting recreated.
  • #1857 Performance: Adds finalizer optimizations in a few places (Thanks to pentp)
  • #1843 Performance: Adds Transport serialization, SessionTokenMismatchRetryPolicy, and store response dictionary optimizations

Fixed

  • #1757 Batch API: Fixes the size limit to reduce timeouts
  • #1758 Connectivity: Fixes address resolution calls when using EnableTcpConnectionEndpointRediscovery
  • #1788 Transient HTTP exceptions: Adds retry logic to all http requests
  • #1863 HttpClientHandler: Fixes HttpClientHandler PlatformNotSupportedException

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

  • #1548 Availability: Fixes SDK failover logic. An HttpClient used the user configured request timeout on metadata request causing an ambiguous OperationCanceledException instead of the HttpRequestException which is used to trigger failovers.
  • #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.1-preview - 2020-10-01

  • #1892 Performance: Fixes High CPU caused by EnableTcpConnectionEndpointRediscovery by reducing HashSet lock contention

3.11.0 - 2020-07-07

3.11.0-preview - 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

How will I be notified of the retiring SDK?

Azure will provide 12 month's advance notice before the end of support of the retiring SDK to facilitate a smooth transition to a supported SDK. We'll notify you through various communication channels: the Azure portal, Azure updates, and direct communication to assigned service administrators.

Can I author applications by using a to-be-retired Azure Cosmos DB SDK during the 12-month period?

Yes, you'll be able to author, deploy, and modify applications by using the to-be-retired Azure Cosmos DB SDK during the 12-month notice period. We recommend that you migrate to a newer supported version of the Azure Cosmos DB SDK during the 12-month notice period, as appropriate.

After the retirement date, what happens to applications that use the unsupported Azure Cosmos DB SDK?

After the retirement date, Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions. If you prefer not to upgrade, requests sent from the retired versions of the SDK will continue to be served by the Azure Cosmos DB service.

Which SDK versions will have the latest features and updates?

New features and updates will be added only to the latest minor version of the latest supported major SDK version. We recommend that you always use the latest version to take advantage of new features, performance improvements, and bug fixes. If you're using an old, non-retired version of the SDK, your requests to Azure Cosmos DB will still function, but you won't have access to any new capabilities.

What should I do if I can't update my application before a cutoff date?

We recommend that you upgrade to the latest SDK as early as possible. After an SDK is tagged for retirement, you'll have 12 months to update your application. If you're not able to update by the retirement date, requests sent from the retired versions of the SDK will continue to be served by Azure Cosmos DB, so your running applications will continue to function. But Azure Cosmos DB will no longer make bug fixes, add new features, or provide support to the retired SDK versions.

If you have a support plan and require technical support, contact us by filing a support ticket.

See also

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