.NET 更改源处理器 SDK:下载和发行说明.NET Change Feed Processor SDK: Download and release notes

适用于: SQL API

SDK 下载SDK download NuGetNuGet
API 文档API documentation 更改源处理器库 API 参考文档Change Feed Processor library API reference documentation
入门Get started 更改源处理器 .NET SDK 入门Get started with the Change Feed Processor .NET SDK
当前受支持的框架Current supported framework Microsoft .NET Framework 4.5Microsoft .NET Framework 4.5
Microsoft .NET CoreMicrosoft .NET Core


如果使用的是更改源处理器,请参阅 .NET SDK 的最新版本 3.x,其中包含内置于 SDK 中的更改源。If you are using change feed processor, please see the latest version 3.x of the .NET SDK, which has change feed built into the SDK.

发行说明Release notes

v2 版本v2 builds

  • 添加了与启用热迁移路径的 V3 SDK 的租用存储兼容性。Added lease store compatibility with V3 SDK that enables hot migration paths. 应用程序可以迁移到 V3 SDK 再迁移回更改源处理器库,而不会丢失任何状态。An application can migrate to V3 SDK and migrate back to the Change Feed processor library without losing any state.

  • 更正了将 FeedProcessing.ChangeFeedObserverCloseReason.Unknown 关闭原因发送到 FeedProcessing.IChangeFeedObserver.CloseAsync 时,如果找不到分区或者目标副本未随读取会话保持最新将发生的情况。Corrected a case when FeedProcessing.ChangeFeedObserverCloseReason.Unknown close reason was sent to FeedProcessing.IChangeFeedObserver.CloseAsync if the partition cannot be found or if the target replica is not up to date up with the read session. 在这些情况下,现在使用 FeedProcessing.ChangeFeedObserverCloseReason.ResourceGoneFeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable 关闭原因。In these cases FeedProcessing.ChangeFeedObserverCloseReason.ResourceGone and FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable close reasons are now used.
  • 添加了新的关闭原因 FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable,当目标副本未随读取会话保持最新时,将发送此原因以关闭更改源观察程序。Added a new close reason FeedProcessing.ChangeFeedObserverCloseReason.ReadSessionNotAvailable that is sent to close the change feed observer when the target replica is not up to date up with the read session.

  • 添加了新方法 ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory 和相应的公共接口 ICheckpointPartitionProcessorFactoryAdded a new method ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory and corresponding public interface ICheckpointPartitionProcessorFactory. 这样可以实现 IPartitionProcessor 接口来使用内置检查点机制。This allows an implementation of the IPartitionProcessor interface to use built-in checkpointing mechanism. 新工厂类似于现有 IPartitionProcessorFactory,只不过其 Create 方法也采用 ILeaseCheckpointer 参数。The new factory is similar to the existing IPartitionProcessorFactory, except that its Create method also takes the ILeaseCheckpointer parameter.
  • 只有 ChangeFeedProcessorBuilder.WithPartitionProcessorFactoryChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory 方法中的一个可用于同一个 ChangeFeedProcessorBuilder 实例。Only one of the two methods, either ChangeFeedProcessorBuilder.WithPartitionProcessorFactory or ChangeFeedProcessorBuilder.WithCheckpointPartitionProcessorFactory, can be used for the same ChangeFeedProcessorBuilder instance.

  • 稳定性和诊断改进:Stability and diagnosability improvements:
    • 添加了对长时间检测读取更改源的支持。Added support to detect reading change feed taking long time. 所用时间比 ChangeFeedProcessorOptions.ChangeFeedTimeout 属性指定的值更长时,将执行以下步骤:When it takes longer than the value specified by the ChangeFeedProcessorOptions.ChangeFeedTimeout property, the following steps are taken:
      • 将中止在有问题的分区上读取更改源的操作。The operation to read change feed on the problematic partition is aborted.
      • 更改源处理器实例将删除有问题的租约的所有权。The change feed processor instance drops ownership of the problematic lease. 将在由相同或不同的更改源处理器实例完成的下次租约获取步骤期间选取已删除的租约。The dropped lease will be picked up during the next lease acquire step that will be done by the same or different change feed processor instance. 这样便可以重新开始读取更改源。This way, reading change feed will start over.
      • 向运行状况监视器报告问题。An issue is reported to the health monitor. 默认运行状况监视器将报告的所有问题发送到跟踪日志。The default heath monitor sends all reported issues to trace log.
    • 添加了新的公共属性:ChangeFeedProcessorOptions.ChangeFeedTimeoutAdded a new public property: ChangeFeedProcessorOptions.ChangeFeedTimeout. 此属性的默认值为 10 分钟。The default value of this property is 10 mins.
    • 添加了新的公共枚举值:Monitoring.MonitoredOperation.ReadChangeFeedAdded a new public enum value: Monitoring.MonitoredOperation.ReadChangeFeed. HealthMonitoringRecord.Operation 的值设置为 Monitoring.MonitoredOperation.ReadChangeFeed 时,表示运行状况问题与读取更改源相关。When the value of HealthMonitoringRecord.Operation is set to Monitoring.MonitoredOperation.ReadChangeFeed, it indicates the health issue is related to reading change feed.

  • 对于获取所有租约花费的时间超过租约过期间隔(例如由于网络问题)的情况,改进了负载均衡策略:Improved load-balancing strategy for scenario when getting all leases takes longer than lease expiration interval, for example, due to network issues:
    • 在这种情况下,负载均衡算法过去常常将租约错误地视为过期,导致从活动所有者盗取租约。In this scenario load-balancing algorithm used to falsely consider leases as expired, causing stealing leases from active owners. 这可能会导致对大量租约重新进行不必要的负载均衡。This could trigger unnecessary rebalancing many leases.
    • 此问题在该版本中已通过以下方法修复,即避免在获取所有者未更改的过期租约发生冲突时进行重试,并将获取过期租约推迟到下次负载均衡迭代。This issue is fixed in this release by avoiding retry on conflict while acquiring expired lease which owner hasn't changed and postponing acquiring expired lease to next load-balancing iteration.

  • 改进了对观察者异常的处理。Improved handling of Observer exceptions.
  • 有关观察者错误的更丰富信息:Richer information on Observer errors:
    • 当观察者由于观察者的 ProcessChangesAsync 抛出异常而关闭时,CloseAsync 现在将接收设置为 ChangeFeedObserverCloseReason.ObserverError 的 reason 参数。When an Observer is closed due to an exception thrown by Observer's ProcessChangesAsync, the CloseAsync will now receive the reason parameter set to ChangeFeedObserverCloseReason.ObserverError.
    • 添加了跟踪以识别观察者的用户代码中的错误。Added traces to identify errors within user code in an Observer.

  • 添加了对使用共享数据库吞吐量的拆分集合的处理支持。Added support for handling split in collections that use shared database throughput.
    • 此版本修复了使用共享数据库吞吐量的拆分集合可能发生的问题,即在拆分导致分区重新均衡时仅创建一个子分区键范围,而不是两个。This release fixes an issue that may occur during split in collections using shared database throughput when split result into partition rebalancing with only one child partition key range created, rather than two. 发生这种情况时,更改源处理器可能会在删除旧分区键范围的租约时卡住,而无法创建新租约。When this happens, Change Feed Processor may get stuck deleting the lease for old partition key range and not creating new leases. 此版本中已修复了此问题。The issue is fixed in this release.

  • 添加了新属性 ChangeFeedProcessorOptions.StartContinuation 来支持从请求继续标记开始更改源。Added new property ChangeFeedProcessorOptions.StartContinuation to support starting change feed from request continuation token. 只有当租约集合为空或者租约未设置 ContinuationToken 时才使用此属性。This is only used when lease collection is empty or a lease does not have ContinuationToken set. 对于租约集合中设置了 ContinuationToken 的租约,将使用 ContinuationToken 并忽略 ChangeFeedProcessorOptions.StartContinuation。For leases in lease collection that have ContinuationToken set, the ContinuationToken is used and ChangeFeedProcessorOptions.StartContinuation is ignored.

  • 增加了对使用自定义存储的支持,用以按分区持久保存继续标记。Added support for using custom store to persist continuation tokens per partition.
    • 例如,自定义租约存储可以是以任何自定义方式分区的 Azure Cosmos DB 租约集合。For example, a custom lease store can be Azure Cosmos DB lease collection partitioned in any custom way.
    • 自定义租约存储可以使用新的扩展点 ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) 和 ILeaseStoreManager 公共接口。Custom lease stores can use new extensibility point ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) and ILeaseStoreManager public interface.
    • 将 ILeaseManager 接口重构到了多个角色接口中。Refactored the ILeaseManager interface into multiple role interfaces.
  • 次要重大更改:删除了扩展点 ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager),请改用 ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager)。Minor breaking change: removed extensibility point ChangeFeedProcessorBuilder.WithLeaseManager(ILeaseManager), use ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) instead.

  • 此版本修复了在处理受监视集合中的拆分和使用已分区租约集合期间发生的一个问题。This release fixes an issue that occurs during processing a split in monitored collection and using a partitioned lease collection. 在处理拆分分区的租约时,可能不会删除对应于该分区的租约。When processing a lease for split partition, the lease corresponding to that partition may not be deleted. 此版本中已修复了此问题。The issue is fixed in this release.

  • 修复了对具有多个写入区域和新会话令牌格式的帐户的估算器计算。Fixed Estimator calculation for accounts with multiple write regions and new Session Token format.

  • 添加了对已分区租用集合的支持。Added support for partitioned lease collections. 分区键必须定义为 /id。The partition key must be defined as /id.
  • 次要重大更改:IChangeFeedDocumentClient 接口和 ChangeFeedDocumentClient 类的方法都已更改为包括 RequestOptions 和 CancellationToken 参数。Minor breaking change: the methods of the IChangeFeedDocumentClient interface and the ChangeFeedDocumentClient class were changed to include RequestOptions and CancellationToken parameters. IChangeFeedDocumentClient 是一种高级的扩展点,通过该扩展点,可以提供文档客户端的自定义实现,以便与更改源处理器结合使用,例如,修饰 DocumentClient 并截获对它的所有调用以进行额外跟踪和错误处理等。利用此更新,实现 IChangeFeedDocumentClient 的代码将需要更改为在实现中包含新参数。IChangeFeedDocumentClient is an advanced extensibility point that allows you to provide custom implementation of the Document Client to use with Change Feed Processor, for example, decorate DocumentClient and intercept all calls to it to do extra tracing, error handling, etc. With this update, the code that implement IChangeFeedDocumentClient will need to be changed to include new parameters in the implementation.
  • 次要诊断改进。Minor diagnostics improvements.

  • 添加了新的 API,Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync()。Added new API, Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync(). 此 API 可用于获取每个分区估算的工作量。This can be used to get estimated work for each partition.
  • 支持 Microsoft.Azure.DocumentDB SDK 2.0。Supports Microsoft.Azure.DocumentDB SDK 2.0. 需要 Microsoft.Azure.DocumentDB 2.0 或更高版本。Requires Microsoft.Azure.DocumentDB 2.0 or later.

  • 添加了 ChangeFeedEventHost.HostName 公共属性以与 v1 兼容。Added ChangeFeedEventHost.HostName public property for compatibility with v1.

  • 修复了在分区拆分期间发生的争用条件。Fixed a race condition that occurs during partition split. 争用条件可能导致获得租用后,在分区拆分期间立即失去该租用,从而引起争用。The race condition may lead to acquiring lease and immediately losing it during partition split and causing contention. 此版本修复了争用条件问题。The race condition issue is fixed with this release.



  • 修复了以下问题:Fixed the following issues:

    • 拆分分区时,可能会重复处理拆分前修改的文档。When partition split happens, there could be duplicate processing of documents modified before the split.
    • 如果租用集合中没有租用,GetEstimatedRemainingWork API 返回的是 0。The GetEstimatedRemainingWork API returned 0 when no leases were present in the lease collection.
  • 以下异常已公开。The following exceptions are made public. 实现 IPartitionProcessor 的扩展可能会抛出这些异常。Extensions that implement IPartitionProcessor can throw these exceptions.

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


  • 小的 API 更改:Minor API changes:
    • 删除了标记为过时的 ChangeFeedProcessorOptions.IsAutoCheckpointEnabled。Removed ChangeFeedProcessorOptions.IsAutoCheckpointEnabled that was marked as obsolete.


  • 稳定性改进:Stability improvements:
    • 更好地处理租用存储初始化。Better handling of lease store initialization. 当租用存储为空时,只有一个处理器实例可以对其进行初始化,其他处理器实例将等待。When lease store is empty, only one instance of processor can initialize it, the others will wait.
    • 更稳定/有效租用续订/发行版。More stable/efficient lease renewal/release. 续订和释放一个分区的租用独立于续订其他租用。Renewing and releasing a lease one partition is independent from renewing others. 在 v1 中,这是针对所有分区按顺序完成的。In v1 that was done sequentially for all partitions.
  • 新 v2 API:New v2 API:
    • 处理器的灵活构造生成器模式:ChangeFeedProcessorBuilder 类。Builder pattern for flexible construction of the processor: the ChangeFeedProcessorBuilder class.
      • 可以采用参数的任何组合。Can take any combination of parameters.
      • 可以采用用于监视的 DocumentClient 实例和/或租用集合(v1 中不可用)。Can take DocumentClient instance for monitoring and/or lease collection (not available in v1).
    • IChangeFeedObserver.ProcessChangesAsync 现在采用 CancellationToken。IChangeFeedObserver.ProcessChangesAsync now takes CancellationToken.
    • IRemainingWorkEstimator - 剩余工作估计器可以与处理器分开使用。IRemainingWorkEstimator - the remaining work estimator can be used separately from the processor.
    • 新的扩展点:New extensibility points:
      • IPartitionLoadBalancingStrategy - 用于对处理器实例之间的分区进行自定义负载均衡。IPartitionLoadBalancingStrategy - for custom load-balancing of partitions between instances of the processor.
      • ILease、ILeaseManager - 用于自定义租用管理。ILease, ILeaseManager - for custom lease management.
      • IPartitionProcessor - 用于对分区进行自定义处理更改。IPartitionProcessor - for custom processing changes on a partition.
  • 日志记录 - 使用 LibLog 库。Logging - uses LibLog library.
  • 与 v1 API 100% 向后兼容。100% backward compatible with v1 API.
  • 新建代码库。New code base.
  • 兼容 SQL .NET SDK 1.21.1 及更高版本。Compatible with SQL .NET SDK versions 1.21.1 and above.

