适用于 SQL API 的 Azure Cosmos DB .NET SDK v3:下载和发行说明Azure Cosmos DB .NET SDK v3 for SQL API: Download and release notes

适用于: SQL API

SDK 下载SDK download NuGetNuGet
API 文档API documentation 参考文档.NET API reference documentation
示例Samples .NET代码示例.NET code samples
入门Get started Azure Cosmos DB .NET SDK 入门Get started with the Azure Cosmos DB .NET SDK
Web 应用教程Web app tutorial 使用 Azure Cosmos DB 开发 Web 应用程序Web application development with Azure Cosmos DB
Entity Framework Core 教程Entity Framework Core tutorial Entity Framework Core 与 Azure Cosmos DB 提供程序Entity Framework Core with Azure Cosmos DB Provider
当前受支持的框架Current supported framework Microsoft .NET Standard 2.0Microsoft .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.

该格式基于保留 Changelog,而此项目遵循语义化版本控制The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

3.15.0-preview - 2020-10-213.15.0-preview - 2020-10-21

已添加Added

  • #1944 性能:添加直接版本以获取响应标头改进#1944 Performance: Adds direct version to get response header improvement
  • #1933 更改源:添加了可通过全新 EmitOldContinuationToken 迁移的全新延续令牌格式。#1933 Change Feed: Adds new continuation token format which can be migrated via new EmitOldContinuationToken.
  • #1933 更改源:添加了在出现 304 错误时重试的功能,并且不再修改 HasMoreResults#1933 Change Feed: Adds the ability to retry on 304s and no longer modifies HasMoreResults
  • #1926 查询:为 c# 查询分析器添加了当服务互操作不可用时对 IN 子句中多个参数的支持。#1926 Query: Adds multiple arguments in IN clause support to c# query parser when service interop is not available.

固定Fixed

  • #1933 更改源:修复了未遵循值的 StartFrom bug#1933 Change Feed: Fixes StartFrom bug where the value was not honored

3.14.0-preview - 2020-10-093.14.0-preview - 2020-10-09

已添加Added

  • #1830 更改源估算器:增加了对每个租约的详细估算的支持#1830 Change Feed Estimator: Adds support for detailed estimation per lease

3.14.0 - 2020-10-093.14.0 - 2020-10-09

已添加Added

  • #1876 性能:添加了会话令牌优化#1876 Performance: Adds session token optimization
  • #1879 性能:添加了 AuthorizationHelper 改进#1879 Performance: Adds AuthorizationHelper improvements
  • #1882 性能:添加了 SessionContainer 优化和样式修复#1882 Performance: Adds SessionContainer optimizations and style fixes
  • #1812 查询:添加了分页库的采用#1812 Query: Adds adoption of pagination library
  • #1920 查询:添加了 RegexMatch 系统函数支持#1920 Query: Adds RegexMatch system function support

固定Fixed

  • #1875 HttpClient:修复了 WASM 中 HttpResponseMessage.RequestMessage 为 null 的问题#1875 HttpClient: Fixes HttpResponseMessage.RequestMessage is null in WASM
  • #1886 更改源处理器:修复了初始化过程中的故障#1886 Change Feed Processor: Fixes failures during initialization
  • #1892 GatewayAddressCache:修复了在地址刷新路径上使用 HashSet 时导致 CPU 利用率过高的问题#1892 GatewayAddressCache: Fixes high CPU from HashSet usage on Address refresh path
  • #1909 授权:修复了在执行写入操作时引发 DocumentClientException 的问题#1909 Authorization: Fixes DocumentClientException being thrown on write operations

3.13.0 - 2020-09-213.13.0 - 2020-09-21

已添加Added

  • #1743 查询性能:添加了在已设置 FeedOptions.PartitionKey 时对非 Windows x64 系统上的非聚合单分区查询跳过“获取查询计划”的功能#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 性能:添加了 SessionToken 优化,以通过删除存储过程、触发器和 UDF 上用于 CRUD 的会话令牌来减小标头大小#1768 Performance: Adds SessionToken optimization to reduce header size by removing session token for CRUD on stored procedure, triggers, and UDFs
  • #1781 性能:添加了标头优化,从而可减少响应分配(每个请求减少 10 KB)。#1781 Performance: Adds headers optimization which can reduce response allocation by 10 KB per a request.
  • #1825 RequestOptions.Properties:为应用程序添加了指定请求上下文的功能#1825 RequestOptions.Properties: Adds the ability for applications to specify request context
  • #1835 性能:添加了 HttpClient 优化以避免双重缓冲网关响应#1835 Performance: Add HttpClient optimization to avoid double buffering gateway responses
  • #1837 查询 SystemFunctions:添加了日期/时间系统函数#1837 Query SystemFunctions : Adds DateTime System Functions
  • #1842 查询性能:添加了单一实例 QueryPartitionProvider。#1842 Query Performance: Adds Singleton QueryPartitionProvider. 在重新创建容器时提供帮助。Helps when Container is getting recreated.
  • #1857 性能:在一些位置添加了终结器优化(向 pentp 致谢)#1857 Performance: Adds finalizer optimizations in a few places (Thanks to pentp)
  • #1843 性能:添加了 Transport 序列化、SessionTokenMismatchRetryPolicy 和存储响应字典优化#1843 Performance: Adds Transport serialization, SessionTokenMismatchRetryPolicy, and store response dictionary optimizations

