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

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
当前受支持的框架Current supported framework Microsoft .NET Framework 4.5Microsoft .NET Framework 4.5

发行说明Release notes


如果使用的是 .NET Framework,请参阅面向 .NET Standard 的 .NET SDK 最新版本 3.x。If you are using .NET Framework, please see the latest version 3.x of the .NET SDK, which targets .NET Standard.

以下 .NET SDK 子版本可在 2.x.x 版本下使用:The following sub versions of .NET SDKs are available under the 2.x.x version:

  • 修复了问题:对存储过程、触发器和用户定义的函数执行 CRUD 操作时发生“请求标头太长”的错误Fixes "request headers is too long" for CRUD operations on stored procedures, triggers, and user defined functions

  • 改进了对查询操作期间区域故障转移情况的检测。Improved detection of regional failover scenarios during query operations.
  • 提高了暂时性 ReadSessionNotAvailable 情形时的复原能力。Improved resiliency during transient ReadSessionNotAvailable scenarios.

  • 修复连接策略中的 PortReuseMode 设置,使 DocumentClient 遵循该设置。Fix PortReuseMode setting in connection policy to be honored by DocumentClient.

  • 为连接到特定区域时发生暂时性连接问题的请求添加了跨区域重试机制。Added a cross-region retry mechanism for requests with transient connectivity issues to a particular region. 此重试机制使用(且需要)用户定义的 ConnectionPolicy.PreferredLocations 首选项列表。This retry mechanism uses (and requires) the user's defined ConnectionPolicy.PreferredLocations preference list.
  • 已将诊断信息添加到操作取消的异常。Added diagnostics information to operation canceled exceptions.

  • 修复查询 FeedOption 中的用户会话令牌,以实现请求级别的会话一致性Fix user session token in query FeedOption for request level session consistency

  • 修复与 ConnectionPolicy.EnableTcpConnectionEndpointRediscovery 的使用相关的 CPU 问题Fix CPU issues related to usage of ConnectionPolicy.EnableTcpConnectionEndpointRediscovery
  • 修复 PartitionKey 在 GROUP BY 查询上未正确传递的问题Fix PartitionKey not being correctly passed on GROUP BY queries
  • 通过添加 Task.Yeild 来修复重试方案中潜在的 StackOverflowException。Fix possible StackOverflowException in retry scenario by adding Task.Yeild. .NET Core 3 的相关修复Related fix for .NET Core 3

  • 将 RequestDiagnosticsString 属性添加到 StoredProcedureResponseAdd RequestDiagnosticsString property to the StoredProcedureResponse
  • 进行修复以提高应用于 ConnectionPolicy.SetCurrentLocation 的启发式方法的准确性Fix to improve the accurancy of heuristics applied to ConnectionPolicy.SetCurrentLocation
  • 在 .NET Core 上使用“直接 + TCP”模式时出现的连接错误现在包括 CPU 使用历史记录。Connectivity errors on .NET core using Direct + TCP mode now includes CPU usage history.

  • 修复了在已关闭的连接的边缘情况下 TCP 连接关闭引发的套接字异常Fix socket exception thrown from TCP connection closure under edge cases for closed connection

  • 修复了执行查询时的空引用异常。Fix null reference exceptions when doing a query. 此修补程序修复了当未找到 Microsoft.Azure.Documents.ServiceInterop.dll 时回退逻辑中的 bug。This is fixes a bug in the fallback logic when the Microsoft.Azure.Documents.ServiceInterop.dll is not found.

  • 添加了对创建几何图形集合的支持Add support for creating geometry collections
  • 添加了为几何空间索引指定边界框的支持Add support to specify bounding box for geometry spatial index
  • 已将 EnableTcpConnectionEndpointRediscovery 添加到 ConnectionPolicy 中,该策略可根据连接关闭通知使地址无效Add EnableTcpConnectionEndpointRediscovery to ConnectionPolicy which enables invalidation of addresses based upon connection close notifications
  • 修复了聚合查询 RuntimeBinderException“无法转换类型”Fixed aggregate query RuntimeBinderException 'Cannot convert type'
  • 修复了权限序列化以包括令牌Fixed permission serialization to include the Token
  • 改进了针对“SDK 无法连接到特定终结点并收到 HttpException”的暂时性区域故障的重试逻辑。Improve retry logic for transient region failures where the SDK cannot connect to a specific endpoint and gets HttpException.
  • 通过将默认 RequestTimeout 从 60 秒减少到 10 秒来降低延迟Improve latency by reducing default RequestTimeout from 60 seconds to 10 seconds

  • 修复了分区键不适用于非 Windows x64 客户端的问题Fixed partition key not being honored for non windows x64 clients

  • 修复了直接 TCP 模式下的计时器池泄漏Fixed timer pool leak in Direct TCP mode
  • 修复了文档中断开的链接Fixed broken links in documentation
  • 过大的标头现在可跟踪标头大小Too large of header now traces the header sizes
  • 通过在获取查询计划调用中排除会话令牌减小了标头大小Reduced header size by excluding session token in get query plan calls

  • 修复了 order by 继续标记中的非 ASCII 字符Fixed non ascii character in order by continuation token

  • 修复了 Microsoft.Azure.Documents.ServiceInterop.dll 正常回退 bug 问题 #750Fix Microsoft.Azure.Documents.ServiceInterop.dll graceful fallback bug Issue #750

  • 添加了对 GROUP BY 查询的支持Add support for GROUP BY queries
  • 查询现在在执行之前会检索查询计划,以确保单分区查询和跨分区查询之间的行为一致。Query now retrieves query plan before execution in order to ensure consistent behavior between single partition and cross partition queries.

  • 已将 RequestDiagnosticsString 添加到 FeedResponseAdded RequestDiagnosticsString to FeedResponse
  • 修复了更新插入和替换文档的序列化设置Fixed serialization settings for upsert and replace document

  • 在 order by 查询中添加了对数组和对象的支持Added support for arrays and objects in order by queries
  • 处理了有效的分区键冲突Handle effective partition key collisions
  • 使用 ThenBy 运算符添加了对多个 OrderBy 运算符的 LINQ 支持Added LINQ support for multiple OrderBy operators with ThenBy operator
  • 修复了 AysncCache 死锁问题,以便它可以使用单线程任务计划程序Fixed AysncCache deadlock issue so that it will work with a single-threaded task scheduler

  • 已将 PortReusePolicy 添加到 ConnectionPolicyAdded PortReusePolicy to ConnectionPolicy
  • 修复了在 UWP 应用中使用 SDK 时出现的 ntdll!RtlGetVersion TypeLoadException 问题Fixed ntdll!RtlGetVersion TypeLoadException issue when SDK is used in a UWP app

  • SDK 的 System.Net.Http 版本现在与 NuGet 包中定义的版本匹配SDK's System.Net.Http version now matches what is defined in the NuGet package
  • 允许写入请求回退到不同的区域(如果原始区域发生故障)Allow write requests to fallback to a different region if the original one fails
  • 为写入请求添加了会话重试策略Add session retry policy for write request

  • 已使程序集版本和文件版本与 nuget 包版本相同。Made assembly version and file version same as nuget package version.

  • 针对导致空页的查询修复了跟踪争用条件Fixes tracing race condition for queries which caused empty pages

  • 增加了 LINQ 查询的十进制精度大小。Increased decimal precision size for LINQ queries.
  • 添加了 CompositePath、CompositePathSortOrder、SpatialSpec、SpatialType 和 PartitionKeyDefinitionVersion 这几种新类Added new classes CompositePath, CompositePathSortOrder, SpatialSpec, SpatialType and PartitionKeyDefinitionVersion
  • 已将 TimeToLivePropertyPath 添加到 DocumentCollectionAdded TimeToLivePropertyPath to DocumentCollection
  • 已将 CompositeIndexes 和 SpatialIndexes 添加到 IndexPolicyAdded CompositeIndexes and SpatialIndexes to IndexPolicy
  • 已将 Version 添加到 PartitionKeyDefinitionAdded Version to PartitionKeyDefinition
  • 已将 None 添加到 PartitionKeyAdded None to PartitionKey
  • 修复了 bug 以正确处理会导致 JsonReaderException 的非 JSON 有效负载Fix a bug to properly handle non-JSON payload that would cause JsonReaderException

  • 已将 IdleTcpConnectionTimeout、OpenTcpConnectionTimeout、MaxRequestsPerTcpConnection 和 MaxTcpConnectionsPerEndpoint 添加到 ConnectionPolicy。Added IdleTcpConnectionTimeout, OpenTcpConnectionTimeout, MaxRequestsPerTcpConnection and MaxTcpConnectionsPerEndpoint to ConnectionPolicy.

  • 诊断改进Diagnostics improvements

  • 添加了环境变量设置“POCOSerializationOnly”。Added environment variable setting "POCOSerializationOnly".
  • 删除了 DocumentDB.Spatial.Sql.dll,现在在 Microsoft.Azure.Documents.ServiceInterop.dll 中包含Removed DocumentDB.Spatial.Sql.dll and now included in Microsoft.Azure.Documents.ServiceInterop.dll

  • 对 StoredProcedure 执行调用故障转移期间的重试逻辑进行了改进。Improvement in retry logic during failover for StoredProcedure execute calls.

  • 将 DocumentClientEventSource 设为单一实例。Made DocumentClientEventSource singleton.

  • 修复了 GatewayAddressCache 超时不遵守 ConnectionPolicy RequestTimeout 的问题。Fix GatewayAddressCache timeout not honoring ConnectionPolicy RequestTimeout.

  • 对于直接/TCP 传输诊断,添加了 TransportException,这是该 SDK 的一个内部异常类型。For direct/TCP transport diagnostics, added TransportException, an internal exception type of the SDK. 出现在异常消息中时,此类型会输出附加信息,以便排查客户端连接问题。When present in exception messages, this type prints additional information for troubleshooting client connectivity problems.

  • 添加了新的构造函数重载,它采用 HttpMessageHandler,后者是用于发送 HttpClient 请求的 HTTP 处理程序堆栈(例如,HttpClientHandler)。Added new constuctor overload which takes a HttpMessageHandler, a HTTP handler stack to use for sending HttpClient requests (e.g., HttpClientHandler).

  • 修复了无法正确处理带有空值的标头的 bug。Fix bug where header with null values were not being handled properly.

  • 改进了集合缓存验证。Improved collection cache validation.

  • 更新到 4.3.2 版 System.Net.Security。Updated System.Net.Security to 4.3.2.

  • 诊断跟踪改进。Diagnostic tracing improvements.

  • 为多区域请求暂时性故障添加了更多复原能力。Added more resilience to Multi-region request transient failures.

  • 添加了多区域写入支持。Added Multi-region write support.
  • 使用 TOP 改进了跨分区查询性能。Cross partition query performance improvements with TOP.
  • 修复了不遵守 MaxBufferedItemCount 导致内存不足问题的 bug。Fixed bug where MaxBufferedItemCount was not being honored causing out of memory issues.

  • 添加了请求取消支持。Added request cancellation support.
  • 将 SetCurrentLocation 添加到 ConnectionPolicy,它会根据区域自动填充首选位置。Added SetCurrentLocation to ConnectionPolicy, which automatically populates the preferred locations based on the region.
  • 修复了具有 Min/Max 以及在单个分区上没有文档匹配的筛选的跨分区查询中的 Bug。Fixed Bug in Cross Partition Queries with Min/Max and a filter that matches no documents on an individual partition.
  • DocumentClient 方法现在与 IDocumentClient 具有奇偶校验。DocumentClient methods now have parity with IDocumentClient.
  • 更新了直接 TCP 传输堆栈以减少建立的连接数。Updated direct TCP transport stack to reduce the number of connections established.
  • 为非 Windows 客户端添加了对 Direct Mode TCP 的支持。Added support for Direct Mode TCP for non-Windows clients.


  • 添加了请求取消支持。Added request cancellation support.
  • 将 SetCurrentLocation 添加到 ConnectionPolicy,它会根据区域自动填充首选位置。Added SetCurrentLocation to ConnectionPolicy, which automatically populates the preferred locations based on the region.
  • 修复了具有 Min/Max 以及在单个分区上没有文档匹配的筛选的跨分区查询中的 Bug。Fixed Bug in Cross Partition Queries with Min/Max and a filter that matches no documents on an individual partition.


  • DocumentClient 方法现在与 IDocumentClient 具有奇偶校验。DocumentClient methods now have parity with IDocumentClient.
  • 更新了直接 TCP 传输堆栈以减少建立的连接数。Updated direct TCP transport stack to reduce the number of connections established.
  • 为非 Windows 客户端添加了对 Direct Mode TCP 的支持。Added support for Direct Mode TCP for non-Windows clients.

  • 将 ConsistencyLevel 属性添加到了 FeedOptions。Added ConsistencyLevel Property to FeedOptions.
  • 将 JsonSerializerSettings 添加到了 RequestOptions 和 FeedOptions。Added JsonSerializerSettings to RequestOptions and FeedOptions.
  • 将 EnableReadRequestsFallback 添加到了 ConnectionPolicy。Added EnableReadRequestsFallback to ConnectionPolicy.

  • 修复了临界情况下跨分区 order by 查询出现的 KeyNotFoundException。Fixed KeyNotFoundException for cross partition order by queries in corner cases.
  • 修复了在 LINQ 查询的 select 子句中不接受 JsonPropery 属性的 bug。Fixed bug where JsonPropery attribute in select clause for LINQ queries was not being honored.

  • 修复了在某些争用情况下出现的 bug,该 bug 在使用会话一致性级别时导致间歇性错误“Microsoft.Azure.Documents.NotFoundException:读取会话不可用于输入会话令牌”。Fixed bug that is hit under certain race conditions, that results in intermittent "Microsoft.Azure.Documents.NotFoundException: The read session is not available for the input session token" errors when using Session consistency level.

  • 改进了在 FeedOptions 中将 MaxDegreeOfParallelism 属性设置为“-1”时的跨分区查询性能。Improved cross partition query performance when the MaxDegreeOfParallelism property is set to -1 in FeedOptions.
  • 向 QueryMetrics 添加了新的 ToString() 函数。Added a new ToString() function to QueryMetrics.
  • 公开了有关读取集合的分区统计信息。Exposed partition statistics on reading collections.
  • 向 ChangeFeedOptions 添加了 PartitionKey 属性。Added PartitionKey property to ChangeFeedOptions.
  • 小 bug 修复。Minor bug fixes.

  • 添加了通过使用 DocumentCollection 上的 UniqueKeyPolicy 属性来指定文档唯一索引的功能。Adds the ability to specify unique indexes for the documents by using UniqueKeyPolicy property on the DocumentCollection.
  • 修复了自定义 JsonSerializer 设置无法用于某些查询和存储过程执行的 bug。Fixed a bug in which the custom JsonSerializer settings were not being honored for some queries and stored procedure execution.

  • 在 API 参考文档、程序集中的元数据信息和 NuGet 包中品牌从 Azure DocumentDB 更改为 Azure Cosmos DB。Branding change from Azure DocumentDB to Azure Cosmos DB in the API Reference documentation, metadata information in assemblies, and the NuGet package.
  • 通过以直接连接模式发送的请求的响应公开诊断信息和延迟。Expose diagnostic information and latency from the response of requests sent with direct connectivity mode. 在 ResourceResponse 类中属性名称是 RequestDiagnosticsString 和 RequestLatency。The property names are RequestDiagnosticsString and RequestLatency on ResourceResponse class.
  • 此 SDK 版本需要最新版本的 Azure Cosmos DB 模拟器(可从 https://aka.ms/cosmosdb-emulator 下载)。This SDK version requires the latest version of Azure Cosmos DB Emulator available for download from https://aka.ms/cosmosdb-emulator.

  • 对 Azure 友元程序集进行了内部更改。Internal changes for Azure friends assemblies.

  • 添加了多项可靠性修复和改进。Added several reliability fixes and improvements.

  • 添加了 PartitionKeyRangeId 的支持作为 FeedOption,将查询结果限定在某个特定分区键范围值。Added support for PartitionKeyRangeId as a FeedOption for scoping query results to a specific partition key range value.
  • 添加了 StartTime 的支持作为 ChangeFeedOption,以开始查找该时间后的更改。Added support for StartTime as a ChangeFeedOption to start looking for the changes after that time.

  • 修复了 JsonSerializable 类中可能引起堆栈溢出异常的问题。Fixed an issue in the JsonSerializable class that may cause a stack overflow exception.

  • 修复了在因在 DocumentClient 构造函数中引入 JsonSerializerSettings 作为可选参数而需要重新编译的问题。Fixed an issue that required recompiling of the application due to the introduction of JsonSerializerSettings as an optional parameter in the DocumentClient constructor.
  • 将 DocumentClient 构造函数标记为已过时,需要 JsonSerializerSettings 作为最后一个参数,以在传入 JsonSerializerSettings 参数时允许 ConnectionPolicy 和 ConsistencyLevel 参数的默认值。Marked the DocumentClient constructor obsolete that required JsonSerializerSettings as the last parameter to allow for default values of ConnectionPolicy and ConsistencyLevel parameters when passing in JsonSerializerSettings parameter.

  • 添加了对在实例化 DocumentClient 时指定自定义 JsonSerializerSettings 的支持。Added support for specifying custom JsonSerializerSettings while instantiating DocumentClient.

  • 修复了影响 x64 计算机的一个问题,该计算机不支持 SSE4 指令,并在运行 Azure Cosmos DB DocumentDB API 查询时引发 SEHException。Fixed an issue that affected x64 machines that don't support SSE4 instruction and throw an SEHException when running Azure Cosmos DB DocumentDB API queries.

  • 添加了对每分钟请求单位数 (RU/m) 功能的支持。Added support for Request Unit per Minute (RU/m) feature.
  • 添加了对称为“ConsistentPrefix”的新一致性级别的支持。Added support for a new consistency level called ConsistentPrefix.
  • 添加了对查询单个分区的指标的支持。Added support for query metrics for individual partitions.
  • 添加了对限制查询的继续标记大小的支持。Added support for limiting the size of the continuation token for queries.
  • 添加了对失败请求的更详细跟踪的支持。Added support for more detailed tracing for failed requests.
  • 在 SDK 中进行了一些性能改进。Made some performance improvements in the SDK.

  • 与 1.13.3 功能相同。Functionally same as 1.13.3. 进行了一些内部更改。Made some internal changes.

  • 在功能上与 1.13.2 相同。Functionally same as 1.13.2. 进行了一些内部更改。Made some internal changes.

  • 修复了忽略 FeedOptions 中为聚合查询提供的 PartitionKey 值的问题。Fixed an issue that ignored the PartitionKey value provided in FeedOptions for aggregate queries.
  • 修复了在中途跨分区执行 OrderBy 查询期间透明处理分区管理的问题。Fixed an issue in transparent handling of partition management during mid-flight cross-partition Order By query execution.

  • 修复了在 ASP.NET 上下文内使用时,在某些异步 API 中导致死锁的问题。Fixed an issue which caused deadlocks in some of the async APIs when used inside ASP.NET context.

  • 修复程序,用于使 SDK 更具弹性,以便在某些情况下自动故障转移。Fixes to make SDK more resilient to automatic failover under certain conditions.

  • 修复了偶尔会导致“WebException:无法解析远程名称”的问题。Fix for an issue that occasionally causes a WebException: The remote name could not be resolved.
  • 通过向 ReadDocumentAsync API 添加新重载,添加了对直接读取类型化文档的支持。Added the support for directly reading a typed document by adding new overloads to ReadDocumentAsync API.

  • 添加了对聚合查询(COUNT、MIN、MAX、SUM 和 AVG)的 LINQ 支持。Added LINQ support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG).
  • 修复了由于使用了事件处理程序而导致的 ConnectionPolicy 对象的内存泄漏问题。Fix for a memory leak issue for the ConnectionPolicy object caused by the use of event handler.
  • 修复了使用 ETag 时 UpsertAttachmentAsync 不正常工作的问题。Fix for an issue wherein UpsertAttachmentAsync was not working when ETag was used.
  • 修复了对字符串字段进行排序时跨分区按查询条件排序不正常工作的问题。Fix for an issue wherein cross partition order-by query continuation was not working when sorting on string field.

  • 添加了对聚合查询(COUNT、MIN、MAX、SUM、AVG)的支持。Added support for aggregation queries (COUNT, MIN, MAX, SUM, and AVG). 请参阅聚合支持See Aggregation support.
  • 将分区集合上的最小吞吐量从 10,100 RU/s 降低到 2500 RU/s。Lowered minimum throughput on partitioned collections from 10,100 RU/s to 2500 RU/s.

  • 针对 32 位主机进程中某些分区查询的失败问题进行了修复。Fix for an issue wherein some of the cross-partition queries were failing in the 32-bit host process.
  • 修复了以下问题:网关模式下,会话容器中不更新失败请求的标记。Fix for an issue wherein the session container was not being updated with the token for failed requests in Gateway mode.
  • 修复了以下问题:投影中调用 UDF 的查询在某些情况下失败。Fix for an issue wherein a query with UDF calls in projection was failing in some cases.

  • 针对使用令牌更新会话容器的请求失败问题进行了修复。Fix for an issue wherein the session container was not being updated with the token for failed requests.
  • 添加了支持,使该 SDK 可用于 32 位主机进程。Added support for the SDK to work in a 32-bit host process. 请注意,如果使用跨分区查询,建议使用 64 位主机进程以提高性能。Note that if you use cross partition queries, 64-bit host processing is recommended for improved performance.
  • 改进了性能,可在 IN 表达式中使用大量分区键值进行查询。Improved performance for scenarios involving queries with a large number of partition key values in an IN expression.

  • 对 1.11.0 版本中引入的 CreateDocumentCollectionIfNotExistsAsync API 的轻微性能修复。Minor performance fix for the CreateDocumentCollectionIfNotExistsAsync API introduced in 1.11.0.
  • 性能修复,针对 SDK 中涉及高度并发请求的方案。Peformance fix in the SDK for scenarios that involve high degree of concurrent requests.

  • 支持新类和方法,可处理集合内的文档更改源Support for new classes and methods to process the change feed of documents within a collection.
  • 支持跨分区查询延续和跨分区查询的一些性能改进。Support for cross-partition query continuation and some perf improvements for cross-partition queries.
  • 添加 CreateDatabaseIfNotExistsAsync 和 CreateDocumentCollectionIfNotExistsAsync 方法。Addition of CreateDatabaseIfNotExistsAsync and CreateDocumentCollectionIfNotExistsAsync methods.
  • 针对以下系统函数提供了 LINQ 支持:IsDefined、IsNull 和 IsPrimitive。LINQ support for system functions: IsDefined, IsNull and IsPrimitive.
  • 修复的问题:在 Nuget 包与具有 project.json 工具的项目配合使用时,Microsoft.Azure.Documents.ServiceInterop.dll 和 DocumentDB.Spatial.Sql.dll 程序集自动 binplace 到应用程序的 bin 文件夹中。Fix for automatic binplacing of Microsoft.Azure.Documents.ServiceInterop.dll and DocumentDB.Spatial.Sql.dll assemblies to application's bin folder when using the Nuget package with projects that have project.json tooling.
  • 支持发出客户端侧 ETW 跟踪,这对调试方案很有用。Support for emitting client side ETW traces which could be helpful in debugging scenarios.

  • 添加已分区集合得直接连接支持。Added direct connectivity support for partitioned collections.
  • 改进了受限停滞一致性级别的性能。Improved performance for the Bounded Staleness consistency level.
  • 添加了转换谓词时对 StringEnumConverter、IsoDateTimeConverter 和 UnixDateTimeConverter 的 LINQ 支持。Added LINQ support for StringEnumConverter, IsoDateTimeConverter and UnixDateTimeConverter while translating predicates.
  • 各种 SDK bug 修复。Various SDK bug fixes.

  • 修复了导致以下 NotFoundException 的问题:读取会话不可用于输入会话令牌。Fixed an issue that caused the following NotFoundException: The read session is not available for the input session token. 在地理分散的帐户的读取区域查询时,在某些情况下会发生此异常。This exception occurred in some cases when querying for the read-region of a geo-distributed account.
  • 已公开 ResourceResponse 类中的 ResponseStream 属性,使用该属性可直接访问响应中的基础流。Exposed the ResponseStream property in the ResourceResponse class, which enables direct access to the underlying stream from a response.

  • 修改了 ResourceResponse、FeedResponse、StoredProcedureResponse 和 MediaResponse 类,以实现相应的公共接口,以便可以模拟它们进行测试驱动的部署 (TDD)。Modified the ResourceResponse, FeedResponse, StoredProcedureResponse and MediaResponse classes to implement the corresponding public interface so that they can be mocked for test driven deployment (TDD).
  • 解决了使用自定义 JsonSerializerSettings 对象序列化数据时导致格式错误的分区键标头的问题。Fixed an issue that caused a malformed partition key header when using a custom JsonSerializerSettings object for serializing data.

  • 修复了一个问题,该问题导致长时间运行的查询失败并显示以下错误:授权令牌当前无效。Fixed an issue that caused long running queries to fail with error: Authorization token is not valid at the current time.
  • 解决了从跨分区 top/order-by 查询中删除了原始 SqlParameterCollection 的问题。Fixed an issue that removed the original SqlParameterCollection from cross partition top/order-by queries.

  • 已对分区集合添加并行查询支持。Added support for parallel queries for partitioned collections.

  • 已对分区集合添加跨分区 ORDER BY 和 TOP 查询支持。Added support for cross partition ORDER BY and TOP queries for partitioned collections.

  • 已修复当使用对 DocumentDB Nuget 包的引用来引用 DocumentDB 项目时缺少所需的 DocumentDB.Spatial.Sql.dll 和 Microsoft.Azure.Documents.ServiceInterop.dll 引用的错误。Fixed the missing references to DocumentDB.Spatial.Sql.dll and Microsoft.Azure.Documents.ServiceInterop.dll that are required when referencing a DocumentDB project with a reference to the DocumentDB Nuget package.

  • 修复了在 LINQ 中使用用户定义的函数时无法使用不同类型的参数的错误。Fixed the ability to use parameters of different types when using user defined functions in LINQ.

  • 修复了多区域复制帐户的 bug,此 bug 会使 Upsert 调用定向至读取位置而非写入位置。Fixed a bug for multiple-regionally replicated accounts where Upsert calls were being directed to read locations instead of write locations.

  • 已将缺少的方法添加到了 IDocumentClient 接口:Added methods to the IDocumentClient interface that were missing:

    • 采用 mediaStream 和选项作为参数的 UpsertAttachmentAsync 方法。UpsertAttachmentAsync method that takes mediaStream and options as parameters.
    • 采用选项作为参数的 CreateAttachmentAsync 方法。CreateAttachmentAsync method that takes options as a parameter.
    • 采用 querySpec 作为参数的 CreateOfferQuery 方法。CreateOfferQuery method that takes querySpec as a parameter.
  • 已解封 IDocumentClient 接口中公开的公共类。Unsealed public classes that are exposed in the IDocumentClient interface.

  • 添加了对多区域数据库帐户的支持。Added the support for multi-region database accounts.
  • 添加了对限制请求重试的支持。用户可以通过配置 ConnectionPolicy.RetryOptions 属性来自定义重试次数和最长等待时间。Added support for retry on throttled requests.User can customize the number of retries and the max wait time by configuring the ConnectionPolicy.RetryOptions property.
  • 添加新的 IDocumentClient 接口,用于定义所有 DocumenClient 属性和方法的签名。Added a new IDocumentClient interface that defines the signatures of all DocumenClient properties and methods. 在做出此项更改的同时,已将用于创建 IQueryable 和 IOrderedQueryable 的扩展方法更改为 DocumentClient 类本身的方法。As part of this change, also changed extension methods that create IQueryable and IOrderedQueryable to methods on the DocumentClient class itself.
  • 添加了配置选项用于设置给定 DocumentDB 终结点 URI 的 ServicePoint.ConnectionLimit。Added configuration option to set the ServicePoint.ConnectionLimit for a given DocumentDB endpoint Uri. 使用 ConnectionPolicy.MaxConnectionLimit 可以更改默认值(设置为 50)。Use ConnectionPolicy.MaxConnectionLimit to change the default value, which is set to 50.
  • 已弃用 IPartitionResolver 及其实现。Deprecated IPartitionResolver and its implementation. 对 IPartitionResolver 的支持现已过时。Support for IPartitionResolver is now obsolete. 建议使用分区集合来提高存储和吞吐量。It's recommended that you use Partitioned Collections for higher storage and throughput.

  • 向采用 RequestOptions 作为参数的基于 Uri 的 ExecuteStoredProcedureAsync 方法添加了重载。Added an overload to Uri based ExecuteStoredProcedureAsync method that takes RequestOptions as a parameter.

  • 对文档添加了生存时间 (TTL) 支持。Added time to live (TTL) support for documents.

  • 修复了 .NET SDK 的 Nuget 打包(用于将其打包为 Azure 云服务解决方案的一部分)中的 bug。Fixed a bug in Nuget packaging of .NET SDK for packaging it as part of a Azure Cloud Service solution.

  • [已修复] 查询 DocumentDB 终结点时引发:“System.Net.Http.HttpRequestException:将内容复制到流时出错。[Fixed] Querying DocumentDB endpoint throws: 'System.Net.Http.HttpRequestException: Error while copying content to a stream.

  • 扩展的 LINQ 支持,包括用于分页、条件表达式和范围比较的新运算符。Expanded LINQ support including new operators for paging, conditional expressions and range comparison.

    • Take 运算符,用于在 LINQ 中启用 SELECT TOP 行为。Take operator to enable SELECT TOP behavior in LINQ.
    • CompareTo 运算符,用于启用字符串范围比较。CompareTo operator to enable string range comparisons.
    • 条件运算符 (?) 和 coalesce 运算符 (??)。Conditional (?) and coalesce operators (??).
  • [已修复] 合并模型投影与 linq 查询中的 Where-In 时出现 ArgumentOutOfRangeException。[Fixed] ArgumentOutOfRangeException when combining Model projection with Where-In in linq query. #81#81

  • [已修复] 如果 Select 不是最后一个表达式,则 LINQ 提供程序假定没有投影,并且错误地生成 SELECT *。[Fixed] If Select is not the last expression the LINQ Provider assumed no projection and produced SELECT * incorrectly. #58#58

  • 实现了 Upsert,添加了 UpsertXXXAsync 方法。Implemented Upsert, Added UpsertXXXAsync methods.
  • 针对所有请求进行了性能改进。Performance improvements for all requests.
  • LINQ 提供程序支持字符串的条件表达式、联合表达式和 CompareTo 方法。LINQ Provider support for conditional, coalesce and CompareTo methods for strings.
  • [已修复] LINQ 提供程序 --> 在列表上实现 Contains 方法以生成与 IEnumerable 和 Array 上相同的 SQL。[Fixed] LINQ provider --> Implement Contains method on List to generate the same SQL as on IEnumerable and Array.
  • [已修复] BackoffRetryUtility 再次使用相同的 HttpRequestMessage 而不是在重试时创建一个新的。[Fixed] BackoffRetryUtility uses the same HttpRequestMessage again instead of creating a new one on retry.
  • [已过时] UriFactory.CreateCollection --> 现在应使用 UriFactory.CreateDocumentCollection。[Obsolete] UriFactory.CreateCollection --> should now use UriFactory.CreateDocumentCollection.

  • [已修复] 使用非 en 区域性信息(如 nl-NL 等)时出现本地化问题。[Fixed] Localization issues when using non en culture info such as nl-NL etc.

  • 基于 ID 的路由ID Based Routing

    • 新增了用于协助构造基于 ID 的资源链接的 UriFactory 帮助程序。New UriFactory helper to assist with constructing ID based resource links.
    • 在 DocumentClient 上新增了重载以接受 URI。New overloads on DocumentClient to take in URI.
  • 在针对地理空间的 LINQ 中添加了 IsValid() 和 IsValidDetailed()。Added IsValid() and IsValidDetailed() in LINQ for geospatial.

  • 增强了 LINQ 提供程序支持。LINQ Provider support enhanced.

    • 数学 - Abs、Acos、Asin、Atan、Ceiling、Cos、Exp、Floor、Log、Log10、Pow、Round、Sign、Sin、Sqrt、Tan、Truncate。Math - Abs, Acos, Asin, Atan, Ceiling, Cos, Exp, Floor, Log, Log10, Pow, Round, Sign, Sin, Sqrt, Tan, Truncate.
    • 字符串 - Concat、Contains、EndsWith、IndexOf、Count、ToLower、TrimStart、Replace、Reverse、TrimEnd、StartsWith、SubString、ToUpper。String - Concat, Contains, EndsWith, IndexOf, Count, ToLower, TrimStart, Replace, Reverse, TrimEnd, StartsWith, SubString, ToUpper.
    • 数组 - Concat、Contains、Count。Array - Concat, Contains, Count.
    • IN 运算符。IN operator.

  • 现已开始支持修改索引策略。Added support for modifying indexing policies.

    • 在 DocumentClient 中新增了 ReplaceDocumentCollectionAsync 方法。New ReplaceDocumentCollectionAsync method in DocumentClient.
    • 在 ResourceResponse 中新增了 IndexTransformationProgress 属性,用于跟踪索引策略更改的百分比进度。New IndexTransformationProgress property in ResourceResponse for tracking percent progress of index policy changes.
    • DocumentCollection.IndexingPolicy 现在是可变的。DocumentCollection.IndexingPolicy is now mutable.
  • 添加了对空间索引和查询的支持Added support for spatial indexing and query

    • 新增了 Microsoft.Azure.Documents.Spatial 命名空间,用于序列化/反序列化 Point 和 Polygon 等空间类型。New Microsoft.Azure.Documents.Spatial namespace for serializing/deserializing spatial types like Point and Polygon.
    • 新增了 SpatialIndex 类,用于为存储在 DocumentDB 中的 GeoJSON 数据编制索引。New SpatialIndex class for indexing GeoJSON data stored in DocumentDB.
  • [已修复] :从 linq 表达式生成的不正确的 SQL 查询。[Fixed] : Incorrect SQL query generated from linq expression. #38#38

  • 对 Newtonsoft.Json v5.0.7 的依赖关系。Dependency on Newtonsoft.Json v5.0.7.

  • 更改为支持 Order By:Changes to support Order By:

    • LINQ 提供程序支持 OrderBy() 或 OrderByDescending()。LINQ provider support for OrderBy() or OrderByDescending().
    • 支持 Order By 的 IndexingPolicy。IndexingPolicy to support Order By.

    NB:可能推出的中断性变更NB: Possible breaking change

    如果现有代码使用自定义索引策略预配集合,那么现有代码将需要更新为支持新的 IndexingPolicy 类。If you have existing code that provisions collections with a custom indexing policy, then your existing code will need to be updated to support the new IndexingPolicy class. 如果没有任何自定义索引策略,此更改不会影响你。If you have no custom indexing policy, then this change does not affect you.

  • 通过使用新的 HashPartitionResolver 和 RangePartitionResolver 类以及 IPartitionResolver 来支持对数据进行分区。Support for partitioning data by using the new HashPartitionResolver and RangePartitionResolver classes and the IPartitionResolver.
  • DataContract 序列化。DataContract serialization.
  • LINQ 提供程序中的 Guid 支持。Guid support in LINQ provider.
  • LINQ 中的 UDF 支持。UDF support in LINQ.


