.NET 更改源处理器 SDK:下载和发行说明

适用于: SQL API

链接
SDK 下载 NuGet
API 文档 更改源处理器库 API 参考文档
入门 更改源处理器 .NET SDK 入门
当前受支持的框架 Microsoft .NET Framework 4.5
Microsoft .NET Core

备注

如果使用的是更改源处理器,请参阅 .NET SDK 的最新版本 3.x,其中包含内置于 SDK 中的更改源。

发行说明

v2 版本

2.4.0

  • 添加了对租用集合的支持,这些租用集合可以使用定义为 /partitionKey 的分区键进行分区。 在此更改前,租约集合的分区键必须定义为 /id。
  • 此版本允许使用带有 Gremlin API 的租用集合,因为 Gremlin 集合无法将分区键定义为 /id。

2.3.2

  • 添加了与启用热迁移路径的 V3 SDK 的租用存储兼容性。 应用程序可以迁移到 V3 SDK 再迁移回更改源处理器库,而不会丢失任何状态。

2.3.1

  • 更正了将 FeedProcessing.ChangeFeedObserverCloseReason.Unknown 关闭原因发送到 FeedProcessing.IChangeFeedObserver.CloseAsync 时,如果找不到分区或者目标副本未随读取会话保持最新将发生的情况。 在这些情况下,现在使用 FeedProcessing.ChangeFeedObserverCloseReason.ResourceGoneFeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable 关闭原因。
  • 添加了新的关闭原因 FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable,当目标副本未随读取会话保持最新时,将发送此原因以关闭更改源观察程序。

2.3.0

  • 添加了新方法 ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory 和相应的公共接口 ICheckpointPartitionProcessorFactory。 这样可以实现 IPartitionProcessor 接口来使用内置检查点机制。 新工厂类似于现有 IPartitionProcessorFactory,只不过其 Create 方法也采用 ILeaseCheckpointer 参数。
  • 只有 ChangeFeedProcessorBuilder.WithPartitionProcessorFactoryChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory 方法中的一个可用于同一个 ChangeFeedProcessorBuilder 实例。

2.2.8

  • 稳定性和诊断改进:
    • 添加了对长时间检测读取更改源的支持。 所用时间比 ChangeFeedProcessorOptions.ChangeFeedTimeout 属性指定的值更长时,将执行以下步骤:
      • 将中止在有问题的分区上读取更改源的操作。
      • 更改源处理器实例将删除有问题的租约的所有权。 将在由相同或不同的更改源处理器实例完成的下次租约获取步骤期间选取已删除的租约。 这样便可以重新开始读取更改源。
      • 向运行状况监视器报告问题。 默认运行状况监视器将报告的所有问题发送到跟踪日志。
    • 添加了新的公共属性:ChangeFeedProcessorOptions.ChangeFeedTimeout。 此属性的默认值为 10 分钟。
    • 添加了新的公共枚举值:Monitoring.MonitoredOperation.ReadChangeFeed。 当 HealthMonitoringRecord.Operation 的值设置为 Monitoring.MonitoredOperation.ReadChangeFeed 时,表示运行状况问题与读取更改源相关。

2.2.7

  • 对于获取所有租约花费的时间超过租约过期间隔(例如由于网络问题)的情况,改进了负载均衡策略:
    • 在这种情况下,负载均衡算法过去常常将租约错误地视为过期,导致从活动所有者盗取租约。 这可能会导致对大量租约重新进行不必要的负载均衡。
    • 此问题在该版本中已通过以下方法修复,即避免在获取所有者未更改的过期租约发生冲突时进行重试,并将获取过期租约推迟到下次负载均衡迭代。

2.2.6

  • 改进了对观察者异常的处理。
  • 有关观察者错误的更丰富信息:
    • 当观察者由于观察者的 ProcessChangesAsync 抛出异常而关闭时,CloseAsync 现在将接收设置为 ChangeFeedObserverCloseReason.ObserverError 的 reason 参数。
    • 添加了跟踪以识别观察者的用户代码中的错误。

2.2.5

  • 添加了对使用共享数据库吞吐量的拆分集合的处理支持。
    • 此版本修复了使用共享数据库吞吐量的拆分集合可能发生的问题,即在拆分导致分区重新均衡时仅创建一个子分区键范围,而不是两个。 发生这种情况时,更改源处理器可能会在删除旧分区键范围的租约时卡住,而无法创建新租约。 此版本中已修复了此问题。