固定Fixed

  • #1757 Batch API:修复大小限制以减少超时#1757 Batch API: Fixes the size limit to reduce timeouts
  • #1758 连接性:修复使用 EnableTcpConnectionEndpointRediscovery 时的地址解析调用#1758 Connectivity: Fixes address resolution calls when using EnableTcpConnectionEndpointRediscovery
  • #1788 暂时性 HTTP 异常:将重试逻辑添加到所有 http 请求#1788 Transient HTTP exceptions: Adds retry logic to all http requests
  • #1863 HttpClientHandler:修复了 HttpClientHandler PlatformNotSupportedException#1863 HttpClientHandler: Fixes HttpClientHandler PlatformNotSupportedException

3.13.0-preview - 2020-08-123.13.0-preview - 2020-08-12

已添加Added

  • #1725 ChangeFeed:添加 ChangeFeedStartFrom 以支持 StartTimes x FeedRanges。#1725 ChangeFeed : Adds ChangeFeedStartFrom to support StartTimes x FeedRanges. 警告:对于预览版 SDK 而言,这是一个中断性变更WARNING: This is breaking change for preview SDK
  • #1764 性能:添加编译器优化标志#1764 Performance: Adds compiler optimize flag
  • #1768 SessionToken:通过删除存储过程、触发器和 UDF 上用于 CRUD 的会话令牌,添加优化以减小标头大小#1768 SessionToken: Adds optimization to reduce header size by removing session token for CRUD on stored procedure, triggers, and UDFs

固定Fixed

  • #1757 Batch API:修复大小限制以减少超时#1757 Batch API: Fixes the size limit to reduce timeouts
  • #1758 连接性:修复使用 EnableTcpConnectionEndpointRediscovery 时的地址解析调用#1758 Connectivity: Fixes address resolution calls when using EnableTcpConnectionEndpointRediscovery

3.12.0 - 2020-08-063.12.0 - 2020-08-06

已添加Added

  • #1548 传输:添加优化以统一所有网关类的 HttpClient 使用#1548 Transport: Adds an optimization to unify HttpClient usage across Gateway classes
  • #1569 Batch API:为“事务批处理”添加请求选项支持#1569 Batch API: Adds support of request options for transactional batch
  • #1693 性能:减少 GlobalAddress 冲突解决程序上的锁争用#1693 Performance: Reduces lock contention on GlobalAddress Resolver
  • #1712 性能:添加优化以减少 AuthorizationHelper 内存分配#1712 Performance: Adds optimization to reduce AuthorizationHelper memory allocations
  • #1715 可用性:针对暂时性连接问题添加跨区域重试机制#1715 Availability: Adds cross-region retry mechanism on transient connectivity issues
  • #1721 LINQ:添加对不区分大小写的搜索的支持(通过 jeffpardy)#1721 LINQ : Adds support for case-insensitive searches (Thanks to jeffpardy)
  • #1733 更改源处理器:添加租用存储的后向兼容性#1733 Change Feed Processor: Adds backward compatibility of lease store

固定Fixed

  • #1720 网关跟踪:修复将 ActivityId 设置为 Guid.Empty 的 bug#1720 Gateway Trace: Fixes a bug where the ActivityId is being set to Guid.Empty
  • #1728 诊断:通过将 ActivityScope 移动到操作级别来修复它#1728 Diagnostics: Fixes ActivityScope by moving it to operation level
  • #1740 连接限制:修复 .NET core 以遵循网关连接限制#1740 Connection limits: Fixes .NET core to honor gateway connection limit
  • #1744 传输:修复 PortReuseMode 和其他直接配置设置的使用问题#1744 Transport: Fixes use of PortReuseMode and other Direct configuration settings

3.11.1-preview - 2020-10-013.11.1-preview - 2020-10-01

  • #1892 性能:通过减少 HashSet 锁争用,修复了由 EnableTcpConnectionEndpointRediscovery 导致的 CPU 利用率过高的问题#1892 Performance: Fixes High CPU caused by EnableTcpConnectionEndpointRediscovery by reducing HashSet lock contention

3.11.0 - 2020-07-073.11.0 - 2020-07-07

3.11.0-preview - 2020-07-073.11.0-preview - 2020-07-07

已添加Added

  • #1587 & 1643 & 1667 诊断:向所有请求添加了同步上下文跟踪#1587 & 1643 & 1667 Diagnostics: Adds synchronization context tracing to all request
  • #1617 性能:修复了对象模型层次结构,以将字符串用于相对路径而不是 URI#1617 Performance: Fixes Object Model hierarchy to use strings for relative paths instead of URI
  • #1639 CosmosClient:添加了针对空键的参数检查,以防止出现不明确的“401 未经授权”异常#1639 CosmosClient: Adds argument check for empty key to prevent ambiguous 401 not authorized exception
  • #1640 批量操作:向批量操作添加了 TimerWheel 以改进延迟#1640 Bulk: Adds TimerWheel to Bulk to improve latency
  • #1678 自动缩放:添加到容器生成器#1678 Autoscale: Adds to container builder

已修复Fixed

  • #1638 文档:修复了所有示例:为 FeedIterator 添加 using 语句#1638 Documentation : Fixes all examples to add using statement to FeedIterator
  • #1666 CosmosOperationCanceledException:修复了处理程序,可以捕获所有“操作已取消”异常#1666 CosmosOperationCanceledException: Fixes handler to catch all operation cancelled exceptions
  • #1682 性能:修复了 EnableTcpConnectionEndpointRediscovery 导致的 CPU 使用率过高问题#1682 Performance: Fixes high CPU consumption caused by EnableTcpConnectionEndpointRediscovery

