Address PR #4295 Copilot review: document UseLegacyIdleTimeoutBehavior switch and tighten idle-timeout test coverage

- Delete redundant IdleTimeout_DefaultIsZero_DisablesExpiry from ChannelDbConnectionPoolTest. The 'default' framing was misleading (the builder-layer default is 300, not 0) and the zero-as-argument path is already covered by IdleTimeout_PoolGroupOptions_ConvertsSecondsToTimeSpan and IdleTimeout_Zero_DoesNotExpire.

- Add IdleTimeout_LegacySwitch_SuppressesEviction to both ChannelDbConnectionPoolTest and WaitHandleDbConnectionPoolIdleTimeoutTest. Flips UseLegacyIdleTimeoutBehavior=true via LocalAppContextSwitchesHelper, back-dates ReturnedTime well past the 1-second timeout, and asserts the connection is still reused. Closes the coverage gap on switch gating in both pool implementations.

- Document the gating in the public surfaces: extend SqlConnectionStringBuilder.xml <remarks> with a paragraph describing the Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext switch (defaults to true), and the three opt-out mechanisms (AppContext.SetSwitch, <RuntimeHostConfigurationOption>, runtimeconfig.json). Mirror the gating note in DbConnectionString_IdleTimeout in Strings.resx and the auto-generated Strings.Designer.cs accessor so the [ResDescription] surfaced in property grids matches.

Author: priyankatiwari08

doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml

@@ -999,6 +999,9 @@ The following example converts an existing connection string from using SQL Serv
         <para>
           Idle timeout operates independently of <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.LoadBalanceTimeout" />. Whichever threshold is exceeded first causes the connection to be discarded.
         </para>
+        <para>
+          Enforcement of this property is gated by the <c>Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior</c> AppContext switch, which defaults to <see langword="true" /> for backward compatibility. While the switch is enabled, the pool preserves its historical idle-handling behavior and the value configured here is not actively enforced as a discard threshold. To opt in to the new behavior described above, set the switch to <see langword="false" />, for example via <c>AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior", false)</c> early in application startup, or via <c>&lt;RuntimeHostConfigurationOption&gt;</c> in your project file or <c>runtimeconfig.json</c>.
+        </para>
       </remarks>
     </IdleTimeout>
     <MaxPoolSize>

src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs

@@ -961,7 +961,7 @@
     <value>The minimum amount of time (in seconds) for this connection to live in the pool before being destroyed.</value>
   </data>
   <data name="DbConnectionString_IdleTimeout" xml:space="preserve">
-    <value>The maximum amount of time (in seconds) a connection can sit unused (idle) in the pool before it is discarded. A value of 0 disables idle expiration.</value>
+    <value>The maximum amount of time (in seconds) a connection can sit unused (idle) in the pool before it is discarded. A value of 0 disables idle expiration. Enforcement is gated by the Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext switch, which defaults to true for backward compatibility.</value>
   </data>
   <data name="DbConnectionString_MaxPoolSize" xml:space="preserve">
     <value>The maximum number of connections allowed in the pool.</value>

src/Microsoft.Data.SqlClient/src/Resources/Strings.resx

@@ -976,22 +976,6 @@ public void IdleTimeout_PoolGroupOptions_ConvertsSecondsToTimeSpan()
             Assert.Equal(TimeSpan.FromSeconds(30), poolGroupOptions.IdleTimeout);
         }
 
-        [Fact]
-        public void IdleTimeout_DefaultIsZero_DisablesExpiry()
-        {
-            // Explicitly passing zero keeps idle expiry off.
-            var poolGroupOptions = new DbConnectionPoolGroupOptions(
-                poolByIdentity: false,
-                minPoolSize: 0,
-                maxPoolSize: 50,
-                creationTimeout: 15,
-                loadBalanceTimeout: 0,
-                hasTransactionAffinity: true,
-                idleTimeout: 0);
-
-            Assert.Equal(TimeSpan.Zero, poolGroupOptions.IdleTimeout);
-        }
-
         [Fact]
         public void IdleTimeout_StampedOnReturn()
         {
@@ -1102,6 +1086,34 @@ public void IdleTimeout_Set_KeepsFreshConnection()
             Assert.Same(first, second);
         }
 
+        [Fact]
+        public void IdleTimeout_LegacySwitch_SuppressesEviction()
+        {
+            using LocalAppContextSwitchesHelper switchesHelper = new();
+            switchesHelper.UseLegacyIdleTimeoutBehavior = true;
+
+            // Arrange - 1-second idle timeout, but legacy switch suppresses the new eviction path.
+            var pool = ConstructPoolWithIdleTimeout(idleTimeoutSeconds: 1);
+            SqlConnection owner = new();
+            pool.TryGetConnection(owner, taskCompletionSource: null,
+                TimeoutTimer.StartNew(TimeSpan.FromSeconds(15)),
+                out DbConnectionInternal? first);
+            Assert.NotNull(first);
+
+            // Return + back-date well past the configured timeout.
+            pool.ReturnInternalConnection(first, owner);
+            BackdateReturnedTime(first, TimeSpan.FromMinutes(5));
+
+            // Act - request another connection.
+            SqlConnection owner2 = new();
+            pool.TryGetConnection(owner2, taskCompletionSource: null,
+                TimeoutTimer.StartNew(TimeSpan.FromSeconds(15)),
+                out DbConnectionInternal? second);
+
+            // Assert - with the legacy switch on, the stale connection is still reused.
+            Assert.Same(first, second);
+        }
+
         // Forcibly rewinds a connection's ReturnedTime by the given amount so tests don't have to sleep.
         private static void BackdateReturnedTime(DbConnectionInternal connection, TimeSpan delta)
         {

src/Microsoft.Data.SqlClient/tests/UnitTests/ConnectionPool/ChannelDbConnectionPoolTest.cs

@@ -162,4 +162,27 @@ public void IdleTimeout_Set_KeepsFreshConnection()
         // Assert - same instance reused, well within idle window
         Assert.Same(first, second);
     }
+
+    [Fact]
+    public void IdleTimeout_LegacySwitch_SuppressesEviction()
+    {
+        using LocalAppContextSwitchesHelper switchesHelper = new();
+        switchesHelper.UseLegacyIdleTimeoutBehavior = true;
+
+        // Arrange - 1-second idle timeout, but legacy switch suppresses the new eviction path.
+        _pool = CreatePool(idleTimeoutSeconds: 1);
+        SqlConnection owner = new();
+        DbConnectionInternal first = GetConnection(owner);
+
+        // Return + back-date well past the configured timeout.
+        _pool.ReturnInternalConnection(first, owner);
+        BackdateReturnedTime(first, TimeSpan.FromMinutes(5));
+
+        // Act - request another connection.
+        SqlConnection owner2 = new();
+        DbConnectionInternal second = GetConnection(owner2);
+
+        // Assert - with the legacy switch on, the stale connection is still reused.
+        Assert.Same(first, second);
+    }
 }