2.2.4

  • 添加了新属性 ChangeFeedProcessorOptions.StartContinuation 来支持从请求继续标记开始更改源。 只有当租约集合为空或者租约未设置 ContinuationToken 时才使用此属性。 对于租约集合中设置了 ContinuationToken 的租约,将使用 ContinuationToken 并忽略 ChangeFeedProcessorOptions.StartContinuation。

2.2.3

  • 增加了对使用自定义存储的支持,用以按分区持久保存继续标记。
    • 例如,自定义租约存储可以是以任何自定义方式分区的 Azure Cosmos DB 租约集合。
    • 自定义租约存储可以使用新的扩展点 ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) 和 ILeaseStoreManager 公共接口。
    • 将 ILeaseManager 接口重构到了多个角色接口中。
  • 次要重大更改:删除了扩展点 ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager),请改用 ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager)。

2.2.2

  • 此版本修复了在处理受监视集合中的拆分和使用已分区租约集合期间发生的一个问题。 在处理拆分分区的租约时,可能不会删除对应于该分区的租约。 此版本中已修复了此问题。

2.2.1

  • 修复了对具有多个写入区域和新会话令牌格式的帐户的估算器计算。

2.2.0

  • 添加了对已分区租用集合的支持。 分区键必须定义为 /id。
  • 次要重大更改:IChangeFeedDocumentClient 接口和 ChangeFeedDocumentClient 类的方法都已更改为包括 RequestOptions 和 CancellationToken 参数。 IChangeFeedDocumentClient 是一种高级的扩展点,通过该扩展点,可以提供文档客户端的自定义实现,以便与更改源处理器结合使用,例如,修饰 DocumentClient 并截获对它的所有调用以进行额外跟踪和错误处理等。利用此更新,实现 IChangeFeedDocumentClient 的代码将需要更改为在实现中包含新参数。
  • 次要诊断改进。

2.1.0

  • 添加了新的 API,Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync()。 此 API 可用于获取每个分区估算的工作量。
  • 支持 Microsoft.Azure.DocumentDB SDK 2.0。 需要 Microsoft.Azure.DocumentDB 2.0 或更高版本。

2.0.6

  • 添加了 ChangeFeedEventHost.HostName 公共属性以与 v1 兼容。

2.0.5

  • 修复了在分区拆分期间发生的争用条件。 争用条件可能导致获得租用后,在分区拆分期间立即失去该租用,从而引起争用。 此版本修复了争用条件问题。

2.0.4

  • GA SDK

2.0.3-prerelease

  • 修复了以下问题:

    • 拆分分区时,可能会重复处理拆分前修改的文档。
    • 如果租用集合中没有租用,GetEstimatedRemainingWork API 返回的是 0。
  • 以下异常已公开。 实现 IPartitionProcessor 的扩展可能会抛出这些异常。

    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.LeaseLostException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionNotFoundException.
    • Microsoft.Azure.Documents.ChangeFeedProcessor.Exceptions.PartitionSplitException.

2.0.2-prerelease

  • 小的 API 更改:
    • 删除了标记为过时的 ChangeFeedProcessorOptions.IsAutoCheckpointEnabled。

2.0.1-prerelease

  • 稳定性改进:
    • 更好地处理租用存储初始化。 当租用存储为空时,只有一个处理器实例可以对其进行初始化,其他处理器实例将等待。
    • 更稳定/有效租用续订/发行版。 续订和释放一个分区的租用独立于续订其他租用。 在 v1 中,这是针对所有分区按顺序完成的。
  • 新 v2 API:
    • 处理器的灵活构造生成器模式:ChangeFeedProcessorBuilder 类。
      • 可以采用参数的任何组合。
      • 可以采用用于监视的 DocumentClient 实例和/或租用集合(v1 中不可用)。
    • IChangeFeedObserver.ProcessChangesAsync 现在采用 CancellationToken。
    • IRemainingWorkEstimator - 剩余工作估计器可以与处理器分开使用。
    • 新的扩展点:
      • IPartitionLoadBalancingStrategy - 用于对处理器实例之间的分区进行自定义负载均衡。
      • ILease、ILeaseManager - 用于自定义租用管理。
      • IPartitionProcessor - 用于对分区进行自定义处理更改。
  • 日志记录 - 使用 LibLog 库。
  • 与 v1 API 100% 向后兼容。
  • 新建代码库。
  • 兼容 SQL .NET SDK 1.21.1 及更高版本。

v1 版本

1.3.3

  • 添加了更多日志记录。
  • 修复了多次调用待处理工作评估时出现的 DocumentClient 泄漏。