3.10.1 - 2020-06-183.10.1 - 2020-06-18

  • #1637 TransportHandler:删除了堆栈跟踪输出。#1637 TransportHandler : Removes stack trace print. 已在 3.10.0 PR 1587 中引入Introduced in 3.10.0 PR 1587

3.10.0 - 2020-06-183.10.0 - 2020-06-18

已添加Added

  • #1613 查询 FeedIterator:添加了 IDisposable 来修复内存泄漏。#1613 Query FeedIterator: Adds IDisposable to fix memory leak. 警告:这将需要进行更改以修复用于检查处置的静态分析工具。WARNING: This will require changes to fix static anlysis tools checking for dispose.
  • #1550 CosmosOperationCanceledException:这使用户能够访问通过取消标记取消操作时的诊断。#1550 CosmosOperationCanceledException: This enables users to access the diagnsotics when an operation is canceled via the cancellation token. 新类型扩展了 OperationCanceledException,因此它没有破坏当前的异常处理,并且在 ToString() 中包括了 CosmosDiagnostic。The new type extends OperationCanceledException so it does not break current exception handling and includes the CosmosDiagnostic in the ToString().
  • #1578 查询:添加了内存优化以防止复制缓冲区#1578 Query: Adds memory optimization to prevent coping the buffer
  • #1578 查询:添加了支持来忽略 ContainsStartsWith 函数的案例。#1578 Query: Adds support for ignore case for Contains and StartsWith functions.
  • #1602 诊断:向所有操作添加了 CPU 使用率#1602 Diagnostics: Adds CPU usage to all operations
  • #1603 文档:添加了新的异常处理文档#1603 Documentation: Adds new exception handling documentation

固定Fixed

  • #1530 ContainerDefinition:修复了 WithDefaultTimeToLive 参数拼写(感谢 tony-xia)#1530 ContainerDefinition : Fixes WithDefaultTimeToLive argument spelling (Thanks to tony-xia)
  • #1547 & #1582 查询和 Readfeed:修复了由于未正确处理拆分而导致的异常#1547 & #1582 Query and Readfeed: Fix exceptions caused by not properly handling splits
  • #1578 ApplicationRegion:修复了 ApplicationRegion 以确保故障转移方案使用正确的顺序#1578 ApplicationRegion: Fixes ApplicationRegion to ensure the correct order is being used for failover scenarios
  • #1585 查询:使用 QueryExecutionInfo 响应头修复了 Multi- ORDER BY 继续标记支持#1585 Query : Fixes Multi- ORDER BY continuation token support with QueryExecutionInfo response headers

3.9.1 - 2020-05-193.9.1 - 2020-05-19

3.9.1-preview - 2020-05-193.9.1-preview - 2020-05-19

已修复Fixed

  • #1539 CosmosException 和诊断:修复了 ToString(),使其不因重试而呈指数增长。#1539 CosmosException and Diagnostics: Fixes ToString() to not grow exponentially with retries. 通过 PR #1189 在 3.7.0 中引入。Introduced in 3.7.0 in PR #1189.

3.9.0 - 2020-05-183.9.0 - 2020-05-18

已添加Added

  • #1356 & #1407 & #1428 & #1407 添加了自动缩放支持。#1356 & #1407 & #1428 & #1407 Adds autoscale support.
  • #1398 诊断:针对 .NET Core 添加了 CPU 监视。#1398 Diagnostics: Adds CPU monitoring for .NET Core.
  • #1441 传输:在 CosmosClientOptions 上添加了 HttpClientFactory 支持。#1441 Transport: Adds HttpClientFactory support on CosmosClientOptions.
  • #1457 容器:向容器添加了数据库引用。#1457 Container: Adds database reference to the container.
  • #1455 序列化程序:向 Client.ClientOptions.Serializer 添加了 SDK 序列化程序。#1455 Serializer: Adds SDK serializer to Client.ClientOptions.Serializer.
  • #1397 CosmosClientBuilder:添加了首选区域和 WithConnectionModeDirect()#1397 CosmosClientBuilder: Adds preferred regions and WithConnectionModeDirect().
  • #1439 响应中无内容:增加了让操作不从 Azure Cosmos DB 返回内容的功能。#1439 No content on Response: Adds the ability to have operations return no content from Azure Cosmos DB.
  • #1398 & #1516 读取源和更改源:增加了序列化优化,使内存和 CPU 使用率降低高达 90%。#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 查询:增加了序列化优化,使内存使用率降低高达 50%,使 CPU 使用率降低高达 25%。#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.Container 时在包含 SynchronizationContext 的场景中出现的死锁。#1401 & #1437: Response type: Fix deadlock on scenarios with SynchronizationContext when using Response.Container.
  • #1445 传输:修复了 WebAssemblyServicePoint#1445 Transport: Fix ServicePoint for WebAssembly.
  • #1462 UserAgent:修复了功能使用情况跟踪。#1462 UserAgent: Fix feature usage tracking.
  • #1469 诊断:修复了 InvalidOperationException 并将运行时间转换为毫秒。#1469 Diagnostics: Fix InvalidOperationException and converts elapsed time to millisecond.
  • #1512 PartitionRoutingHelper:修复了由于容器缓存未命中而导致的 ReadFeed ArgumentNullException#1512 PartitionRoutingHelper: Fix ReadFeed ArgumentNullException due to container cache miss.
  • #1530 CosmosClientBuilder:修复了 WithDefaultTimeToLive 参数拼写。#1530 CosmosClientBuilder: Fix WithDefaultTimeToLive parameter spelling.

3.9.0-preview3 - 2020-05-113.9.0-preview3 - 2020-05-11