v1 版本v1 builds

  • 添加了更多日志记录。Added more logging.
  • 修复了多次调用待处理工作评估时出现的 DocumentClient 泄漏。Fixed a DocumentClient leak when calling the pending work estimation multiple times.

  • 修复了待处理工作评估。Fixes in the pending work estimation.

  • 稳定性改进。Stability improvements.
    • 修复了处理取消的任务问题,该问题可能导致某些分区上的观察者停止。Fix for handling canceled tasks issue that might lead to stopped observers on some partitions.
  • 支持手动检查点。Support for manual checkpointing.
  • 兼容 SQL .NET SDK 1.21 及更高版本。Compatible with SQL .NET SDK versions 1.21 and above.

  • 增加了对 .NET Standard 2.0 的支持。Adds support for .NET Standard 2.0. 程序包现在支持 netstandard2.0net451 Framework 名字对象。The package now supports netstandard2.0 and net451 framework monikers.
  • 兼容 SQL .NET SDK 1.17.0 及更高版本。Compatible with SQL .NET SDK versions 1.17.0 and above.
  • 兼容 SQL .NET Core SDK 1.5.1 及更高版本。Compatible with SQL .NET Core SDK versions 1.5.1 and above.

  • 修复了更改源为空或无任何工作挂起时计算剩余工作估计值时的一个问题。Fixes an issue with the calculation of the estimate of remaining work when the Change Feed was empty or no work was pending.
  • 兼容 SQL .NET SDK 1.13.2 及更高版本。Compatible with SQL .NET SDK versions 1.13.2 and above.

  • 添加了一个获取更改源中剩余待处理工作估计值的方法。Added a method to obtain an estimate of remaining work to be processed in the Change Feed.
  • 兼容 SQL .NET SDK 1.13.2 及更高版本。Compatible with SQL .NET SDK versions 1.13.2 and above.