1.3.2

  • 修复了待处理工作评估。

1.3.1

  • 稳定性改进。
    • 修复了处理取消的任务问题,该问题可能导致某些分区上的观察者停止。
  • 支持手动检查点。
  • 兼容 SQL .NET SDK 1.21 及更高版本。

1.2.0

  • 增加了对 .NET Standard 2.0 的支持。 程序包现在支持 netstandard2.0net451 Framework 名字对象。
  • 兼容 SQL .NET SDK 1.17.0 及更高版本。
  • 兼容 SQL .NET Core SDK 1.5.1 及更高版本。

1.1.1

  • 修复了更改源为空或无任何工作挂起时计算剩余工作估计值时的一个问题。
  • 兼容 SQL .NET SDK 1.13.2 及更高版本。

1.1.0

  • 添加了一个获取更改源中剩余待处理工作估计值的方法。
  • 兼容 SQL .NET SDK 1.13.2 及更高版本。

1.0.0

发布和停用日期

Azure 会在停用 SDK 时至少提前 12 个月发出通知,以便用户顺利转换为更高版本/受支持版本。 新特性和功能以及优化仅添加到当前 SDK,因此建议始终尽早升级到最新的 SDK 版本。

警告

在 2022 年 8 月 31 日之后,Azure Cosmos DB 将不再进行 bug 修复,不再添加新功能,也不再支持 1.x 版的 Azure Cosmos DB .NET 或 .NET Core SDK for SQL API。 如果你不想升级,则从 1.x 版 SDK 发送的请求将继续由 Azure Cosmos DB 服务处理。


版本 发布日期 停用日期
2.4.0 2021 年 5 月 6 日 ---
2.3.2 2020 年 8 月 11 日 ---
2.3.1 2020 年 7 月 30 日 ---
2.3.0 2020 年 4 月 2 日 ---
2.2.8 2019 年 10 月 28 日 ---
2.2.7 2019 年 5 月 14 日 ---
2.2.6 2019 年 1 月 29 日 ---
2.2.5 2018 年 12 月 13 日 ---
2.2.4 2018 年 11 月 29 日 ---
2.2.3 2018 年 11 月 19 日 ---
2.2.2 2018 年 10 月 31 日 ---
2.2.1 2018 年 10 月 24 日 ---
1.3.3 2018 年 5 月 8 日 ---
1.3.2 2018 年 4 月 18 日 ---
1.3.1 2018 年 3 月 13 日 ---
1.2.0 2017 年 10 月 31 日 ---
1.1.1 2017 年 8 月 29 日 ---
1.1.0 2017 年 8 月 13 日 ---
1.0.0 2017 年 7 月 7 日 ---

常见问题解答

1.如何向客户通知即将停用的 SDK?

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知,以便协助平稳地转换到支持的 SDK。 此外,会通过各种通信渠道(Azure 管理门户、开发人员中心、博客文章以及与分配的服务管理员的直接通信)来通知客户。

2. 在这 12 个月期间,客户是否可以使用即将停用的 Azure Cosmos DB SDK 来创作应用程序?

可以,客户在 12 个月宽限期内具有完全访问权限,可以使用“即将”停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。 在 12 个月宽限期内,建议客户根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。

3. 在 12 个月通知期之后,客户是否可以使用已停用的 Azure Cosmos DB SDK 创作和修改应用程序?

在 12 个月通知期之后,SDK 将停用。 Azure Cosmos DB 平台不允许使用已停用 SDK 的应用程序对 Azure Cosmos DB 进行任何访问。 此外,Azure 不会对已停用的 SDK 提供客户支持。

4. 如果客户运行的应用程序使用不受支持的 Azure Cosmos DB SDK 版本,会发生什么情况?

任何使用已停用 SDK 版本连接 Azure Cosmos DB 服务的尝试都会被拒绝。

5. 新特性和功能是否会适用于所有未停用的 SDK?

新特性和功能只添加到新版本。 如果使用的是未停用的旧版本 SDK,则对 Azure Cosmos DB 进行的请求仍会与以前一样正常工作,但是你无法访问任何新功能。

6. 如果无法在截止日期之前更新应用程序,该怎么办?

我们建议尽早升级到最新 SDK。 SDK 标记为要停用之后,会有 12 个月来更新应用程序。 如果由于任何原因而无法在此时间范围内完成应用程序更新,请在截止日期之前与 Cosmos DB 团队联系并请求其帮助。

另请参阅

若要了解有关 Cosmos DB 的详细信息,请参阅 Azure Cosmos DB 服务页。