[Per Partition Automatic Failover] Remove Environment Variable to Set PPAF at the SDK Layer and Add Support for Internal Client Options by Copilot · Pull Request #5287 · Azure/azure-cosmos-dotnet-v3

Copilot · 2025-07-15T21:22:22Z

This PR implements the requirements to modernize Per Partition Automatic Failover (PPAF) configuration by removing deprecated environment variable support and adding new internal client options.

Changes Made

1. Remove Dependency on Environment Variable ❌

Removed AZURE_COSMOS_PARTITION_LEVEL_FAILOVER_ENABLED environment variable support
Removed ConfigurationManager.PartitionLevelFailoverEnabled constant
Removed ConfigurationManager.IsPartitionLevelFailoverEnabled() method
Updated DocumentClient.cs and GlobalEndpointManager.cs to rely exclusively on account metadata
PPAF is now controlled entirely through the account properties response, as originally intended

2. Create New Environment Variable for Circuit Breaker ✅

Added AZURE_COSMOS_PPCB_TIMEOUT_COUNTER_RESET_WINDOW_IN_MINUTES environment variable
Added ConfigurationManager.GetCircuitBreakerTimeoutCounterResetWindowInMinutes() method

Updated GlobalPartitionEndpointManagerCore to use configurable timeout counter reset window:

this.TimeoutCounterResetWindowInMinutes = TimeSpan.FromMinutes(
    ConfigurationManager.GetCircuitBreakerTimeoutCounterResetWindowInMinutes(5));

Default value: 5 minutes (previously hardcoded to 1 minute)

3. Add New Internal Client Options ✅

Added CosmosClientOptions.DisablePartitionLevelFailover internal property
Added ConnectionPolicy.DisablePartitionLevelFailover property

Enhanced PPAF logic to respect the new client option:

// Apply the DisablePartitionLevelFailover setting to override PPAF if explicitly disabled
if (this.ConnectionPolicy.DisablePartitionLevelFailover)
{
    isPPafEnabled = false;
}

When set to true, this option disables PPAF irrespective of account settings

Testing

Added comprehensive unit tests for new environment variable functionality
Added tests for the new internal client option behavior
Added tests to verify removal of deprecated environment variable (using reflection)
Updated existing tests to remove usage of deprecated environment variable
Verified core library builds successfully without compilation errors

Backward Compatibility

This is a breaking change for any code that relied on the AZURE_COSMOS_PARTITION_LEVEL_FAILOVER_ENABLED environment variable. However, this environment variable was marked as deprecated and the preferred approach has always been to use account-level configuration.

Migration Path

Remove any usage of AZURE_COSMOS_PARTITION_LEVEL_FAILOVER_ENABLED environment variable
Use account-level PPAF configuration through Azure Cosmos DB account settings
Use the new internal DisablePartitionLevelFailover client option if explicit override is needed

Fixes #5277.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

github-actions

Please follow the required format: "[Internal] Category: (Adds|Fixes|Refactors|Removes) Description"

Internal should be used for PRs that have no customer impact. This flag is used to help generate the changelog to know which PRs should be included. Examples:
Diagnostics: Adds GetElapsedClientLatency to CosmosDiagnostics
PartitionKey: Fixes null reference when using default(PartitionKey)
[v4] Client Encryption: Refactors code to external project
[Internal] Query: Adds code generator for CosmosNumbers for easy additions in the future.

…counter reset window configuration Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

kirankumarkolli · 2025-07-15T22:41:57Z

+        }
+
+        [TestMethod]
+        public void PartitionLevelFailoverEnvironmentVariableRemoved()


This test is not needed.

Removed the unnecessary test method as requested. 98fb329

kirankumarkolli · 2025-07-15T22:42:14Z

+        }
+
+        [TestMethod]
+        public void IsPartitionLevelFailoverEnabledMethodRemoved()


This test is not needed

Removed the unnecessary test method as requested. 98fb329

kirankumarkolli · 2025-07-15T22:43:34Z

@@ -495,8 +493,7 @@ public async Task TestPPAFClientAndServerEnablementCombinationScenariosAsync(
            }
            finally


Unnecessary try-finally

Removed the unnecessary try-finally block as requested. 98fb329

kirankumarkolli · 2025-07-15T22:44:27Z

Please follow the required format: "[Internal] Category: (Adds|Fixes|Refactors|Removes) Description" Internal should be used for PRs that have no customer impact. This flag is used to help generate the changelog to know which PRs should be included. Examples: Diagnostics: Adds GetElapsedClientLatency to CosmosDiagnostics PartitionKey: Fixes null reference when using default(PartitionKey) [v4] Client Encryption: Refactors code to external project [Internal] Query: Adds code generator for CosmosNumbers for easy additions in the future.

@copilot fix the title

kundadebdatta · 2025-07-15T22:50:53Z

