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

@@ -990,6 +990,9 @@ The following example converts an existing connection string from using SQL Serv
         <para>
           This property corresponds to the "Connection Idle Timeout" key within the connection string.
         </para>
+        <para>
+          In versions where the AppContext switch <c>Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior</c> is enabled (the default), the driver preserves historical pooling behavior and does not enforce this setting. Set the switch to <see langword="false" /> to enable idle-timeout enforcement.
+        </para>
         <para>
           The driver makes a best effort to discard connections that have remained idle in the pool for longer than this value. The exact point in the connection lifecycle at which the check occurs is an implementation detail and may change over time. This protects callers from receiving connections that may have been silently closed by firewalls, load balancers, or server-side inactivity thresholds.
         </para>

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);
+    }
 }