已添加Added

  • #1356 & #1407 & #1428 自动缩放预览版。#1356 & #1407 & #1428 Autoscale preview release.
  • #1407 自动缩放:添加了 CreateDatabaseIfNotExistsAsyncCreateContainerIfNotExistsAsync 方法。#1407 Autoscale: Adds CreateDatabaseIfNotExistsAsync and CreateContainerIfNotExistsAsync methods.
  • #1410 FeedRange:添加了 Json 序列化支持。#1410 FeedRange: Adds Json serialization support.
  • #1398 诊断:针对 .NET Core 添加了 CPU 监视。#1398 Diagnostics: Adds CPU monitoring for .NET Core.
  • #1441 传输:在 CosmosClientOptions 上添加了 HttpClientFactory 支持。#1441 Transport: Adds HttpClientFactory support on CosmosClientOptions.
  • #1457 容器:向容器添加了数据库引用。#1457 Container: Adds database reference to the container.
  • #1453 响应工厂:向公共 API 添加了一个响应工厂。#1453 Response factory: Adds a response factory to the public API.
  • #1455 序列化程序:向 Client.ClientOptions.Serializer 添加了 SDK 序列化程序。#1455 Serializer: Adds SDK serializer to Client.ClientOptions.Serializer.
  • #1397 CosmosClientBuilder:添加了首选区域和公共内部函数 WithConnectionModeDirect()#1397 CosmosClientBuilder: Adds preferred regions and public internal func WithConnectionModeDirect().
  • #1439 响应中无内容:增加了让操作不从 Azure Cosmos DB 返回内容的功能。#1439 No content on response: Adds the ability to have operation return no content from Azure Cosmos DB.
  • #1469 诊断:修复了 InvalidOperationException 并将运行时间转换为毫秒。#1469 Diagnostics: Fixes the InvalidOperationException and converts elapsed time to millisecond.

已修复Fixed

  • #1398 降低了查询反序列化的内存分配。#1398 Reduced memory allocations on query deserialization.
  • #1401 & #1437:响应类型:修复了使用 Response.Container 时在包含 SynchronizationContext 的场景中出现的死锁。#1401 & #1437: Response type: Fixes deadlock on scenarios with SynchronizationContext when using Response.Container.
  • #1445 传输:修复了 WebAssembly 的 ServicePoint#1445 Transport: Fixes ServicePoint for WebAssembly.
  • #1462 UserAgent:修复了功能使用情况跟踪。#1462 UserAgent: Fixes feature usage tracking.

3.9.0-preview - 2020-04-173.9.0-preview - 2020-04-17

已添加Added

  • #1356 自动缩放:已添加到公共预览版#1356 Autoscale: Adds to public preview release

3.8.0-preview - 2020-04-163.8.0-preview - 2020-04-16

已添加Added

  • #1331 为事务性批处理请求启用了客户端加密/解密#1331 Enabled client encryption / decryption for transactional batch requests

已修复Fixed

  • #1369 修复了“order by”查询结果的解密#1369 Fixes decryption for 'order by' query results

3.8.0 - 2020-04-073.8.0 - 2020-04-07

已添加Added

  • #1314 添加了用于主动 TCP 连接端检测的配置。#1314 Adds configuration for proactive TCP end-of-connection detection.
  • #1305 添加了对首选区域自定义的支持。#1305 Adds support for preferred region customization.

固定Fixed

  • #1312 修复了使用 default(PartitionKey) 时的空引用。#1312 Fixes null reference when using default(PartitionKey).
  • #1296 在返回查询结果之前解密已加密的属性。#1296 Decrypts the encrypted properties before returning query result.
  • #1345 修复了获取查询计划诊断。#1345 Fixes get query plan diagnostics.

3.7.1-preview - 2020-03-303.7.1-preview - 2020-03-30

  • #1210 添加了更改源拉取模型。#1210 Adds change feed pull model.
  • #1242 客户端加密 - 修复了不含已加密属性的读取路径中的 bug。#1242 Client encryption - fixes bug in read path without encrypted properties.
  • #1314 添加了用于主动 TCP 连接端检测的配置。#1314 Adds configuration for proactive TCP end-of-connection detection.
  • #1312 修复了使用 default(PartitionKey) 时的空引用。#1312 Fixes null reference when using default(PartitionKey).
  • #1296 在返回查询结果之前解密已加密的属性。#1296 Decrypts the encrypted properties before returning query result.

3.7.0 - 2020-03-263.7.0 - 2020-03-26

已添加Added

  • #1268CosmosDiagnostics 添加了 GetElapsedClientLatency#1268 Adds GetElapsedClientLatency to CosmosDiagnostics.
  • #1239 使 MultiPolygonPolygonCoordinates 类成为公共类。#1239 Made MultiPolygon and PolygonCoordinates classes public.
  • #1233 分区键现在支持使用运算符 ==, != 进行等式比较。#1233 Partition key now supports operators ==, != for equality comparison.
  • #1285 向诊断添加了查询计划检索。#1285 Add query plan retrieval to diagnostics.
  • #1289 查询 ORDER BY 恢复优化。#1289 Query ORDER BY resume optimization.
  • #1074 批量操作 API 拥塞控制。#1074 Bulk API congestion control.

