AppContext switches in Sqlclient

Download ADO.NET

The AppContext class allows SqlClient to provide new functionality while continuing to support callers who depend on the previous behavior. Users can opt out of a change in behavior by setting specific AppContext switches.

Enabling decimal truncation behavior

Applies to: .NET Framework .NET .NET Standard

Starting with Microsoft.Data.SqlClient 2.0, decimal data is rounded by default, as is done by SQL Server. To enable the previous behavior of truncation, you can set the AppContext switch "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" to true at application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

Enabling managed networking on Windows

Applies to: .NET Framework .NET Core .NET Standard

(Available starting with version 2.0)

On Windows, SqlClient uses a native implementation of the SNI network interface by default. To enable the use of a managed SNI implementation, you can set the AppContext switch "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows" to true at application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

This switch toggles the driver's behavior to use a managed networking implementation in .NET Core 2.1+ and .NET Standard 2.0+ projects on Windows, eliminating all dependencies on native libraries for the Microsoft.Data.SqlClient library. It is for testing and debugging purposes only.

Disabling Transparent Network IP Resolution

Applies to: .NET Framework .NET Core .NET Standard

Transparent Network IP Resolution (TNIR) is a revision of the existing MultiSubnetFailover feature. TNIR affects the connection sequence of the driver in the case where the first resolved IP of the hostname doesn't respond and there are multiple IPs associated with the hostname. TNIR interacts with MultiSubnetFailover to provide the following three connection sequences:

• 0: One IP is attempted, followed by all IPs in parallel
• 1: All IPs are attempted in parallel
• 2: All IPs are attempted one after another

TransparentNetworkIPResolution is enabled by default. MultiSubnetFailover is disabled by default. To disable TNIR, you can set the AppContext switch "Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString" to true at application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);

For more information about setting these properties, see the documentation for SqlConnection.ConnectionString Property.

Enable a minimum timeout during login

Applies to: .NET Framework .NET .NET Standard

To prevent a login attempt from waiting indefinitely, you can set the AppContext switch Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin to true at application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);

Disable blocking behavior of ReadAsync

Applies to: .NET Framework .NET .NET Standard

Starting in version 3.0, ReadAsync runs asynchronously. Previous versions run ReadAsync synchronously and block the calling thread on .NET Framework. To control this blocking behavior, you can set the AppContext switch Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking to true or false at application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);

Enabling rowversion null behavior

Applies to: .NET Framework .NET .NET Standard

Starting in version 3.0, when a rowversion has a value of null, SqlDataReader returns a DBNull value instead of an empty byte[]. To enable the legacy behavior of returning an empty byte[], enable the AppContext switch Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior on application startup.

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);

Suppress insecure TLS warning

Applies to: .NET Framework .NET .NET Standard

(Available starting with version 4.0.1)

When using Encrypt=false in the connection string, a security warning is output to the console if the TLS version is 1.2 or lower. This warning can be suppressed by enabling the following AppContext switch on application startup:

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);

See also

AppContext Class