From b6094bb70b235a58d7cf5dd8ad487089a8263ec4 Mon Sep 17 00:00:00 2001 From: Fede Paganini Date: Mon, 24 Aug 2026 11:17:43 -0300 Subject: [PATCH 1/4] Add five missing SqlClient AppContext switches and a switch-latching note --- docs/connect/ado-net/appcontext-switches.md | 54 ++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/docs/connect/ado-net/appcontext-switches.md b/docs/connect/ado-net/appcontext-switches.md index a7cd96f9897..6777d0f614b 100644 --- a/docs/connect/ado-net/appcontext-switches.md +++ b/docs/connect/ado-net/appcontext-switches.md @@ -4,7 +4,7 @@ description: Learn about the AppContext switches available in SqlClient and how author: dlevy-msft-sql ms.author: dlevy ms.reviewer: davidengel, paulmedynski, cmalhotra -ms.date: 08/11/2026 +ms.date: 08/24/2026 ms.service: sql ms.subservice: connectivity ms.topic: concept-article @@ -22,6 +22,8 @@ ai-usage: ai-assisted The AppContext class allows SqlClient to provide new functionality while continuing to support callers who depend on the previous behavior. Users can opt out of a change in behavior by setting specific AppContext switches. +SqlClient reads each switch once and caches the value the first time the switch is consulted. Set switches at application startup, before the first use of any SqlClient type — a switch set later in the application's lifetime has no effect. + ## Enable MultiSubnetFailover by default [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] @@ -208,6 +210,56 @@ Upon failover, failover partner information provided by the server is preferred AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true); ``` +## Enforce the connection idle timeout + +[!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] + +Starting in version 7.1.0-preview2, the `Connection Idle Timeout` connection string keyword configures the maximum time, in seconds, that a pooled connection can sit unused before the pool discards it (default 300; a value of 0 disables idle expiration). The keyword is only enforced when the legacy idle-timeout behavior is disabled. With the switch at its default value of `true`, the pool preserves the historical behavior and the keyword has no effect. + +```csharp +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false); +``` + +## Enable the V2 connection pool + +[!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] + +Starting in version 6.1, SqlClient includes a new connection pool implementation (V2). The V1 pool remains the default. To opt in to the V2 pool, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2** on application startup. + +```csharp +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true); +``` + +## Count pool waits against the connect timeout + +[!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] + +Starting in version 7.1.0-preview2, time spent waiting for a connection from the pool can be counted against the caller's `Connect Timeout` budget, so pool waits and the network connection attempt share one overall timeout. When the switch is at its default value of `false`, pool operations receive a full `Connect Timeout` and the network connection attempt receives a further full budget. + +```csharp +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait", true); +``` + +## Revert to legacy failover alternation on login errors + +[!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] + +Starting in version 7.1.0-preview2, when connecting with failover configured, SqlClient no longer alternates to the failover partner on login-phase SQL errors if the connection's parser state isn't closed. To revert to the legacy alternation behavior, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors** on application startup. + +```csharp +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true); +``` + +## Honor an explicit zero scale on vartime parameters + +[!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] + +By default, when a parameter's scale is explicitly set to zero for the vartime data types (`datetime2`, `datetimeoffset`, and `time`), SqlClient sends the default scale of 7 instead. Starting in version 6.0, you can disable the legacy behavior, so that an explicitly set zero scale is honored, by disabling the AppContext switch **Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour** on application startup. + +```csharp +AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false); +``` + ## See also [AppContext Class](/dotnet/api/system.appcontext?view=netcore-3.1&preserve-view=true) From 8a3390318be19e5d8a86f279ad89cbc2bd81093b Mon Sep 17 00:00:00 2001 From: Fede Paganini Date: Mon, 24 Aug 2026 11:56:23 -0300 Subject: [PATCH 2/4] State each switch default explicitly; tighten the latching note --- docs/connect/ado-net/appcontext-switches.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/connect/ado-net/appcontext-switches.md b/docs/connect/ado-net/appcontext-switches.md index 6777d0f614b..c8b689d9497 100644 --- a/docs/connect/ado-net/appcontext-switches.md +++ b/docs/connect/ado-net/appcontext-switches.md @@ -22,7 +22,7 @@ ai-usage: ai-assisted The AppContext class allows SqlClient to provide new functionality while continuing to support callers who depend on the previous behavior. Users can opt out of a change in behavior by setting specific AppContext switches. -SqlClient reads each switch once and caches the value the first time the switch is consulted. Set switches at application startup, before the first use of any SqlClient type — a switch set later in the application's lifetime has no effect. +SqlClient reads each switch once and caches the value the first time it consults that switch. Because it isn't generally observable when a given switch is first consulted, set switches at application startup, before the first use of any SqlClient type — a switch set after it has been consulted has no effect. ## Enable MultiSubnetFailover by default @@ -224,7 +224,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavi [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -Starting in version 6.1, SqlClient includes a new connection pool implementation (V2). The V1 pool remains the default. To opt in to the V2 pool, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2** on application startup. +Starting in version 6.1, SqlClient includes a new connection pool implementation (V2). The V1 pool remains the default (the switch defaults to `false`). To opt in to the V2 pool, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2** on application startup. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true); @@ -244,7 +244,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutFo [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -Starting in version 7.1.0-preview2, when connecting with failover configured, SqlClient no longer alternates to the failover partner on login-phase SQL errors if the connection's parser state isn't closed. To revert to the legacy alternation behavior, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors** on application startup. +Starting in version 7.1.0-preview2, when connecting with failover configured, SqlClient no longer alternates to the failover partner on login-phase SQL errors if the connection's parser state isn't closed. To revert to the legacy alternation behavior, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors** on application startup. The switch defaults to `false`. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true); @@ -254,7 +254,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternati [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -By default, when a parameter's scale is explicitly set to zero for the vartime data types (`datetime2`, `datetimeoffset`, and `time`), SqlClient sends the default scale of 7 instead. Starting in version 6.0, you can disable the legacy behavior, so that an explicitly set zero scale is honored, by disabling the AppContext switch **Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour** on application startup. +By default, when a parameter's scale is explicitly set to zero for the vartime data types (`datetime2`, `datetimeoffset`, and `time`), SqlClient sends the default scale of 7 instead. Starting in version 6.0, you can disable the legacy behavior, so that an explicitly set zero scale is honored, by disabling the AppContext switch **Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour** on application startup. The switch defaults to `true`. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false); From 9c6c69efdc046fa8ad17a6ecf1569aba77be933f Mon Sep 17 00:00:00 2001 From: Fede Paganini Date: Mon, 24 Aug 2026 12:23:08 -0300 Subject: [PATCH 3/4] Apply review feedback: best-effort eviction wording, experimental V2, Learn style alignment --- docs/connect/ado-net/appcontext-switches.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/connect/ado-net/appcontext-switches.md b/docs/connect/ado-net/appcontext-switches.md index c8b689d9497..9b009a530bb 100644 --- a/docs/connect/ado-net/appcontext-switches.md +++ b/docs/connect/ado-net/appcontext-switches.md @@ -22,7 +22,7 @@ ai-usage: ai-assisted The AppContext class allows SqlClient to provide new functionality while continuing to support callers who depend on the previous behavior. Users can opt out of a change in behavior by setting specific AppContext switches. -SqlClient reads each switch once and caches the value the first time it consults that switch. Because it isn't generally observable when a given switch is first consulted, set switches at application startup, before the first use of any SqlClient type — a switch set after it has been consulted has no effect. +SqlClient reads and caches each switch the first time it uses that switch. Set switches at application startup, before you use any SqlClient types. Changing a switch after SqlClient has cached its value has no effect. ## Enable MultiSubnetFailover by default @@ -214,7 +214,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailov [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -Starting in version 7.1.0-preview2, the `Connection Idle Timeout` connection string keyword configures the maximum time, in seconds, that a pooled connection can sit unused before the pool discards it (default 300; a value of 0 disables idle expiration). The keyword is only enforced when the legacy idle-timeout behavior is disabled. With the switch at its default value of `true`, the pool preserves the historical behavior and the keyword has no effect. +Starting in version 7.1.0-preview2, the `Connection Idle Timeout` connection string keyword configures the idle duration, in seconds, after which a pooled connection becomes eligible for eviction (default 300; a value of 0 disables idle expiration). An eligible connection is discarded on a later retrieval or maintenance pass, so the exact timing can vary by pool implementation and maintenance cadence. The keyword is only enforced when the legacy idle-timeout behavior is disabled. With the switch at its default value of `true`, the pool preserves the historical behavior and the keyword has no effect. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false); @@ -224,7 +224,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavi [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -Starting in version 6.1, SqlClient includes a new connection pool implementation (V2). The V1 pool remains the default (the switch defaults to `false`). To opt in to the V2 pool, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2** on application startup. +Starting in version 6.1, SqlClient includes an alternative, experimental connection pool implementation (V2). The V1 pool remains the default (the switch defaults to `false`). To opt in to the V2 pool, enable the AppContext switch `Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2` at application startup. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseConnectionPoolV2", true); @@ -244,7 +244,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutFo [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -Starting in version 7.1.0-preview2, when connecting with failover configured, SqlClient no longer alternates to the failover partner on login-phase SQL errors if the connection's parser state isn't closed. To revert to the legacy alternation behavior, enable the AppContext switch **Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors** on application startup. The switch defaults to `false`. +Starting in version 7.1.0-preview2, when connecting with failover configured, SqlClient no longer alternates to the failover partner for SQL errors returned during the login phase. To revert to the legacy alternation behavior, enable the AppContext switch `Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors` at application startup. The switch defaults to `false`. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors", true); @@ -254,7 +254,7 @@ AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternati [!INCLUDE [dotnet-all](../../includes/products/applies-plain/dotnet-all.md)] -By default, when a parameter's scale is explicitly set to zero for the vartime data types (`datetime2`, `datetimeoffset`, and `time`), SqlClient sends the default scale of 7 instead. Starting in version 6.0, you can disable the legacy behavior, so that an explicitly set zero scale is honored, by disabling the AppContext switch **Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour** on application startup. The switch defaults to `true`. +By default, SqlClient sends a scale of 7 when you explicitly set the scale to 0 for **datetime2**, **datetimeoffset**, or **time** parameters. With version 6.0 and later versions, set `Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour` to `false` at application startup to preserve the explicit scale of 0. The switch defaults to `true`. ```csharp AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false); From e80893c27651cd76bcd37a2fc94aee5ba79dd97f Mon Sep 17 00:00:00 2001 From: Fede Paganini Date: Mon, 24 Aug 2026 20:18:58 -0300 Subject: [PATCH 4/4] Adopt the Related content heading from live --- docs/connect/ado-net/appcontext-switches.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/connect/ado-net/appcontext-switches.md b/docs/connect/ado-net/appcontext-switches.md index 9b009a530bb..87651c8c422 100644 --- a/docs/connect/ado-net/appcontext-switches.md +++ b/docs/connect/ado-net/appcontext-switches.md @@ -260,6 +260,6 @@ By default, SqlClient sends a scale of 7 when you explicitly set the scale to 0 AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyVarTimeZeroScaleBehaviour", false); ``` -## See also +## Related content -[AppContext Class](/dotnet/api/system.appcontext?view=netcore-3.1&preserve-view=true) +- [AppContext Class](/dotnet/api/system.appcontext?view=netcore-3.1&preserve-view=true)