发布和停用日期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 to 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 2020 年 7 月 30 日July 30, 2020 --- 2020 年 7 月 29 日July 29, 2020 --- 2020 年 7 月 14 日July 14, 2020 --- 2020 年 7 月 1 日July 1, 2020 --- 2019 年 11 月 15 日November 15, 2019 --- 2019 年 11 月 13 日November 13, 2019 --- 2019 年 10 月 30 日October 30, 2019 --- 2019 年 11 月 8 日October 11, 2019 --- 2019 年 9 月 23 日September 23, 2019 --- 2019 年 8 月 30 日August 30, 2019 --- 2019 年 7 月 2 日July 02, 2019 --- 2019 年 6 月 20 日June 20, 2019 --- 2019 年 5 月 5 日May 05, 2019 --- 2019 年 4 月 4 日April 04, 2019 --- 2019 年 2 月 11 日February 11, 2019 --- 2019 年 2 月 6 日February 06, 2019 --- 2018 年 12 月 24 日December 24, 2018 --- 2018 年 12 月 7 日December 07, 2018 --- 2018 年 10 月 15 日October 15, 2018 --- 2018 年 10 月 4 日October 04, 2018 --- 2018 年 9 月 27 日September 27, 2018 --- 2018 年 9 月 21 日September 21, 2018 --- 2018 年 9 月 7 日September 07, 2018 --- 2018 年 4 月 19 日April 19, 2018 2022 年 8 月 31 日August 31, 2022 2018 年 3 月 9 日March 09, 2018 2022 年 8 月 31 日August 31, 2022 2018 年 2 月 21 日February 21, 2018 2022 年 8 月 31 日August 31, 2022 2018 年 2 月 5 日February 05, 2018 2022 年 8 月 31 日August 31, 2022 2017 年 11 月 16 日November 16, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 11 月 10 日November 10, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 11 月 7 日November 07, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 10 月 17 日October 17, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 8 月 10 日August 10, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 8 月 7 日August 07, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 8 月 2 日August 02, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 6 月 30 日June 30, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 5 月 23 日May 23, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 5 月 10 日May 10, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 5 月 9 日May 09, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 5 月 6 日May 06, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 4 月 19 日April 19, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 3 月 29 日March 29, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 3 月 24 日March 24, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 3 月 14 日March 14, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 2 月 15 日February 15, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 2 月 6 日February 06, 2017 2022 年 8 月 31 日August 31, 2022 2017 年 1 月 26 日January 26, 2017 2022 年 8 月 31 日August 31, 2022 2016 年 12 月 21 日December 21, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 12 月 08 日December 08, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 9 月 27 日September 27, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 9 月 1 日September 01, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 8 月 24 日August 24, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 8 月 15 日August 15, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 7 月 23 日July 23, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 6 月 14 日June 14, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 5 月 6 日May 06, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 4 月 26 日April 26, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 4 月 8 日April 08, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 3 月 29 日March 29, 2016 2022 年 8 月 31 日August 31, 2022 2016 年 2 月 19 日February 19, 2016 2022 年 8 月 31 日August 31, 2022 2015 年 12 月 14 日December 14, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 11 月 23 日November 23, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 10 月 5 日October 05, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 8 月 25 日August 25, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 8 月 13 日August 13, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 8 月 5 日August 05, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 7 月 6 日July 06, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 4 月 30 日April 30, 2015 2022 年 8 月 31 日August 31, 2022 2015 年 4 月 8 日April 08, 2015 2022 年 8 月 31 日August 31, 2022


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.