SqlConnectionStringBuilder 类

定义

命名空间:

System.Data.SqlClient

程序集:

System.Data.dll

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

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

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

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

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

继承

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

属性

TypeConverterAttribute

示例

以下控制台应用程序为 SQL Server 数据库生成连接字符串。 该代码使用 SqlConnectionStringBuilder 类创建连接字符串。 然后，该示例分析连接字符串，并演示了操作其内容的各种方法。

// Create a new SqlConnectionStringBuilder and
// initialize it with a few name/value pairs.
SqlConnectionStringBuilder builder = new(
    "Server=(local);Integrated Security=true;" +
    "Initial Catalog=AdventureWorks"
    );

// The input connection string used the
// Server key, but the new connection string uses
// the well-known Data Source key instead.
Console.WriteLine($"Original connection string: '{builder.ConnectionString}'");

// Now that the connection string has been parsed,
// you can work with individual items.
Console.WriteLine($"Initial catalog: '{builder.InitialCatalog}'");
builder.InitialCatalog = "Northwind";
builder.AsynchronousProcessing = true;

// 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($"Modified connection string: '{builder.ConnectionString}'");

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As New SqlConnectionStringBuilder(
            "Server=(local);Integrated Security=true;" &
            "Initial Catalog=AdventureWorks"
            )

        ' The input connection string used the 
        ' Server key, but the new connection string uses
        ' the well-known Data Source key instead.
        Console.WriteLine("Original connection string: " + builder.ConnectionString)

        ' Now that the connection string has been parsed,
        ' you can work with individual items.
        Console.WriteLine("Initial catalog: " + builder.InitialCatalog)
        builder.InitialCatalog = "Northwind"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine("Modified connection string: " + builder.ConnectionString)
    End Sub
End Module

注解

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

SqlConnectionStringBuilder 对执行有效键/值对检查。 因此，不能使用此类创建无效的连接字符串;尝试添加无效对将引发异常。 该类维护同义词的固定集合，并且可以从同义词转换为相应的已知键名称。

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

