通过

迁移应用程序以使用 Azure Cosmos DB .NET SDK v2

适用范围： NoSQL

重要

请务必注意，.NET SDK 的 v3 当前可用，此处提供了从 v2 到 v3 的迁移计划。 若要了解 Azure Cosmos DB .NET SDK v2，请参阅发行说明、.NET GitHub 存储库、.NET SDK v2 性能提示和故障排除指南。

本文重点介绍将现有 v1 .NET 应用程序升级到适用于 API for NoSQL 的 Azure Cosmos DB .NET SDK v2 时的一些注意事项。 Azure Cosmos DB .NET SDK v2 对应于 Microsoft.Azure.DocumentDB 命名空间。 如果要从以下任何 Azure Cosmos DB .NET 平台迁移应用程序以使用 v2 SDK Microsoft.Azure.Cosmos，则可以使用本文档中提供的信息：

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

.NET v2 SDK 中提供了哪些功能

v2 SDK 包含许多可用性和性能改进，包括：

  • 为非 Windows 客户端提供对 TCP 直接模式的支持
  • 多区域写入支持
  • 查询性能改进
  • 支持地理空间/几何集合和索引编制
  • 增加了对直接/TCP 传输诊断的改进
  • 直接 TCP 传输堆栈更新，以减少建立的连接数
  • 关于 RequestTimeout 中延迟减少的改进

大多数重试逻辑和较低级别的 SDK 基本保持不变。

为何要迁移到 .NET v2 SDK

除了大量性能改进之外，在最新 SDK 中所做的新功能投资不会移植到旧版本。

此外，较旧的 SDK 将被较新的版本取代，而 v1 SDK 将进入维护模式。 为了获得最佳的开发体验，建议将应用程序迁移到更高版本的 SDK。

从 v1 SDK 到 v2 SDK 的重大更改

直接模式 + TCP

.NET v2 SDK 现在支持直接模式和网关模式。 直接模式支持通过 TCP 协议进行连接并提供更佳的性能，因为它直接连接到后端副本，且网络跃点较少。

有关更多详细信息，请仔细阅读 Azure Cosmos DB SQL SDK 连接模式指南。

会话令牌格式

v2 SDK 不再使用 v1 中所使用的简单会话令牌格式，改为使用向量格式 。 由于格式不可互换，在传递给具有不同版本的客户端应用程序时应转换格式。

有关详细信息，请参阅 .NET SDK 中的转换会话令牌格式。

使用 .NET 更改源处理器 SDK

.NET 更改源处理器库 2.1.x 需要 Microsoft.Azure.DocumentDB 2.0 或更高版本。

2\.1.x 库具有以下主要更改：

  • 稳定性和诊断改进
  • 改进了对错误和异常的处理
  • 对分区租用集合的其他支持
  • 用于实现 ChangeFeedDocument 接口和类的高级扩展，以增强额外的错误处理和跟踪功能
  • 添加了对使用自定义存储来持久存储每个分区的延续令牌的支持

有关详细信息，请参阅更改源处理器库发行说明。

使用批量执行工具库

v2 批量执行工具库当前对 Azure Cosmos DB .NET SDK 2.5.1 或更高版本具有依赖项。

有关详细信息，请参阅 Azure Cosmos DB 批量执行工具库概述和 .NET 批量执行工具库发行说明。

后续步骤