SqlConnection.ConnectionString 属性

定义

命名空间:

System.Data.SqlClient

程序集:

System.Data.SqlClient.dll

程序集:

System.Data.dll

获取或设置用于打开 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 (默认) ，则减去安全信息。 SQL Server.NET Framework数据提供程序不会持久保存或返回连接字符串中的密码，除非将“持久安全信息”设置为 true。

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

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

使用新 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) 会导致共用连接具有最大连接超时。
ConnectRetryCount	1	控制客户端标识空闲连接失败后重新连接尝试次数。 有效值为 0 到 255。 默认值为 1。 0 表示不会尝试重新连接 (禁用连接复原) 。 若要详细了解空闲连接复原，请参阅技术文章 - 空闲连接复原。
ConnectRetryInterval	10	指定每个连接重试尝试 (ConnectRetryCount) 之间的时间。 有效值为 1 到 60 秒 (default=10) ，在第一次重新连接尝试后应用。 检测到断开的连接时，客户端会立即尝试重新连接;这是第一次重新连接尝试，仅当 ConnectRetryCount 大于 0 时才发生。 如果第一次重新连接尝试失败，ConnectRetryCount 大于 1，客户端将等待 ConnectRetryInterval 尝试第二次和后续重新连接尝试。 若要详细了解空闲连接复原，请参阅技术文章 - 空闲连接复原。
上下文连接	“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>\<实例名称> - tcp：<host name>，<TCP/IP port number> TCP 格式必须以前缀“tcp：”开头，后跟数据库实例，由主机名和实例名称指定。 连接到Azure SQL 数据库时，此格式不适用。 如果未指定任何协议，则会自动选择 TCP 连接到Azure SQL 数据库。 必须通过以下方式之一指定主机名： - NetBIOSName - IPv4Address - IPv6Address 实例名称用于解析为托管数据库实例的特定 TCP/IP 端口号。 或者，还允许直接指定 TCP/IP 端口号。 如果实例名称和端口号不存在，则使用默认数据库实例。 命名管道格式如下所示： - np：\\<主机名>\管道\<管道名称> 命名管道格式必须以前缀“np：”开头，后跟命名管道名称。 必须通过以下方式之一指定主机名： - NetBIOSName - IPv4Address - IPv6Address 管道名称用于标识.NET Framework应用程序要连接到的数据库实例。 如果指定 了网络 键的值，则不应指定前缀“tcp：”和“np：”。 注意： 可以通过在连接字符串中的服务器名称或 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 个字符或更少。 如果指定故障转移伙伴，但未为数据库镜像配置故障转移伙伴服务器，并且主服务器 (使用服务器关键字) 指定的主服务器不可用，则连接将失败。 如果指定故障转移伙伴且未为数据库镜像配置主服务器，则与主服务器的连接 (使用服务器关键字) 成功（如果主服务器可用）。
初始目录 - 或 - 数据库	不可用	数据库的名称。 数据库名称可以是 128 个字符或更少。
集成安全性 - 或 - Trusted_Connection	“false”	在连接中指定用户 ID 和密码时 false。 当true，当前Windows帐户凭据用于身份验证。 识别的值是、、、和 no``sspi (强烈建议) ，这相当于true。 yes``false``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	始终指定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 - 或 - 网络 - 或 - Net	不可用	用于建立与SQL Server实例的连接的网络库。 支持的值包括： dbnmpntw (命名管道) dbmsrpcn (Multiprotocol，Windows RPC) dbmsadsn (Apple Talk) dbmsgnet (VIA) dbmslpcn (共享内存) dbmsspxn (IPX/SPX) dbmssocn (TCP/IP) Dbmsvinn (班扬文斯) 必须在系统上安装您要连接到的相应网络 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 属性。 事务结束后，会在自动模式下执行其他请求。 如果系统在上一个命令完成之前使用块) 的作用域内结束事务 (，则会引发 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”	When set to true, SSL is used to encrypt the channel when bypassing walking the certificate chain to validate trust. 如果将 TrustServerCertificate 设置为 true “加密 false”，则不会对通道进行加密。 已识别的值为 true、false、yes 和 no。 有关详细信息，请参阅连接字符串语法。
类型系统版本	不可用	一个字符串值，指示应用程序所需的类型系统。 可用于客户端应用程序的功能取决于 SQL Server 版本和数据库的兼容性级别。 如果使用的是 SQL Server 的其他版本，则显式设置编写的客户端应用程序所针对的类型系统版本可避免导致应用程序中断的潜在问题。 注意： 无法为公共语言运行时 (CLR) 代码在 SQL Server 中执行进程内的代码设置类型系统版本。 有关详细信息，请参阅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 概述