SqlConnectionStringBuilder 类

定义

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

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
[System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
[<System.ComponentModel.TypeConverter(typeof(System.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder
Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder
继承
SqlConnectionStringBuilder
属性

示例

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

注意

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

using System.Data;
using System.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";
        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(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";
    }
}
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(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"
        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(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

注解

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

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

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

Item 属性句柄尝试插入恶意条目。 例如,下面的代码使用默认 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 设置此属性的值。 有关对 Always On 可用性组的 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

获取或设置一个布尔值,该值指示是否在连接中指定用户 ID 和密码(值为 false 时),或者是否使用当前的 Windows 帐户凭据进行身份验证(值为 true 时)。

IsFixedSize

获取一个值,该值指示 SqlConnectionStringBuilder 是否具有固定大小。

IsFixedSize

获取一个值,该值指示 DbConnectionStringBuilder 是否具有固定大小。

(继承自 DbConnectionStringBuilder)
IsReadOnly

获取一个值,该值指示 DbConnectionStringBuilder 是否为只读。

(继承自 DbConnectionStringBuilder)
Item[String]

获取或设置与指定的键关联的值。 在 C# 中,此属性为索引器。

Keys

获取包含 ICollection 中的键的 SqlConnectionStringBuilder

LoadBalanceTimeout

获取或设置连接被销毁前在连接池中存活的最短时间(以秒为单位)。

MaxPoolSize

获取或设置针对此特定连接字符串连接池中所允许的最大连接数。

MinPoolSize

获取或设置针对此特定连接字符串连接池中所允许的最小连接数。

MultipleActiveResultSets

如果为 true,则应用程序可以维护多个活动结果集 (MARS)。 如果为 false,则应用程序必须先处理或取消某一批中的所有结果集,才可以在该连接上执行任何其他批次。

有关详细信息,请参阅多个活动结果集 (MARS)

MultiSubnetFailover

如果应用程序连接到Always On可用性组, (AG) 或Always On故障转移群集实例 (FCI) 不同子网,则设置 MultiSubnetFailover=true 可以更快地检测当前) 活动服务器的 (并连接到。 有关 sqlClient 对Always On功能的支持的详细信息,请参阅 SqlClient 支持高可用性和灾难恢复

NetworkLibrary

获取或设置一个字符串,该字符串包含用于建立与 SQL Server 的连接的网络库的名称。

PacketSize

获取或设置用来与 SQL Server 的实例通信的网络数据包的大小(以字节为单位)。

Password

获取或设置 SQL Server 帐户的密码。

PersistSecurityInfo

获取或设置一个值,该值指示安全敏感信息(如密码或访问令牌)是否应作为连接字符串的一部分返回,该连接一直处于打开状态后,使用该SqlConnectionStringBuilder连接创建的连接。

PoolBlockingPeriod

连接池的暂停时段行为。

Pooling

获取或设置一个布尔值,该值指示每次请求连接时该连接是汇入连接池还是显式打开。

Replication

获取或设置一个布尔值,该值指示是否使用连接来支持复制。

TransactionBinding

获取或设置一个字符串值,该值表示连接如何保持与登记的 System.Transactions 事务的关联。

TransparentNetworkIPResolution

将该键的值设置为 true 时,需要应用程序检索特定 DNS 条目的所有 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)

从特定的 ICollection 索引开始,将 Array 的元素复制到一个 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.IsFixedSize

获取一个值,该值指示 IDictionary 对象是否具有固定大小。

(继承自 DbConnectionStringBuilder)
IDictionary.IsReadOnly

获取一个值,该值指示 IDictionary 是否为只读。

(继承自 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

适用于

另请参阅