Microsoft.Data.SqlClient 的连接选项

本文列出了Microsoft.所有的连接字符串关键字。Data.SqlClient 接受。 每个关键词也有一个匹配 SqlConnectionStringBuilder 的属性。 关于介绍、常见模式和解析规则，请参见 连接字符串。

关键词和别名不区分大小写。 当你通过建筑商物业设置价值时，建筑商会在 关键词 栏中写入规范关键词。

使用 SqlConnectionStringBuilder 设置选项

从一个包含服务器、数据库和认证设置的基础连接字符串开始。 然后通过建筑物属性设置工作负载特定的选项。 .NET 框架标签页使用 C# 7.3。 要创建运行样本的项目，请参见 “创建项目”。

.NET

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

.NET 框架

using System;
using System.Threading.Tasks;
using Microsoft.Data.SqlClient;

class Program
{
    static async Task Main()
    {
        string connectionString =
            Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
            ?? throw new InvalidOperationException(
                "Set the SQL_CONNECTION_STRING environment variable.");

        var builder = new SqlConnectionStringBuilder(connectionString)
        {
            ApplicationName = "Orders.Worker",
            ConnectTimeout = 30,
            CommandTimeout = 60,
            MaxPoolSize = 50,
        };

        using (var connection = new SqlConnection(builder.ConnectionString))
        {
            await connection.OpenAsync();

            using (var command = new SqlCommand("SELECT APP_NAME();", connection))
            {
                Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
                Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
                Console.WriteLine($"Command timeout: {command.CommandTimeout}");
            }
        }
    }
}

输出为：

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

新建 SqlCommand 的超时时间取自 Command Timeout 其连接的关键词。

检查默认值

新用户 SqlConnectionStringBuilder 报告每个选项的默认值。 该程序打印大多数应用程序会审查的默认值：

.NET

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

.NET 框架

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        var defaults = new SqlConnectionStringBuilder();

        Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
        Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
        Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
        Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
        Console.WriteLine($"Encrypt: {defaults.Encrypt}");
        Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
        Console.WriteLine($"Pooling: {defaults.Pooling}");
        Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
        Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
        Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
        Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
        Console.WriteLine($"Packet Size: {defaults.PacketSize}");
        Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
        Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
        Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
        Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
        Console.WriteLine($"Application Name: {defaults.ApplicationName}");
        Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
        Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
    }
}

在 .NET 上，输出为：

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True 这是选项 Mandatory 。 在 .NET 框架中，默认应用程序名称为 Framework Microsoft SqlClient Data Provider。

服务器和数据库选项

关键 字	Aliases	建筑物业	默认	说明
Data Source	Server、Address、Addr、Network Address	DataSource	空	连接服务器。 接受主机名、 host,port、 host\instance、 (localdb)\instance和 tcp: 协议 np: 前缀 或 。 关于被接受的表单，请参见 “指定服务器和数据库”。
Initial Catalog	Database	InitialCatalog	空	登录后使用的数据库。 当它为空时，服务器会使用登录的默认数据库。
AttachDbFilename	Extended Properties、Initial File Name	AttachDBFilename	空	主数据库文件的完整路径，用于SQL Server Express和LocalDB。
User Instance	None	UserInstance	false	将连接重定向到 SQL Server Express 用户实例。 欲了解更多信息，请参见 SQL Server Express 用户实例。
Failover Partner	FailoverPartner	FailoverPartner	空	当主服务器不可用时，数据库镜像合作伙伴尝试。 数据库镜像已被弃用。 对于新的部署，请使用可用性组。
Current Language	Language	CurrentLanguage	空	会话的 SQL Server 语言名称，例如 us_english。 控制日期格式和系统消息语言。

应用身份选项

关键 字	Aliases	建筑物业	默认	说明
Application Name	App	ApplicationName	Core Microsoft SqlClient Data Provider	服务器通过会话视图和报告 APP_NAME() 的名称。 每个部署的工作负载使用一个稳定名称。 不同的值会创造不同的连接池。
Workstation ID	WorkstationID、WSID	WorkstationID	本地计算机名称	服务器通过 HOST_NAME()报告的客户端计算机名称。
Application Intent	ApplicationIntent	ApplicationIntent	ReadWrite	ReadOnly 当目标支持时请求读意图路由。 它不会让语句变成只读。 更多信息请参见 高可用性和灾难恢复。

