Clarify docs for CosmosClientOptions.ApplicationRegion

The documentation for CosmosClientOptions.ApplicationRegion can be more explicit, especially in the fallback case. This will avoid confusion with the other setting, ApplicationPreferredRegions that is listed as an alternative

According to the remarks section (copy-pasted here for convenience):

Also SDK auto-selects fallback geo-replicated regions for high availability.

It should be clarified that the fallback actually happens based on proximity, as is described in this how-to.

This can be verified for example with the following Linqpad query:

#load "config" // load configuration such as dbName etc.

var options = new CosmosClientOptions();
options.ApplicationRegion = Regions.SwitzerlandNorth; // not available location on our Cosmos

var client = new CosmosClient(endpoint, servicePrincipal, options); // Cosmos account has WestUS and EastUS
var container = client.GetContainer(dbName, containerName);
client = new CosmosClient(endpoint, servicePrincipal, options);
container = client.GetContainer(dbName, containerName);

var response = await container.ReadItemAsync<object>(documentId, new PartitionKey(partitionId));
response.Diagnostics.GetContactedRegions().Dump(); // EastUS was chosen, based on proximity

For comparison, if we were to set the ApplicationPreferredRegions property instead, we would have contacted “WestUS”- our primary location.

From a quick search on StackOverflow, other users seem to have been confused by that (e.g. here and here)

Proposed changes

Summary Get or set the application location. This will affect the choice of the SDK for Azure Cosmos DB service interaction.

Remarks When this property is specified, the SDK prefers the region to perform operations. When the region specified is not available, SDK auto-selects fallback geo-replicated regions based on proximity for high availability. When this property is not specified, the SDK uses the write region as the preferred region for all operations, see troubleshooting SDK availability for more details.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 5c3e4213-e406-00c7-b714-e298ad007044
• Version Independent ID: 70ca5d39-7326-b225-4334-9bb3e37dc419
• Content: CosmosClientOptions.ApplicationRegion Property (Microsoft.Azure.Cosmos) - Azure for .NET Developers
• Content Source: xml/Microsoft.Azure.Cosmos/CosmosClientOptions.xml
• Service: cosmos-db
• GitHub Login: @rloutlaw
• Microsoft Alias: routlaw

[ealsur]

@spygi Thanks for reporting, this item is now in the backlog, we can address it as we get time available. These texts are also coming off the files in this repo, so you could also send a PR to suggest the edit if you with: https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos/src/CosmosClientOptions.cs#L99-L109

[spygi]

Done @ealsur