固定Fixed

  • #1213 CosmosException 现在返回原始堆栈跟踪。#1213 CosmosException now returns the original stack trace.
  • #1213 ResponseMessage.ErrorMessage 现在始终会正确进行填充。#1213 ResponseMessage.ErrorMessage is now always correctly populated. 过去存在一个 bug,在某些场景下,错误消息会留在内容流中。There was bug in some scenarios where the error message was left in the content stream.
  • #1298 CosmosException.Message 包含与 CosmosException.ToString() 相同的信息以确保跟踪所有信息。#1298 CosmosException.Message contains the same information as CosmosException.ToString() to ensure all the information is being tracked.
  • #1242 客户端加密 - 修复了不含已加密属性的读取路径中的 bug。#1242 Client encryption - Fixes bug in read path without encrypted properties.
  • #1189 查询诊断显示正确的总体时间。#1189 Query diagnostics shows correct overall time.
  • #1189 修复了在诊断上下文中导致重复信息的一个 bug。#1189 Fixes a bug that caused duplicate information in diagnostic context.
  • #1263 修复了以下 bug:未在查询流响应上设置间隔后重试。#1263 Fixes a bug where retry after interval did not get set on query stream responses.
  • #1198 修复了调用已处理的 CosmosClient 时出现的空引用异常。#1198 Fixes null reference exception when calling a disposed CosmosClient.
  • #1274 调用引用已处理客户端的所有 SDK 对象(例如数据库和容器)时引发 ObjectDisposedException#1274 ObjectDisposedException is thrown when calling all SDK objects like Database and Container that reference a disposed client.
  • #1268 修复了 Database.ReadStreamAsyncDatabase.DeleteStreamAsync 方法的请求选项丢失的 bug。#1268 Fixes bug where Request Options was getting lost for Database.ReadStreamAsync and Database.DeleteStreamAsync methods.
  • #1304 修复了 XML 文档,使其现在可在 Visual Studio 中显示。#1304 Fixes XML documentation so it now is visible in Visual Studio.

3.7.0-preview2 - 2020-03-093.7.0-preview2 - 2020-03-09

  • #1210 更改源拉取模型。#1210 Change feed pull model.
  • #1242 客户端加密 - 修复了不含已加密属性的读取路径中的 bug。#1242 Client encryption - fixes bug in read path without encrypted properties.

3.7.0-preview - 2020-02-253.7.0-preview - 2020-02-25

  • #1074 批量操作 API 拥塞控制。#1074 Bulk API congestion control.
  • #1210 更改源拉取模型。#1210 Change feed pull model.

3.6.0 - 2020-01-233.6.0 - 2020-01-23

  • #1105 CosmosClient 不变性 + 可处理项修复#1105 CosmosClient Immutability + Disposable Fixes

已添加Added

  • #1097ContainerProperties 添加了 GeospatialConfig,向 SpatialPath 添加了 BoundingBoxProperties#1097 GeospatialConfig to ContainerProperties, BoundingBoxProperties to SpatialPath.
  • #1061ExecuteStoredProcedureStreamAsync 添加了流有效负载。#1061 Stream payload to ExecuteStoredProcedureStreamAsync.
  • #1062 添加了更多诊断信息,包括通过不同的 SDK 层跟踪时间的功能。#1062 Additional diagnostic information including the ability to track time through the different SDK layers.
  • #1107 源链接支持。#1107 Source Link support.
  • #1121 StandByFeedIterator 广度优先读取策略。#1121 StandByFeedIterator breath-first read strategy.

固定Fixed

  • #1105 自定义序列化程序不再调用 SDK 拥有的会导致序列化异常的类型。#1105 Custom serializer no longer calls SDK owned types that would cause serialization exceptions.
  • #1112 修复了 DatabaseProperties 之类的 SDK 属性,使其具有相同的 JSON 特性。#1112 Fixes SDK properties like DatabaseProperties to have the same JSON attributes.
  • #1116 修复了执行异步查询操作时在包含 SynchronizationContext 的场景中出现的死锁。#1116 Fixes a deadlock on scenarios with SynchronizationContext while executing async query operations.
  • #1143 修复了通过资源令牌针对特定分区键执行查询时出现的权限资源链接和授权问题。#1143 Fixes permission resource link and authorization issue when doing a query with resource token for a specific partition key.
  • #1150 修复了使用不存在的租赁容器时的 NullReferenceException#1150 Fixes NullReferenceException when using a non-existent Lease Container.

3.5.1 - 2019-12-113.5.1 - 2019-12-11

已修复Fixed

  • #1060 修复了 DISTINCT 查询中的 Unicode 编码 bug。#1060 Fixes unicode encoding bug in DISTINCT queries.
  • #1070 在重新创建集合的情况下,CreateItem 将仅针对自动提取的分区键进行重试。#1070 CreateItem will only retry for auto-extracted partition key in-case of collection re-creation.
  • #1075 针对具有大型标头的错误请求包括了标头大小详细信息。#1075 Including header size details for bad request with large headers.
  • #1078 修复了执行异步 SDK API 时在包含 SynchronizationContext 的场景中出现的死锁。#1078 Fixes a deadlock on scenarios with SynchronizationContext while executing async SDK API.
  • #1081 修复了序列化程序中由空引用异常导致的争用条件。#1081 Fixes race condition in serializer caused by null reference exception.
  • #1086 修复了 TransactionalBatch 代码路径上可能的 NullReferenceException#1086 Fix possible NullReferenceException on a TransactionalBatch code path.
  • #1091 修复了进行分区拆分时查询中会引发 NotImplementedException 的一个 bug。#1091 Fixes a bug in query when a partition split occurs that causes a NotImplementedException to be thrown.
  • #1089 修复了在不使用分区键的情况下对项目使用批量操作时的 NullReferenceException#1089 Fixes a NullReferenceException when using Bulk with items without partition key.

3.5.0 - 2019-12-033.5.0 - 2019-12-03