要报告是哪个框架或工具打开了连接，请使用该 RegisteredApplication 属性。 它没有 连接字符串 关键字。 欲了解更多信息，请参见 报告应用身份。

身份验证选项

关键 字	Aliases	建筑物业	默认	说明
Authentication	None	Authentication	未指定	身份验证方法。 关于公认值，请参见下表。
Integrated Security	Trusted_Connection	IntegratedSecurity	false	true yes， ， 或sspi使用当前进程的身份。
User ID	UID、User	UserID	空	SQL 登录名，或 Microsoft Entra ID 用户或客户端标识符，具体取决于 Authentication。
Password	PWD	Password	空	密码或客户端秘密，适用于接受密码的方法。
Persist Security Info	PersistSecurityInfo	PersistSecurityInfo	false	当 false时，驱动在连接打开后移除密码 SqlConnection.ConnectionString 。 别管了 false。
Server SPN	ServerSPN	ServerSPN	派生自服务器名称	替代用于主服务器集成身份验证的服务主体名称 (SPN)。
Failover Partner SPN	FailoverPartnerSPN	FailoverPartnerSPN	源自合伙人名称	覆盖用于集成认证的SPN对故障切换伙伴。

Authentication 接受这些价值观。 构建者写出时不加空格，如 ActiveDirectoryDefault，解析器接受这两种形式。

Value	Identity
Sql Password	一个带有 User ID 和 Password的 SQL 登录。
Active Directory Default	一连串凭证源，如环境变量、管理身份和开发者工具登录。
Active Directory Managed Identity	一个可管理的身份。 设置为 User ID 用户分配身份的客户端ID。 Active Directory MSI 是别名。
Active Directory Workload Identity	Kubernetes 工作负载身份。
Active Directory Service Principal	一个应用程序， User ID 设置为客户端 ID 和 Password 设置为客户端秘密。
Active Directory Interactive	一个通过浏览器提示登录的用户。
Active Directory Device Code Flow	一个用代码登录另一台设备的用户。
Active Directory Integrated	登录的 Windows 用户通过联邦或无缝单点登录配置实现。
Active Directory Password	用户名和密码。 此方法已过时。 用别的方法。

Microsoft Entra ID 的方法需要该Microsoft.Data.SqlClient.Extensions.Azure软件包。 有关设置和示例，请参见 Microsoft Entra ID 认证和 SQL Server 认证。

加密选项

关键 字	Aliases	建筑物业	默认	说明
Encrypt	None	Encrypt	Mandatory	Strict 使用 TDS 8.0，并且始终验证服务器证书。 Mandatory， ， true或 yes 加密连接。 Optional， false或者 no 只有在服务器需要时才加密整个连接。 当服务器支持加密但不强制时，只有登录包被加密。
Trust Server Certificate	TrustServerCertificate	TrustServerCertificate	false	true 跳过服务器证书验证。 当Encrypt=Strict时，将被忽略。 请勿在生产环境中使用它。
Host Name In Certificate	HostNameInCertificate	HostNameInCertificate	空	作为证书验证的备用名称。 SqlClient 首先验证该证书与服务器名称的 Data Source关系。 它只在名称不匹配时检查 Host Name In Certificate ，所以当服务器名称匹配时，错误值不会导致失败。 它不会为证书提供固定。 如需特定证书，请使用 Server Certificate。 它不会改变网络目的地，也不会绕过信任链和到期日检查。 当服务器名称已经与证书匹配时，保持未设置。
Server Certificate	ServerCertificate	ServerCertificate	空	PEM、DER或CER文件的路径必须与服务器证书完全匹配。 司机只有在验证证书时才会检查匹配，因此使用与 Encrypt=Mandatory 或 Encrypt=StrictTrust Server Certificate=false和 的匹配。 匹配文件取代了链名和主机名验证，因此它与客户端不信任的自签名证书工作。

完整的验证规则请参见 加密与证书验证。

始终加密选项

