Merge pull request #281922 from jcocchi/update-cfp-avad

[Cosmos DB] Add all versions and deletes .NET sample for change feed processor

Author: prmerger-automator[bot]

articles/cosmos-db/nosql/change-feed-modes.md

@@ -7,7 +7,7 @@ ms.reviewer: jucocchi
 ms.service: cosmos-db
 ms.custom: build-2023
 ms.topic: conceptual
-ms.date: 08/14/2023
+ms.date: 07/25/2024
 ---
 # Change feed modes in Azure Cosmos DB
 
@@ -121,7 +121,7 @@ During the preview, the following methods to read the change feed are available
 | **Method to read change feed** | **.NET** | **Java** | **Python** | **Node.js** |
 | --- | --- | --- | --- | --- |
 | [Change feed pull model](change-feed-pull-model.md) | [>= 3.32.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.32.0-preview) | [>= 4.42.0](https://mvnrepository.com/artifact/com.azure/azure-cosmos/4.37.0) |  No  |  No  |
-| [Change feed processor](change-feed-processor.md) | No | [>= 4.42.0](https://mvnrepository.com/artifact/com.azure/azure-cosmos/4.42.0) | No | No |
+| [Change feed processor](change-feed-processor.md) | [>= 3.40.0-preview.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.40.0-preview.0) | [>= 4.42.0](https://mvnrepository.com/artifact/com.azure/azure-cosmos/4.42.0) | No | No |
 | Azure Functions trigger | No | No | No | No |
 
 > [!NOTE]

articles/cosmos-db/nosql/change-feed-processor.md

@@ -8,7 +8,7 @@ ms.service: cosmos-db
 ms.subservice: nosql
 ms.devlang: csharp
 ms.topic: conceptual
-ms.date: 07/10/2024
+ms.date: 07/25/2024
 ms.custom: devx-track-csharp, build-2023
 ---
 
@@ -51,20 +51,33 @@ Each range is read in parallel. A range's progress is maintained separately from
 
 ### [.NET](#tab/dotnet)
 
-The change feed processor in .NET is currently available only for [latest version mode](change-feed-modes.md#latest-version-change-feed-mode). The point of entry is always the monitored container. In a `Container` instance, you call `GetChangeFeedProcessorBuilder`:
+The change feed processor in .NET is available for [latest version mode](change-feed-modes.md#latest-version-change-feed-mode) and [all versions and deletes mode](change-feed-modes.md#all-versions-and-deletes-change-feed-mode-preview). All versions and deletes mode is in preview and is supported for the change feed processor beginning in version `3.40.0-preview.0`. The point of entry for both modes is always the monitored container. 
+
+To read using latest version mode, in a `Container` instance, you call `GetChangeFeedProcessorBuilder`:
 
 [!code-csharp[Main](~/samples-cosmosdb-dotnet-change-feed-processor/src/Program.cs?name=DefineProcessor)]
 
-The first parameter is a distinct name that describes the goal of this processor. The second name is the delegate implementation that handles changes.
+To read using all versions and deletes mode, call `GetChangeFeedProcessorBuilderWithAllVersionsAndDeletes` from the `Container` instance:
+
+[!code-csharp[Main](~/samples-cosmosdb-dotnet-v3/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeedAllVersionsAndDeletes/Program.cs?name=BasicInitialization)]
+
+For both modes, the first parameter is a distinct name that describes the goal of this processor. The second name is the delegate implementation that handles changes.
 
-Here's an example of a delegate:
+Here's an example of a delegate for latest version mode:
 
 [!code-csharp[Main](~/samples-cosmosdb-dotnet-change-feed-processor/src/Program.cs?name=Delegate)]
 
+Here's an example of a delegate for all versions and deletes mode: 
+
+[!code-csharp[Main](~/samples-cosmosdb-dotnet-v3/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeedAllVersionsAndDeletes/Program.cs?name=Delegate)]
+
 Afterward, you define the compute instance name or unique identifier by using `WithInstanceName`. The compute instance name should be unique and different for each compute instance you're deploying. You set the container to maintain the lease state by using `WithLeaseContainer`.
 
 Calling `Build` gives you the processor instance that you can start by calling `StartAsync`.
 
+>[!NOTE]
+> The preceding code snippets are taken from samples in GitHub. You can get the sample for [latest version mode](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed) or [all versions and deletes mode](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeedAllVersionsAndDeletes).
+
 ## Processing life cycle
 
 The normal life cycle of a host instance is:
@@ -93,6 +106,8 @@ You can connect the change feed processor to any relevant event in its [life cyc
 * Register a handler for `WithLeaseReleaseNotification` to be notified when the current host releases a lease and stops processing it.
 * Register a handler for `WithErrorNotification` to be notified when the current host encounters an exception during processing. You need to be able to distinguish whether the source is the user delegate (an unhandled exception) or an error that the processor encounters when it tries to access the monitored container (for example, networking issues).
 
+Life cycle notifications are available in both change feed modes. Here's an example of life cycle notifications in latest version mode:
+
 [!code-csharp[Main](~/samples-cosmosdb-dotnet-v3/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed/Program.cs?name=StartWithNotifications)]
 
 ## Deployment unit
@@ -137,6 +152,8 @@ The change feed processor is initialized, and it starts reading changes from the
 
 > [!NOTE]
 > These customization options work only to set up the starting point in time of the change feed processor. After the lease container is initialized for the first time, changing these options has no effect.
+>
+> Customizing the starting point is only available for latest version change feed mode. When using all versions and deletes mode you must start reading from the time the processor is started, or resume from a prior lease state that is within the [continuous backup](../continuous-backup-restore-introduction.md) retention period of your account.
 
 ### [Java](#tab/java)
 

articles/cosmos-db/nosql/change-feed-pull-model.md

@@ -64,14 +64,16 @@ FeedIterator<User> InteratorWithPOCOS = container.GetChangeFeedIterator<User>(Ch
 > [!TIP]
 > Prior to version `3.34.0`, latest version mode can be used by setting `ChangeFeedMode.Incremental`. Both `Incremental` and `LatestVersion` refer to latest version mode of the change feed and applications that use either mode will see the same behavior.
 
-All versions and deletes mode is in preview and can be used with preview .NET SDK versions >= `3.32.0-preview`. Here's an example for obtaining `FeedIterator` in all versions and deletes mode that returns dynamic objects:
+All versions and deletes mode is in preview and can be used with preview .NET SDK versions >= `3.32.0-preview`. Here's an example for obtaining `FeedIterator` in all versions and deletes mode that returns `User` objects:
 
 ```csharp
-FeedIterator<dynamic> InteratorWithDynamic = container.GetChangeFeedIterator<dynamic>(ChangeFeedStartFrom.Now(), ChangeFeedMode.AllVersionsAndDeletes);
+FeedIterator<ChangeFeedItem<User>> InteratorWithPOCOS = container.GetChangeFeedIterator<ChangeFeedItem<User>>(ChangeFeedStartFrom.Now(), ChangeFeedMode.AllVersionsAndDeletes);
 ```
 
 > [!NOTE]
 > In latest version mode, you receive objects that represent the item that changed, with some [extra metadata](change-feed-modes.md#parse-the-response-object). All versions and deletes mode returns a different data model. For more information, see [Parse the response object](change-feed-modes.md#parse-the-response-object-1).
+>
+> You can get the complete sample for [latest version mode](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/CFPullModelLatestVersionMode) or [all versions and deletes mode](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/CFPullModelAllVersionsAndDeletesMode).
 
 ### Consume the change feed via streams
 

articles/cosmos-db/nosql/how-to-use-change-feed-estimator.md

@@ -5,7 +5,7 @@ author: ealsur
 ms.service: cosmos-db
 ms.subservice: nosql
 ms.topic: how-to
-ms.date: 05/11/2023
+ms.date: 07/25/2024
 ms.author: maquaran
 ms.devlang: csharp
 ms.custom: devx-track-csharp
@@ -22,7 +22,7 @@ The change feed processor acts as a pointer that moves forward across your [chan
 
 Your change feed processor deployment can process changes at a particular rate based on its available resources like CPU, memory, network, and so on.
 
-If this rate is slower than the rate at which your changes happen in your Azure Cosmos DB container, your processor will start to lag behind.
+If this rate is slower than the rate at which your changes happen in your Azure Cosmos DB container, your processor starts to lag behind.
 
 Identifying this scenario helps understand if we need to scale our change feed processor deployment.
 
@@ -32,9 +32,9 @@ Identifying this scenario helps understand if we need to scale our change feed p
 
 #### As a push model for automatic notifications
 
-Like the [change feed processor](./change-feed-processor.md), the change feed estimator can work as a push model. The estimator will measure the difference between the last processed item (defined by the state of the leases container) and the latest change in the container, and push this value to a delegate. The interval at which the measurement is taken can also be customized with a default value of 5 seconds.
+Like the [change feed processor](./change-feed-processor.md), the change feed estimator can work as a push model. The estimator measures the difference between the last processed item (defined by the state of the leases container) and the latest change in the container, and pushes this value to a delegate. The interval at which the measurement is taken can also be customized with a default value of 5 seconds.
 
-As an example, if your change feed processor is defined like this:
+As an example, if your change feed processor is using latest version mode and is defined like this:
 
 [!code-csharp[Main](~/samples-cosmosdb-dotnet-v3/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed/Program.cs?name=StartProcessorEstimator)]
 
@@ -44,7 +44,7 @@ The correct way to initialize an estimator to measure that processor would be us
 
 Where both the processor and the estimator share the same `leaseContainer` and the same name.
 
-The other two parameters are the delegate, which will receive a number that represents **how many changes are pending to be read** by the processor, and the time interval at which you want this measurement to be taken.
+The other two parameters are the delegate, which receives a number that represents **how many changes are pending to be read** by the processor, and the time interval at which you want this measurement to be taken.
 
 An example of a delegate that receives the estimation is:
 
@@ -71,24 +71,24 @@ And whenever you want it, with the frequency you require, you can obtain the det
 
 [!code-csharp[Main](~/samples-cosmosdb-dotnet-v3/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed/Program.cs?name=GetIteratorEstimatorDetailed)]
 
-Each `ChangeFeedProcessorState` will contain the lease and lag information, and also who is the current instance owning it.
+Each `ChangeFeedProcessorState` contains the lease and lag information, and also who is the current instance owning it.
 
 #### Estimator deployment
 
-The change feed estimator does not need to be deployed as part of your change feed processor, nor be part of the same project. We recommend deploying the estimator on an independent and completely different instance from your processors. A single estimator instance can track the progress for the all the leases and instances in your change feed processor deployment.
+The change feed estimator doesn't need to be deployed as part of your change feed processor, nor be part of the same project. We recommend deploying the estimator on an independent instance from your processors. A single estimator instance can track the progress for the all the leases and instances in your change feed processor deployment.
 
-Each estimation will consume [request units](../request-units.md) from your [monitored and lease containers](change-feed-processor.md#components-of-the-change-feed-processor). A frequency of 1 minute in-between is a good starting point, the lower the frequency, the higher the request units consumed.
+Each estimation consumes [request units](../request-units.md) from your [monitored and lease containers](change-feed-processor.md#components-of-the-change-feed-processor). A frequency of 1 minute in-between is a good starting point, the lower the frequency, the higher the request units consumed.
 
 ### [Java](#tab/java)
 
-The provided example represents a sample Java application that demonstrates the implementation of the Change Feed Processor with the estimation of the lag in processing change feed events. In the application - documents are being inserted into one container (the "feed container"), and meanwhile another worker thread or worker application is pulling inserted documents from the feed container's Change Feed and operating on them in some way.
+This example uses the change feed processor in latest version mode with the estimation of the lag in processing change feed events. In the application - documents are being inserted into one container (the "feed container"), and meanwhile another worker thread or worker application is pulling inserted documents from the feed container's change feed and operating on them in some way.
 
 The change Feed Processor is built and started like this:
 [!code-java[](~/azure-cosmos-java-sql-api-samples/src/main/java/com/azure/cosmos/examples/changefeed/SampleChangeFeedEstimator.java?name=ChangeFeedProcessorBuilder)]
 
-Change Feed Processor lag checking can be performed on a separate application (like a health monitor) as long as the same input containers (feedContainer and leaseContainer) and the exact same lease prefix (```CONTAINER_NAME + "-lease"```) are used. The estimator code requires that the Change Feed Processor had an opportunity to fully initialize the leaseContainer's documents.
+Change feed processor lag checking can be performed on a separate application (like a health monitor) as long as the same input containers (feedContainer and leaseContainer) and the exact same lease prefix (```CONTAINER_NAME + "-lease"```) are used. The estimator code requires that the change feed processor had an opportunity to fully initialize the leaseContainer's documents.
 
-The estimator calculates the accumulated lag by retrieving the current state of the Change Feed Processor and summing up the estimated lag values for each event being processed:
+The estimator calculates the accumulated lag by retrieving the current state of the change feed processor and summing up the estimated lag values for each event being processed:
 [!code-java[](~/azure-cosmos-java-sql-api-samples/src/main/java/com/azure/cosmos/examples/changefeed/SampleChangeFeedEstimator.java?name=EstimatedLag)]
 
 The total lag initially should be zero and finally should be greater or equal to the number of documents created. The total lag value can be logged or used for further analysis, allowing to monitor the performance of the change feed processing and identify any potential bottlenecks or delays in the system:
@@ -99,15 +99,20 @@ An example of a delegate that receives changes and handles them with a lag is:
 
 ---
 
+## Supported change feed modes
+
+The change feed estimator can be used for both [latest version mode](./change-feed-modes.md#latest-version-change-feed-mode) and [all versions and deletes mode](./change-feed-modes.md#all-versions-and-deletes-change-feed-mode-preview). In both modes, the estimate provided isn't guaranteed to be an exact count of outstanding changes to process.
+
 ## Additional resources
 
 * [Azure Cosmos DB SDK](sdk-dotnet-v3.md)
-* [Usage samples on GitHub (.NET)](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed)
+* [Usage samples on GitHub (.NET latest version)](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeed)
+* [Usage samples on GitHub (.NET all versions and deletes)](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/ChangeFeedAllVersionsAndDeletes)
 * [Usage samples on GitHub (Java)](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/tree/main/src/main/java/com/azure/cosmos/examples/changefeed)
 * [Additional samples on GitHub](https://github.com/Azure-Samples/cosmos-dotnet-change-feed-processor)
 
 ## Next steps
 
-You can now proceed to learn more about change feed processor in the following articles:
+You can now proceed to learn more about change feed processor in the following article:
 
 * [Overview of change feed processor](change-feed-processor.md)