Microsoft.Data.SqlClient 的连接字符串

Microsoft.Data.SqlClient 连接字符串用于告知驱动程序应使用哪个与 SQL Server 兼容的端点和数据库、如何进行身份验证以及如何配置连接。 传给 SqlConnection 或 SqlConnectionStringBuilder。

从四个决定开始：

  1. 应用使用哪台服务器和数据库？
  2. 应用程序以哪个身份运行？
  3. 客户端如何验证服务器证书？
  4. 工作负载需要哪种连接行为？

当所选身份验证方法支持这种做法时，不要将凭据和访问令牌放入连接字符串中。

选择一种认证模式

使用最窄且适合部署的图案。

Environment 首选图案 核心连接字符串
以域或本地 Windows 身份运行的 Windows 上的 SQL Server Windows 集成身份验证 Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
开发者工作站连接 Microsoft Fabric 中的 SQL 数据库 Microsoft Entra ID 默认凭证链 Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
托管在 Azure 中并连接到 Azure SQL 的应用程序 Microsoft Entra ID 托管标识 Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
连接到 Azure SQL 的开发人员工作站 Microsoft Entra ID 默认凭证链 Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
连接到 Azure SQL 的交互式桌面工具 Microsoft Entra ID 交互式认证 Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
需要SQL认证的环境 来自机密存储的用户名和密码 Server=<server>;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true

Microsoft.Data.SqlClient 7.0 及更高版本对于驱动程序提供的 Microsoft Entra ID 身份验证模式，需要使用与版本匹配的 Microsoft.Data.SqlClient.Extensions.Azure 包。 当应用代码提供访问令牌或访问令牌回调时，你就不需要这个扩展了。

认证还需要数据库端用户、权限和身份配置。 完整的选择矩阵和设置，请参见 Microsoft Entra ID 认证和 SQL Server 认证。

指定服务器和数据库

使用 Server 和 Database 作为标准关键词名称。 驱动程序也接受将 Data Source 作为 Server 的别名，以及将 Initial Catalog 作为 Database 的别名。

常见的服务器形式包括：

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

生产 TCP 连接时，优先选择显式协议、主机名和端口。 使用与服务器证书匹配的稳定DNS名称，而不是IP地址。

对于可用性组监听器、故障转移组、Azure SQL端点或其他多地址TCP端点，也请在连接选项中查看MultiSubnetFailover。

配置加密和证书验证

Microsoft.Data.SqlClient 4.0 及更高版本默认将 Encrypt 设置为 true。 Microsoft.Data.SqlClient 5.0 及更高版本也支持适用于协商 TDS 8.0 的服务器的 Encrypt=Strict。

使用：

  • Encrypt=Strict 当服务器支持 TDS 8.0 并持有证书时，客户端可以进行验证。
  • Encrypt=true 用于与其他支持服务器的加密连接。
  • TrustServerCertificate=false，作为生产证书验证的默认选项。

不要将 TrustServerCertificate=true 用作通用的连接修复方案。 它会加密信道，但跳过服务器身份验证。 限制在受控开发环境中，没有可信证书可用。

关于服务器需求、版本行为和证书选项，请参见 加密与证书验证。

了解连接字符串语法

连接字符串 是一个用分号分隔的关键词和值对列表：

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=true

遵循以下规则：

  • 关键词名称不区分大小写。
  • 数值可以区分大小写。
  • 末尾分号是可选的。
  • 当值包含分号或前置或后置空白时，请用单引号或双引号引用。
  • 通过翻倍来逃避那个包含价值的报价。
  • 不要使用重复的关键词。 解析器使用最后一个值，这使得有效配置难以复查。

被接受的关键词和别名集合属于提供者。 Microsoft.Data.SqlClient接受的连接字符串可能无法与System.Data.SqlClient或其他数据提供程序配合使用。

安全地构建连接字符串

当代码需要添加、验证或替换值时使用 SqlConnectionStringBuilder 。 不要把不可信的值串接到连接字符串里。

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

建造者：

  • 拒绝无支持的关键词和无效值。
  • 将别名映射到规范属性。
  • 在需要时为值加上引号。
  • 防止某个值注入另一个关键词。

构建器不会保护密码或令牌进入进程内存后。 它也无法决定服务器、身份或证书设置是否安全。

代码外存储连接信息

加载来自应用使用的配置系统的连接字符串。 当前的 .NET 应用通常使用环境变量、本地开发的用户秘密、Azure 应用程序配置 以及 Azure 密钥保管库 支持的配置。

遵守以下规则：

  • 不要提交密码、客户端秘密、访问令牌或生产连接字符串。
  • 更倾向于基于身份的认证方法，不需要在连接字符串中输入密码。
  • 限制对配置源的访问。
  • 轮换已存储的机密，并重启或刷新缓存这些机密的应用程序。
  • 不要给日志、异常、跟踪或遥测写入连接字符串。
  • 保持 Persist Security Info=false为默认值，这样打开的连接不会通过其连接字符串暴露安全敏感值。

关于 .NET 配置提供者，请参见 .NET 中的配置。 有关更多控制，请参见 保护连接信息。

保持泳池钥匙稳定

连接池使用精确的连接配置作为池密钥的一部分。 等效字符串在文本不同时会创建单独的池，包括关键词以不同顺序出现的情况。

在应用启动时构建一个规范的 连接字符串 并重复使用。 不要在字符串中添加请求ID、用户名、访问令牌或其他每个请求的值。 完整关键规则请参见 SQL Server 连接池。

独立连接和命令设置

连接字符串控制着连接的建立和会话行为。 命令控制一个SQL操作。

Requirement 配置启用
建立连接或从池中获得连接的时间 Connect Timeout 连接选项
默认命令执行超时时间 Command Timeout 连接选项，当驱动程序版本支持时
单个命令的超时时间 CommandTimeout
由呼叫方取消 CancellationToken 被传递给异步 API
打开连接或执行命令时的重试策略 针对 SqlConnection 或 SqlCommand 的可配置重试逻辑

不要把更长的超时时间当作重试逻辑。 暂停时间限制了等待时间。 重试开始下一次尝试，必须有界限且安全才能重复。

审查版本敏感行为

驱动程序版本 连接字符串更改
4.0 Encrypt 默认为 true。
5.0 Encrypt=Strict和HostNameInCertificate可用。 SqlConnectionStringBuilder.Encrypt 使用 SqlConnectionEncryptOption。
5.1 ServerCertificate 可以将服务器证书与文件匹配。
5.2 AccessTokenCallback 适用于可续期的应用程序提供的代币。
7.0 驱动程序提供的 Microsoft Entra ID 认证将迁移至 Microsoft.Data.SqlClient.Extensions.Azure。
7.0.2 核心驱动及其配套软件包采用对齐的版本号。

使用支持的稳定驱动版本，并在更新前阅读发布说明。 当前版本请参见 SqlClient 驱动支持生命周期。

相关内容

  • Last updated on