Add configurable idle connection timeout (ADO #39970)

[priyankatiwari08]

Adds a configurable idle connection timeout for pooled SqlConnection instances.

Compatibility and behavior:

• The existing default remains unchanged: IdleTimeout defaults to 300 seconds.
• Idle-expiration behavior is gated by Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior, which defaults to true so current behavior is preserved unless the switch is disabled.
• When the legacy switch is disabled, the configured IdleTimeout controls when pooled connections are considered idle and eligible for expiration.

Additional changes:

• Updates both pool implementations to honor the new behavior consistently.
• Adds tests for parsing, legacy compatibility, and idle-expiration behavior.

[Copilot]

Pull request overview

Adds a new pooling-related connection-string keyword, Connection Idle Timeout (synonym: Pool Idle Timeout), enabling lazy eviction of pooled connections that have sat idle longer than the configured number of seconds. This targets stale/half-open pooled connections (e.g., behind firewalls/load balancers) by discarding expired idle connections on the retrieval path in both pool implementations.

Changes:

• Introduces Connection Idle Timeout parsing + SqlConnectionStringBuilder.IdleTimeout property (default 0 disables).
• Tracks per-connection idle timestamp (DbConnectionInternal.IdleSinceUtc) and stamps it on return-to-pool; evicts idle-expired connections on retrieval in both pool designs.
• Adds unit/functional tests for the new builder keyword/property and Channel pool idle-expiry behavior.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml	Adds XML doc snippet for SqlConnectionStringBuilder.IdleTimeout.
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs	Updates reference assembly surface with IdleTimeout property.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/Common/ConnectionString/DbConnectionStringKeywords.cs	Adds canonical keyword string Connection Idle Timeout.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/Common/ConnectionString/DbConnectionStringDefaults.cs	Adds default IdleTimeout = 0.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/Common/ConnectionString/DbConnectionStringSynonyms.cs	Adds synonym pool idle timeout.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/ProviderBase/DbConnectionInternal.cs	Adds IdleSinceUtc tracking + MarkPooledIdle() stamping helper.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/ChannelDbConnectionPool.cs	Stamps idle time on return and adds idle-expiry check in IsLiveConnection.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/DbConnectionPoolOptions.cs	Adds IdleTimeout option (as TimeSpan) to pool group options.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/WaitHandleDbConnectionPool.cs	Stamps idle time on return and adds IsIdleExpired check at retrieval sites.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionFactory.cs	Wires parsed idle-timeout option into pool group options creation.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionOptions.cs	Parses/validates idle-timeout integer from connection string.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs	Adds IdleTimeout keyword/property support + synonym mapping.
src/Microsoft.Data.SqlClient/src/Resources/Strings.resx	Adds localized description string for the new keyword/property.
src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs	Regenerates resource accessor for DbConnectionString_IdleTimeout.
src/Microsoft.Data.SqlClient/tests/UnitTests/ConnectionPool/ChannelDbConnectionPoolTest.cs	Adds unit tests for Channel pool idle-timeout behavior and stamping.
src/Microsoft.Data.SqlClient/tests/FunctionalTests/SqlConnectionStringBuilderTest.cs	Adds functional tests for keyword parsing, round-trip, default, and invalid values.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

Comments suppressed due to low confidence (2)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/ChannelDbConnectionPool.cs:445

• The comment says that when IdleSinceUtc is the default (DateTime.MinValue) the idle-timeout check is a no-op and indicates the connection has never been pooled. In this PR IdleSinceUtc is initialized to CreateTime in DbConnectionInternal, so it will not be DateTime.MinValue, and even if it were, the current comparison would not be a no-op. Please update/remove this comment to match the actual semantics (e.g., describe the create-time initialization and that the check applies to any connection read from the idle channel).

            // Connection has been sitting idle longer than the configured idle timeout.
            // IdleSinceUtc is stamped by ReturnInternalConnection on each return; if it is the default
            // (DateTime.MinValue), the connection has never been pooled yet and the check is a no-op.
            TimeSpan idleTimeout = PoolGroupOptions.IdleTimeout;

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/WaitHandleDbConnectionPool.cs:1351

• Idle-timeout enforcement was added to the legacy WaitHandleDbConnectionPool (new IsIdleExpired check + MarkPooledIdle stamping), but there doesn’t appear to be any unit test coverage exercising this path (existing idle-timeout unit tests are only for ChannelDbConnectionPool). Please add at least one focused test validating that an idle-expired connection is discarded and replaced in WaitHandleDbConnectionPool, and that IdleTimeout==0 leaves behavior unchanged.

        /// <summary>
        /// Returns true when the supplied connection has been sitting idle in the pool longer than the
        /// configured <see cref="DbConnectionPoolGroupOptions.IdleTimeout"/>. Returns false when idle timeout
        /// is disabled (zero).
        /// </summary>
        private bool IsIdleExpired(DbConnectionInternal obj)
        {
            TimeSpan idleTimeout = PoolGroupOptions.IdleTimeout;
            return idleTimeout != TimeSpan.Zero && DateTime.UtcNow > obj.IdleSinceUtc + idleTimeout;
        }

[codecov]

Codecov Report

❌ Patch coverage is 91.35802% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.58%. Comparing base (bfbdd30) to head (5b1bbe9).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...lient/ConnectionPool/WaitHandleDbConnectionPool.cs	88.00%	3 Missing ⚠️
...qlClient/ConnectionPool/DbConnectionPoolOptions.cs	80.00%	2 Missing ⚠️
...c/Microsoft/Data/SqlClient/SqlConnectionOptions.cs	71.42%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4295      +/-   ##
==========================================
- Coverage   66.69%   64.58%   -2.11%     
==========================================
  Files         284      279       -5     
  Lines       43238    66146   +22908     
==========================================
+ Hits        28836    42721   +13885     
- Misses      14402    23425    +9023     

Flag	Coverage Δ
CI-SqlClient	?
PR-SqlClient-Project	64.58% <91.35%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

Comments suppressed due to low confidence (2)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/WaitHandleDbConnectionPool.cs:1043

• The idle-timeout eviction check is evaluated after obj.IsConnectionAlive(). For long-idle pooled connections, IsConnectionAlive() may perform an expensive SNI-level liveness probe; if the connection is already idle-expired, that work is unnecessary. Consider checking IsIdleExpired(obj) first (or reordering the condition) so expired connections are discarded without doing a liveness check.

This issue also appears on line 1218 of the same file.

                                if ((obj != null) && (!obj.IsConnectionAlive() || IsIdleExpired(obj)))
                                {
                                    SqlClientEventSource.Log.TryPoolerTraceEvent("<prov.DbConnectionPool.GetConnection|RES|CPOOL> {0}, Connection {1}, found dead and removed.", Id, obj.ObjectID);
                                    DestroyObject(obj);
                                    obj = null;     // Setting to null in case creating a new object fails

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/ConnectionPool/WaitHandleDbConnectionPool.cs:1222

• Similar to the general-pool path: in the transacted-pool retrieval, the code calls obj.IsConnectionAlive() before IsIdleExpired(obj). Since IsConnectionAlive() can trigger an SNI liveness probe for idle connections, consider checking IsIdleExpired(obj) first to avoid extra work when the idle-timeout policy is what causes the connection to be recycled.

                    else if (!obj.IsConnectionAlive() || IsIdleExpired(obj))
                    {
                        SqlClientEventSource.Log.TryPoolerTraceEvent("<prov.DbConnectionPool.GetFromTransactedPool|RES|CPOOL> {0}, Connection {1}, found dead and removed.", Id, obj.ObjectID);
                        DestroyObject(obj);
                        obj = null;

[priyankatiwari08]

All review feedback has been addressed:

• Default value for Connection Idle Timeout is now 300 (5 min, matches Npgsql); 0 disables idle expiration.
• The Pool Idle Timeout synonym has been removed; only the canonical keyword is accepted.
• idleTimeout is now a required parameter in DbConnectionPoolGroupOptions.
• The constructor uses TimeSpan.FromSeconds as suggested.
• WaitHandle pool: dropped MarkPooledIdle() on transacted-pool return and removed idle-expiry check on transacted-pool retrieval (transacting connections are never proactively closed).
• WaitHandle pool: general-pool retrieval now checks idle expiry before liveness; _cleanupWait is driven by IdleTimeout (random fallback when 0).
• Channel pool: IsLiveConnection now checks idle expiry before liveness.
• All affected tests and docs updated; release notes entry added.
• All unit and functional tests pass (except 5 pre-existing AlwaysEncrypted admin-rights failures).

Ready for re-review. Please confirm if any further changes are needed.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

[mdaigle]

Thanks for making those changes. I have a few more updates that I'd like to see. Otherwise it's very close.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

Comments suppressed due to low confidence (1)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/LocalAppContextSwitches.cs:138

• The XML doc comment for UseOverallConnectTimeoutForPoolWaitString is malformed (it closes without an opening
  ). With TreatWarningsAsErrors enabled, this can fail the build with an XML-doc warning (CS1570).

    /// The name of the app context switch that controls whether pool operations
    /// should count against the caller's overall ConnectTimeout budget.
    /// </summary>
    private const string UseOverallConnectTimeoutForPoolWaitString =
        "Switch.Microsoft.Data.SqlClient.UseOverallConnectTimeoutForPoolWait";

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

[priyankatiwari08]

rightly pointed. Added in document

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 1 comment.

Files not reviewed (1)

• src/Microsoft.Data.SqlClient/src/Resources/Strings.Designer.cs: Language not supported

[paulmedynski]

Let's avoid duplicating the calculation and move this condition up to the first block:

if (LocalAppContextSwitches.UseLegacyIdleTimeoutBehavior || idleTimeout == TimeSpan.Zero)
{
  // Historical calculation.
}
else
{
  // Use new Idle Timeout value.
}

Note that your changes here eliminate the "None" state I discussed earlier - this old pool will always perform idle connection cleanup, despite the connection string option claiming that a value of 0 means idle cleanup is disabled.

[paulmedynski]

Hmm... so now we're in a situation where the pool is 100% returning this connection to the idle pool, but we're not calling ReturnedToPool(), which seems wrong based on the context here and method name.

Maybe a less-general method name like SetReturnedTime() would be better, since that's exactly what we want the connection to do. The connection is responsible for knowing what sort of time to use, and the pool is responsible for telling the connection to set it. I think that keeps our mechanism/policy separation, and makes the calling code clearer. Thoughts?