SqlConnectionStringBuilder 类

定义

命名空间:

Microsoft.Data.SqlClient

程序集:

Microsoft.Data.SqlClient.dll

包:

Microsoft.Data.SqlClient v5.2.0

为创建和管理由 SqlConnection 类使用的连接字符串的内容提供了一种简单方法。

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

继承

DbConnectionStringBuilder

SqlConnectionStringBuilder

示例

以下控制台应用程序为SQL Server数据库生成连接字符串。 该代码使用 SqlConnectionStringBuilder 类创建连接字符串，然后将 ConnectionString 实例的 SqlConnectionStringBuilder 属性传递到连接类的构造函数。 该示例还分析了现有连接字符串，并演示了各种操作连接字符串的内容的方法。

注意

该示例包括一个密码以演示 SqlConnectionStringBuilder 如何使用连接字符串。 在您的应用程序中，建议使用 Windows 身份验证。 如果必须使用密码，请不要在你的应用程序中包括硬编码的密码。

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password= a!Pass113;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "new@1Password";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

注解

通过连接字符串生成器，开发人员可以使用该类的属性和方法，以编程方式创建语法正确的连接字符串以及分析和重新生成现有的连接字符串。 连接字符串生成器提供了与 SQL Server 允许的已知键/值对相对应的强类型属性。 需要在应用程序中创建连接字符串的开发人员可以使用 SqlConnectionStringBuilder 类生成和修改连接字符串。 使用该类还可以轻松管理存储在应用程序配置文件中的连接字符串。

SqlConnectionStringBuilder 对键/值对的有效性进行检查。 因此，您不能使用该类创建无效的连接字符串；尝试添加无效对将引发异常。 该类保持一个固定的同义词集合，可以将同义词转换为相应的已知键名。

例如，使用 Item 属性检索值时，可以指定包含所需键的任何同义词的字符串。 例如，使用需要包含键名称的字符串（如 Item 属性或 方法）的任何成员时，可以在连接字符串中为此键指定“网络地址”、“addr”或Remove任何其他可接受的同义词。 有关可接受同义词的完整列表，请参见 ConnectionString 属性。

Item 属性句柄尝试插入恶意条目。 例如，下面的代码使用默认 Item 属性（在 C# 中为索引器）正确转义嵌套的键/值对：

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
  new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

结果为以下连接字符串，该字符串以安全方式处理无效值：

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

构造函数

SqlConnectionStringBuilder()	初始化 SqlConnectionStringBuilder 类的新实例。
SqlConnectionStringBuilder(String)	初始化 SqlConnectionStringBuilder 类的新实例。 所提供的连接字符串为实例的内部连接信息提供数据。

属性