已添加Added

  • #979 使 QueryRequestOptions 上的 SessionToken 成为公共的。#979 Make SessionToken on QueryRequestOptions public.
  • #995 在诊断中包括了会话令牌。#995 Included session token in diagnostics.
  • #1000CosmosClientOptions 添加了 PortReuseMode#1000 Adds PortReuseMode to CosmosClientOptions.
  • #1017 向网关调用添加了 ClientSideRequestStatistics 并使结束时间可为空。#1017 Adds ClientSideRequestStatistics to gateway calls and making end time nullable.
  • #1038 向资源属性添加了自链接。#1038 Adds self-link to resource properties.

已修复Fixed

  • #921 修复了在某些情况下保留堆栈跟踪所需的错误处理。#921 Fixes error handling to preserve stack trace in certain scenarios.
  • #944 对于内部操作,更改源处理器不使用用户序列化程序。#944 Change feed processor won't use user serializer for internal operations.
  • #988 修复了由于重试用完/名称缓存过时而导致的查询变异。#988 Fixes query mutating due to retry of gone / name cache is stale.
  • #954 在多主帐户中,支持对更改源处理器使用“从头开始”功能。#954 Support start from beginning for change feed processor in multi master accounts.
  • #999 修复了抓取额外页面的问题,更新了异常路径上的继续标记,并修复了 order by 继续标记中的非 ASCII 字符。#999 Fixes grabbing extra page, updated continuation token on exception path, and non-Ascii character in order by continuation token.
  • #1013 网关 OperationCanceledExceptions 现在作为请求超时返回。#1013 Gateway OperationCanceledExceptions are now returned as request timeouts.
  • #1020 直接更新包会删除 debug 语句。#1020 Direct package update removes debug statements.
  • #1023 修复了 ThroughputResponse.IsReplacePending 标头映射。#1023 Fixes ThroughputResponse.IsReplacePending header mapping.
  • #1036 修复了查询响应,以在失败时返回 null 内容。#1036 Fixes query responses to return null Content if it is a failure.
  • #1045CosmosException 添加了堆栈跟踪和内部异常。#1045 Adds stack trace and inner exception to CosmosException.
  • #1050TransactionalBatchOperationResult 添加了模拟构造函数。#1050 Adds mocking constructors to TransactionalBatchOperationResult.

3.4.1 - 2019-11-063.4.1 - 2019-11-06

已修复Fixed

  • #978 修复了针对 FeedIterator 和响应类的模拟。#978 Fixes mocking for FeedIterator and response classes.

3.4.0 - 2019-11-043.4.0 - 2019-11-04

已添加Added

  • #853 ORDER BY 数组和对象支持。#853 ORDER BY arrays and object support.
  • #877 查询诊断现在包含客户端请求诊断信息。#877 Query diagnostics now contains client-side request diagnostics information.
  • #923 批量操作支持现在为公共版。#923 Bulk support is now public.
  • #922 在用户代理中包括了批量操作支持使用情况信息。#922 Included information of bulk support usage in user agent.
  • #934GROUP BY 查询中保留了投影的顺序。#934 Preserved the ordering of projections in a GROUP BY query.
  • #952 ORDER BY 未定义和混合类型 ORDER BY 支持。#952 ORDER BY undefined and mixed type ORDER BY support.
  • #965 Batch API 现在为公共版。#965 Batch API is now public.

固定Fixed

  • #901 修复了导致查询响应为每个内容调用创建新流的一个 bug。#901 Fixes a bug causing query response to create a new stream for each content call.
  • #918 修复了用于与脚本、权限和冲突相关的迭代器的序列化程序。#918 Fixes serializer being used for scripts, permissions, and conflict-related iterators.
  • #936 修复了包含大型资源的批量请求以使异常自然化。#936 Fixes bulk requests with large resources to have natural exception.

3.3.3 - 2019-10-303.3.3 - 2019-10-30

  • #837 修复了非 Windows 平台的分组依据 bug。#837 Fixes group by bug for non-Windows platforms.
  • #927 修复了返回部分结果而非错误的查询。#927 Fixes query returning partial results instead of error.

3.3.2 - 2019-10-163.3.2 - 2019-10-16

已修复Fixed

  • #905 修复了 LINQ 驼峰式大小写 bug。#905 Fixes lINQ camel case bug.

3.3.1 - 2019-10-113.3.1 - 2019-10-11

已修复Fixed

  • #895 修复了在非 Windows 平台上导致格式异常的用户代理 bug。#895 Fixes user agent bug that caused format exceptions on non-Windows platforms.

3.3.0 - 2019-10-093.3.0 - 2019-10-09

已添加Added

  • #801 启用了 OrderBy 后的 LINQ ThenBy 运算符。#801 Enabled LINQ ThenBy operator after OrderBy.
  • #814 仅限使用已配置终结点的功能。#814 Ability to limit to configured endpoint only.
  • #822 GROUP BY 查询支持。#822 GROUP BY query support.
  • #844 向容器生成器添加了 PartitionKeyDefinitionVersion#844 Adds PartitionKeyDefinitionVersion to container builder.

固定Fixed

  • #835 修复了导致排序后范围异常的一个 bug。#835 Fixes a bug that caused sorted ranges exceptions.
  • #846 统计信息在 CosmosException 中未正确填充。#846 Statistics not getting populated correctly on CosmosException.
  • #857 修复了批量操作支持在容器实例之间的可重用性。#857 Fixes reusability of the bulk support across container instances.
  • #860 修复了基础用户代理字符串。#860 Fixes base user agent string.
  • #876 默认连接超时从 60 秒减少到 10 秒。#876 Default connection time out reduced from 60 s to 10 s.

