.NET Change Feed Processor SDK: Download and release notes

SDK download NuGet
API documentation Change Feed Processor library API reference documentation
Get started Get started with the Change Feed Processor .NET SDK
Current supported framework Microsoft .NET Framework 4.5
Microsoft .NET Core


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 builds


  • Stability and diagnosability improvements:
    • Added support to detect reading change feed taking long time. 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.
    • Added a new public property: ChangeFeedProcessorOptions.ChangeFeedTimeout. The default value of this property is 10 mins.
    • Added a new public enum value: 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, e.g. 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 re-balancing a lot of leases.
    • This issue is fixed in this release by avoiding retry on conflict while acquiring expired lease which owner hasn't changed and posponing acquiring expired lease to next load balancing iteration.


  • Improved handling of Observer exceptions.
  • Richer information on Observer errors:
    • 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 re-balancing 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.


  • Added new property ChangeFeedProcessorOptions.StartContinuation to support starting change feed from request continuation token. This is only used when lease collection is empty or a lease does not have ContinuationToken set. 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.
    • For example, a custom lease store can be Azure Cosmos DB lease collection partitioned in any custom way.
    • Custom lease stores can use new extensibility point ChangeFeedProcessorBuilder.WithLeaseStoreManager(ILeaseStoreManager) and ILeaseStoreManager public interface.
    • Refactored the ILeaseManager interface into multiple role interfaces.
  • 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 Multi Master accounts and new Session Token format.


  • Added support for partitioned lease collections. The partition key must be defined as /id.
  • Minor breaking change: the methods of the IChangeFeedDocumentClient interface and the ChangeFeedDocumentClient class were changed to include RequestOptions and CancellationToken parameters. IChangeFeedDocumentClient is an advanced extensibility point that allows you to provide custom implementation of the Document Client to use with Change Feed Processor, e.g. 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.


  • Added new API, Task<IReadOnlyList<RemainingPartitionWork>> IRemainingWorkEstimator.GetEstimatedRemainingWorkPerPartitionAsync(). This can be used to get estimated work for each partition.
  • Supports Microsoft.Azure.DocumentDB SDK 2.0. Requires Microsoft.Azure.DocumentDB 2.0 or later.


  • 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.


  • GA SDK


  • Fixed the following issues:

    • When partition split happens, there could be duplicate processing of documents modified before the split.
    • The GetEstimatedRemainingWork API returned 0 when no leases were present in the lease collection.
  • The following exceptions are made public. Extensions that implement IPartitionProcessor can throw these exceptions.

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


  • Minor API changes:
    • 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. In v1 that was done sequentially for all partitions.
  • New v2 API:
    • Builder pattern for flexible construction of the processor: the ChangeFeedProcessorBuilder class.
      • Can take any combination of parameters.
      • Can take DocumentClient instance for monitoring and/or lease collection (not available in v1).
    • IChangeFeedObserver.ProcessChangesAsync now takes CancellationToken.
    • IRemainingWorkEstimator - the remaining work estimator can be used separately from the processor.
    • New extensibility points:
      • IPartitionLoadBalancingStrategy - for custom load-balancing of partitions between instances of the processor.
      • ILease, ILeaseManager - for custom lease management.
      • IPartitionProcessor - for custom processing changes on a partition.
  • Logging - uses LibLog library.
  • 100% backward compatible with v1 API.
  • New code base.
  • Compatible with SQL .NET SDK versions 1.21.1 and above.

v1 builds


  • Added more logging.
  • 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.
  • Compatible with SQL .NET SDK versions 1.21 and above.


  • Adds support for .NET Standard 2.0. The package now supports netstandard2.0 and net451 framework monikers.
  • Compatible with SQL .NET SDK versions 1.17.0 and above.
  • 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.
  • 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.
  • Compatible with SQL .NET SDK versions 1.13.2 and above.


  • GA SDK
  • Compatible with SQL .NET SDK versions 1.14.1 and below.

Release & Retirement dates

Microsoft will provide notification at least 12 months in advance of retiring an SDK in order to smooth the transition to a newer/supported version.

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.

Any request to Cosmos DB using a retired SDK will be rejected by the service.

Version Release Date Retirement Date
2.2.8 October 28, 2019 ---
2.2.7 May 14, 2019 ---
2.2.6 January 29, 2019 ---
2.2.5 December 13, 2018 ---
2.2.4 November 29, 2018 ---
2.2.3 November 19, 2018 ---
2.2.2 October 31, 2018 ---
2.2.1 October 24, 2018 ---
1.3.3 May 08, 2018 ---
1.3.2 April 18, 2018 ---
1.3.1 March 13, 2018 ---
1.2.0 October 31, 2017 ---
1.1.1 August 29, 2017 ---
1.1.0 August 13, 2017 ---
1.0.0 July 07, 2017 ---


1. How will customers be notified of the retiring SDK?

Microsoft 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. Further, customers will be notified through various communication channels – Azure Management Portal, Developer Center, blog post, and direct communication to assigned service administrators.

2. Can customers author applications using a "to-be" retired Azure Cosmos DB SDK during the 12 month period?

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. During the 12 month grace period, customers are advised to migrate to a newer supported version of Azure Cosmos DB SDK as appropriate.

3. Can customers author and modify applications using a retired Azure Cosmos DB SDK after the 12 month notification period?

After the 12 month notification period, the SDK will be retired. Any access to Azure Cosmos DB by an applications using a retired SDK will not be permitted by the Azure Cosmos DB platform. Further, Microsoft will not provide customer support on the retired SDK.

4. What happens to Customer’s running applications that are using unsupported Azure Cosmos DB SDK version?

Any attempts made to connect to the Azure Cosmos DB service with a retired SDK version will be rejected.

5. Will new features and functionality be applied to all non-retired SDKs?

New features and functionality will only be added to new versions. 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. What should I do if I cannot update my application before a cut-off date?

We recommend that you upgrade to the latest SDK as early as possible. Once an SDK has been tagged for retirement you will have 12 months to update your application. 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

To learn more about Cosmos DB, see Microsoft Azure Cosmos DB service page.