ApplicationIntent	连接到 SQL Server 可用性组中的数据库时声明应用程序工作负荷类型。 您可以使用 ApplicationIntent 设置此属性的值。 有关对 Always On 可用性组的 SqlClient 支持的详细信息，请参阅对高可用性、灾难恢复的 SqlClient 支持。
ApplicationName	获取或设置与连接字符串关联的应用程序的名称。
AttachDBFilename	获取或设置包含主数据文件名称的字符串。 该字符串包括可附加数据库的完整路径名。
AttestationProtocol	获取或设置证明协议的值。
Authentication	获取或设置用于使用 Azure Active Directory 身份验证连接到 SQL 数据库 的身份验证方法。
ColumnEncryptionSetting	获取或设置连接字符串生成器的列加密设置。
CommandTimeout	在终止执行命令并生成错误的尝试之前，默认等待时间) (秒。 默认为 30 秒。
ConnectRetryCount	在确定有一个空闲的连接失败之后尝试重新连接的次数。 该值必须是介于 0 和 255 之间的整数。 非 Azure 终结点的默认值为 1。 对于Azure SQL终结点，默认值为 2。 从版本 5.x 开始，对于Azure SQL无服务器或按需终结点，默认值为 5，以提高连接到空闲或暂停实例的连接成功率。 设置为 0 将禁止在空闲连接失败时重新连接。 如果设置的值超过允许的范围，则将引发 ArgumentException。
ConnectRetryInterval	标识空闲连接失败之后每次重新连接尝试之间的时间量（以秒为单位）。 此值必须是介于 1 和 60 之间的整数。 默认值为 10 秒。
ConnectTimeout	获取或设置在终止尝试并产生错误之前，等待与服务器连接的时间长度（以秒为单位）。
CurrentLanguage	获取或设置用于数据库服务器警告或错误消息的语言。
DataSource	获取或设置要连接到的 SQL Server 实例的名称或网络地址。
EnclaveAttestationUrl	获取或设置要与基于 enclave 的Always Encrypted一起使用的 enclave 证明 URL。
Encrypt	获取或设置 SqlConnectionEncryptOption 自版本 5.0 起的值或 Boolean 早期版本的值，该值指示客户端和服务器之间发送的所有数据是否需要 TLS 加密。
Enlist	获取或设置一个布尔值，该值指示 SQL Server 连接池程序是否在创建线程的当前事务上下文中自动登记连接。
FailoverPartner	获取或设置在主服务器停机时要连接到的伙伴服务器的名称或地址。
FailoverPartnerSPN	获取或设置服务主体名称 (连接故障转移伙伴的 SPN) 。
HostNameInCertificate	获取或设置验证连接服务器证书时要使用的主机名。 如果未指定，将使用 中的 Data Source 服务器名称进行证书验证。 (仅适用于 v5.0+)
InitialCatalog	获取或设置与连接关联的数据库的名称。
IntegratedSecurity	获取或设置一个布尔值，该值指示是否在连接中指定用户 ID 和密码（值为 false 时），或者是否使用当前的 Windows 帐户凭据进行身份验证（值为 true 时）。
IPAddressPreference	获取或设置建立 TCP 连接时的 IP 地址系列首选项。
IsFixedSize	获取一个值，该值指示 SqlConnectionStringBuilder 是否具有固定大小。
Item[String]	获取或设置与指定的键关联的值。 在 C# 中，此属性为索引器。
Keys	获取包含 ICollection 中的键的 SqlConnectionStringBuilder。
LoadBalanceTimeout	获取或设置连接被销毁前在连接池中存活的最短时间（以秒为单位）。
MaxPoolSize	获取或设置针对此特定连接字符串连接池中所允许的最大连接数。
MinPoolSize	获取或设置针对此特定连接字符串连接池中所允许的最小连接数。
MultipleActiveResultSets	如果为 true，则应用程序可以维护多个活动结果集 (MARS)。 如果为 false，则应用程序必须先处理或取消某一批中的所有结果集，才可以在该连接上执行任何其他批次。 有关详细信息，请参阅多个活动结果集 (MARS)。
MultiSubnetFailover	如果你的应用程序要连接到不同子网上的 AlwaysOn 可用性组 (AG)，则设置 MultiSubnetFailover=true 会加快检测（当前）活动服务器以及与服务器的连接。 有关对 Always On 可用性组的 SqlClient 支持的详细信息，请参阅对高可用性、灾难恢复的 SqlClient 支持。
PacketSize	获取或设置用来与 SQL Server 的实例通信的网络数据包的大小（以字节为单位）。
Password	获取或设置 SQL Server 帐户的密码。
PersistSecurityInfo	获取或设置一个布尔值，该值指示安全敏感信息（如密码或访问令牌）是否应作为连接字符串的一部分返回，SqlConnectionStringBuilder该连接在连接处于打开状态后创建。 仅当应用程序需要从已打开的数据库连接中读取密码时，才应将此属性设置为 true 。 的默认值 false 是更安全的设置;使用 true for 此属性会打开应用程序的安全风险，例如意外日志记录或跟踪数据库密码。
PoolBlockingPeriod	连接池的暂停时段行为。
Pooling	获取或设置一个布尔值，该值指示每次请求连接时该连接是汇入连接池还是显式打开。
Replication	获取或设置一个布尔值，该值指示是否使用连接来支持复制。
ServerCertificate	获取或设置证书文件的路径，以便与连接的 SQL Server TLS/SSL 证书匹配。 接受的证书格式为 PEM、DER 和 CER。 如果指定，则通过验证提供的 是否ServerCertificate完全匹配来检查SQL Server证书。 (仅适用于 v5.1+)
ServerSPN	获取或设置数据源的 SPN) (服务主体名称。
TransactionBinding	获取或设置一个字符串值，该值表示连接如何保持与登记的 System.Transactions 事务的关联。
TrustServerCertificate	获取或设置一个值，该值指示在跳过用于验证信任的证书链遍历时是否加密信道。
TypeSystemVersion	获取或设置一个字符串值，该值指示应用程序所需的类型系统。
UserID	获取或设置连接到 SQL Server 时要使用的用户 ID。
UserInstance	获取或设置一个值，该值指示是否将连接从默认的 SQL Server Express 实例重定向到在调用方帐户之下运行并且在运行时启动的实例。
Values	获取一个包含 ICollection 中的值的 SqlConnectionStringBuilder。
WorkstationID	获取或设置连接到 SQL Server 的工作站的名称。

方法

Clear()	清除 SqlConnectionStringBuilder 实例的内容。
ContainsKey(String)	确定 SqlConnectionStringBuilder 是否包含特定键。
Remove(String)	从 SqlConnectionStringBuilder 实例中移除具有指定的键的项。
ShouldSerialize(String)	指示此 SqlConnectionStringBuilder 实例中是否存在指定的键。
TryGetValue(String, Object)	从此 SqlConnectionStringBuilder 中检索与提供的键相对应的值。