关键 字	Aliases	建筑物业	默认	说明
Column Encryption Setting	ColumnEncryption	ColumnEncryptionSetting	Disabled	Enabled 开启连接时的“始终加密”。
Attestation Protocol	None	AttestationProtocol	未指定	飞地认证协议： AAS， ， HGS或 None。
Enclave Attestation Url	None	EnclaveAttestationUrl	空	Always Encrypted 的安全隔区认证服务端点。

网络选项

关键 字	Aliases	建筑物业	默认	说明
Multi Subnet Failover	MultiSubnetFailover	MultiSubnetFailover	false	尝试并行解析服务器名称的所有IP地址。 它用于可用性组监听器和通过TCP访问的故障转移集群实例。 不支持数据库镜像。 命名实例取决于网络实现。 托管实现（.NET 在 Linux 和 macOS 以及 Windows 上运行托管网络时）支持命名实例，并并行向每个解析地址发送 SQL Server 浏览器请求。 Windows 的原生实现可以拒绝带有 SNI 错误 48 的命名实例。
IP Address Preference	IPAddressPreference	IPAddressPreference	IPv4First	尝试解析地址的顺序为： IPv4First、、 IPv6First或 UsePlatformDefault。
Packet Size	PacketSize	PacketSize	8000	表式数据流（TDS）数据包大小（字节）范围为512至32,768。

进程范围的 AppContext 开关可以将默认值 Multi Subnet Failover 更改为 true。 更多信息请参见 SqlClient 中的 AppContext 切换。

暂停选项

关键 字	Aliases	建筑物业	默认	说明
Connect Timeout	Connection Timeout、ConnectTimeout、Timeout	ConnectTimeout	15	等待连接的时间是几秒钟，包括等待池满时的池状连接。 0 无限期等待。
Command Timeout	None	CommandTimeout	30	连接上创建的命令 CommandTimeout 默认值，每秒计。 0 无限期等待。

Connect Timeout 不限制查询执行。 Command Timeout 这不限制登录或等待合并连接的时间。 将a CancellationToken 传递给异步调用，使呼叫者在任一超时结束前停止等待。

连接恢复选项

关键 字	Aliases	建筑物业	默认	说明
Connect Retry Count	ConnectRetryCount	ConnectRetryCount	1	在第一次开放赛中出现排位赛暂时故障后，以及恢复断裂的怠速连接时进行重试。 0 关闭重试。 有效值为 0 到 255。
Connect Retry Interval	ConnectRetryInterval	ConnectRetryInterval	10	重试之间有几秒钟。 有效数值为1到60。

当 Connect Retry Count 是 1，即默认时，驱动会用于 Azure SQL 端点，而5对于 Azure Synapse Analytics 的无服务器 SQL 池端点，当它恢复了损坏的空闲连接时。2 第一次打开使用设置值，默认允许每个端点重试一次。 驱动程序在两种情况下都使用其他设定值。

这些关键词不会在命令运行时重试失败的命令。 要跳过一个开局的内置重试，调用 Open 一个带有 OpenWithoutRetry的超载。 关于自定义策略，请参见 可配置重试逻辑。 只有在安全重复命令时才重试。

池化选项

关键 字	Aliases	建筑物业	默认	说明
Pooling	None	Pooling	true	重用物理连接以匹配连接字符串。
Min Pool Size	None	MinPoolSize	0	池创建后保持开放的物理连接。
Max Pool Size	None	MaxPoolSize	100	一个池子里最多的物理连接。 必须至少为 1。
Connection Idle Timeout	None	IdleTimeout	300	连接可以在泳池关闭前保持闲置的秒数。 0 关闭怠速过期。 仅在 Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext切换为 false时强制执行。 该名称默认为 true。
Load Balance Timeout	Connection Lifetime	LoadBalanceTimeout	0	连接时的最大年龄（秒数）返回到池中。 一个较旧的连接已关闭。 0 关闭了限速。
Pool Blocking Period	PoolBlockingPeriod	PoolBlockingPeriod	Auto	池是否会在短时间内重新抛出缓存登录失败： Auto、、 AlwaysBlock或 NeverBlock。 Auto关闭阻挡 for Azure SQL endpoints.

每个不同的连接字符串都有自己的池。 关于池密钥、清除和空闲时间，请参见 SQL Server 连接池。

交易和会话选项

