SqlConnectionStringBuilder 类

定义

命名空间:

Microsoft.Data.SqlClient

程序集:

Microsoft.Data.SqlClient.dll

程序包:

Microsoft.Data.SqlClient v7.1.0

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

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

[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

继承

DbConnectionStringBuilder

SqlConnectionStringBuilder

属性

TypeConverterAttribute

示例

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

注释

此示例包含一个密码，用于演示如何 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=********;initial catalog=AdventureWorks";

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

        // 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设置此属性的值。 有关 SqlClient 对 AlwaysOn 可用性组支持的更多信息，请参阅 SqlClient 对高可用性和灾难恢复的支持。
ApplicationName	获取或设置与连接字符串关联的应用程序的名称。
AttachDBFilename	获取或设置一个字符串，其中包含主数据文件的名称。 这包括可附加数据库的完整路径名称。
AttestationProtocol	获取或设置证明协议的值。
Authentication	获取或设置用于连接与Microsoft Entra Azure SQL资源的身份验证方法。
ColumnEncryptionSetting	获取或设置连接字符串生成器的列加密设置。
CommandTimeout	在终止尝试执行命令并生成错误之前的默认等待时间（以秒为单位）。 默认为 30 秒。
ConnectionReset	已过时. Obsolete. 获取或设置一个布尔值，该值指示是否从连接池绘制连接时重置连接。
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+）
IdleTimeout	获取或设置连接在放弃连接池之前，连接可以处于未使用状态（空闲）的最大时间（以秒为单位）。 默认值为 300 （5 分钟）。
InitialCatalog	获取或设置与连接关联的数据库的名称。
IntegratedSecurity	获取或设置一个布尔值，该值指示用户 ID 和密码是在连接（何时false）中指定的，还是当前Windows帐户凭据用于身份验证（时间true）。
IPAddressPreference	获取或设置建立 TCP 连接时的 IP 地址系列首选项。
IsFixedSize	获取一个值，该值指示是否 SqlConnectionStringBuilder 具有固定大小。
Item[String]	获取或设置与指定键关联的值。 在 C# 中，此属性是索引器。
Keys	获取一个包含键的 < a0 /> 。
LoadBalanceTimeout	获取或设置连接在被销毁之前在连接池中生存的最短时间（以秒为单位）。
MaxPoolSize	获取或设置此特定连接字符串的连接池中允许的最大连接数。
MinPoolSize	获取或设置此特定连接字符串的连接池中允许的最小连接数。
MultipleActiveResultSets	如果为 true，应用程序可以维护多个活动结果集（MARS）。 如果为 false，应用程序必须处理或取消一个批处理中的所有结果集，然后才能在该连接上执行任何其他批处理。 有关详细信息，请参阅多个活动结果集（MARS）。
MultiSubnetFailover	如果应用程序连接到不同子网上的 AlwaysOn 可用性组（AG），则设置 MultiSubnetFailover=true 可更快地检测和连接到活动服务器（当前）活动服务器。 有关 SqlClient 对 AlwaysOn 可用性组支持的更多信息，请参阅 SqlClient 对高可用性和灾难恢复的支持。
NetworkLibrary	获取或设置一个字符串，该字符串包含用于建立与 SQL Server 的连接的网络库的名称。
PacketSize	获取或设置用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。
Password	获取或设置 SQL Server 帐户的密码。
PersistSecurityInfo	获取或设置一个布尔值，该值指示安全敏感信息（如密码或访问令牌）是否应作为在连接处于打开状态之后创建SqlConnectionStringBuilder的连接上的连接字符串的一部分返回。 仅当应用程序需要从已打开的数据库连接中读取密码时，才应将此属性设置为 true 该属性。 默认值 false 为更安全的设置;使用 true 此属性可打开应用程序，面临安全风险，例如意外记录或跟踪数据库密码。
PoolBlockingPeriod	连接池的阻塞期行为。
Pooling	获取或设置一个布尔值，该值指示每次请求连接时连接是共用还是显式打开。
Replication	获取或设置一个布尔值，该值指示是否支持使用连接进行复制。
ServerCertificate	获取或设置证书文件的路径，使其与连接的 SQL Server TLS/SSL 证书匹配。 接受的证书格式为 PEM、DER 和 CER。 如果指定，则通过验证提供的证书是否ServerCertificate完全匹配来检查SQL Server证书。 （仅在 v5.1+ 中可用）
ServerSPN	获取或设置数据源的服务主体名称（SPN）。
TransactionBinding	获取或设置一个字符串值，该值指示连接如何保持其与登记 System.Transactions 事务的关联。
TransparentNetworkIPResolution	已过时. 在 .NET Framework 上，当此密钥的值设置为true时，驱动程序会跨 DNS 解析的 IP 地址运行多个连接轮次，每次尝试超时逐渐增大，在顺序模式尝试上至少运行 500 毫秒，直到连接成功或达到整体Connect Timeout为止。
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 检索与提供的键对应的值。