通过

SqlConnection.ConnectionString 属性

定义

命名空间:
System.Data.SqlClient
程序集:
System.Data.SqlClient.dll
程序集:
System.Data.dll
Source:
System.Data.SqlClient.notsupported.cs

获取或设置用于打开 SQL Server 数据库的字符串。

public:
 virtual property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
public:
 property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };
public override string ConnectionString { get; set; }
[System.Data.DataSysDescription("SqlConnection_ConnectionString")]
public string ConnectionString { get; set; }
[System.ComponentModel.SettingsBindable(true)]
public override string ConnectionString { get; set; }
member this.ConnectionString : string with get, set
[<System.Data.DataSysDescription("SqlConnection_ConnectionString")>]
member this.ConnectionString : string with get, set
[<System.ComponentModel.SettingsBindable(true)>]
member this.ConnectionString : string with get, set
Public Overrides Property ConnectionString As String
Public Property ConnectionString As String

属性值

String

包含源数据库名称的连接字符串，以及建立初始连接所需的其他参数。 默认值为空字符串。

实现

ConnectionString
属性
DataSysDescriptionAttribute SettingsBindableAttribute

例外

ArgumentException

提供了无效的连接字符串参数，或者尚未提供所需的连接字符串参数。

示例

以下示例在打开连接之前创建 SqlConnection 并设置 ConnectionString 属性。

private static void OpenSqlConnection()
{
    string connectionString = GetConnectionString();

    using (SqlConnection connection = new SqlConnection())
    {
        connection.ConnectionString = connectionString;

        connection.Open();

        Console.WriteLine("State: {0}", connection.State);
        Console.WriteLine("ConnectionString: {0}",
            connection.ConnectionString);
    }
}

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

Private Sub OpenSqlConnection()
    Dim connectionString As String = GetConnectionString()

    Using connection As New SqlConnection()

        connection.ConnectionString = connectionString

        connection.Open()

        Console.WriteLine("State: {0}", connection.State)
        Console.WriteLine("ConnectionString: {0}", _
            connection.ConnectionString)
    End Using
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 "Data Source=MSSQL1;Database=AdventureWorks;" _
      & "Integrated Security=true;"
End Function

注解

这 ConnectionString 类似于 OLE DB 连接字符串，但并不相同。 与 OLE DB 或 ADO 不同，返回的连接字符串与用户集 ConnectionString相同，如果持久安全信息值设置为 false （默认值），则减去安全信息。 除非将持久安全信息 true设置为 ，否则用于 SQL Server 的 .NET Framework 数据提供程序不会持久保存或返回连接字符串中的密码。

可以使用该 ConnectionString 属性连接到数据库。 以下示例演示了典型的连接字符串。

"Persist Security Info=False;Integrated Security=true;Initial Catalog=Northwind;server=(local)"

使用新 SqlConnectionStringBuilder 函数在运行时构造有效的连接字符串。 有关详细信息，请参阅连接字符串生成器。

ConnectionString仅当连接关闭时，才能设置该属性。 许多连接字符串值都具有相应的只读属性。 设置连接字符串时，将更新这些属性，但检测到错误时除外。 在这种情况下，不会更新任何属性。 SqlConnection 属性仅返回包含在 中的 ConnectionString设置。

若要连接到本地计算机，请为服务器指定“（local）”。 如果未指定服务器名称，则会尝试连接到本地计算机上的默认实例。

重置 ConnectionString 关闭的连接会重置所有连接字符串值（和相关属性），包括密码。 例如，如果设置包含“Database= AdventureWorks”的连接字符串，然后将连接字符串重置为“Data Source=myserver;Integrated Security=true“， Database 该属性不再设置为”AdventureWorks”。

设置后立即分析连接字符串。 如果在分析时发现语法中的错误，则会生成运行时异常（例如 ArgumentException）。 仅当尝试打开连接时，才能找到其他错误。

连接字符串的基本格式包括由分号分隔的一系列关键字/值对。 等号 （=） 连接每个关键字及其值。 若要包含包含分号、单引号字符或双引号字符的值，该值必须用双引号引起来。 如果值同时包含分号和双引号字符，则该值可以括在单引号中。 如果值以双引号字符开头，则单引号也很有用。 相反，如果值以单引号开头，则可以使用双引号。 如果值同时包含单引号字符和双引号字符，则每次值在值内发生时，都必须将用于封闭值的引号字符加倍。