关键 字	Aliases	建筑物业	默认	说明
Enlist	None	Enlist	true	在业务开启时将连接列入环境 System.Transactions 事务。
Transaction Binding	None	TransactionBinding	Implicit Unbind	Implicit Unbind 当列兵事务结束时，连接断开。 Explicit Unbind 保持连接连接，直到连接关闭或代码将其断开。
Multiple Active Result Sets	MultipleActiveResultSets	MultipleActiveResultSets	false	允许一个连接上有多个活跃批次。
Type System Version	None	TypeSystemVersion	Latest	驱动暴露的服务器类型系统。 接受 Latest、 SQL Server 2012、 SQL Server 2008和 SQL Server 2005。 请留言。Latest
Replication	None	Replication	false	将连接标识为复制连接。

仅限.NET框架选项

这些关键词仅在 .NET 框架上被接受。 在.NET上，建造者不断NotSupportedExceptionSqlConnectionArgumentException抛掷。

关键 字	Aliases	建筑物业	默认	说明
Network Library	Net、Network	NetworkLibrary	空	网络图书馆。 不要把它和 a tcp: 或 np: 前缀 合并 Data Source，因为连接会失败。 在 .NET 上，前Data Source缀用 tcp: 或 np: 代替。
Connection Reset	None	ConnectionReset	true	Obsolete.
Transparent Network IP Resolution	TransparentNetworkIPResolution	TransparentNetworkIPResolution	true	Obsolete.

不支持的关键词

关键 字	Result
Context Connection	Context Connection=true 投掷 InvalidOperationException。 Microsoft。Data.SqlClient 不支持 SQL CLR 上下文连接。
Asynchronous Processing	引发 ArgumentException: Keyword not supported。 异步方法无需它也能工作。
Driver、Provider	引发 ArgumentException: Keyword not supported。 这些关键词属于ODBC和OLE DB。

验证规则

SqlConnectionStringBuilder 设置时会拒绝未知关键词和许多无效值。 SqlConnection设置 连接字符串 时会进行更多检查，包括构建者接受的单个值和关键词组合。 建造者接受的弦在建立连接时仍可能失效。

建构者和连接拒绝这些值，满足 ArgumentException：

• Connect Timeout， Command Timeout， Load Balance Timeout， Connection Idle Timeout， 或 Min Pool Size 小于0。
• Max Pool Size 少于1。
• Packet Size 512号外，32,768号。
• Connect Retry Count 外侧0到255。
• Connect Retry Interval 1至60号外侧。
• 这是本文中没有的关键词。

SqlConnection 也拒绝这些值，尽管 ArgumentException建造者接受：

• Type System Version 除 Latest、 SQL Server 2012、 SQL Server 2008、 或 SQL Server 2005之外。
• Transaction Binding 除 Implicit Unbind 或 Explicit Unbind外。
• 对于 、 、 Data Source、 PasswordFailover PartnerInitial CatalogUser ID、 、 或 Workstation IDAttachDBFilename，的 TDS 限制Application Name，这个值要长于 。 Current Language

SqlConnection 也拒绝这些组合，满足 ArgumentException：

• Min Pool Size 大于 Max Pool Size。
• Failover Partner 没有 Initial Catalog。
• Failover Partner 替换为 Multi Subnet Failover=true、 User Instance=true或 Application Intent=ReadOnly。
• 带 Authentication 的 Integrated Security=true。
• Password 其中 Active Directory Integrated， Active Directory Interactive， Active Directory Managed Identity， Active Directory MSI， Active Directory Default， ， 或 Active Directory Workload Identity。
• User ID或 Password 。Active Directory Device Code Flow

查看选项更改

在你更改生产选项之前：

1. 记录当前的连接字符串、驱动版本、端点类型以及你正在解决的问题。
2. 一次只改变一个选项。
3. 测试连接建立、认证、证书验证、池化、故障切换、取消和查询执行。
4. 测量连接延迟、池等待和错误数值。
5. 确认每个部署实例的设置。

更改的 连接字符串 会创建一个新的 pool。 在分阶段部署期间，旧池和新池同时存在，因此服务器的物理连接总数可能会增加。

相关内容

• 连接字符串
• 连接字符串生成器
• 连接到数据源
• SQL Server 连接池
• 加密和证书验证