发布和停用日期Release & Retirement dates

Azure 会在停用 SDK 时至少提前 12 个月发出通知,以便用户顺利转换为更高版本/受支持版本。Azure will provide notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version. 新特性和功能以及优化仅添加到当前 SDK,因此建议始终尽早升级到最新的 SDK 版本。New features and functionality and optimizations are only added to the current SDK, as such it is recommended that you always upgrade to the latest SDK version as early as possible.


在 2022 年 8 月 31 日之后,Azure Cosmos DB 将不再进行 bug 修复,不再添加新功能,也不再支持 1.x 版的 Azure Cosmos DB .NET 或 .NET Core SDK for SQL API。After 31 August 2022, Azure Cosmos DB will no longer make bug fixes, add new features, and provide support to versions 1.x of the Azure Cosmos DB .NET or .NET Core SDK for SQL API. 如果你不想升级,则从 1.x 版 SDK 发送的请求将继续由 Azure Cosmos DB 服务处理。If you prefer not to upgrade, requests sent from version 1.x of the SDK will continue to be served by the Azure Cosmos DB service.

版本Version 发布日期Release Date 停用日期Retirement Date 2020 年 8 月 11 日August 11, 2020 --- 2020 年 7 月 30 日July 30, 2020 --- 2020 年 4 月 2 日April 2, 2020 --- 2019 年 10 月 28 日October 28, 2019 --- 2019 年 5 月 14 日May 14, 2019 --- 2019 年 1 月 29 日January 29, 2019 --- 2018 年 12 月 13 日December 13, 2018 --- 2018 年 11 月 29 日November 29, 2018 --- 2018 年 11 月 19 日November 19, 2018 --- 2018 年 10 月 31 日October 31, 2018 --- 2018 年 10 月 24 日October 24, 2018 --- 2018 年 5 月 8 日May 08, 2018 --- 2018 年 4 月 18 日April 18, 2018 --- 2018 年 3 月 13 日March 13, 2018 --- 2017 年 10 月 31 日October 31, 2017 --- 2017 年 8 月 29 日August 29, 2017 --- 2017 年 8 月 13 日August 13, 2017 --- 2017 年 7 月 7 日July 07, 2017 ---