若要在字符串值中包含前面或尾随空格，该值必须括在单引号或双引号中。 即使用引号括起来，整数、布尔值或枚举值周围的任何前导或尾随空格也会被忽略。 但是，保留字符串文本关键字或值内的空格。 在连接字符串中可以使用单引号或双引号而不使用分隔符（例如，Data Source= my'Server 或 Data Source= my“Server），除非引号字符是值中的第一个字符或最后一个字符。

关键字不区分大小写。

下表列出了 中的 ConnectionString关键字值的有效名称。

关键字 默认 说明
Addr 不适用 数据源的同义词。
Address 不适用 数据源的同义词。
App 不适用 应用程序名称的同义词。
Application Name 不适用 应用程序的名称;如果未提供任何应用程序名称，则为“.NET SQLClient 数据提供程序”。

应用程序名称可以是 128 个字符或更少。
ApplicationIntent ReadWrite 连接到服务器时声明应用程序工作负荷类型。 可能的值为 ReadOnly 和 ReadWrite。 例如：

ApplicationIntent=ReadOnly

有关 SqlClient 对 AlwaysOn 可用性组支持的更多信息，请参阅 SqlClient 对高可用性和灾难恢复的支持。
Asynchronous Processing
-或-
Async		 “false” 启用异步操作支持时 true。 已识别的值为 true、false、yes 和 no。

此属性从 .NET Framework 4.5 开始被忽略。 有关 SqlClient 对异步编程的支持的详细信息，请参阅 异步编程。
AttachDBFilename
-或-
Extended Properties
-或-
Initial File Name		 不适用 主数据库文件的名称，包括可附加数据库的完整路径名称。 仅支持扩展名为 .mdf 的主数据文件的 AttachDBFilename。

如果在连接字符串中指定了 AttachDBFileName 键的值，则会附加数据库，并成为连接的默认数据库。

如果未指定此键，并且以前附加了数据库，则不会重新附加数据库。 以前附加的数据库将用作连接的默认数据库。

如果此键与 AttachDBFileName 键一起指定，则此键的值将用作别名。 但是，如果名称已在另一个附加数据库中使用，则连接将失败。

路径可以是绝对路径，也可以是相对路径，方法是使用 DataDirectory 替换字符串。 如果使用 DataDirectory，数据库文件必须存在于替换字符串指向的目录的子目录中。 注意： 不支持远程服务器、HTTP 和 UNC 路径名称。

必须使用关键字“database”（或其别名之一）指定数据库名称，如下所示：

"AttachDbFileName=&#124;DataDirectory&#124;\data\YourDB.mdf;integrated security=true;database=YourDatabase"

如果日志文件与数据文件位于同一目录中，并且附加主数据文件时使用“database”关键字，则会生成错误。 在这种情况下，请删除日志文件。 附加数据库后，将基于物理路径自动生成新的日志文件。
Authentication 不适用 用于 使用 Azure Active Directory 身份验证连接到 SQL 数据库的身份验证方法。

有效值为：

Active Directory 集成、Active Directory 密码、Sql 密码。
Column Encryption Setting 不适用 启用或禁用连接的 Always Encrypted 功能。
Connect Timeout
-或-
Connection Timeout
-或-
Timeout		 15 在终止尝试并生成错误之前等待与服务器建立连接的时间（以秒为单位）。

有效值大于或等于 0，小于或等于2147483647。

打开与 Azure SQL 数据库的连接时，将连接超时设置为 30 秒。
Connection Lifetime
-或-
Load Balance Timeout		 0 连接返回到池中后，创建时间将与当前时间进行比较，如果时间跨度（秒）超过 Connection Lifetime 指定的值，该连接将被破坏。 在聚集配置中可以使用它来强制在运行服务器和刚联机的服务器之间达到负载平衡。

值为零（0）会导致共用连接具有最大连接超时。
ConnectRetryCount 1 控制客户端标识空闲连接失败后重新连接尝试次数。 有效值为 0 到 255。 默认值为 1。 0 表示不尝试重新连接（禁用连接复原）。