3.2.0 - 2019-09-173.2.0 - 2019-09-17

已添加Added

  • #100CosmosClientOptions 添加了可配置的 Tcp 设置。#100 Configurable Tcp settings to CosmosClientOptions.
  • #615#775 向响应添加了请求诊断。#615, #775 Adds request diagnostics to response.
  • #622 添加了针对用户和权限的 CRUD 和查询操作,这启用了 ResourceToken 支持。#622 Adds CRUD and query operations for users and permissions, which enables ResourceToken support.
  • #716 添加了在 LINQ 查询生成时会启用的驼峰式大小写序列化。#716 Added camel case serialization on LINQ query generation.
  • #729#776 针对 LINQ 查询添加了 aggregate(CountAsync/SumAsync 等)扩展。#729, #776 Adds aggregate (CountAsync/SumAsync etc.) extensions for LINQ query.
  • #743CosmosClientOptions 添加了 WebProxy#743 Adds WebProxy to CosmosClientOptions.

固定Fixed

  • #726 当遇到异常时,查询迭代器 HasMoreResults 现在返回 false。#726 Query iterator HasMoreResults now returns false if an exception is hit.
  • #705 用户代理后缀被截断。#705 User agent suffix gets truncated.
  • #753 冲突异常的原因未传播。#753 Reason was not being propagated for conflict exceptions.
  • #756WithStartTime 的更改源处理器在第一次执行委托时将不使用任何项。#756 Change feed processor with WithStartTime would execute the delegate the first time with no items.
  • #761 当使用自定义任务计划程序(例如 Orleans)时,CosmosClient 发生死锁。#761 CosmosClient deadlocks when using a custom task scheduler like Orleans.
  • #769 会话一致性和网关模式会话-令牌 bug 修复 - 几个罕见的非成功案例会话令牌可能不正确。#769 Session consistency and gateway mode session-token bug fix- under few rare non-success cases session token might be in-correct.
  • #772 修复了在使用自定义序列化程序的情况下或产品/服务不存在的情况下引发的吞吐量异常。#772 Fixes throughput throwing when custom serializer used or offer doesn't exists.
  • #785 错误的键引发状态代码为 HttpStatusCode.UnauthorizedCosmosExceptions#785 Incorrect key to throw CosmosExceptions with HttpStatusCode.Unauthorized status code.

3.2.0-preview2 - 2019-09-103.2.0-preview2 - 2019-09-10

  • #585#741 批量操作执行支持。#585, #741 Bulk execution support.
  • #427 事务性批处理支持(项 CRUD)。#427 Transactional batch support (Item CRUD).

3.2.0-preview - 2019-08-093.2.0-preview - 2019-08-09

  • #427 事务性批处理支持(项 CRUD)。#427 Transactional batch support (Item CRUD).

3.1.1 - 2019-08-123.1.1 - 2019-08-12

已添加Added

  • #650 添加了 CosmosSerializerOptions 以自定义序列化。#650 CosmosSerializerOptions to customize serialization.

固定Fixed

  • #612 修复了具有分区键的 ReadFeed 的 bug。#612 Bug fix for ReadFeed with partition key.
  • #614 修复了空间路径序列化以及与较旧索引版本的兼容性。#614 Fixes spatial path serialization and compatibility with older index versions.
  • #619 修复了 .NET Framework 的 PInvokeStackImbalance 异常。#619 Fixes PInvokeStackImbalance exception for .NET framework.
  • #626 对于成功的情况,FeedResponse<T> 状态代码现在返回 OK 而非无效的状态代码 0 或 Accepted。#626 FeedResponse<T> status codes now return OK for success instead of the invalid status code 0 or Accepted.
  • #629 修复了 CreateContainerIfNotExistsAsync 验证,使其仅限于分区键路径。#629 Fixes CreateContainerIfNotExistsAsync validation to limited to partition key path only.
  • #630 修复了用户代理以包含环境和包信息。#630 Fixes user agent to contain environment and package information.

3.1.0 - 2019-07-29 - 未列出3.1.0 - 2019-07-29 - Unlisted

已添加Added

  • #541 向客户端和查询选项添加了一致性级别。#541 Adds consistency level to client and query options.
  • #544 为 LINQ 添加了继续标记支持。#544 Adds continuation token support for LINQ.
  • #557 向项请求选项添加了触发器选项。#557 Adds trigger options to item request options.
  • #572CreateContainerIfNotExistsAsync 上添加了分区键验证。#572 Adds partition key validation on CreateContainerIfNotExistsAsync.
  • #581QueryDefinition API 添加了 LINQ。#581 Adds LINQ to QueryDefinition API.
  • #592 向容器生成器添加了 CreateIfNotExistsAsync#592 Adds CreateIfNotExistsAsync to container builder.
  • #597ResponseMessage 添加了继续标记属性。#597 Adds continuation token property to ResponseMessage.
  • #604 添加了 LINQ ToStreamIterator 扩展方法。#604 Adds LINQ ToStreamIterator extension method.

固定Fixed

  • #548 修复了 CosmosException.ToString() 中错误键入的消息。#548 Fixes mis-typed message in CosmosException.ToString().
  • #558 修复了位置缓存 ConcurrentDict 锁争用。#558 Location cache ConcurrentDict lock contentions fix.
  • #561 GetItemLinqQueryable 现在可以处理 null 查询。#561 GetItemLinqQueryable now works with null query.
  • #567 查询可以正确处理不同的语言区域性。#567 Query correctly handles different language cultures.
  • #574 修复了查询分析因意外异常而失败时的空错误消息。#574 Fixes empty error message if query parsing fails from unexpected exception.
  • #576 查询将输入正确地序列化为流。#576 Query correctly serializes the input into a stream.

