docs: correct TransparentNetworkIPResolution behavior wording (Fixes #4489)

[dlevy-msft-sql]

Fixes #4489.

What changed

Three edits to the TransparentNetworkIPResolution documentation on both SqlConnection.ConnectionString and SqlConnectionStringBuilder.TransparentNetworkIPResolution:

1. Replace the misleading 0.5 seconds phrasing with an accurate description of the multi-round retry loop, per the code in SqlConnectionInternal.LoginNoFailover and AdapterUtil.MinimumTimeoutForTnirMs.
2. Expand the Authentication list from two methods to the full Entra ID set plus the access-token path, per SqlConnectionInternal.ShouldDisableTnir.
3. Add the missing Azure SQL endpoint override and explicit-set escape hatch (netfx), and document the modern .NET (KeywordNotSupported) parse-throw behavior, per the #if NETFRAMEWORK guards in SqlConnectionOptions.cs and TdsParserStateObject.cs.

Wording follows the suggested text in #4489 and the follow-up correction comment on Bug 3.

Verification

• Ran Select-String for the removed TNIR phrases; no matches remain in the TNIR documentation.
• Both XML files parse as well-formed XML.
• Snippet rendering is flagged for the docs build to verify.

[Copilot]

Pull request overview

This PR updates the TransparentNetworkIPResolution documentation to match the current implementation behavior, primarily for .NET Framework (TNIR retry/timeout behavior and automatic disable conditions), and clarifies the unsupported-keyword behavior on modern .NET.

Changes:

• Replaces the misleading “0.5 seconds then parallel” description with a multi-round retry/timeout description aligned to the implementation.
• Expands the documented Entra ID authentication cases and the AccessToken-related behavior that affect TNIR defaults on .NET Framework.
• Documents the .NET (non-Framework) behavior where TransparentNetworkIPResolution is not a recognized keyword and parsing throws ArgumentException (KeywordNotSupported).

Reviewed changes

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

File	Description
doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml	Updates the TransparentNetworkIPResolution property documentation and remarks to reflect current TNIR behavior and keyword support by platform.
doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml	Updates the connection-string keyword table entry for TransparentNetworkIPResolution to reflect current TNIR behavior and keyword support by platform.

Comments suppressed due to low confidence (1)

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

• The Azure-endpoint paragraph suggests you can "restore the automatic override" by setting TransparentNetworkIPResolution=False, but that doesn't restore the automatic conditional behavior; it forces TNIR off for all connections. Also, after updating the previous paragraph to describe the Entra/AccessToken default-disable semantics, this paragraph can focus on the Azure SQL endpoint case to avoid duplication.

        <para>
          On .NET Framework, if <c>TransparentNetworkIPResolution</c> isn't specified in the connection string, the driver automatically disables TNIR when the data source is an Azure SQL endpoint (<c>.database.windows.net</c>, <c>.database.cloudapi.de</c>, <c>.database.usgovcloudapi.net</c>, <c>.database.chinacloudapi.cn</c>, or <c>.database.fabric.microsoft.com</c>) or when <c>Authentication</c> uses a Microsoft Entra ID method. An explicit <c>TransparentNetworkIPResolution=True</c> in the connection string overrides this automatic behavior; to restore the automatic override, remove the keyword from the connection string, or set it explicitly to <c>False</c>.
        </para>

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

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

• This paragraph says TNIR is ignored when Authentication uses Entra ID or when AccessToken is set, but on .NET Framework that automatic disable only happens when TransparentNetworkIPResolution is NOT explicitly present in the connection string (SqlConnectionInternal.ShouldDisableTnir checks Parsetable.ContainsKey(...) and returns false when explicitly specified). Also, "TNIR" is introduced without expansion and "set it explicitly to False" does not restore the automatic behavior (it disables TNIR unconditionally).

          On .NET Framework, if <c>TransparentNetworkIPResolution</c> isn't specified in the connection string, the driver automatically disables TNIR when the data source is an Azure SQL endpoint (<c>.database.windows.net</c>, <c>.database.cloudapi.de</c>, <c>.database.usgovcloudapi.net</c>, <c>.database.chinacloudapi.cn</c>, or <c>.database.fabric.microsoft.com</c>), when the <c>Authentication</c> 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 <c>AccessToken</c> is set. For these automatic conditions, an explicit <c>TransparentNetworkIPResolution</c> value bypasses the automatic behavior: <c>True</c> enables TNIR, and <c>False</c> disables TNIR unconditionally. To restore the automatic behavior, remove the keyword from the connection string.
        </para>
        <para>
          On .NET (Core, .NET 5+), <c>TransparentNetworkIPResolution</c> isn't a recognized connection-string keyword. Setting it (with any value) throws <c>ArgumentException</c> (<c>KeywordNotSupported</c>) when the driver parses the connection string.
        </para>

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml:1024

• This row describes TNIR as "trying one address at a time" and says it is ignored for Entra ID auth / AccessToken, but the .NET Framework implementation uses a sequential first attempt followed by parallel attempts (TdsParser.Connect sets TransparentNetworkResolutionState.SequentialMode only for the first attempt, otherwise ParallelMode) and it only auto-disables TNIR for Azure endpoints / federated auth when the keyword is NOT explicitly present in the connection string (SqlConnectionInternal.ShouldDisableTnir checks Parsetable.ContainsKey(...)). The wording should be adjusted to match the actual behavior and avoid implying the keyword is always ignored.

|Transparent Network IP Resolution<br /><br /> -or-<br /><br />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.<br /><br /> If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.<br /><br /> If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.<br /><br /> 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.<br /><br /> 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.<br /><br /> The value of this key must be `true`, `false`, `yes`, or `no`.<br /><br /> A value of `yes` is treated the same as a value of `true`.<br /><br /> A value of `no` is treated the same as a value of `false`.|

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

• The summary says TNIR tries one address at a time for multiple rounds, but the implementation uses a sequential first attempt and then switches to parallel mode for subsequent attempts (TdsParser.Connect sets TransparentNetworkResolutionState.SequentialMode only for the first attempt, otherwise ParallelMode). The wording here should reflect the sequential-first / parallel-after behavior.

        On .NET Framework, when the value of this key is set to <see langword="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 <c>Connect Timeout</c> is reached.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml:1024

• This row says TNIR works by "trying one address at a time" with a 500 ms floor on the "first attempt". In netfx, TNIR has distinct sequential vs parallel modes (first attempt sequential, subsequent attempts parallel) as described by TransparentNetworkResolutionState (TdsEnums.cs) and selected in TdsParser.Connect. Consider updating this opening sentence so it doesn’t imply TNIR remains sequential for all rounds.

|Transparent Network IP Resolution<br /><br /> -or-<br /><br />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.<br /><br /> If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.<br /><br /> If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.<br /><br /> 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.<br /><br /> 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.<br /><br /> The value of this key must be `true`, `false`, `yes`, or `no`.<br /><br /> A value of `yes` is treated the same as a value of `true`.<br /><br /> A value of `no` is treated the same as a value of `false`.|

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

• The summary describes TNIR as "trying one address at a time" with a 500 ms floor on the "first attempt", but the implementation uses distinct sequential vs parallel TNIR modes (first attempt sequential, subsequent attempts parallel) via TransparentNetworkResolutionState (TdsEnums.cs) and TdsParser.Connect. As written, the summary reads like TNIR stays sequential for all rounds and may mislead about later parallel attempts.

        On .NET Framework, when the value of this key is set to <see langword="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 <c>Connect Timeout</c> is reached.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

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

• This summary calls “the default”, but TNIR can be automatically disabled when the keyword is not present (Azure SQL endpoint / Entra ID / AccessToken), making the effective default conditional. Dropping “(the default)” avoids implying TNIR is always enabled by default.

        On .NET Framework, when the value of this key is set to <see langword="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 <c>Connect Timeout</c> is reached.

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml:1024

• This row (1) describes true as “the default” even though TNIR is automatically disabled in some cases when the keyword is absent, (2) lists Entra ID Authentication values in an abbreviated form that doesn’t match the accepted connection-string values (e.g., “Active Directory Integrated”, “Active Directory MSI”), and (3) states “The value of this key must be …” without scoping it to .NET Framework even though the preceding sentence says the keyword is not recognized on modern .NET. Tweaking the wording to remove ambiguity keeps the table consistent and copy/paste-safe.

|Transparent Network IP Resolution<br /><br /> -or-<br /><br />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.<br /><br /> If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.<br /><br /> If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.<br /><br /> 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.<br /><br /> 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.<br /><br /> The value of this key must be `true`, `false`, `yes`, or `no`.<br /><br /> A value of `yes` is treated the same as a value of `true`.<br /><br /> A value of `no` is treated the same as a value of `false`.|

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

• The list of Microsoft Entra ID authentication methods is written in abbreviated form (e.g., “Integrated”, “MSI”, “Default”), but the driver’s accepted Authentication connection-string values are the full strings (for example “Active Directory Integrated”, “Active Directory MSI”, “Active Directory Default”, etc.; see DbConnectionStringUtilities.cs). Using the exact values prevents users from copy/pasting a value that won’t parse.

          On .NET Framework, if <c>TransparentNetworkIPResolution</c> isn't specified in the connection string, the driver automatically disables TNIR when the data source is an Azure SQL endpoint (<c>.database.windows.net</c>, <c>.database.cloudapi.de</c>, <c>.database.usgovcloudapi.net</c>, <c>.database.chinacloudapi.cn</c>, or <c>.database.fabric.microsoft.com</c>), when the <c>Authentication</c> 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 <c>AccessToken</c> is set. For these automatic conditions, an explicit <c>TransparentNetworkIPResolution</c> value bypasses the automatic behavior: <c>True</c> enables TNIR, and <c>False</c> disables TNIR unconditionally. To restore the automatic behavior, remove the keyword from the connection string.

[dlevy-msft-sql]

@dotnet-policy-service agree company="Microsoft"

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

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

• The docs mention "KeywordNotSupported" in parentheses, but that's an internal resource/helper identifier rather than a user-visible exception type. Public docs should generally state the exception type (ArgumentException) without exposing internal string/resource names.

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

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml:1024

• This row describes the 500 ms minimum as being on the "first attempt" and also references "KeywordNotSupported". In the current .NET Framework implementation the 500 ms floor is tied to the attempt treated as the sequential TNIR attempt, and "KeywordNotSupported" is an internal resource/helper name (not a public exception type). Consider rewording both phrases for accuracy and to avoid leaking internal identifiers.

|Transparent Network IP Resolution<br /><br /> -or-<br /><br />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.<br /><br /> If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.<br /><br /> If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.<br /><br /> 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.<br /><br /> 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.<br /><br /> On .NET Framework, the value of this key must be `true`, `false`, `yes`, or `no`.<br /><br /> A value of `yes` is treated the same as a value of `true`.<br /><br /> A value of `no` is treated the same as a value of `false`.|

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

• The summary says the 500 ms minimum applies on the "first attempt", but the current .NET Framework implementation applies the 500 ms floor only for the attempt flagged as the sequential TNIR attempt (see LoginNoFailover's isFirstTransparentAttempt + MinimumTimeoutForTnirMs). Rewording avoids documenting a specific attempt order that doesn't match the implementation.

        On .NET Framework, when the value of this key is set to <see langword="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 <c>Connect Timeout</c> is reached.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

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

• The remark mentions "AccessToken" as if it were a connection-string keyword, but SqlClient's TNIR auto-disable check is based on the connection's SqlConnection.AccessToken property (there is no AccessToken connection-string keyword). This wording can confuse readers of a connection-string keyword doc block.

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

doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml:1024

• This connection-string keyword table row says "or if AccessToken is set", which reads like AccessToken is a connection-string keyword. In the implementation, the TNIR auto-disable condition is based on the SqlConnection.AccessToken property being set (there is no AccessToken connection-string keyword). Clarifying this avoids misleading readers.

|Transparent Network IP Resolution<br /><br /> -or-<br /><br />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.<br /><br /> If the `MultiSubnetFailover` key is set to `true`, `TransparentNetworkIPResolution` is ignored.<br /><br /> If the `Failover Partner` key is set, `TransparentNetworkIPResolution` is ignored.<br /><br /> 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.<br /><br /> 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.<br /><br /> On .NET Framework, the value of this key must be `true`, `false`, `yes`, or `no`.<br /><br /> A value of `yes` is treated the same as a value of `true`.<br /><br /> A value of `no` is treated the same as a value of `false`.|