有关连接复原的其他信息，请参阅 有关连接重试的 .NET SqlConnection 参数 和技术 文章 - 空闲连接复原能力。
ConnectRetryInterval 10 指定每个连接重试尝试（ConnectRetryCount）之间的时间。 有效值为 1 到 60 秒（default=10），在首次重新连接尝试后应用。 检测到断开的连接时，客户端会立即尝试重新连接;这是第一次重新连接尝试，仅当 ConnectRetryCount 大于 0 时才发生。 如果第一次重新连接尝试失败并且 ConnectRetryCount 大于 1，客户端将等待 ConnectRetryInterval 尝试第二次和后续重新连接尝试。

有关连接复原的其他信息，请参阅 有关连接重试的 .NET SqlConnection 参数 和技术 文章 - 空闲连接复原能力。
Context Connection “false” true 如果应建立与 SQL Server 的进程内连接，则为
Current Language
-或-
Language		 不适用 设置用于数据库服务器警告或错误消息的语言。

语言名称可以是 128 个字符或更少。
Data Source
-或-
Server
-或-
Address
-或-
Addr
-或-
Network Address		 不适用 要连接到的 SQL Server 实例的名称或网络地址。 可以在服务器名称后指定端口号：

server=tcp:servername, portnumber

指定本地实例时，请始终使用（本地）。 若要强制协议，请添加以下前缀之一：

np:(local), tcp:(local), lpc:(local)

从 .NET Framework 4.5 开始，还可以按如下所示连接到 LocalDB 数据库：

server=(localdb)\\myInstance

有关 LocalDB 的详细信息，请参阅 SqlClient 对 LocalDB 的支持。

数据源 必须使用 TCP 格式或命名管道格式。

TCP 格式如下所示：

- tcp：<host name>\<instance name>
- tcp：<主机名>，<TCP/IP 端口号>

TCP 格式必须以前缀“tcp：”开头，后跟数据库实例，由主机名和实例名称指定。 连接到 Azure SQL 数据库时，此格式不适用。 如果未指定协议，则会自动选择 TCP 以连接到 Azure SQL 数据库。

必须通过以下方式之一指定主机名：

- NetBIOSName
- IPv4Address
- IPv6Address

实例名称用于解析为托管数据库实例的特定 TCP/IP 端口号。 或者，还可以直接指定 TCP/IP 端口号。 如果实例名称和端口号均不存在，则使用默认数据库实例。

命名管道格式如下所示：

- np：\\<host name>\pipe\pipe 名称<>

命名管道格式必须以前缀“np：”开头，后跟命名管道名称。

必须通过以下方式之一指定主机名：

- NetBIOSName
- IPv4Address
- IPv6Address

管道名称用于标识 .NET Framework 应用程序要连接到的数据库实例。

如果指定 了网络 键的值，则不应指定前缀“tcp：”和“np：”。 注意：可以通过将 tcp 前缀添加到连接字符串中的服务器名称或使用 localhost 来强制使用 TCP 而不是共享内存。
Encrypt “false” 当 true，如果服务器安装了证书，则 SQL Server 对客户端和服务器之间发送的所有数据使用 SSL 加密。 已识别的值为 true、false、yes 和 no。 有关详细信息，请参阅连接字符串语法。

从 .NET Framework 4.5 开始，如果 TrustServerCertificate 为 false 且 Encrypt 为 true，则 SQL Server SSL 证书中的服务器名称（或 IP 地址）必须与连接字符串中指定的服务器名称（或 IP 地址）完全匹配。 否则，连接尝试将失败。
Enlist 'true' true 指示 SQL Server 连接池器会自动在创建线程的当前事务上下文中登记连接。
Failover Partner 不适用 配置数据库镜像的故障转移伙伴服务器的名称。

如果此键的值为“”，则 初始目录 必须存在，并且其值不得为“”。

服务器名称可以是 128 个字符或更少。

如果指定了故障转移伙伴，但故障转移伙伴服务器未配置为数据库镜像，并且主服务器（使用服务器关键字指定）不可用，则连接将失败。

如果指定故障转移伙伴，并且主服务器未配置为数据库镜像，则如果主服务器可用，则与主服务器（使用服务器关键字指定的）的连接将成功。
Initial Catalog
-或-
Database		 不适用 数据库的名称。

数据库名称可以是 128 个字符或更少。
Integrated Security
-或-
Trusted_Connection		 “false” 在连接中指定用户 ID 和密码时 false。 当 true，当前 Windows 帐户凭据用于身份验证。

识别的值是true、false、yes和 nosspi （强烈建议），这相当于true。