1.如何向客户通知即将停用的 SDK?1. How will customers be notified of the retiring SDK?

Azure 会在即将停用的 SDK 的支持结束之前提前 12 个月进行通知,以便协助平稳地转换到支持的 SDK。Azure will provide 12 month advance notification to the end of support of the retiring SDK in order to facilitate a smooth transition to a supported SDK. 此外,会通过各种通信渠道(Azure 管理门户、开发人员中心、博客文章以及与分配的服务管理员的直接通信)来通知客户。Further, customers will be notified through various communication channels - Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2.在这 12 个月期间,客户是否可以使用“即将”停用的 Azure Cosmos DB SDK 来创作应用程序?2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

可以,客户在 12 个月宽限期内具有完全访问权限,可以使用“即将”停用的 Azure Cosmos DB SDK 创作、部署和修改应用程序。Yes, customers will have full access to author, deploy and modify applications using the "to-be" retired Azure Cosmos DB SDK during the 12 month grace period. 在 12 个月宽限期内,建议客户根据相应情况迁移到支持的较新版本 Azure Cosmos DB SDK。During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3.在 12 个月通知期之后,客户是否可以使用已停用的 Azure Cosmos DB SDK 创建和修改应用程序?3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

在 12 个月通知期之后,SDK 会停用。After the 12 month notification period, the SDK will be retired. Azure Cosmos DB 平台不允许使用已停用 SDK 的应用程序对 Azure Cosmos DB 进行任何访问。Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. 此外,Azure 不会对已停用的 SDK 提供客户支持。Further, Azure will not provide customer support on the retired SDK.

