SqlConnection.ConnectionString 属性

定义

命名空间:

System.Data.SqlClient

程序集:

System.Data.SqlClient.dll

包:

System.Data.SqlClient v4.8.6

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

public:
 virtual property System::String ^ ConnectionString { System::String ^ get(); void set(System::String ^ value); };

public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

属性值

String

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

例外

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 不同，如果“持久安全信息”值 (设置为false默认) ，则返回的连接字符串与用户集 ConnectionString相同，减去安全信息。 SQL Server的.NET Framework数据提供程序不会保留或返回连接字符串中的密码，除非将“持久化安全信息”设置为 true。

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

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

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

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

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

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

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

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

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

关键字不区分大小写。

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

关键字	默认	说明
Addr	不可用	数据源的同义词。
地址	不可用	数据源的同义词。
应用	不可用	应用程序名称的同义词。
应用程序名称	不可用	应用程序的名称，如果未提供应用程序名称，则为“.NET SQLClient 数据提供程序”。 应用程序名称可以是 128 个字符或更少。
ApplicationIntent	ReadWrite	连接到服务器时声明应用程序工作负荷类型。 可能的值为 ReadOnly 和 ReadWrite。 例如： ApplicationIntent=ReadOnly 有关对 Always On 可用性组的 SqlClient 支持的详细信息，请参阅对高可用性、灾难恢复的 SqlClient 支持。
Asynchronous Processing - 或 - Async	“false”	如果 true为 ，则启用异步操作支持。 已识别的值为 true、false、yes 和 no。 从 .NET Framework 4.5 开始忽略此属性。 有关 SqlClient 对异步编程的支持的详细信息，请参阅 异步编程。
AttachDBFilename - 或 - 扩展属性 - 或 - 初始文件名	不可用	主数据库文件的名称，包括可附加数据库的完整路径名称。 只有扩展名为 .mdf 的主数据文件才支持 AttachDBFilename。 如果在连接字符串中指定了 AttachDBFileName 键的值，则附加数据库并成为连接的默认数据库。 如果未指定此键，并且以前附加了数据库，则不会重新附加该数据库。 先前附加的数据库将用作连接的默认数据库。 如果此键与 AttachDBFileName 键一起指定，则此键的值将用作别名。 但是，如果该名称已在另一个附加数据库中使用，则连接将失败。 通过使用 DataDirectory 替换字符串，路径可以是绝对路径或相对路径。 如果使用 DataDirectory，则数据库文件必须存在于替换字符串指向的目录的子目录中。 注意： 不支持远程服务器、HTTP 和 UNC 路径名称。 必须使用关键字“database” (或其别名之一) 指定数据库名称，如下所示： "AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase" 如果日志文件和数据文件存在于同一个目录中，并且在附加主数据文件时使用“database”关键字，则将生成错误。 在这种情况下，请移除日志文件。 附加数据库后，将基于物理路径自动生成一个新日志文件。
身份验证	空值	用于使用 Azure Active Directory 身份验证连接到 SQL 数据库 的身份验证方法。 有效值是： Active Directory 集成、Active Directory 密码、Sql 密码。
列加密设置	不可用	启用或禁用连接Always Encrypted功能。
连接超时值 - 或 - 连接超时值 - 或 - 超时	15	在终止尝试并生成错误之前，) 等待与服务器的连接 (的时间长度（以秒为单位）。 有效值大于或等于 0，小于或等于 2147483647。 打开与 Azure SQL 数据库的连接时，将连接超时设置为 30 秒。
连接生存期 - 或 - Load Balance Timeout	0	连接返回到池中后，创建时间将与当前时间进行比较，如果时间跨度（秒）超过 Connection Lifetime 指定的值，该连接将被破坏。 在聚集配置中可以使用它来强制在运行服务器和刚联机的服务器之间达到负载平衡。 值为 0 (0) 会导致共用连接具有最大连接超时。
ConnectRetryCount	1	控制客户端识别空闲连接失败后的重新连接尝试次数。 有效值为 0 到 255。 默认值为 1。 0 表示不要尝试重新连接 (禁用连接复原) 。 有关连接复原能力的其他信息，请参阅 连接重试的 .NET SqlConnection 参数 和技术 文章 - 空闲连接复原。
ConnectRetryInterval	10	指定每次连接重试尝试 (ConnectRetryCount) 之间的时间。 第一次重新连接尝试后应用的有效值为 1 到 60 秒， (default=10) 。 检测到连接断开时，客户端会立即尝试重新连接;这是第一次重新连接尝试，仅当 ConnectRetryCount 大于 0 时才会发生。 如果第一次重新连接尝试失败，并且 ConnectRetryCount 大于 1，客户端将等待 ConnectRetryInterval 尝试第二次和后续重新连接尝试。 有关连接复原能力的其他信息，请参阅 连接重试的 .NET SqlConnection 参数 和技术 文章 - 空闲连接复原。
上下文连接	“false”	true如果应与SQL Server建立进程内连接，则为 。
当前语言 - 或 - 语言	不可用	设置用于数据库服务器警告或错误消息的语言。 语言名称可以是 128 个字符或更少。
数据源 - 或 - 服务器 - 或 - 地址 - 或 - Addr - 或 - 网络地址	不可用	要连接到的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 name<> 命名管道格式必须以前缀“np：”开头，后跟命名管道名称。 必须通过以下方式之一指定主机名： - NetBIOSName - IPv4Address - IPv6Address 管道名称用于标识.NET Framework应用程序将连接到的数据库实例。 如果指定 了网络 键的值，则不应指定前缀“tcp：”和“np：”。 注意： 可以通过在连接字符串中的服务器名称前加上 tcp： 前缀，或使用 localhost 来强制使用 TCP 而不是共享内存。
加密	“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 个字符或更少。 如果指定了故障转移伙伴，但未为数据库镜像配置故障转移伙伴服务器，并且使用 Server 关键字) 指定的主服务器 (不可用，则连接将失败。 如果指定了故障转移伙伴，并且主服务器未配置数据库镜像，则如果主服务器可用，则使用 Server 关键字) 指定的主服务器 (连接将成功。
初始目录 - 或 - 数据库	不可用	数据库的名称。 数据库名称可以是 128 个字符或更少。
集成安全性 - 或 - Trusted_Connection	“false”	如果 false为 ，则会在连接中指定用户 ID 和密码。 如果 true为 ，则使用当前的 Windows 帐户凭据进行身份验证。 已识别的值是 true、 false、 yes、 no和 sspi (强烈建议) ，这等效于 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	false	在连接到 SQL Server 2012 (或更高版本的可用性组侦听器时，始终指定multiSubnetFailover=True) 可用性组或 SQL Server 2012 (或更高版本) 故障转移群集实例。 multiSubnetFailover=True 配置 SqlClient 以更快地检测当前) 活动服务器的 (并连接到该服务器。 可能的值为 Yes 和 No、 True 和 False 或 1 。0 例如： MultiSubnetFailover=True 默认值为 False。 有关 SqlClient 对 Always On AG 的支持的详细信息，请参阅 SqlClient 支持高可用性和灾难恢复。
Network Library - 或 - 网络 - 或 - Net	不可用	用于与 SQL Server 实例建立连接的网络库。 支持的值包括： dbnmpntw (命名管道) dbmsrpcn (Multiprotocol、Windows RPC) dbmsadsn (Apple Talk) dbmsgnet (VIA) dbmslpcn (共享内存) dbmsspxn (IPX/SPX) dbmssocn (TCP/IP) Dbmsvinn (Banyan Vines) 必须在系统上安装您要连接到的相应网络 DLL。 如果未指定网络，并且使用本地服务器 (例如“.”或“ (本地) ”) ，则使用共享内存。 在此示例中，网络库是 Win32 Winsock TCP/IP (dbmssocn)，1433 是使用的端口。 Network Library=dbmssocn;Data Source=000.000.000.000,1433;
Packet Size	8000	用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。 数据包大小可以大于或等于 512，小于或等于 32768。
密码 - 或 - PWD	不可用	SQL Server帐户登录的密码。 建议不要使用。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential是指定使用SQL Server身份验证的连接凭据的更安全方法。 密码必须为 128 个字符或更少。
持久性安全信息 - 或 - PersistSecurityInfo	“false”	false设置为 或no (强烈建议) 时，如果连接处于打开状态或一直处于打开状态，则不会作为连接的一部分返回安全敏感信息（如密码）。 重置连接字符串会重置所有连接字符串值，包括密码。 已识别的值为 true、false、yes 和 no。
PoolBlockingPeriod	自动	设置连接池的阻塞时间段行为。 有关详细信息，请参阅 PoolBlockingPeriod 属性。
Pooling	'true'	如果此键的值设置为 true，则应用程序关闭时，任何新创建的连接都将添加到池中。 在下一次尝试打开同一连接时，将从池中提取该连接。 如果连接具有相同的连接字符串，则它们被视为相同。 不同的连接具有不同的连接字符串。 此键的值可以是“true”、“false”、“yes”或“no”。
复制	“false”	true 如果支持使用连接进行复制，则为 。
Transaction Binding	Implicit Unbind	控制与登记 System.Transactions 事务的连接关联。 可能的值包括： Transaction Binding=Implicit Unbind; Transaction Binding=Explicit Unbind; 隐式取消绑定会导致连接在事务结束时从该事务分离。 分离后，在自动模式下对连接执行其他请求。 在事务处于活动状态的情况下，执行请求时不会检查 System.Transactions.Transaction.Current 属性。 事务结束后，会在自动模式下执行其他请求。 如果系统在最后一个命令完成之前，在 using 块) 的范围内结束事务 (，则会引发 InvalidOperationException。 显式取消绑定会导致连接一直附加到事务，直到连接关闭或调用显式 SqlConnection.TransactionEnlist(null) 。 从 .NET Framework 4 开始，对隐式取消绑定的更改会使显式取消绑定过时。 如果 InvalidOperationException 不是登记事务或者登记事务未处于活动状态，则将引发 Transaction.Current。
TransparentNetworkIPResolution	请参阅说明。	将该键的值设置为 true 时，需要应用程序检索特定 DNS 条目的所有 IP 地址并尝试连接到列表中的第一个地址。 如果未在 0.5 秒内建立连接，应用程序将尝试并行连接到所有其他地址。 第一个地址响应后，应用程序将与响应的 IP 地址建立连接。 如果键 MultiSubnetFailover 设置为 true， TransparentNetworkIPResolution 则忽略 。 Failover Partner如果设置了键，TransparentNetworkIPResolution则忽略 。 此键的值必须是 true、 false、 yes或 no。 值 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”	如果设置为 true，则 SSL 用于在绕过证书链以验证信任时加密通道。 如果将 TrustServerCertificate 设置为 true ，并将 Encrypt 设置为 false，则通道不会加密。 已识别的值为 true、false、yes 和 no。 有关详细信息，请参阅连接字符串语法。
类型系统版本	不可用	一个字符串值，指示应用程序所需的类型系统。 可用于客户端应用程序的功能取决于 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;。
用户 ID - 或 - UID - 或 - 用户	不可用	SQL Server登录帐户。 建议不要使用。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential是为使用 SQL Server 身份验证的连接指定凭据的更安全方法。 用户 ID 必须为 128 个字符或更少。
User Instance	“false”	一个 值，该值指示是否将连接从默认SQL Server Express 实例重定向到在调用方帐户下运行的运行时启动的实例。
工作站 ID - 或 - WSID	本地计算机名称	连接到SQL Server的工作站的名称。 ID 必须为 128 个字符或更少。

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

• 连接生存期 (或负载均衡超时)

• Enlist

• Max Pool Size

• Min Pool Size

• Pooling

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

注意

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

注意

.NET Framework data Provider for SQL Server 不支持 UDL) 文件的通用数据链接 (。

注意

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

另请参阅

• ADO.NET 托管提供程序和 DataSet 开发人员中心
• ADO.NET 中的连接字符串
• SQL Server 连接池 (ADO.NET)
• 在 ADO.NET 中连接到数据源
• ADO.NET 概述