如果指定了用户 ID 和密码，并且集成安全性设置为 true，则会忽略用户 ID 和密码，并且将使用集成安全性。

SqlCredential 是一种更安全的方法，用于指定使用 SQL Server 身份验证的连接凭据（Integrated Security=false）。
Max Pool Size 100 池中允许的最大连接数。

有效值大于或等于 1。 小于 最小池大小 的值将生成错误。
Min Pool Size 0 池中允许的最小连接数。

有效值大于或等于 0。 此字段中的零（0）表示最初未打开最小连接。

大于 最大池大小 的值将生成错误。
MultipleActiveResultSets “false” 当 true，应用程序可以维护多个活动结果集（MARS）。 当 false，应用程序必须处理或取消一个批处理中的所有结果集，然后才能在该连接上执行任何其他批处理。

已识别的值为 true 和 false。

有关详细信息，请参阅多个活动结果集（MARS）。
MultiSubnetFailover 假 始终指定 multiSubnetFailover=True 连接到 SQL Server 2012（或更高版本）可用性组或 SQL Server 2012（或更高版本）故障转移群集实例的可用性组侦听器时。 multiSubnetFailover=True 将 SqlClient 配置为更快地检测和连接到活动服务器（当前）服务器。 可能的值为Yes和No，True以及False或或1。0 例如：

MultiSubnetFailover=True

默认值为 False。 有关 SqlClient 对 Always On AG 的支持的详细信息，请参阅 SqlClient 对高可用性、灾难恢复的支持。
Network Library
-或-
Network
-或-
Net		 不适用 用于建立与 SQL Server 实例的连接的网络库。 支持的值包括：

dbnmpntw （命名管道）

dbmsrpcn （Multiprotocol， Windows RPC）

dbmsadsn （Apple Talk）

dbmsgnet （VIA）

dbmslpcn （共享内存）

dbmsspxn （IPX/SPX）

dbmssocn （TCP/IP）

Dbmsvinn （班扬文斯）

必须在连接到的系统上安装相应的网络 DLL。 如果未指定网络并使用本地服务器（例如“.”或“（local），则使用共享内存。 在此示例中，网络库为 Win32 Winsock TCP/IP（dbmssocn），1433 是正在使用的端口。

Network Library=dbmssocn;Data Source=000.000.000.000,1433;
Packet Size 8,000 用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。

数据包大小可以大于或等于 512，小于或等于 32768。
Password
-或-
PWD		 不适用 登录的 SQL Server 帐户的密码。 不建议这样做。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential 是指定使用 SQL Server 身份验证的连接凭据的更安全方法。

密码必须为 128 个字符或更少。
Persist Security Info
-或-
PersistSecurityInfo		 “false” 设置为 false 或（强烈建议使用）时，如果连接处于打开状态或 no 处于打开状态，则不会返回安全敏感信息（如密码）作为连接的一部分。 重置连接字符串会重置所有连接字符串值，包括密码。 已识别的值为 true、false、yes 和 no。
PoolBlockingPeriod 自动 设置连接池的阻塞期行为。 有关详细信息，请参阅 PoolBlockingPeriod 属性。
Pooling 'true' 当此键的值设置为 true 时，应用程序关闭时，任何新创建的连接都将添加到池中。 在下一次尝试打开同一连接时，将从池中提取该连接。

如果连接具有相同的连接字符串，则被视为相同的连接。 不同的连接具有不同的连接字符串。

此键的值可以是“true”、“false”、“yes”或“no”。
Replication “false” true 如果连接支持复制，则为 。
Transaction Binding 隐式解除绑定 控制与登记事务 System.Transactions 的连接关联。

可能的值为：

Transaction Binding=Implicit Unbind;

Transaction Binding=Explicit Unbind;

隐式取消绑定会导致连接在事务结束时与事务分离。 分离后，在自动提交模式下对连接执行其他请求。 在 System.Transactions.Transaction.Current 事务处于活动状态时执行请求时，不会检查该属性。 事务结束后，以自动提交模式执行其他请求。

如果系统在最后一个命令完成之前（在 using 块的范围内）结束事务，它将引发 InvalidOperationException。

