From ec43fd64de945647c320381ded43bab806557f17 Mon Sep 17 00:00:00 2001 From: David Levy Date: Thu, 30 Jul 2026 10:51:17 -0500 Subject: [PATCH 1/4] docs: correct TNIR behavior wording on SqlConnection.ConnectionString and SqlConnectionStringBuilder Fixes #4489 --- .../SqlConnection.xml | 2 +- .../SqlConnectionStringBuilder.xml | 29 +++++-------------- 2 files changed, 8 insertions(+), 23 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 55b60b6120..583e5336e6 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.|On .NET Framework, when the value of this key is set to `true` (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, trying one address at a time with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if `AccessToken` is set. 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` (`KeywordNotSupported`) when the driver parses the connection string.

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.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 4014bd1450..78f9604175 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1403,7 +1403,7 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co - When the value of this key is set to , 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. + On .NET Framework, when the value of this key is set to (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, trying one address at a time with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. A boolean value. @@ -1416,32 +1416,17 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co If the Failover Partner key is set, Transparent Network IP Resolution is ignored. - The value of this key must be true, false, yes, or no. + 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if AccessToken is set. 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. - 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. + On .NET (Core, .NET 5+), TransparentNetworkIPResolution isn't a recognized connection-string keyword. Setting it (with any value) throws ArgumentException (KeywordNotSupported) when the driver parses the connection string. - This key defaults to false when: + 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. - - - - 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' - - Otherwise it defaults to true. - From e29a51d529a7996690da5ecb70e05507e06a2a73 Mon Sep 17 00:00:00 2001 From: David Levy Date: Thu, 30 Jul 2026 11:09:02 -0500 Subject: [PATCH 2/4] docs: drop inaccurate 'trying one address at a time' TNIR claim TransparentNetworkResolutionState alternates between SequentialMode and ParallelMode across attempts; the driver does not uniformly try one address at a time. Reverts that single sub-change and keeps the rest of the TNIR docs correction. --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 583e5336e6..028e142c05 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.|On .NET Framework, when the value of this key is set to `true` (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, trying one address at a time with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if `AccessToken` is set. 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` (`KeywordNotSupported`) when the driver parses the connection string.

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.|On .NET Framework, when the value of this key is set to `true` (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if `AccessToken` is set. 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` (`KeywordNotSupported`) when the driver parses the connection string.

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.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 78f9604175..419bc84970 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1403,7 +1403,7 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co - On .NET Framework, when the value of this key is set to (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, trying one address at a time with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. + On .NET Framework, when the value of this key is set to (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. A boolean value. From 78fa692e27a3060a3cc0edfb1625bfb2a1c509ce Mon Sep 17 00:00:00 2001 From: David Levy Date: Thu, 30 Jul 2026 11:26:24 -0500 Subject: [PATCH 3/4] docs: address low-confidence Copilot review on TNIR remarks - Drop '(the default)' from the summary sentence: TNIR is auto-disabled when the keyword is absent for Azure SQL/Entra/AccessToken, so calling 'true' the effective default is misleading. - Expand the Entra ID Authentication list to the full connection-string values (Active Directory Password, Active Directory Integrated, ...), which are the strings the parser accepts (DbConnectionStringUtilities.cs). - Scope 'The value of this key must be true/false/yes/no' to .NET Framework, matching the preceding paragraph that says the keyword is unrecognized on modern .NET. --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 028e142c05..262ed0867f 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.|On .NET Framework, when the value of this key is set to `true` (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if `AccessToken` is set. 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` (`KeywordNotSupported`) when the driver parses the connection string.

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.|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 a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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 if `AccessToken` is set. 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` (`KeywordNotSupported`) 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.| diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml index 419bc84970..5cb00994dd 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1403,7 +1403,7 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co - On .NET Framework, when the value of this key is set to (the default), the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. + On .NET Framework, when the value of this key is set to , the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. A boolean value. @@ -1416,13 +1416,13 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co If the Failover Partner key is set, Transparent Network IP Resolution 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, Integrated, Interactive, Service Principal, Device Code Flow, Managed Identity, MSI, Default, or Workload Identity), or if AccessToken is set. 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 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 if AccessToken is set. 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 (KeywordNotSupported) when the driver parses the connection string. - The value of this key must be true, false, yes, or no. + 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. From 49c0d540ed9d39d63ba03b4ab50aff07071c021d Mon Sep 17 00:00:00 2001 From: David Levy Date: Thu, 30 Jul 2026 12:11:05 -0500 Subject: [PATCH 4/4] docs: refine TNIR 500 ms floor wording and drop SR resource name - '500 ms floor on the first attempt' misrepresents the code: the floor is applied when SqlConnectionInternal sets isFirstTransparentAttempt (attemptNumber == 1), which corresponds to TransparentNetworkResolutionState.SequentialMode in TdsParser.Connect. Reword to 'a 500 ms minimum on the sequential-mode attempt'. - Drop the '(KeywordNotSupported)' parenthetical from the modern-.NET paragraph: that's an SR resource key, not the public exception type. --- doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml | 2 +- .../Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml | 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 262ed0867f..da0918d000 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.|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 a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, 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 if `AccessToken` is set. 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` (`KeywordNotSupported`) 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.|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 if `AccessToken` is set. 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`.| |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 5cb00994dd..1b621a90af 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml @@ -1403,7 +1403,7 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co - On .NET Framework, when the value of this key is set to , the driver runs multiple connect rounds across the DNS-resolved IP addresses, with a 500 ms floor on the first attempt and progressively larger per-attempt timeouts, until a connection succeeds or the overall Connect Timeout is reached. + On .NET Framework, when the value of this key is set to , 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. A boolean value. @@ -1419,7 +1419,7 @@ This property corresponds to the "ServerSPN" and "Server SPN" keys within the co 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 if AccessToken is set. 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 (KeywordNotSupported) when the driver parses 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.