SqlConnectionStringBuilder 可用于通过类型化属性创建和编辑连接字符串。 它继承自 DbConnectionStringBuilder. 只要你的代码添加或更改某个值,就用它,而不是连接字符串。
建造者:
- 将每个关键字公开为具有类型的属性,例如将
ConnectTimeout公开为整数,并将Encrypt公开为一个SqlConnectionEncryptOption。 - 在设置时,会拒绝未知关键字和许多超出范围的值,并显示 ArgumentException。
- 将同义词(如
Server和uid)映射到典范关键词(如Data Source和User ID)。 - 为包含分号、引号或前后空格的值加上引号。
关于关键词列表,请参见 连接选项。 关于文本格式,请参见 解析规则。
每个样本都是完整的程序。 .NET Framework 选项卡中使用 C# 7.3。 要创建运行样本的项目,请参见“创建项目”。
防止连接字符串注入
当你的代码在 连接字符串 中插入不受信任的文本时,文本中的分号可以添加关键字或替换前面较早的关键字,因为最后一个值会胜出。 构建器将整个值存储在一个属性中并将其加上引号,这样文本就不会变成另一个关键词。
该程序将 InitialCatalog 设为一个会尝试关闭池化的值:
using Microsoft.Data.SqlClient;
// Simulates a value that came from a user or another untrusted source.
string databaseFromUser = "Orders;Pooling=false";
var builder = new SqlConnectionStringBuilder
{
DataSource = "tcp:sql.example.com,1433",
InitialCatalog = databaseFromUser,
IntegratedSecurity = true,
Encrypt = SqlConnectionEncryptOption.Strict,
};
Console.WriteLine(builder.ConnectionString);
Console.WriteLine($"Pooling: {builder.Pooling}");
输出为:
Data Source=tcp:sql.example.com,1433;Initial Catalog="Orders;Pooling=false";Integrated Security=True;Encrypt=Strict
Pooling: True
生成器会为该值加上引号,而 Pooling 保持为 True。 驱动程序将 Orders;Pooling=false 作为数据库名称发送到服务器。
加引号可以阻止关键字注入。 它并不决定是否允许某个值。 使用前请将不可信输入与允许的服务器或数据库列表进行核对。
填写基础连接字符串
将连接字符串中不变的部分,比如服务器和数据库,存储在配置中。 运行时添加秘密值和工作负载特定的值。 把基础字符串传递给生成器构造函数,然后设置属性。
该程序从单独的环境变量中读取基础字符串和密码,使用 SQL 身份验证进行连接,并确认连接打开后密码不可见。
using Microsoft.Data.SqlClient;
// The base string holds no secret. The password comes from a separate secret source.
string baseConnectionString =
Environment.GetEnvironmentVariable("SQL_BASE_CONNECTION_STRING")
?? throw new InvalidOperationException(
"Set the SQL_BASE_CONNECTION_STRING environment variable.");
string password =
Environment.GetEnvironmentVariable("SQL_PASSWORD")
?? throw new InvalidOperationException(
"Set the SQL_PASSWORD environment variable.");
var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
Password = password,
ApplicationName = "Orders.Worker",
};
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()}");
var opened = new SqlConnectionStringBuilder(connection.ConnectionString);
Console.WriteLine($"Password visible after open: {opened.ContainsKey("Password") && opened.Password.Length > 0}");
将 SQL_BASE_CONNECTION_STRING 设置为 Server=tcp:<server>,1433;Database=<database>;User ID=<user>;Encrypt=true 之类的值。 输出为:
APP_NAME(): Orders.Worker
Password visible after open: False
Persist Security Info 默认为 false,因此驱动会在连接打开后从 SqlConnection.ConnectionString 中移除密码。 保留默认设置。
更倾向于使用无需密码的认证方式,如 Windows 集成认证或 Microsoft Entra ID 托管标识。 欲了解更多信息,请参见 Microsoft Entra ID 认证和 保护连接信息。
读取并更改数值
构建器还兼具词典功能。 索引器 ContainsKey、Remove 和 TryGetValue 接受关键词或其任一同义词。
using Microsoft.Data.SqlClient;
var b = new SqlConnectionStringBuilder("Server=sql.example.com;Database=Orders;uid=app_user;pwd=x");
b["server"] = "tcp:sql2.example.com,1433";
Console.WriteLine($"DataSource: {b.DataSource}");
Console.WriteLine($"ContainsKey(\"uid\"): {b.ContainsKey("uid")}");
Console.WriteLine($"Remove(\"pwd\"): {b.Remove("pwd")}");
Console.WriteLine($"TryGetValue: {b.TryGetValue("Database", out object? db)} {db}");
Console.WriteLine($"ShouldSerialize(\"Pooling\"): {b.ShouldSerialize("Pooling")}");
Console.WriteLine(b.ConnectionString);
try { b["Bogus"] = 1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
try { b.ConnectTimeout = -1; } catch (Exception e) { Console.WriteLine($"{e.GetType().Name}: {e.Message}"); }
输出为:
DataSource: tcp:sql2.example.com,1433
ContainsKey("uid"): True
Remove("pwd"): True
TryGetValue: True Orders
ShouldSerialize("Pooling"): False
Data Source=tcp:sql2.example.com,1433;Initial Catalog=Orders;User ID=app_user
ArgumentException: Keyword not supported: 'Bogus'.
ArgumentException: Invalid value for key 'Connect Timeout'.
ShouldSerialize对于不在字符串中的关键字返回false。
ContainsKey对每个支持的关键词都返回true,无论字符串是否设置了该关键词。 该 ConnectionString 属性只包含你设置的关键词。
了解生成器不会检查哪些内容
构建者会拒绝未知的关键词和许多无效值,但它不会检查所有值。 例如,它接受Type System Version和Transaction Binding的任何文本,且不检查字符串长度。 它也不检查关键词组合,因此接受 Authentication=Active Directory Default 与 Integrated Security=true一起。
SqlConnection 当你向其传入该字符串时,会拒绝与 ArgumentException 的这种组合。 完整规则列表请参见 验证规则。
构建器写入不带空格的值 Authentication,例如 Authentication=ActiveDirectoryDefault。 驱动程序同时接受这两种形式。
生成器在密码进入进程内存后也不会保护密码,也不会判断服务器、身份或证书设置是否安全。
保留一个规范的连接字符串
每个不同的连接字符串都有自己的连接池。 两个仅在关键词顺序或同义词上不同的手写字符串会形成两个池。 构建者以一致顺序写入典范关键词,因此 Server=a;Database=d 和 Database=d;Server=a 都变为 Data Source=a;Initial Catalog=d。 启动时构建一次连接字符串,然后重复使用builder.ConnectionString。 不要添加每个请求的值,比如用户名或请求ID。 更多池化指导,请参见 使用连接池。