通过

SqlClient 中的 AppContext 开关

适用于： .NET Framework .NET .NET Standard

下载 ADO.NET

AppContext 类允许 SqlClient 提供新的功能，同时继续支持依赖于先前行为的调用方。 用户可通过设置特定的 AppContext 开关来选择退出一种行为更改。

默认启用 MultiSubnetFailover

适用于：.NET Framework;.NET;.NET Standard

（从版本 7.0 开始可用）

若要全局设置 MultiSubnetFailover=true 而不修改单个连接字符串，可以在应用程序启动时将 AppContext 开关 “Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault” 设置为 true ：

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

还可以在 App.Config 中启用此开关：

<runtime>
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>

启用后，所有连接的行为就像连接字符串中设置了 MultiSubnetFailover=true 参数一样。 默认情况下，此开关处于禁用状态。

为异步读取启用数据包复用

适用于：.NET Framework;.NET;.NET Standard

（从版本 7.0 开始可用）

数据包多路复用可提高大型异步读取操作的性能，例如 ExecuteReaderAsync 使用大型结果集、流式处理方案或批量数据检索。 此功能由两个选择加入 AppContext 开关控制。 将两个开关设置为 false 启用新的异步处理路径：

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

默认情况下，这两个开关都保留在true位置，从而保留现有（兼容）的行为。

启用用户代理功能扩展

适用于：.NET Framework;.NET;.NET Standard

（从版本 7.0 开始可用）

启用 AppContext 开关 “Switch.Microsoft.Data.SqlClient.EnableUserAgent” 时，驱动程序会将用户代理详细信息作为连接的一部分发送到服务器。 此信息有助于按版本和操作系统对驱动程序使用情况进行故障排除和量化。 默认情况下，此开关处于禁用状态。 若要启用它，请在应用程序启动时将 AppContext 开关设置为 true ：

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

启用小数截断行为

适用于：.NET Framework;.NET;.NET Standard

从 Microsoft.Data.SqlClient 2.0 开始，与 SQL Server 一样，小数数据默认四舍五入。 若要启用之前的截断行为，可以在应用程序启动时将 AppContext 开关“Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal”设置为 true：

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

在 Windows 上启用托管网络

适用于：.NET; .NET Standard

（仅从版本 2.0 开始可用）

在 Windows 上，SqlClient 默认使用 SNI 网络接口的本机实现。 若要支持使用托管 SNI 实现，可在应用程序启动时将 AppContext 开关“Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows”设置为 ：

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

此开关会切换驱动程序的行为，以便在 Windows 上的 .NET Core 2.1+ 和 .NET Standard 2.0+ 项目中使用托管的网络实现，从而消除对 Microsoft.Data.SqlClient 库的本机库的所有依赖项。 仅用于测试和调试目的。

注意

与本机实现相比，两者存在一些已知的差异。 例如，托管实现不支持非域 Windows 身份验证。

禁用透明网络 IP 解析

适用于：.NET Framework

透明网络 IP 解析 (TNIR) 是对现有 MultiSubnetFailover 功能的修订。 如果第一个解析的主机名 IP 未响应，且存在多个与主机名关联的 IP，TNIR 就会影响驱动程序的连接序列。 TNIR 与 MultiSubnetFailover 交互，以提供下列三个连接序列：

  • 0：先尝试一个 IP，再并行尝试所有 IP
  • 1：并行尝试所有 IP
  • 2:逐一尝试所有 IP
透明网络IP解析 MultiSubnetFailover 行为
真 真 1
真 假 0
假 为真 1
假 假 2

TransparentNetworkIPResolution 默认处于启用状态。 MultiSubnetFailover 默认处于禁用状态。 若要禁用 TNIR，可在应用程序启动时将 AppContext 开关“Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString”设置为 true：

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

有关设置这些属性的详细信息，请参阅 SqlConnection.ConnectionString 属性文档。

在登录期间启用最小超时

适用于：.NET Framework;.NET;.NET Standard

若要防止登录尝试无期限等待，可在应用程序启动时将 AppContext 开关“Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin”设置为 true：

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

禁用 ReadAsync 的阻止行为

适用于：.NET Framework;.NET;.NET Standard

从版本 3.0 开始，ReadAsync 以异步方式运行。 以前的版本以同步方式运行 ReadAsync，并阻止 .NET Framework 上的调用线程。 若要控制此阻止行为，可在应用程序启动时将 AppContext 开关“Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking”设置为 或 true：

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

启用行版本 null 行为

适用于：.NET Framework;.NET;.NET Standard

从版本 3.0 开始，当行版本的值为 null 时，SqlDataReader 会返回 DBNull 值而不是空的 byte[]。 要启用返回空占位符byte[]的旧版行为，请在应用程序启动时启用 AppContext 开关 Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior。

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

禁止显示不安全的 TLS 警告

适用于：.NET Framework;.NET;.NET Standard

（从版本 4.0.1 开始可用）

在连接字符串中使用 Encrypt=false 时，如果 TLS 版本为 1.2 或更低版本，则安全警告将输出到控制台。 可以通过在应用程序启动时启用以下 AppContext 开关来禁止显示此警告：

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

忽略服务器指定的故障切换伙伴

适用于：.NET Framework;.NET;.NET Standard

（从版本 5.1.8、6.0.4 和 6.1.3 开始可用）

故障转移后，服务器提供的故障转移伙伴信息优先于连接字符串中提供的故障转移伙伴信息。 若要忽略服务器提供的故障转移伙伴信息，并且只考虑连接字符串中提供的故障转移伙伴信息，请启用应用程序启动时的此 AppContext 开关：

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

另请参阅

AppContext 类

  • Last updated on