4.如果客户运行使用不支持的 Azure Cosmos DB SDK 版本的应用程序,会发生什么情况?4. What happens to Customer's running applications that are using unsupported Azure Cosmos DB SDK version?

任何使用已停用 SDK 版本连接 Azure Cosmos DB 服务的尝试都会被拒绝。Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5.新特性和功能是否会适用于所有未停用的 SDK?5. Will new features and functionality be applied to all non-retired SDKs?

新特性和功能只添加到新版本。New features and functionality will only be added to new versions. 如果使用的是未停用的旧版本 SDK,则对 Azure Cosmos DB 进行的请求仍会与以前一样正常工作,但是你无法访问任何新功能。If you are using an old, non-retired, version of the SDK your requests to Azure Cosmos DB will still function as previous but you will not have access to any new capabilities.

6.如果无法在截止日期之前更新应用程序,该怎么办?6. What should I do if I cannot update my application before a cut-off date?

我们建议尽早升级到最新 SDK。We recommend that you upgrade to the latest SDK as early as possible. SDK 标记为要停用之后,会有 12 个月来更新应用程序。Once an SDK has been tagged for retirement you will have 12 months to update your application. 如果由于任何原因而无法在此时间范围内完成应用程序更新,请在截止日期之前与 Cosmos DB 团队联系并请求其帮助。If, for whatever reason, you cannot complete your application update within this timeframe then please contact the Cosmos DB Team and request their assistance before the cutoff date.

另请参阅See also

若要了解有关 Cosmos DB 的详细信息,请参阅 Azure Cosmos DB 服务页。To learn more about Cosmos DB, see Azure Cosmos DB service page.