迁移应用程序以使用 Azure Cosmos DB .NET SDK v2Migrate your application to use the Azure Cosmos DB .NET SDK v2

重要

请务必注意,.NET SDK 的 v3 当前可用,此处提供了从 v2 到 v3 的迁移计划。It is important to note that the v3 of the .NET SDK is currently available and a migration plan from v2 to v3 is available here. 若要了解 Azure Cosmos DB .NET SDK v2,请参阅发行说明.NET GitHub 存储库、.NET SDK v2 性能提示故障排除指南To learn about the Azure Cosmos DB .NET SDK v2, see the Release notes, the .NET GitHub repository, .NET SDK v2 Performance Tips, and the Troubleshooting guide.

本文重点介绍将现有 v1 .NET 应用程序升级到适用于 Core (SQL) API 的 Azure Cosmos DB .NET SDK v2 时的一些注意事项。This article highlights some of the considerations to upgrade your existing v1 .NET application to Azure Cosmos DB .NET SDK v2 for Core (SQL) API. Azure Cosmos DB .NET SDK v2 对应于 Microsoft.Azure.DocumentDB 命名空间。Azure Cosmos DB .NET SDK v2 corresponds to the Microsoft.Azure.DocumentDB namespace. 如果要从以下任何 Azure Cosmos DB .NET 平台迁移应用程序以使用 v2 SDK Microsoft.Azure.Cosmos,则可以使用本文档中提供的信息:You can use the information provided in this document if you are migrating your application from any of the following Azure Cosmos DB .NET Platforms to use the v2 SDK Microsoft.Azure.Cosmos:

  • 适用于 SQL API 的 Azure Cosmos DB .NET Framework v1 SDKAzure Cosmos DB .NET Framework v1 SDK for SQL API
  • 适用于 SQL API 的 Azure Cosmos DB .NET Core SDK v1Azure Cosmos DB .NET Core SDK v1 for SQL API

.NET v2 SDK 中提供了哪些功能What's available in the .NET v2 SDK

v2 SDK 包含许多可用性和性能改进,包括:The v2 SDK contains many usability and performance improvements, including:

  • 为非 Windows 客户端提供对 TCP 直接模式的支持Support for TCP direct mode for non-Windows clients
  • 多区域写入支持Multi-region write support
  • 查询性能改进Improvements on query performance
  • 支持地理空间/几何集合和索引编制Support for geospatial/geometry collections and indexing
  • 增加了对直接/TCP 传输诊断的改进Increased improvements for direct/TCP transport diagnostics
  • 直接 TCP 传输堆栈更新,以减少建立的连接数Updates on direct TCP transport stack to reduce the number of connections established
  • 关于 RequestTimeout 中延迟减少的改进Improvements in latency reduction in the RequestTimeout

大多数重试逻辑和较低级别的 SDK 基本保持不变。Most of the retry logic and lower levels of the SDK remains largely unchanged.

为何要迁移到 .NET v2 SDKWhy migrate to the .NET v2 SDK

除了大量的性能改进之外,最新 SDK 中的新功能投资将不会反向移植到较旧版本。In addition to the numerous performance improvements, new feature investments made in the latest SDK will not be back ported to older versions.

此外,较旧的 SDK 将被较新的版本取代,而 v1 SDK 将进入维护模式Additionally, the older SDKs will be replaced by newer versions and the v1 SDK will go into maintenance mode. 为了获得最佳的开发体验,建议将应用程序迁移到更高版本的 SDK。For the best development experience, we recommend migrating your application to a later version of the SDK.

从 v1 SDK 到 v2 SDK 的重大更改Major changes from v1 SDK to v2 SDK

直接模式 + TCPDirect mode + TCP

.NET v2 SDK 现在支持直接模式和网关模式。The .NET v2 SDK now supports both direct and gateway mode. 直接模式支持通过 TCP 协议进行连接并提供更佳的性能,因为它直接连接到后端副本,且网络跃点较少。Direct mode supports connectivity through TCP protocol and offers better performance as it connects directly to the backend replicas with fewer network hops.

有关更多详细信息,请仔细阅读 Azure Cosmos DB SQL SDK 连接模式指南For more details, read through the Azure Cosmos DB SQL SDK connectivity modes guide.

会话令牌格式Session token formatting

v2 SDK 不再使用 v1 中所使用的简单会话令牌格式,改为使用向量格式 。The v2 SDK no longer uses the simple session token format as used in v1, instead the SDK uses vector formatting. 由于格式不可互换,在传递给具有不同版本的客户端应用程序时应转换格式。The format should be converted when passing to the client application with different versions, since the formats are not interchangeable.

有关详细信息,请参阅 .NET SDK 中的转换会话令牌格式For more information, see converting session token formats in the .NET SDK.

使用 .NET 更改源处理器 SDKUsing the .NET change feed processor SDK

.NET 更改源处理器库 2.1.x 需要 Microsoft.Azure.DocumentDB 2.0 或更高版本。The .NET change feed processor library 2.1.x requires Microsoft.Azure.DocumentDB 2.0 or later.

2.1.x 库具有以下主要更改:The 2.1.x library has the following key changes:

  • 稳定性和诊断改进Stability and diagnosability improvements
  • 改进了对错误和异常的处理Improved handling of errors and exceptions
  • 对分区租用集合的其他支持Additional support for partitioned lease collections
  • 用于实现 ChangeFeedDocument 接口和类的高级扩展,适用于其他错误处理和跟踪Advanced extensions to implement the ChangeFeedDocument interface and class for additional error handling and tracing
  • 添加了对使用自定义存储来持久存储每个分区的延续令牌的支持Added support for using a custom store to persist continuation tokens per partition

有关详细信息,请参阅更改源处理器库发行说明For more information, see the change feed processor library release notes.

使用批量执行工具库Using the bulk executor library

v2 批量执行工具库当前对 Azure Cosmos DB .NET SDK 2.5.1 或更高版本具有依赖项。The v2 bulk executor library currently has a dependency on the Azure Cosmos DB .NET SDK 2.5.1 or later.

有关详细信息,请参阅 Azure Cosmos DB 批量执行工具库概述和 .NET 批量执行工具库发行说明For more information, see the Azure Cosmos DB bulk executor library overview and the .NET bulk executor library release notes.

后续步骤Next steps