From ce72f8c363f3164d6c96e877d4d029342bb436bb Mon Sep 17 00:00:00 2001 From: Cheena Malhotra Date: Thu, 13 Aug 2026 22:11:15 -0700 Subject: [PATCH 1/5] Deprecate TransparentNetworkIPResolution Partially implements #4494 (deprecation only; no default changes). - Mark SqlConnectionStringBuilder.TransparentNetworkIPResolution obsolete in both the implementation and the reference assembly, pointing callers at MultiSubnetFailover and noting that TNIR is .NET Framework-only. - Suppress the resulting obsolete warnings at the internal call sites in SqlConnectionStringBuilder and in tests that exercise the keyword. - Document the deprecation in the SqlConnection and SqlConnectionStringBuilder doc snippets. Connection string defaults are intentionally unchanged in this version: TransparentNetworkIPResolution still defaults to true on .NET Framework and MultiSubnetFailover still defaults to false. Flipping those defaults and adding the associated compatibility switches is deferred. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../SqlConnectionStringBuilder.xml | 3 +++ .../ref/Microsoft.Data.SqlClient.cs | 1 + .../Data/SqlClient/SqlConnectionStringBuilder.cs | 5 +++++ .../SimulatedServerTests/ConnectionFailoverTests.cs | 8 ++++++++ .../SimulatedServerTests/ConnectionRoutingTests.cs | 4 ++++ .../UnitTests/SimulatedServerTests/ConnectionTests.cs | 8 ++++++++ .../SimulatedServerTests/SNICloseDeadlockTest.cs | 6 ++++++ .../SNICloseHandshakeCancellationTest.cs | 2 ++ .../SimulatedServerTests/SNICloseRaceDeadlockTest.cs | 2 ++ 10 files changed, 40 insertions(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 55b60b6120..15ddd5d51f 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -1021,7 +1021,7 @@ The following table lists the valid names for keyword values within the
-or-

ServerSPN|N/A|The SPN for the data source. The default value is an empty string, which causes SqlClient to use the default, driver-generated SPN.

(Only available in v5.0+)| |Transaction Binding|Implicit Unbind|Controls connection association with an enlisted `System.Transactions` transaction.

Possible values are:

`Transaction Binding=Implicit Unbind;`

`Transaction Binding=Explicit Unbind;`

Implicit Unbind causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The `System.Transactions.Transaction.Current` property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.

If the system ends the transaction (in the scope of a using block) before the last command completes, it will throw .

Explicit Unbind causes the connection to remain attached to the transaction until the connection is closed or an explicit `SqlConnection.TransactionEnlist(null)` is called. Beginning in .NET Framework 4.0, changes to Implicit Unbind make Explicit Unbind obsolete. An `InvalidOperationException` is thrown if `Transaction.Current` is not the enlisted transaction or if the enlisted transaction is not active.| -|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|When the value of this key is set to `true`, the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

The value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.

The default values are as follows:

  • `false` when:

    • Connecting to Azure SQL Database where the data source ends with:

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
      • .database.fabric.microsoft.com
    • `Authentication` is 'Active Directory Password' or 'Active Directory Integrated'
  • `true` in all other cases.
| +|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|**Deprecated.** Use `Multi Subnet Failover` instead. This keyword is supported only on .NET Framework; on .NET it is not recognized and throws an `ArgumentException`.

When the value of this key is set to `true`, the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

The value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.

The default values are as follows:

  • `false` when:

    • Connecting to Azure SQL Database where the data source ends with:

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
      • .database.fabric.microsoft.com
    • `Authentication` is 'Active Directory Password' or 'Active Directory Integrated'
  • `true` in all other cases.
| |Trust Server Certificate

-or-

