Microsoft。Data.SqlClient 连接选项控制驱动程序如何建立、识别、路由、重试和池化连接。 可以在连接字符串中设置它们，或通过相应的 SqlConnectionStringBuilder 属性进行设置。
关于 Microsoft Entra ID 认证，请参见 Microsoft Entra ID 认证。 关于TLS设置，请参见 加密与证书验证。
使用 SqlConnectionStringBuilder 设置选项
使用构建器，而不是拼接连接字符串片段：
var builder = new SqlConnectionStringBuilder
{
DataSource = "tcp:sql.example.com,1433",
InitialCatalog = "Orders",
IntegratedSecurity = true,
Encrypt = SqlConnectionEncryptOption.Mandatory,
ApplicationName = "Orders.Worker",
ConnectTimeout = 30,
ConnectRetryCount = 3,
ConnectRetryInterval = 10,
MultiSubnetFailover = true,
};
规范中使用了建筑商的物业名称。 这些表格使用连接字符串的常见写法。 该驱动程序也接受文档中说明的别名。
暂停选项
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Connect Timeout |
15 秒 | 限制了建立联系的时间。 当连接池处于 Max Pool Size 时，也会限制等待可用池化连接的最长时间。
Connection Timeout 和 Timeout 是别名。 |
所有 Microsoft.Data.SqlClient 版本 |
Command Timeout |
30 秒 | 设置与该连接关联的命令的默认超时时间。 当某个操作需要不同的限制时，设置 CommandTimeout 在命令上。 值 0 为无时间限制，可以让工作无限期等待。 |
Microsoft。Data.SqlClient 2.1及更高版本 |
连接超时和命令超时针对的是不同的操作。
Connect Timeout 不限制查询执行。
Command Timeout 这不限制认证或等待共享连接的时间。
CancellationToken 独立于这两项设置。 将其传递给 OpenAsync、命令执行和读取器方法，以便调用方能够在超时到期前停止等待。
工作负载身份与路由选项
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Application Name |
提供者定义名称 | 识别SQL Server会话、审计和诊断中的工作负载。 为每个已部署的工作负载使用一个稳定且低基数的名称。 | 所有 Microsoft.Data.SqlClient 版本 |
Application Intent |
ReadWrite |
ReadOnly 当目标组和可用性组配置好时，请求读意图路由。 它不会将 SQL 语句设为只读。 |
所有 Microsoft.Data.SqlClient 版本 |
Application Intent=ReadOnly 通常与可用性组监听器或支持读取路由的服务端点配对。 参见 高可用性和灾难恢复。
网络和数据包选项
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Packet Size |
8000字节 | 设置表式数据流（TDS）网络数据包大小。 支持的数值为512至32,768字节。 除非工作负载测量和服务器配置需要更改，否则保持默认。 | 所有 Microsoft.Data.SqlClient 版本 |
MultiSubnetFailover |
false |
使用并行 TCP 连接尝试连接为多地址端点返回的 IP 地址。 对于通过 TCP 访问的 Azure SQL 终结点、可用性组侦听器和故障转移群集实例，将其设置为 true。 |
所有 Microsoft.Data.SqlClient 版本 |
MultiSubnetFailover=true 不支持命名实例、非TCP协议、数据库镜像或配置超过64个IP地址的端点。 对于单IP TCP端点来说是安全的。
Microsoft.Data.SqlClient 7.0 还提供了一个进程范围内的 AppContext 开关，可以使所有连接的行为都如同 MultiSubnetFailover=true。 当未启用该开关时，连接字符串默认仍为 false。 请参见 SqlClient 中的 AppContext 切换。
池化选项
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Pooling |
true |
针对匹配的连接配置，重用物理连接。 仅在出于诊断目的，或对于经评估无法安全进行池化的工作负载时，才禁用它。 | 所有 Microsoft.Data.SqlClient 版本 |
Min Pool Size |
0 |
在池创建后，至少保留这么多物理连接。 正值可使数据库会话一直保持打开状态，直到连接池或进程结束。 | 所有 Microsoft.Data.SqlClient 版本 |
Max Pool Size |
100 |
将物理连接限制在一个池内。 请求会等 Connect Timeout 到池子满了才会发。 |
所有 Microsoft.Data.SqlClient 版本 |
Load Balance Timeout |
0 秒 |
如果连接的年龄超过该值，则在返回池时丢弃该连接。
Connection Lifetime 是别名。
0 禁止基于年龄的移除。 |
所有 Microsoft.Data.SqlClient 版本 |
Pool Blocking Period |
Auto |
控制池是否会暂时重新抛出已缓存的登录失败。
Auto禁用已识别的 Azure SQL 终结点的阻断期，并为其他终结点启用阻断期。 |
所有 Microsoft.Data.SqlClient 版本 |
Enlist |
true |
自动在环境 System.Transactions 事务中调用已打开的连接。 |
所有 Microsoft.Data.SqlClient 版本 |
池设置适用于每个独立的池，而不是整个进程或数据库服务器。 在提出 Max Pool Size之前，确认连接和读卡器被及时处理，并且数据库能够接受每个应用实例的总和。
关于池密钥、令牌行为、阻塞周期、清除和诊断，请参见 SQL Server 连接池。
连接恢复选项
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Connect Retry Count |
1 |
设置初始连接期间发生的符合条件的暂时性故障以及恢复已断开的空闲连接的重试次数。 实际默认是2用于已识别的Azure SQL端点以及5已识别的Azure Synapse和按需端点。
0 禁用这些重试。 |
所有 Microsoft.Data.SqlClient 版本 |
Connect Retry Interval |
10 秒 | 设置后续初始连接或空闲恢复尝试之前的延迟时间。 有效时间为1到60秒。 | 所有 Microsoft.Data.SqlClient 版本 |
连接恢复期间的第一次重试是立即发生的。
Connect Retry Interval 先于后续尝试生效。 若要针对单次操作绕过内置的首次打开重试，请使用带有 OpenWithoutRetry 的 open 重载。
这些关键词不会在命令运行时重试失败的命令。 使用 可配置的重试逻辑，用于自定义打开或命令策略。 仅当重复执行这些命令是安全时，才重试这些命令。
服务器身份和证书选项
这些选项可满足特定的证书或 Kerberos 命名要求。 它们不能取代正常的认证和证书验证。
| 关键 字 | 默认 | Behavior | 版本 |
|---|---|---|---|
Host Name In Certificate |
服务器主机名称 | 当连接使用与证书不同的DNS别名时，提供预期的通用名称（CN）或主题备用名称（SAN）。 | Microsoft。Data.SqlClient 5.0及更高版本 |
Server Certificate |
空 | 提供一个 PEM、DER 或 CER 格式的文件，当 Encrypt=Strict 或 Encrypt=Mandatory 时，该文件必须与服务器证书完全匹配。 |
Microsoft。Data.SqlClient 5.1及更高版本 |
Server SPN |
派生自服务器名称 | 替代用于主服务器集成身份验证的服务主体名称 (SPN)。 仅当所部署的 Kerberos 命名方式需要显式指定的 SPN 时，才进行配置。 | Microsoft。Data.SqlClient 5.0及更高版本 |
Failover Partner SPN |
派生自故障转移伙伴 | 替代数据库镜像故障转移伙伴的 SPN。 数据库镜像已被弃用。 对于新的部署，请使用可用性组。 | Microsoft。Data.SqlClient 5.0及更高版本 |
Host Name In Certificate 更改用于证书匹配的名称。 它不信任不受信任的发行机构。
Server Certificate 固定一个完全相同的证书文件，并在该证书轮换时需要应用更新。
错误的 SPN 覆盖配置可能会阻止 Kerberos 身份验证，或削弱预期的身份验证检查。 如果可以，应修正 DNS 和 SPN 注册，而不是设置替代配置。
保持连接字符串简短。 只有当你能说明它改变了哪个行为以及工作负载如何验证该行为时，才添加选项。
查看选项更改
在生产中更改选项之前：
- 记录当前的连接字符串、驱动程序版本、端点类型和观察到的问题。
- 一次只改变一个行为。
- 测试连接建立、认证、证书验证、池化、故障切换、取消和查询执行。
- 衡量硬连接数、连接池等待时间、连接延迟和错误数量。
- 确认每个部署实例的设置。
连接字符串是池密钥的一部分。 分阶段部署可以临时创建旧数据库和新数据库池，从而增加物理数据库连接的总数。