3.0.0 - 2019-07-153.0.0 - 2019-07-15

  • .NET SDK 版本 3.0.0 正式发布。General availability of Version 3.0.0 of the .NET SDK.
  • 适用于 .NET Standard 2.0,此版本支持 .NET Framework 4.6.1+ 和 .NET Core 2.0+。Targets .NET Standard 2.0, which supports .NET framework 4.6.1+ and .NET Core 2.0+.
  • 新对象模型,顶级的 CosmosClient 和方法在相关的数据库和容器类之间进行拆分。New object model, with top level CosmosClient and methods split across relevant database and container classes.
  • 具有高性能的新流 API。New stream APIs that have high performance.
  • 对更改源处理器 API 提供了内置支持。Built-in support for change feed processor APIs.
  • 适用于 CosmosClient、容器和更改源处理器的 Fluent 生成器 API。Fluent builder APIs for CosmosClient, container, and change feed processor.
  • 惯用的吞吐量管理 API。Idiomatic throughput management APIs.
  • 适用于数据库、容器、项、查询和吞吐量请求的粒度化 RequestOptionsResponseTypesGranular 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

Azure 会在停用 SDK 时至少提前 12 个月发出通知,以便用户顺利转换为更高版本/受支持版本。Azure provides notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version. 新特性和功能以及优化仅添加到当前 SDK,因此建议始终尽早升级到最新的 SDK 版本。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.

2022 年 8 月 31 日 之后,Azure Cosmos DB 将不再进行 bug 修复,不再添加新功能,也不再支持 1.x 版的 Azure Cosmos DB .NET 或 .NET Core SDK for SQL API。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. 如果你不想升级,则从 1.x 版 SDK 发送的请求将继续由 Azure Cosmos DB 服务处理。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.03.6.0 2020 年 1 月 23 日January 23, 2020 ---
3.5.13.5.1 2019 年 12 月 11 日December 11, 2019 ---
3.5.03.5.0 2019 年 12 月 3 日December 03, 2019 ---
3.4.13.4.1 2019 年 11 月 6 日November 06, 2019 ---
3.4.03.4.0 2019 年 11 月 4 日November 04, 2019 ---
3.3.33.3.3 2019 年 10 月 30 日October 30, 2019 ---
3.3.23.3.2 2019 年 10 月 16 日October 16, 2019 ---
3.3.13.3.1 2019 年 11 月 8 日October 11, 2019 ---
3.3.03.3.0 2019 年 10 月 8 日October 8, 2019 ---
3.2.03.2.0 2019 年 9 月 18 日September 18, 2019 ---
3.1.13.1.1 2019 年 8 月 12 日August 12, 2019 ---
3.1.03.1.0 2019 年 7 月 29 日July 29, 2019 ---
3.0.03.0.0 2019 年 7 月 15 日July 15, 2019 ---

常见问题FAQ

1.如何向客户通知即将停用的 SDK?1. How will customers be notified of the retiring SDK?

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知,以便协助平稳地转换到支持的 SDK。Azure 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. 此外,会通过各种通信渠道(Azure 管理门户、开发人员中心、博客文章以及与分配的服务管理员的直接通信)来通知客户。Further, customers will be notified through various communication channels - Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2.在这 12 个月期间,客户是否可以使用“即将”停用的 Azure Cosmos DB SDK 来创作应用程序?2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

可以,客户在 12 个月宽限期内具有完全访问权限,可以使用“即将”停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。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. 在 12 个月宽限期内,建议客户根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3.在 12 个月通知期之后,客户是否可以使用已停用的 Azure Cosmos DB SDK 创建和修改应用程序?3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

在 12 个月通知期之后,SDK 会停用。After the 12 month notification period, the SDK will be retired. Azure Cosmos DB 平台不允许使用已停用 SDK 的应用程序对 Azure Cosmos DB 进行任何访问。Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. 此外,Azure 不会对已停用的 SDK 提供客户支持。Further, Azure will not provide customer support on the retired SDK.

4.如果客户运行使用不支持的 Azure Cosmos DB SDK 版本的应用程序,会发生什么情况?4. What happens to Customer's running applications that are using unsupported Azure Cosmos DB SDK version?

任何使用已停用 SDK 版本连接 Azure Cosmos DB 服务的尝试都会被拒绝。Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5.新特性和功能是否会适用于所有未停用的 SDK?5. Will new features and functionality be applied to all non-retired SDKs?

新特性和功能只添加到新版本。New features and functionality will only be added to new versions. 如果使用的是未停用的旧版本 SDK,则对 Azure Cosmos DB 进行的请求仍会与以前一样正常工作,但是你无法访问任何新功能。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.如果无法在截止日期之前更新应用程序,该怎么办?6. What should I do if I cannot update my application before a cut-off date?

我们建议尽早升级到最新 SDK。We recommend that you upgrade to the latest SDK as early as possible. SDK 标记为要停用之后,会有 12 个月来更新应用程序。Once an SDK has been tagged for retirement you will have 12 months to update your application. 如果由于任何原因而无法在此时间范围内完成应用程序更新,请在截止日期之前与 Cosmos DB 团队联系并请求其帮助。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

若要了解有关 Cosmos DB 的详细信息,请参阅 Azure Cosmos DB 服务页。To learn more about Cosmos DB, see Azure Cosmos DB service page.