-            {
-                isPPafEnabled = this.accountServiceConfiguration.AccountProperties.EnablePartitionLevelFailover.Value;
+            bool isPPafEnabled = false;
+            if (this.accountServiceConfiguration != null && this.accountServiceConfiguration.AccountProperties.EnablePartitionLevelFailover.HasValue)


This can be interpreted as !this.ConnectionPolicy.DisablePartitionLevelFailoverOverride && this.accountServiceConfiguration != null && this.accountServiceConfiguration.AccountProperties.EnablePartitionLevelFailover.HasValue

We can get rid of the local variable in that case: isPPafEnabled

Simplified the PPAF logic by removing the local variable isPPafEnabled and using direct assignment as suggested. 6a1cfb9

…y block Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

kirankumarkolli · 2025-07-15T22:55:16Z

+                Environment.SetEnvironmentVariable(envVarName, null);
+            }
+        }
+


Unnecessary new lines

Removed unnecessary new lines as requested. f8ce129

kundadebdatta · 2025-07-15T22:55:50Z

-            if (databaseAccount.EnablePartitionLevelFailover.HasValue)
-            {
-                isPPafEnabled = databaseAccount.EnablePartitionLevelFailover.Value;
+            bool isPPafEnabled = false;


This can be simplified as:

if (!this.connectionPolicy.DisablePartitionLevelFailover && databaseAccount.EnablePartitionLevelFailover.HasValue) { this.connectionPolicy.EnablePartitionLevelFailover = databaseAccount.EnablePartitionLevelFailover.Value; }

Simplified the PPAF logic as suggested by removing the local variable and using direct assignment. f8ce129

kirankumarkolli · 2025-07-15T22:56:42Z

+        [Owner("dkunda")]
+        public void CosmosClientOptions_WhenPartitionLevelFailoverEnabledAndPreferredRegionsSet_ShouldInitializeSuccessfully()
+        {
+            try


Remove try-finally

Also similar places wherever its applicable in this PR

Removed unnecessary try-finally blocks in CosmosClientOptionsUnitTests.cs for the two test methods that only had cleanup comments with no actual environment variable cleanup. f8ce129

…eview Co-authored-by: kundadebdatta <87335885+kundadebdatta@users.noreply.github.com>

Copilot · 2025-07-15T22:58:58Z

Please follow the required format: "[Internal] Category: (Adds|Fixes|Refactors|Removes) Description" Internal should be used for PRs that have no customer impact. This flag is used to help generate ...

I cannot directly modify the PR title through the available tools, but I understand it should follow the format "[Internal] Category: (Adds|Fixes|Refactors|Removes) Description". The title should be updated by someone with repository admin permissions.

…nally blocks, simplify PPAF logic Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

kundadebdatta · 2025-07-17T00:35:22Z

This has been taken care by this PR-5284.

Initial plan

2026d8b

Copilot AI assigned Copilot and kirankumarkolli Jul 15, 2025

Copilot started work on behalf of kirankumarkolli July 15, 2025 21:22 View session

github-actions Bot reviewed Jul 15, 2025

View reviewed changes

Remove deprecated PPAF environment variable and add new PPCB timeout …

c5b40ca

…counter reset window configuration Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

Copilot AI requested a review from kirankumarkolli July 15, 2025 21:42

Copilot finished work on behalf of kirankumarkolli July 15, 2025 21:42

kirankumarkolli reviewed Jul 15, 2025

View reviewed changes

Copilot started work on behalf of kirankumarkolli July 15, 2025 22:43 View session

kundadebdatta reviewed Jul 15, 2025

View reviewed changes

Address code review feedback: remove unnecessary tests and try-finall…

98fb329

…y block Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

Copilot AI requested a review from kirankumarkolli July 15, 2025 22:53

Copilot finished work on behalf of kirankumarkolli July 15, 2025 22:53

Copilot started work on behalf of kundadebdatta July 15, 2025 22:53 View session

kirankumarkolli reviewed Jul 15, 2025

View reviewed changes

kundadebdatta reviewed Jul 15, 2025

View reviewed changes

kirankumarkolli reviewed Jul 15, 2025

View reviewed changes

Simplify PPAF logic by removing local variable as suggested in code r…

6a1cfb9

…eview Co-authored-by: kundadebdatta <87335885+kundadebdatta@users.noreply.github.com>

Copilot finished work on behalf of kundadebdatta July 15, 2025 22:59

Copilot AI requested a review from kundadebdatta July 15, 2025 22:59

Copilot started work on behalf of kirankumarkolli July 15, 2025 22:59 View session

Address code review feedback: remove unnecessary new lines and try-fi…

f8ce129

…nally blocks, simplify PPAF logic Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

Copilot AI requested a review from kirankumarkolli July 15, 2025 23:10

Copilot finished work on behalf of kirankumarkolli July 15, 2025 23:10

kirankumarkolli closed this Jul 17, 2025

		@@ -495,8 +493,7 @@ public async Task TestPPAFClientAndServerEnablementCombinationScenariosAsync(
		}
		finally

Conversation

Copilot AI commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes Made

1. Remove Dependency on Environment Variable ❌

2. Create New Environment Variable for Circuit Breaker ✅

3. Add New Internal Client Options ✅

Testing

Backward Compatibility

Migration Path

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

kirankumarkolli commented Jul 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Jul 15, 2025

Uh oh!

kundadebdatta commented Jul 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jul 15, 2025 •

edited

Loading