通过

迁移应用程序以使用 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 应用程序升级到适用于 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，则可以使用本文档中提供的信息：

  • Azure Cosmos DB .NET 框架 v1 SDK 用于 NoSQL 的 API
  • Azure Cosmos DB .NET Core SDK v1 用于 NoSQL 的 API

.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 批量执行程序库 发行说明。

后续步骤

  • Last updated on