.NET 更改源处理器 SDK：下载和发行说明（旧版）

适用范围： NoSQL

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

发行说明

v2 版本

2.5.0

• 已为 Microsoft.Azure.Documents.ChangeFeedProcessor.Logging.TraceLogProvider 类添加新的构造函数，其采用 System.Diagnostics.TraceSource 的实例作为参数。 这便可以从源代码中初始化的自定义 TraceSource 实例以编程方式创建 用于 .net 跟踪的 TraceLogProvider。 在此更改之前，只能使用 App.config 文件配置 .net 跟踪。

2.4.0

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

2.3.2

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

2.3.1

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

2.3.0

• 添加了新方法 ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory 和相应的公共接口 ICheckpointPartitionProcessorFactory。 这样可以实现 IPartitionProcessor 接口来使用内置检查点机制。 新工厂类似于现有 IPartitionProcessorFactory，只不过其 Create 方法也采用 ILeaseCheckpointer 参数。
• 只有 ChangeFeedProcessorBuilder.WithPartitionProcessorFactory 或 ChangeFeedProcessorBuilder.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.0 和 net451 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

• GA SDK
• 兼容 SQL .NET SDK 1.14.1 及更低版本。

发布和停用日期

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

版本	发布日期	停用日期
2.5.0	2023 年 5 月 15 日	---
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 日	---

常见问题解答

如何收到即将停用的 SDK 的通知？

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知，以便协助平稳地转换到支持的 SDK。 我们会通过以下通信通道通知你：Azure 门户、Azure 更新以及与分配的服务管理员的直接通信。

在这 12 个月期间，我是否可以使用即将停用的 Azure Cosmos DB SDK 来创作应用程序？

可以，你可以在 12 个月的宽限期内使用即将停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。 建议在 12 个月的宽限期内根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。

停用日期之后，使用不受支持的 Azure Cosmos DB SDK 的应用程序会发生什么情况？

停用日期之后，Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。 如果不想升级，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 服务提供服务。

哪些 SDK 版本将包含最新功能和更新？

新功能和更新将仅添加到最新的受支持的主要 SDK 版本的最新次要版本。 建议始终使用最新版本，以充分利用新功能、性能改进和 bug 修补程序。 如果使用的是未停用的旧版本 SDK，则对 Azure Cosmos DB 进行的请求仍然有效，但是你无法访问任何新功能。

如果无法在截止日期之前更新应用程序，该怎么办？

我们建议尽早升级到最新 SDK。 SDK 标记为要停用之后，你将有 12 个月的时间来更新应用程序。 如果无法在停用日期之前更新，从已停用的 SDK 版本发送的请求将继续由 Azure Cosmos DB 提供服务，因此正在运行的应用程序将继续运行。 但 Azure Cosmos DB 将不再进行 bug 修复、添加新功能或为已停用的 SDK 版本提供支持。

如果你有支持计划并需要技术支持，请创建支持工单以联系我们。

如何请求将功能添加到 SDK 或连接器？

新功能并不总是立即添加到每个 SDK 或连接器中。 如果你想添加的功能不受支持，请在我们的社区论坛提出反馈。

另请参阅

若要详细了解 Azure Cosmos DB，请参阅 Azure Cosmos DB 服务页。