Deprecate TransparentNetworkIPResolution

[cheenamalhotra]

Description

Addresses #4494

TransparentNetworkIPResolution (TNIR) is the more error-prone of two overlapping "connect faster across multiple DNS-resolved IPs" strategies. It is only available on .NET Framework (setting it on modern .NET throws ArgumentException), and even on .NET Framework the driver already silently ignores it for Azure SQL endpoints, any Microsoft Entra ID auth method, and AccessToken. MultiSubnetFailover covers the same goal, works consistently on all target frameworks, and is the documented strategy for Always On availability group listeners.

This PR takes the first, non-breaking step of the staged deprecation described in #4494: it marks the API obsolete and documents the recommended alternative.

What this changes:

• Adds [Obsolete] to SqlConnectionStringBuilder.TransparentNetworkIPResolution in both the implementation and the reference assembly. The message points callers at MultiSubnetFailover and notes that TNIR is .NET Framework-only.
• Suppresses the resulting CS0618 at the two internal call sites in SqlConnectionStringBuilder (the GetAt and SetValue keyword dispatch) and in the netfx-gated tests that set the property. These are internal plumbing that must keep working for the keyword to function at all, so suppression is the correct treatment rather than removal.
• Documents the deprecation in the SqlConnection and SqlConnectionStringBuilder doc snippets.

Explicitly out of scope: no behavior changes. Connection string defaults are untouched. TNIR still defaults to true on .NET Framework and MultiSubnetFailover still defaults to false. No new AppContext switches are introduced. Flipping those defaults, along with the associated compatibility switches, is deferred to a future major version so this change carries no runtime risk and no migration burden.

The only reviewer-visible consequence is a new build warning for consumers who reference the property. That is the intended signal for a staged deprecation, and callers can suppress it or migrate to MultiSubnetFailover at their own pace.

Issues

Partially addresses #4494 (item 1: mark TNIR obsolete on the public API surface). Items 2 and 3 of that issue, flipping the TNIR and MultiSubnetFailover defaults, are intentionally not included here.

Testing

No new tests were added, which is appropriate here: this change adds no new runtime behavior to cover. An [Obsolete] attribute is a compile-time signal, and the existing test suite already validates that the keyword continues to parse and round-trip correctly. Those existing tests now double as a regression check that the attribute did not break the keyword.

Validation performed:

• Microsoft.Data.SqlClient builds clean for net8.0 with 0 warnings and 0 errors. The repository sets TreatWarningsAsErrors=true, so the pragma placement is confirmed correct for the paths that compile on this host.
• Targeted unit tests pass (SqlConnectionOptionsTest, LocalAppContextSwitchesTest).
• Broader unit and functional runs were diffed against a stashed baseline of the same tree. Failures are identical before and after, so there are no regressions. The remaining failures are pre-existing and Windows-specific (certificate store and DataDirectory path tests) on this macOS dev machine.

Gap worth flagging for review: net462 cannot be compiled on macOS, so the #pragma warning disable 618 suppressions added inside #if NETFRAMEWORK blocks (the builder call sites and the netfx-gated test usages) are unverified locally and rely on CI to confirm.

Guidelines

Please review the contribution guidelines before submitting a pull request:

• Contributing
• Code of Conduct
• Best Practices
• Coding Style
• Review Process

[Copilot]

Pull request overview

This PR implements the first (non-breaking) step of deprecating Transparent Network IP Resolution (TNIR) by marking SqlConnectionStringBuilder.TransparentNetworkIPResolution obsolete on the .NET Framework-only API surface, suppressing resulting internal/test build warnings, and updating documentation to recommend MultiSubnetFailover.

Changes:

• Marked SqlConnectionStringBuilder.TransparentNetworkIPResolution as obsolete in the implementation and reference assembly.
• Added targeted CS0618 suppressions at internal keyword-dispatch call sites and in netfx-gated tests that set the property.
• Updated doc snippets to label TNIR as deprecated and point to Multi Subnet Failover / MultiSubnetFailover.

Reviewed changes

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

Show a summary per file

File	Description
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseRaceDeadlockTest.cs	Suppresses obsolete warnings for TNIR usage in netfx-gated simulated server deadlock test setup.
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseHandshakeCancellationTest.cs	Suppresses obsolete warnings for TNIR usage in netfx-gated handshake cancellation test setup.
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/SNICloseDeadlockTest.cs	Suppresses obsolete warnings for TNIR usage in multiple netfx-gated simulated server deadlock scenarios.
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs	Suppresses obsolete warnings for TNIR usage in simulated server connection tests.
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionRoutingTests.cs	Suppresses obsolete warnings for TNIR usage in routing-related simulated server tests.
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionFailoverTests.cs	Suppresses obsolete warnings for TNIR usage in simulated failover tests.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs	Adds [Obsolete] to the TNIR property and suppresses CS0618 in internal keyword dispatch.
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs	Updates the reference assembly surface with ObsoleteAttribute for the TNIR property (netfx-only).
doc/snippets/Microsoft.Data.SqlClient/SqlConnectionStringBuilder.xml	Documents TNIR as obsolete and recommends MultiSubnetFailover, including the modern-.NET unsupported behavior note.
doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml	Labels TNIR keyword as deprecated and recommends Multi Subnet Failover in the connection string keyword table.

Suppressed comments (1)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlConnectionStringBuilder.cs:1090

• In the keyword setter dispatch, the added #pragma warning disable 618 around TransparentNetworkIPResolution doesn’t include a rationale comment (unlike the existing // Obsolete properties suppression just above). Please add a brief comment (or refactor the suppression scope) to document why CS0618 must be suppressed in this internal keyword plumbing.

#if NETFRAMEWORK
#pragma warning disable 618 // Obsolete properties
                        case Keywords.ConnectionReset:
                            ConnectionReset = ConvertToBoolean(value);
                            break;
#pragma warning restore 618
                        case Keywords.NetworkLibrary:
                            NetworkLibrary = ConvertToString(value);
                            break;
                        case Keywords.TransparentNetworkIPResolution:
#pragma warning disable 618
                            TransparentNetworkIPResolution = ConvertToBoolean(value);
#pragma warning restore 618

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

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

• In the new note, the sentence “Transparent Network IP Resolution is supported only on .NET Framework; on .NET the keyword is not recognized …” is a bit ambiguous in this property’s docs (the property itself is NETFRAMEWORK-only). Consider rewording to explicitly refer to the connection-string keyword usage on .NET (e.g., “If the keyword is present in a connection string on .NET, it is not recognized and throws ArgumentException.”) to avoid implying the property exists but is unsupported on .NET.

        <para>
          This property is obsolete. Use <see cref="P:Microsoft.Data.SqlClient.SqlConnectionStringBuilder.MultiSubnetFailover" /> instead. Transparent Network IP Resolution is supported only on .NET Framework; on .NET the keyword is not recognized and throws an <see cref="T:System.ArgumentException" />.
        </para>

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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