Item[String] 属性处理插入恶意条目的尝试。 例如，以下代码使用默认 Item 属性（C# 中的索引器）正确地转义嵌套键/值对：

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

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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设置此属性的值。 有关对 AlwaysOn 可用性组的 SqlClient 支持的详细信息，请参阅 SqlClient 对高可用性的支持、灾难恢复。
ApplicationName	获取或设置与连接字符串关联的应用程序的名称。
AsynchronousProcessing	获取或设置一个布尔值，该值指示是否允许使用此连接字符串创建的连接进行异步处理。
AttachDBFilename	获取或设置一个字符串，其中包含主数据文件的名称。 这包括可附加数据库的完整路径名称。
Authentication	获取连接字符串的身份验证。
BrowsableConnectionString	获取或设置一个值，该值指示 ConnectionString 属性在 Visual Studio 设计器中是否可见。 (继承自 DbConnectionStringBuilder)
ColumnEncryptionSetting	获取或设置连接字符串生成器的列加密设置。
ConnectionReset	已过时. 过时。 获取或设置一个布尔值，该值指示是否从连接池绘制连接时重置连接。
ConnectionString	获取或设置与 DbConnectionStringBuilder关联的连接字符串。 (继承自 DbConnectionStringBuilder)
ConnectRetryCount	确定出现空闲连接失败后尝试的重新连接次数。 这必须是介于 0 和 255 之间的整数。 默认值为 1。 设置为 0 可禁用空闲连接失败时重新连接。 如果设置为允许范围之外的值，将引发 ArgumentException。
ConnectRetryInterval	确定出现空闲连接失败后，每次重新连接尝试之间的时间（以秒为单位）。 这必须是介于 1 和 60 之间的整数。 默认值为 10 秒。 如果设置为允许范围之外的值，将引发 ArgumentException。
ConnectTimeout	获取或设置在终止尝试并生成错误之前等待与服务器的连接的时间长度（以秒为单位）。
ContextConnection	获取或设置一个值，该值指示是否应建立与 SQL Server 的客户端/服务器或进程内连接。
Count	获取 ConnectionString 属性中包含的当前键数。 (继承自 DbConnectionStringBuilder)
CurrentLanguage	获取或设置 SQL Server 语言记录名称。
DataSource	获取或设置要连接到的 SQL Server 实例的名称或网络地址。
EnclaveAttestationUrl	获取或设置要与基于 enclave 的 Always Encrypted 一起使用的 enclave 证明 URL。
Encrypt	获取或设置一个布尔值，该值指示如果服务器安装了证书，则 SQL Server 是否对客户端和服务器之间发送的所有数据使用 SSL 加密。
Enlist	获取或设置一个布尔值，该值指示 SQL Server 连接池程序是否自动在创建线程的当前事务上下文中登记连接。
FailoverPartner	获取或设置在主服务器关闭时要连接到的伙伴服务器的名称或地址。
InitialCatalog	获取或设置与连接关联的数据库的名称。
IntegratedSecurity	获取或设置一个布尔值，该值指示是否在连接（false时）或当前 Windows 帐户凭据是否用于身份验证（true时）。
IsFixedSize	获取一个值，该值指示 SqlConnectionStringBuilder 是否具有固定大小。
IsReadOnly	获取一个值，该值指示 DbConnectionStringBuilder 是否为只读。 (继承自 DbConnectionStringBuilder)
Item[String]	获取或设置与指定键关联的值。 在 C# 中，此属性是索引器。
Keys	获取一个 ICollection，其中包含 SqlConnectionStringBuilder中的键。
LoadBalanceTimeout	获取或设置连接在被销毁之前在连接池中生存的最短时间（以秒为单位）。
MaxPoolSize	获取或设置此特定连接字符串的连接池中允许的最大连接数。
MinPoolSize	获取或设置此特定连接字符串的连接池中允许的最小连接数。
MultipleActiveResultSets	如果为 true，应用程序可以维护多个活动结果集（MARS）。 如果为 false，应用程序必须处理或取消一个批处理中的所有结果集，然后才能在该连接上执行任何其他批处理。 有关详细信息，请参阅 多个活动结果集（MARS）。
MultiSubnetFailover	如果应用程序连接到不同子网上的 AlwaysOn 可用性组（AG）或 AlwaysOn 故障转移群集实例（FCI），则设置 MultiSubnetFailover=true 可以更快地检测和连接到活动服务器（当前） 活动服务器。 有关对 AlwaysOn 功能的 SqlClient 支持的详细信息，请参阅 SqlClient 对高可用性、灾难恢复的支持。
NetworkLibrary	获取或设置一个字符串，该字符串包含用于建立与 SQL Server 的连接的网络库的名称。
PacketSize	获取或设置用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。
Password	获取或设置 SQL Server 帐户的密码。
PersistSecurityInfo	获取或设置一个值，该值指示在连接处于打开状态后，是否应返回安全敏感信息（如密码或访问令牌）作为 SqlConnectionStringBuilder 连接字符串的一部分。
PoolBlockingPeriod	连接池的阻塞期行为。
Pooling	获取或设置一个布尔值，该值指示每次请求连接时连接是共用还是显式打开。
Replication	获取或设置一个布尔值，该值指示是否支持使用连接进行复制。
TransactionBinding	获取或设置一个字符串值，该值指示连接如何保持其与登记 System.Transactions 事务的关联。
TransparentNetworkIPResolution	当此密钥的值设置为 true时，应用程序需要检索特定 DNS 条目的所有 IP 地址，并尝试与列表中的第一个 IP 地址进行连接。 如果在 0.5 秒内未建立连接，应用程序将尝试并行连接到所有其他连接。 当第一个答案时，应用程序将与被调查者 IP 地址建立连接。
TrustServerCertificate	获取或设置一个值，该值指示通道是否在绕过证书链来验证信任时加密通道。
TypeSystemVersion	获取或设置一个字符串值，该值指示应用程序所需的类型系统。
UserID	获取或设置连接到 SQL Server 时要使用的用户 ID。
UserInstance	获取或设置一个值，该值指示是否将连接从默认 SQL Server Express 实例重定向到在调用方帐户下运行的运行时启动的实例。
Values	获取一个 ICollection，其中包含 SqlConnectionStringBuilder中的值。
WorkstationID	获取或设置连接到 SQL Server 的工作站的名称。

方法