TrustServerCertificate|'false'|When set to `true`, TLS is used to encrypt the channel when bypassing walking the certificate chain to validate trust. If TrustServerCertificate is set to `true` and Encrypt is set to `false`, the channel is not encrypted. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](https://learn.microsoft.com/sql/connect/ado-net/connection-string-syntax).| |Type System Version|N/A|A string value that indicates the type system the application expects. The functionality available to a client application is dependent on the version of SQL Server and the compatibility level of the database. Explicitly setting the type system version that the client application was written for avoids potential problems that could cause an application to break if a different version of SQL Server is used. **Note:** The type system version cannot be set for common language runtime (CLR) code executing in-process in SQL Server. For more information, see [SQL Server Common Language Runtime Integration](https://learn.microsoft.com/dotnet/framework/data/adonet/sql/sql-server-common-language-runtime-integration).

Possible values are:

`Type System Version=SQL Server 2012;`

`Type System Version=SQL Server 2008;`

`Type System Version=SQL Server 2005;`

`Type System Version=Latest;`

`Type System Version=SQL Server 2012;` specifies that the application will require version 11.0.0.0 of Microsoft.SqlServer.Types.dll. The other `Type System Version` settings will require version 10.0.0.0 of Microsoft.SqlServer.Types.dll.

`Latest` is obsolete and should not be used. `Latest` is equivalent to `Type System Version=SQL Server 2008;`.| |User ID

-or-

UID

-or-

User|N/A|The SQL Server login account. Not recommended. To maintain a high level of security, we strongly recommend that you use the `Integrated Security` or `Trusted_Connection` keywords instead. is a more secure way to specify credentials for a connection that uses SQL Server Authentication.

The user ID must be 128 characters or less.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 4014bd1450..943789a0ee 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1409,6 +1409,9 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co A boolean value. + + This property is obsolete. Use instead. Transparent Network IP Resolution is supported only on .NET Framework; on .NET the keyword is not recognized and throws an . + If the Multi Subnet Failover key is set to true, Transparent Network IP Resolution is ignored. diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs index a5e3f1a473..266d0b9a1d 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs @@ -1492,6 +1492,7 @@ public override void Clear() { } #if NETFRAMEWORK /// + [System.ObsoleteAttribute("TransparentNetworkIPResolution has been deprecated and is only supported on .NET Framework. Use MultiSubnetFailover instead.")] [System.ComponentModel.DisplayNameAttribute("Transparent Network IP Resolution")] [System.ComponentModel.RefreshPropertiesAttribute(System.ComponentModel.RefreshProperties.All)] public bool TransparentNetworkIPResolution { get { throw null; } set { } } diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs index 4038dbb295..934ca08400 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs @@ -411,7 +411,9 @@ private object GetAt(Keywords index) return ConnectionReset; #pragma warning restore 618 case Keywords.TransparentNetworkIPResolution: +#pragma warning disable 618 return TransparentNetworkIPResolution; +#pragma warning restore 618 case Keywords.NetworkLibrary: return NetworkLibrary; #endif @@ -1083,7 +1085,9 @@ public override object this[string keyword] NetworkLibrary = ConvertToString(value); break; case Keywords.TransparentNetworkIPResolution: +#pragma warning disable 618 TransparentNetworkIPResolution = ConvertToBoolean(value); +#pragma warning restore 618 break; #endif default: @@ -1879,6 +1883,7 @@ public bool ConnectionReset } /// + [Obsolete("TransparentNetworkIPResolution has been deprecated and is only supported on .NET Framework. Use MultiSubnetFailover instead.")] [DisplayName(DbConnectionStringKeywords.TransparentNetworkIpResolution)] [ResCategory(nameof(Strings.DataCategory_Source))] [ResDescription(nameof(Strings.DbConnectionString_TransparentNetworkIPResolution))] diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionFailoverTests.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionFailoverTests.cs index ba1a852626..216a131ad8 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionFailoverTests.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionFailoverTests.cs @@ -129,7 +129,9 @@ public void NetworkError_TriggersFailover_ClearsPool() InitialCatalog = "test", MultiSubnetFailover = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; @@ -199,7 +201,9 @@ public void NetworkTimeout_ShouldFail() Encrypt = false, MultiSubnetFailover = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; using SqlConnection connection = new(builder.ConnectionString); @@ -246,7 +250,9 @@ public void NetworkDelay_ShouldConnectToPrimary() Pooling = false, // Disable pooling to ensure a fresh connection attempt is made MultiSubnetFailover = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; using SqlConnection connection = new(builder.ConnectionString); @@ -388,7 +394,9 @@ public void NetworkError_WithUserProvidedPartner_RetryEnabled_ShouldConnectToFai FailoverPartner = $"localhost,{failoverServer.EndPoint.Port}", // User provided failover partner Encrypt = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; using SqlConnection connection = new(builder.ConnectionString); diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionRoutingTests.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionRoutingTests.cs index 262770f563..918f7228f3 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionRoutingTests.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionRoutingTests.cs @@ -136,7 +136,9 @@ public void NetworkDelayAtRoutedLocation_RetryDisabled_ShouldSucceed(bool multiS Encrypt = false, MultiSubnetFailover = multiSubnetFailoverEnabled, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = multiSubnetFailoverEnabled, + #pragma warning restore 618 #endif }; using SqlConnection connection = new(builder.ConnectionString); @@ -190,7 +192,9 @@ public void NetworkTimeoutAtRoutedLocation_RetryDisabled_ShouldFail() Encrypt = false, MultiSubnetFailover = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false + #pragma warning restore 618 #endif }; using SqlConnection connection = new(builder.ConnectionString); diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs index a082c8c7e6..018968b6b4 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs @@ -110,7 +110,9 @@ public async Task TransientFault_RetryEnabled_ShouldSucceed_Async(uint errorCode DataSource = "localhost," + server.EndPoint.Port, Encrypt = SqlConnectionEncryptOption.Optional, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false + #pragma warning restore 618 #endif }; @@ -251,7 +253,9 @@ public async Task NetworkError_RetryEnabled_ShouldSucceed_Async(bool multiSubnet Pooling = false, // Disable pooling to ensure a fresh connection attempt is made MultiSubnetFailover = multiSubnetFailoverEnabled, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = multiSubnetFailoverEnabled + #pragma warning restore 618 #endif }; @@ -289,7 +293,9 @@ public async Task NetworkDelay_RetryDisabled_Async(bool multiSubnetFailoverEnabl Encrypt = SqlConnectionEncryptOption.Optional, MultiSubnetFailover = multiSubnetFailoverEnabled, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = multiSubnetFailoverEnabled, + #pragma warning restore 618 #endif }; @@ -337,7 +343,9 @@ public void NetworkDelay_RetryDisabled(bool multiSubnetFailoverEnabled) ConnectTimeout = 5, MultiSubnetFailover = multiSubnetFailoverEnabled, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = multiSubnetFailoverEnabled, + #pragma warning restore 618 #endif }; diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseDeadlockTest.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseDeadlockTest.cs index 465e284b6d..fa333e9215 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseDeadlockTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseDeadlockTest.cs @@ -119,7 +119,9 @@ public void CloseOrDispose_WithPendingAsyncRead_DoesNotDeadlock(bool disposeInst // pool. Pooling = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; @@ -292,7 +294,9 @@ public void CloseOrDispose_DuringPreLoginHandshake_DoesNotDeadlock(bool disposeI ConnectRetryCount = 0, Pooling = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; @@ -502,7 +506,9 @@ public void CloseOrDispose_DuringTlsHandshake_DoesNotDeadlock(bool disposeInstea ConnectRetryCount = 0, Pooling = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseHandshakeCancellationTest.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseHandshakeCancellationTest.cs index 9a41c2f3c7..b11b5ed291 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseHandshakeCancellationTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseHandshakeCancellationTest.cs @@ -119,7 +119,9 @@ public void CancelOpenAsyncDuringTlsHandshake_DoesNotDeadlock() ConnectRetryCount = 0, Pooling = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseRaceDeadlockTest.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseRaceDeadlockTest.cs index 27ab3a7516..78a099bba4 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseRaceDeadlockTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseRaceDeadlockTest.cs @@ -106,7 +106,9 @@ public void ResponseCompletionRacesClose_DoesNotDeadlock(bool disposeInsteadOfCl // connection (reaching SNIClose) instead of returning it to the pool. Pooling = false, #if NETFRAMEWORK + #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete TransparentNetworkIPResolution = false, + #pragma warning restore 618 #endif }; From 5dbb264a10b35304ab76781640f02e366d16cb5c Mon Sep 17 00:00:00 2001 From: Cheena Malhotra Date: Fri, 21 Aug 2026 16:16:19 -0700 Subject: [PATCH 2/5] Address review feedback: annotate CS0618 suppressions and use xref for ArgumentException - Add the existing '// Obsolete properties' rationale comment to the two new CS0618 suppressions around TransparentNetworkIPResolution so the intent matches the neighbouring ConnectionReset suppressions. - Use instead of a backtick literal in the SqlConnection.xml keyword table, matching the file's existing convention. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 108f631b-430f-40a3-bd20-74f19527c192 --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 15ddd5d51f..86919ecd74 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -1021,7 +1021,7 @@ The following table lists the valid names for keyword values within the
-or-

ServerSPN|N/A|The SPN for the data source. The default value is an empty string, which causes SqlClient to use the default, driver-generated SPN.

(Only available in v5.0+)| |Transaction Binding|Implicit Unbind|Controls connection association with an enlisted `System.Transactions` transaction.

Possible values are:

`Transaction Binding=Implicit Unbind;`

`Transaction Binding=Explicit Unbind;`

Implicit Unbind causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The `System.Transactions.Transaction.Current` property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.

If the system ends the transaction (in the scope of a using block) before the last command completes, it will throw .

Explicit Unbind causes the connection to remain attached to the transaction until the connection is closed or an explicit `SqlConnection.TransactionEnlist(null)` is called. Beginning in .NET Framework 4.0, changes to Implicit Unbind make Explicit Unbind obsolete. An `InvalidOperationException` is thrown if `Transaction.Current` is not the enlisted transaction or if the enlisted transaction is not active.| -|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|**Deprecated.** Use `Multi Subnet Failover` instead. This keyword is supported only on .NET Framework; on .NET it is not recognized and throws an `ArgumentException`.

When the value of this key is set to `true`, the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

The value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.

The default values are as follows:

  • `false` when:

    • Connecting to Azure SQL Database where the data source ends with:

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
      • .database.fabric.microsoft.com
    • `Authentication` is 'Active Directory Password' or 'Active Directory Integrated'
  • `true` in all other cases.
| +|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|**Deprecated.** Use `Multi Subnet Failover` instead. This keyword is supported only on .NET Framework; on .NET it is not recognized and throws an .

When the value of this key is set to `true`, the application is required to retrieve all IP addresses for a particular DNS entry and attempt to connect with the first one in the list. If the connection is not established within 0.5 seconds, the application will try to connect to all others in parallel. When the first answers, the application will establish the connection with the respondent IP address.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

The value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.

The default values are as follows:

  • `false` when:

    • Connecting to Azure SQL Database where the data source ends with:

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
      • .database.fabric.microsoft.com
    • `Authentication` is 'Active Directory Password' or 'Active Directory Integrated'
  • `true` in all other cases.
| |Trust Server Certificate

-or-

TrustServerCertificate|'false'|When set to `true`, TLS is used to encrypt the channel when bypassing walking the certificate chain to validate trust. If TrustServerCertificate is set to `true` and Encrypt is set to `false`, the channel is not encrypted. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](https://learn.microsoft.com/sql/connect/ado-net/connection-string-syntax).| |Type System Version|N/A|A string value that indicates the type system the application expects. The functionality available to a client application is dependent on the version of SQL Server and the compatibility level of the database. Explicitly setting the type system version that the client application was written for avoids potential problems that could cause an application to break if a different version of SQL Server is used. **Note:** The type system version cannot be set for common language runtime (CLR) code executing in-process in SQL Server. For more information, see [SQL Server Common Language Runtime Integration](https://learn.microsoft.com/dotnet/framework/data/adonet/sql/sql-server-common-language-runtime-integration).

Possible values are:

`Type System Version=SQL Server 2012;`

`Type System Version=SQL Server 2008;`

`Type System Version=SQL Server 2005;`

`Type System Version=Latest;`

`Type System Version=SQL Server 2012;` specifies that the application will require version 11.0.0.0 of Microsoft.SqlServer.Types.dll. The other `Type System Version` settings will require version 10.0.0.0 of Microsoft.SqlServer.Types.dll.

`Latest` is obsolete and should not be used. `Latest` is equivalent to `Type System Version=SQL Server 2008;`.| |User ID

-or-

UID

-or-

User|N/A|The SQL Server login account. Not recommended. To maintain a high level of security, we strongly recommend that you use the `Integrated Security` or `Trusted_Connection` keywords instead. is a more secure way to specify credentials for a connection that uses SQL Server Authentication.

The user ID must be 128 characters or less.| diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs index 934ca08400..bb4871ed4a 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs @@ -411,7 +411,7 @@ private object GetAt(Keywords index) return ConnectionReset; #pragma warning restore 618 case Keywords.TransparentNetworkIPResolution: -#pragma warning disable 618 +#pragma warning disable 618 // Obsolete properties return TransparentNetworkIPResolution; #pragma warning restore 618 case Keywords.NetworkLibrary: @@ -1085,7 +1085,7 @@ public override object this[string keyword] NetworkLibrary = ConvertToString(value); break; case Keywords.TransparentNetworkIPResolution: -#pragma warning disable 618 +#pragma warning disable 618 // Obsolete properties TransparentNetworkIPResolution = ConvertToBoolean(value); #pragma warning restore 618 break; From 329a8d548959827f7124b0f4c4ca184accb96638 Mon Sep 17 00:00:00 2001 From: Cheena Malhotra Date: Mon, 24 Aug 2026 23:20:29 -0700 Subject: [PATCH 3/5] Suppress CS0618 for TNIR usages in SqlConnectionOptionsTest (net462) The net462 legs failed to build with CS0618 because SqlConnectionOptionsTest sets SqlConnectionStringBuilder.TransparentNetworkIPResolution in two netfx-gated tests. These usages arrived on main after this branch was cut, so they were missing the suppressions applied to the other test files. Merged main into the branch so the build matches what CI compiles, and wrapped both call sites in the same '#pragma warning disable 618' pattern used elsewhere. Verified locally by building net462 with -p:TargetOs=Windows_NT for the UnitTests, FunctionalTests and ManualTests projects: all clean with 0 warnings. Confirmed the check is faithful by removing the pragmas and reproducing the exact CS0618 errors CI reported. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 108f631b-430f-40a3-bd20-74f19527c192 --- .../Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs index 11b4ed8637..cc2f3cb8d7 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs @@ -59,7 +59,9 @@ public void TestDefaultTnir(string dataSource, bool? tnirEnabledInConnString, bo builder.DataSource = dataSource; if (tnirEnabledInConnString.HasValue) { - builder.TransparentNetworkIPResolution = tnirEnabledInConnString.Value; +#pragma warning disable 618 // TransparentNetworkIPResolution is obsolete + builder.TransparentNetworkIPResolution = tnirEnabledInConnString.Value; +#pragma warning restore 618 } SqlConnectionOptions connectionString = new(builder.ConnectionString); @@ -99,7 +101,9 @@ public void TestShouldDisableTnirWithCallerSuppliedToken( SqlConnectionStringBuilder builder = new() { DataSource = dataSource }; if (tnirInConnString.HasValue) { +#pragma warning disable 618 // TransparentNetworkIPResolution is obsolete builder.TransparentNetworkIPResolution = tnirInConnString.Value; +#pragma warning restore 618 } SqlConnectionOptions connectionOptions = new(builder.ConnectionString); From 3212f141b88e716e9675f3bb0d80ead2738f5c88 Mon Sep 17 00:00:00 2001 From: Cheena Malhotra Date: Mon, 24 Aug 2026 23:25:28 -0700 Subject: [PATCH 4/5] Fix indentation of TNIR assignment in SqlConnectionOptionsTest The pragma-wrapped assignment lost its block-scope indentation, making it inconsistent with the matching tnirInConnString block below. The diff against main is now purely additive. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 108f631b-430f-40a3-bd20-74f19527c192 --- .../Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs b/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs index cc2f3cb8d7..4c15a65789 100644 --- a/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs +++ b/src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlClient/SqlConnectionOptionsTest.cs @@ -60,7 +60,7 @@ public void TestDefaultTnir(string dataSource, bool? tnirEnabledInConnString, bo if (tnirEnabledInConnString.HasValue) { #pragma warning disable 618 // TransparentNetworkIPResolution is obsolete - builder.TransparentNetworkIPResolution = tnirEnabledInConnString.Value; + builder.TransparentNetworkIPResolution = tnirEnabledInConnString.Value; #pragma warning restore 618 } SqlConnectionOptions connectionString = new(builder.ConnectionString); From e51ab35b4f1fbb7bffe9654ca3342e0637400c61 Mon Sep 17 00:00:00 2001 From: Cheena Malhotra Date: Mon, 24 Aug 2026 23:36:14 -0700 Subject: [PATCH 5/5] Use xref for ArgumentException in TNIR keyword docs Matches the convention used elsewhere in SqlConnection.xml so the type reference stays linkable in generated docs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 108f631b-430f-40a3-bd20-74f19527c192 --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index c858dbf00d..5f88a1498e 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -1033,7 +1033,7 @@ The following table lists the valid names for keyword values within the
-or-

ServerSPN|N/A|The SPN for the data source. The default value is an empty string, which causes SqlClient to use the default, driver-generated SPN.

(Only available in v5.0+)| |Transaction Binding|Implicit Unbind|Controls connection association with an enlisted `System.Transactions` transaction.

Possible values are:

`Transaction Binding=Implicit Unbind;`

`Transaction Binding=Explicit Unbind;`

Implicit Unbind causes the connection to detach from the transaction when it ends. After detaching, additional requests on the connection are performed in autocommit mode. The `System.Transactions.Transaction.Current` property is not checked when executing requests while the transaction is active. After the transaction has ended, additional requests are performed in autocommit mode.

If the system ends the transaction (in the scope of a using block) before the last command completes, it will throw .

Explicit Unbind causes the connection to remain attached to the transaction until the connection is closed or an explicit `SqlConnection.TransactionEnlist(null)` is called. Beginning in .NET Framework 4.0, changes to Implicit Unbind make Explicit Unbind obsolete. An `InvalidOperationException` is thrown if `Transaction.Current` is not the enlisted transaction or if the enlisted transaction is not active.| -|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|**Deprecated.** Use `Multi Subnet Failover` instead.

On .NET Framework, when the value of this key is set to `true`, the driver runs multiple connect rounds across the DNS-resolved IP addresses, with progressively larger per-attempt timeouts and a 500 ms minimum on the sequential-mode attempt, until a connection succeeds or the overall `Connect Timeout` is reached.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

On .NET Framework, if `TransparentNetworkIPResolution` isn't specified in the connection string, the driver automatically disables TNIR when the data source is an Azure SQL endpoint (`.database.windows.net`, `.database.cloudapi.de`, `.database.usgovcloudapi.net`, `.database.chinacloudapi.cn`, or `.database.fabric.microsoft.com`), when the `Authentication` key is set to any Microsoft Entra ID method (`Active Directory Password`, `Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, or `Active Directory Workload Identity`), or when the or property is set on the . For these automatic conditions, an explicit `TransparentNetworkIPResolution` value bypasses the automatic behavior: `True` enables TNIR, and `False` disables TNIR unconditionally. To restore the automatic behavior, remove the keyword from the connection string.

On .NET (Core, .NET 5+), `TransparentNetworkIPResolution` isn't a recognized connection-string keyword. Setting it (with any value) throws `ArgumentException` when the driver parses the connection string.

On .NET Framework, the value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.| +|Transparent Network IP Resolution

-or-

TransparentNetworkIPResolution|See description.|**Deprecated.** Use `Multi Subnet Failover` instead.

On .NET Framework, when the value of this key is set to `true`, the driver runs multiple connect rounds across the DNS-resolved IP addresses, with progressively larger per-attempt timeouts and a 500 ms minimum on the sequential-mode attempt, until a connection succeeds or the overall `Connect Timeout` is reached.

If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.

If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.

On .NET Framework, if `TransparentNetworkIPResolution` isn't specified in the connection string, the driver automatically disables TNIR when the data source is an Azure SQL endpoint (`.database.windows.net`, `.database.cloudapi.de`, `.database.usgovcloudapi.net`, `.database.chinacloudapi.cn`, or `.database.fabric.microsoft.com`), when the `Authentication` key is set to any Microsoft Entra ID method (`Active Directory Password`, `Active Directory Integrated`, `Active Directory Interactive`, `Active Directory Service Principal`, `Active Directory Device Code Flow`, `Active Directory Managed Identity`, `Active Directory MSI`, `Active Directory Default`, or `Active Directory Workload Identity`), or when the or property is set on the . For these automatic conditions, an explicit `TransparentNetworkIPResolution` value bypasses the automatic behavior: `True` enables TNIR, and `False` disables TNIR unconditionally. To restore the automatic behavior, remove the keyword from the connection string.

On .NET (Core, .NET 5+), `TransparentNetworkIPResolution` isn't a recognized connection-string keyword. Setting it (with any value) throws when the driver parses the connection string.

On .NET Framework, the value of this key must be `true`, `false`, `yes`, or `no`.

A value of `yes` is treated the same as a value of `true`.

A value of `no` is treated the same as a value of `false`.| |Trust Server Certificate

-or-

TrustServerCertificate|'false'|When set to `true`, TLS is used to encrypt the channel when bypassing walking the certificate chain to validate trust. If TrustServerCertificate is set to `true` and Encrypt is set to `false`, the channel is not encrypted. Recognized values are `true`, `false`, `yes`, and `no`. For more information, see [Connection String Syntax](https://learn.microsoft.com/sql/connect/ado-net/connection-string-syntax).| |Type System Version|N/A|A string value that indicates the type system the application expects. The functionality available to a client application is dependent on the version of SQL Server and the compatibility level of the database. Explicitly setting the type system version that the client application was written for avoids potential problems that could cause an application to break if a different version of SQL Server is used. **Note:** The type system version cannot be set for common language runtime (CLR) code executing in-process in SQL Server. For more information, see [SQL Server Common Language Runtime Integration](https://learn.microsoft.com/dotnet/framework/data/adonet/sql/sql-server-common-language-runtime-integration).

Possible values are:

`Type System Version=SQL Server 2012;`

`Type System Version=SQL Server 2008;`

`Type System Version=SQL Server 2005;`

`Type System Version=Latest;`

`Type System Version=SQL Server 2012;` specifies that the application will require version 11.0.0.0 of Microsoft.SqlServer.Types.dll. The other `Type System Version` settings will require version 10.0.0.0 of Microsoft.SqlServer.Types.dll.

`Latest` is obsolete and should not be used. `Latest` is equivalent to `Type System Version=SQL Server 2008;`.| |User ID

-or-

UID

-or-

User|N/A|The SQL Server login account. Not recommended. To maintain a high level of security, we strongly recommend that you use the `Integrated Security` or `Trusted_Connection` keywords instead. is a more secure way to specify credentials for a connection that uses SQL Server Authentication.

The user ID must be 128 characters or less.|