Skip to content

Commit f8dffd3

Browse files
learn-build-service-prod[bot]learn-build-service-prod[bot]
authored
Merge pull request #3860 from MicrosoftDocs/main
Auto Publish – main to live - 2025-11-26 23:03 UTC
2 parents 9a9587c + 0a516fc commit f8dffd3

File tree

1 file changed

+94
-0
lines changed

1 file changed

+94
-0
lines changed

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

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,57 @@ Afterward, you define the compute instance name or unique identifier by using `W
7373

7474
Calling `Build` gives you the processor instance that you can start by calling `StartAsync`.
7575

76+
> [!IMPORTANT]
77+
> When creating the `CosmosClient` for both the feed and lease containers, and initializing a new change feed processor workload:
78+
>
79+
> **Use a global endpoint**
80+
>
81+
> - Always specify a global endpoint (for example, `contoso.documents.azure.com`) rather than a regional endpoint (for example, `contoso-westus.documents.azure.com`).
82+
>
83+
> **Switch regions using ApplicationRegion or ApplicationPreferredRegions**
84+
>
85+
> - To redirect change feed traffic between regions, rely on the `ApplicationRegion` or `ApplicationPreferredRegions` property.
86+
> - Change Feed Processor creates lease documents that are scoped to the configured endpoint, hence changing the endpoints results in the creation of new independent lease documents.
87+
>
88+
> **✅ Do this - Use global endpoint with ApplicationRegion:**
89+
>
90+
> ```csharp
91+
> CosmosClient client = new CosmosClient(
92+
> "https://contoso.documents.azure.com:443/", // Global endpoint
93+
> "<account-key>",
94+
> new CosmosClientOptions()
95+
> {
96+
> ApplicationRegion = Regions.WestUS2 // Specify region here
97+
> });
98+
>
99+
> Container monitoredContainer = client.GetContainer("myDatabase", "myContainer");
100+
> Container leaseContainer = client.GetContainer("myDatabase", "leases");
101+
> ```
102+
>
103+
> **✅ Do this - Use global endpoint with ApplicationPreferredRegions:**
104+
>
105+
> ```csharp
106+
> CosmosClient client = new CosmosClient(
107+
> "https://contoso.documents.azure.com:443/", // Global endpoint
108+
> "<account-key>",
109+
> new CosmosClientOptions()
110+
> {
111+
> ApplicationPreferredRegions = new List<string> { Regions.WestUS2, Regions.EastUS2 }
112+
> });
113+
>
114+
> Container monitoredContainer = client.GetContainer("myDatabase", "myContainer");
115+
> Container leaseContainer = client.GetContainer("myDatabase", "leases");
116+
> ```
117+
>
118+
> **❌ Don't do this - Avoid regional endpoints:**
119+
>
120+
> ```csharp
121+
> // DON'T: Using regional endpoint will create region-scoped lease documents
122+
> CosmosClient client = new CosmosClient(
123+
> "https://contoso-westus.documents.azure.com:443/", // Regional endpoint - AVOID
124+
> "<account-key>");
125+
> ```
126+
76127
> [!IMPORTANT]
77128
> **Avoid asynchronous processing in delegate methods**: When using asynchronous APIs within your `handleChanges()` delegate method, be aware that the change feed processor may checkpoint the lease before all asynchronous operations complete. This can lead to missed events if the application experiences issues during recovery. Consider using synchronous processing or implement proper completion tracking before allowing the delegate to return.
78129
@@ -179,6 +230,49 @@ In either change feed mode, you can assign it to `changeFeedProcessorInstance` a
179230
180231
[!code-java[](~/azure-cosmos-java-sql-api-samples/src/main/java/com/azure/cosmos/examples/changefeed/SampleChangeFeedProcessor.java?name=StartChangeFeedProcessor)]
181232
233+
> [!IMPORTANT]
234+
> When creating the `CosmosAsyncClient` for both the feed and lease containers, and initializing a new change feed processor workload:
235+
>
236+
> **Use a global endpoint**
237+
>
238+
> - Always specify a global endpoint (for example, `contoso.documents.azure.com`) rather than a regional endpoint (for example, `contoso-westus.documents.azure.com`).
239+
>
240+
> **Switch regions using preferredRegions**
241+
>
242+
> - To redirect change feed traffic between regions, rely on the `preferredRegions` property.
243+
> - Change Feed Processor creates lease documents that are scoped to the configured endpoint, hence changing the endpoints results in the creation of new independent lease documents.
244+
>
245+
> **✅ Do this - Use global endpoint with preferredRegions:**
246+
>
247+
> ```java
248+
> List<String> preferredRegions = new ArrayList<>();
249+
> preferredRegions.add("West US 2");
250+
> preferredRegions.add("East US 2");
251+
>
252+
> CosmosAsyncClient client = new CosmosClientBuilder()
253+
> .endpoint("https://contoso.documents.azure.com:443/") // Global endpoint
254+
> .key("<account-key>")
255+
> .preferredRegions(preferredRegions) // Specify regions here
256+
> .buildAsyncClient();
257+
>
258+
> CosmosAsyncContainer feedContainer = client
259+
> .getDatabase("myDatabase")
260+
> .getContainer("myContainer");
261+
> CosmosAsyncContainer leaseContainer = client
262+
> .getDatabase("myDatabase")
263+
> .getContainer("leases");
264+
> ```
265+
>
266+
> **❌ Don't do this - Avoid regional endpoints:**
267+
>
268+
> ```java
269+
> // DON'T: Using regional endpoint will create region-scoped lease documents
270+
> CosmosAsyncClient client = new CosmosClientBuilder()
271+
> .endpoint("https://contoso-westus.documents.azure.com:443/") // Regional endpoint - AVOID
272+
> .key("<account-key>")
273+
> .buildAsyncClient();
274+
> ```
275+
182276
> [!IMPORTANT]
183277
> **Avoid asynchronous processing in delegate methods**: When using asynchronous APIs within your `handleChanges()` delegate method, be aware that the change feed processor may checkpoint the lease before all asynchronous operations complete. This can lead to missed events if the application experiences issues during recovery. Consider using synchronous processing or implement proper completion tracking before allowing the delegate to return.
184278

0 commit comments

Comments
 (0)