Add(String, Object)	将具有指定键和值的条目添加到 DbConnectionStringBuilder中。 (继承自 DbConnectionStringBuilder)
Clear()	清除 SqlConnectionStringBuilder 实例的内容。
ClearPropertyDescriptors()	清除关联 DbConnectionStringBuilder上 PropertyDescriptor 对象的集合。 (继承自 DbConnectionStringBuilder)
ContainsKey(String)	确定 SqlConnectionStringBuilder 是否包含特定密钥。
Equals(Object)	确定指定的对象是否等于当前对象。 (继承自 Object)
EquivalentTo(DbConnectionStringBuilder)	将此 DbConnectionStringBuilder 对象中的连接信息与所提供的对象中的连接信息进行比较。 (继承自 DbConnectionStringBuilder)
GetHashCode()	用作默认哈希函数。 (继承自 Object)
GetProperties(Hashtable)	用有关此 DbConnectionStringBuilder的所有属性的信息填充提供的 Hashtable。 (继承自 DbConnectionStringBuilder)
GetType()	获取当前实例的 Type。 (继承自 Object)
MemberwiseClone()	创建当前 Object的浅表副本。 (继承自 Object)
Remove(String)	从 SqlConnectionStringBuilder 实例中删除具有指定键的条目。
ShouldSerialize(String)	指示此 SqlConnectionStringBuilder 实例中是否存在指定的键。
ToString()	返回与此 DbConnectionStringBuilder关联的连接字符串。 (继承自 DbConnectionStringBuilder)
TryGetValue(String, Object)	从此 SqlConnectionStringBuilder检索与提供的键对应的值。

显式接口实现

ICollection.CopyTo(Array, Int32)	从特定 Array 索引开始，将 ICollection 的元素复制到 Array。 (继承自 DbConnectionStringBuilder)
ICollection.IsSynchronized	获取一个值，该值指示是否同步对 ICollection 的访问（线程安全）。 (继承自 DbConnectionStringBuilder)
ICollection.SyncRoot	获取可用于同步对 ICollection的访问的对象。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetAttributes()	返回此组件的实例的自定义属性集合。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetClassName()	返回组件的此实例的类名。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetComponentName()	返回组件的此实例的名称。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetConverter()	返回组件的此实例的类型转换器。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultEvent()	返回此组件实例的默认事件。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetDefaultProperty()	返回组件的此实例的默认属性。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEditor(Type)	返回此组件的实例的指定类型的编辑器。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents()	返回组件的此实例的事件。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetEvents(Attribute[])	使用指定的属性数组作为筛选器返回组件的此实例的事件。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties()	返回组件的此实例的属性。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetProperties(Attribute[])	使用属性数组作为筛选器返回组件的此实例的属性。 (继承自 DbConnectionStringBuilder)
ICustomTypeDescriptor.GetPropertyOwner(PropertyDescriptor)	返回一个对象，该对象包含指定属性描述符描述符描述的属性。 (继承自 DbConnectionStringBuilder)
IDictionary.Add(Object, Object)	将具有提供的键和值的元素添加到 IDictionary 对象。 (继承自 DbConnectionStringBuilder)
IDictionary.Contains(Object)	确定 IDictionary 对象是否包含具有指定键的元素。 (继承自 DbConnectionStringBuilder)
IDictionary.GetEnumerator()	返回 IDictionary 对象的 IDictionaryEnumerator 对象。 (继承自 DbConnectionStringBuilder)
IDictionary.Item[Object]	获取或设置具有指定键的元素。 (继承自 DbConnectionStringBuilder)
IDictionary.Remove(Object)	从 IDictionary 对象中删除具有指定键的元素。 (继承自 DbConnectionStringBuilder)
IEnumerable.GetEnumerator()	返回循环访问集合的枚举器。 (继承自 DbConnectionStringBuilder)

扩展方法

Cast<TResult>(IEnumerable)	将 IEnumerable 的元素强制转换为指定类型。
OfType<TResult>(IEnumerable)	根据指定类型筛选 IEnumerable 的元素。
AsParallel(IEnumerable)	启用查询的并行化。
AsQueryable(IEnumerable)	将 IEnumerable 转换为 IQueryable。

另请参阅

• 连接字符串 （ADO.NET）
• ADO.NET 概述