显式取消绑定会导致连接保持附加到事务，直到连接关闭或调用显式 SqlConnection.TransactionEnlist(null) 。 从 .NET Framework 4 开始，对隐式取消绑定的更改使显式取消绑定已过时。 如果Transaction.Current不是登记的事务，或者登记的事务未处于活动状态，则会引发 anInvalidOperationException。
TransparentNetworkIPResolution 请参阅说明。 如果此密钥的值设置为 true，则应用程序需要检索特定 DNS 条目的所有 IP 地址，并尝试与列表中的第一个 IP 地址进行连接。 如果在 0.5 秒内未建立连接，应用程序将尝试并行连接到所有其他连接。 当第一个答案时，应用程序将与被调查者 IP 地址建立连接。

MultiSubnetFailover如果键设置为true，TransparentNetworkIPResolution则忽略。

Failover Partner如果设置了密钥，TransparentNetworkIPResolution则忽略。

此键的值必须为true、false或yesno。

值 yes 被视为与值 true相同的值。

值 no 被视为与值 false相同的值。

默认值如下：

  • false 当：

    • 连接到数据源结尾处的 Azure SQL 数据库：

      • .database.chinacloudapi.cn
      • .database.usgovcloudapi.net
      • .database.cloudapi.de
      • .database.windows.net
    • Authentication 是“Active Directory 密码”或“Active Directory 集成”
  • true 在所有其他情况下。
TrustServerCertificate “false” 设置为 /> 时，SSL 用于在绕过证书链来验证信任时加密通道。 如果将 TrustServerCertificate 设置为 true “加密 false”，则通道不会加密。 已识别的值为 true、false、yes 和 no。 有关详细信息，请参阅连接字符串语法。
Type System Version 不适用 一个字符串值，指示应用程序所需的类型系统。 客户端应用程序可用的功能取决于 SQL Server 的版本和数据库的兼容性级别。 显式设置客户端应用程序编写的类型系统版本，以避免在使用不同版本的 SQL Server 时可能导致应用程序中断的潜在问题。 注意： 无法为在 SQL Server 中执行进程内的公共语言运行时 （CLR） 代码设置类型系统版本。 有关详细信息，请参阅 SQL Server 公共语言运行时集成。

可能的值为：

Type System Version=SQL Server 2012;

Type System Version=SQL Server 2008;

Type System Version=SQL Server 2005;

Type System Version=Latest;

Type System Version=SQL Server 2012; 指定应用程序需要 11.0.0.0 版 Microsoft.SqlServer.Types.dll。 其他 Type System Version 设置需要版本 10.0.0.0 Microsoft.SqlServer.Types.dll。

Latest 已过时且不应使用。 Latest 等效于 Type System Version=SQL Server 2008;。
User ID
-或-
UID
-或-
User		 不适用 SQL Server 登录帐户。 不建议这样做。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential 是指定使用 SQL Server 身份验证的连接凭据的更安全方法。

用户 ID 必须为 128 个字符或更少。
User Instance “false” 一个值，该值指示是否将连接从默认 SQL Server Express 实例重定向到在调用方帐户下运行的运行时启动的实例。
Workstation ID
-或-
WSID		 本地计算机名称 连接到 SQL Server 的工作站的名称。

ID 必须为 128 个字符或更少。

以下列表包含连接池值的有效 ConnectionString名称。 有关详细信息，请参阅 SQL Server 连接池（ADO.NET）。

  • Connection Lifetime（或 Load Balance Timeout）
  • Enlist
  • Max Pool Size
  • Min Pool Size
  • Pooling

设置需要布尔值的关键字或连接池值时，可以使用yes而不是true布尔nofalse值。 整数值表示为字符串。

注释

适用于 SQL Server 的 .NET Framework 数据提供程序使用自己的协议来与 SQL Server 通信。 因此，它不支持在连接到 SQL Server 时使用 ODBC 数据源名称（DSN），因为它不添加 ODBC 层。

注释

适用于 SQL Server 的 .NET Framework 数据提供程序不支持通用数据链接 （UDL） 文件。

注意

基于用户输入构造连接字符串时要小心（例如，从对话框中检索用户 ID 和密码信息，并将其追加到连接字符串）。 确保用户不能在这些值中嵌入其他连接字符串参数（例如，输入密码为“validpassword;尝试附加到其他数据库时，database=somedb”。 如果需要基于用户输入构造连接字符串，请使用 SqlConnectionStringBuilder，这将验证连接字符串并帮助消除此问题。 有关详细信息，请参阅连接字符串生成器。

适用于

另请参阅