SqlConnection.ConnectionString 属性

定义

命名空间:

Microsoft.Data.SqlClient

程序集:

Microsoft.Data.SqlClient.dll

包:

Microsoft.Data.SqlClient v7.0.1

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

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

[System.ComponentModel.SettingsBindable(true)]
public override string ConnectionString { get; set; }

[<System.ComponentModel.SettingsBindable(true)>]
member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

属性值

String

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

属性

SettingsBindableAttribute

例外

ArgumentException

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

示例

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

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        OpenSqlConnection();
        Console.ReadLine();
    }

    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;";
    }
}

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

using System;
using System.Data;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        OpenSqlConnection();
        Console.ReadLine();
    }

    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;";
    }
}

注解

这 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关键字值的有效名称。

关键 字	默认	Description
Addr	N/A	数据源的同义词。
Address	N/A	数据源的同义词。
App	N/A	应用程序名称的同义词。
应用程序意向 -or- 应用意图	读写	连接到服务器时声明应用程序工作负荷类型。 可能的值为 ReadOnly 和 ReadWrite。 例如： ApplicationIntent=ReadOnly 有关 SqlClient 对 AlwaysOn 可用性组支持的更多信息，请参阅 SqlClient 对高可用性和灾难恢复的支持。
应用程序名称	N/A	申请名称。 如果未提供任何应用程序名称，则当在 .NET Framework 上运行时，“Framework Microsoft SqlClient Data Provider”，否则为“Core Microsoft SqlClient Data Provider”。 应用程序名称可以是 128 个字符或更少。
AttachDBFilename -or- 扩展属性 -or- 初始文件名	N/A	主数据库文件的名称，包括可附加数据库的完整路径名称。 仅支持扩展名为 .mdf 的主数据文件的 AttachDBFilename。 如果在连接字符串中指定了 AttachDBFileName 键的值，则会附加数据库，并成为连接的默认数据库。 如果未指定此键，并且以前附加了数据库，则不会重新附加数据库。 以前附加的数据库将用作连接的默认数据库。 如果此键与 AttachDBFileName 键一起指定，则此键的值将用作别名。 但是，如果名称已在另一个附加数据库中使用，则连接将失败。 路径可以是绝对路径，也可以是相对路径，方法是使用 DataDirectory 替换字符串。 如果使用 DataDirectory，数据库文件必须存在于替换字符串指向的目录的子目录中。 注意： 不支持远程服务器、HTTP 和 UNC 路径名称。 必须使用关键字“database”（或其别名之一）指定数据库名称，如下所示： "AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase" 如果日志文件与数据文件位于同一目录中，并且附加主数据文件时使用“database”关键字，则会生成错误。 在这种情况下，请删除日志文件。 附加数据库后，将基于物理路径自动生成新的日志文件。
证明协议	未指定	获取或设置证明协议的值。 如果未指定任何值，则会在连接上禁用安全 enclave。 有效值为： AAS HGS None （仅在 v3.1 和 v4.1+中有效）
Authentication	N/A	用于使用 Entra ID 身份验证连接 SQL 数据库的身份验证方法。 有效值为： Active Directory Integrated、Active Directory Interactive、Active Directory Password、Active Directory Service Principal、Active Directory Device Code Flow、Active Directory Managed Identity、Active Directory MSI、Active Directory Default、Sql Password。 有关详细信息，请参阅 使用 SqlClient 0 Entra ID身份验证。
列加密设置	禁用的	启用或禁用连接的 Always Encrypted 功能。 支持的值包括： enableddisabled
命令超时	30	在终止尝试执行命令并生成错误之前的默认等待时间（以秒为单位）。 有效值大于或等于 0，小于或等于2147483647。
连接重试计数 -or- 连接重试次数 (ConnectRetryCount)	1	控制客户端标识空闲连接失败后重新连接尝试次数。 有效值为 0 到 255。 0 表示不尝试重新连接（禁用连接复原）。 注意：由于版本 5.x，非Azure终结点的默认值为 1。 对于Azure SQL终结点，默认值为 2。 对于Azure SQL无服务器或按需终结点，默认值为 5，用于改善与空闲或已暂停实例的连接连接成功。 有关空闲连接复原的其他信息，请参阅 .NET SqlConnection 参数以获取连接重试和技术文章 - 空闲连接复原。
连接重试间隔 -or- ConnectRetryInterval (连接重试间隔)	10	指定每个连接重试尝试之间的时间（ConnectRetryCount）。 有效值为 1 到 60 秒（default=10），在首次重新连接尝试后应用。 检测到断开的连接时，客户端会立即尝试重新连接;这是第一次重新连接尝试，仅当大于 0 时才 ConnectRetryCount 发生。 如果第一次重新连接尝试失败且 ConnectRetryCount 大于 1，客户端将等待 ConnectRetryInterval 尝试第二次和后续重新连接尝试。 有关空闲连接复原的其他信息，请参阅.NET有关连接重试的 SqlConnection 参数和技术文章 - 空闲连接复原。
连接超时 -or- 连接超时值 -or- 超时	15	在终止尝试并生成错误之前等待与服务器建立连接的时间（以秒为单位）。 有效值大于或等于 0，小于或等于2147483647。 打开与 Azure SQL 数据库的连接时，将连接超时设置为 30 秒。
当前语言 -or- 语言	N/A	设置用于数据库服务器警告或错误消息的语言。 语言名称可以是 128 个字符或更少。
数据源 -or- 服务器 -or- Address -or- Addr -or- 网络地址	N/A	要连接到的 SQL Server 实例的名称或网络地址。 可以在服务器名称后指定端口号： server=tcp:servername, portnumber 指定本地实例时，请始终使用（本地）。 若要强制协议，请添加以下前缀之一： np:(local), tcp:(local), lpc:(local) 还可以按如下所示连接到 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应用程序要连接到的数据库实例。 如果指定 了网络 键的值，则不应指定前缀“tcp：”和“np：”。 注意：可以通过将 tcp 前缀添加到连接字符串中的服务器名称或使用 localhost 来强制使用 TCP 而不是共享内存。
Enclave 证明 URL	N/A	获取或设置用于基于 enclave 的 Always Encrypted 的 enclave 证明 URL。
加密	4.0 及更高版本中的“true” 3.x 及更低版本中的“false”	识别的值包括： 版本 1 - 4： true/yes 和 false/no 版本 5+：true/yesmandatory/和。 false/no/optionalstrict 如果 true服务器安装了证书，则 TLS 加密用于客户端和服务器之间发送的所有数据。 使用 TDS 8.0 TLS 加密时strictTrustServerCertificate，将忽略该设置并将其视为 false。 有关详细信息，请参阅连接字符串语法。 当 Encrypt 为 mandatory 或 strict，TrustServerCertificatefalse时，服务器证书中的服务器名称（或 IP 地址）必须与连接字符串中指定的服务器名称（或 IP 地址）完全匹配。 否则，连接尝试将失败。
争取	'true'	true 指示 SQL Server 连接池器会自动在创建线程的当前事务上下文中登记连接。
故障转移合作伙伴	N/A	配置数据库镜像的故障转移伙伴服务器的名称。 如果此键的值为“”，则 初始目录 必须存在，并且其值不得为“”。 服务器名称可以是 128 个字符或更少。 如果指定了故障转移伙伴，但故障转移伙伴服务器未配置为数据库镜像，并且主服务器（使用服务器关键字指定）不可用，则连接将失败。 如果指定故障转移伙伴，并且主服务器未配置为数据库镜像，则如果主服务器可用，则与主服务器（使用服务器关键字指定的）的连接将成功。
故障转移合作伙伴 SPN -or- FailoverPartnerSPN	N/A	故障转移伙伴的 SPN。 默认值为空字符串，导致 SqlClient 使用默认的驱动程序生成的 SPN。 （仅适用于 v5.0+）
证书中的主机名 -or- HostNameInCertificate	N/A	验证服务器证书时要使用的主机名。 如果未指定，则数据源中的服务器名称用于证书验证。 （仅适用于 v5.0+）
服务器证书 -or- ServerCertificate	N/A	要与 SQL Server TLS/SSL 证书匹配的证书文件的路径。 接受的证书格式为 PEM、DER 和 CER。 如果指定，则通过验证提供的 ServerCertificate 是否完全匹配来检查SQL Server证书。 （仅在 v5.1+ 中可用）
初始目录 -or- 数据库	N/A	数据库的名称。 数据库名称可以是 128 个字符或更少。
集成安全性 -or- Trusted_Connection	'false'	在连接中指定用户 ID 和密码时 false。 当 true，当前 Windows 帐户凭据用于身份验证。 识别的值是true、false、yes和 nosspi （强烈建议），这相当于true。 如果指定了用户 ID 和密码，并且集成安全性设置为 true，则会忽略用户 ID 和密码，并且将使用集成安全性。 SqlCredential 是一种更安全的方法，用于指定使用 SQL Server 身份验证的连接凭据（Integrated Security=false）。
IP 地址首选项 -or- IPAddressPreference	IPv4First	建立 TCP 连接时，IP 地址系列首选项。 如果 Transparent Network IP Resolution （在 .NET Framework 中） 或 Multi Subnet Failover 设置为 true，则此设置不起作用。 支持的值包括： IPAddressPreference=IPv4First IPAddressPreference=IPv6First IPAddressPreference=UsePlatformDefault
负载均衡超时 -or- 连接生存期	0	连接返回到池中后，创建时间将与当前时间进行比较，如果时间跨度（秒）超过 Connection Lifetime 指定的值，该连接将被破坏。 在聚集配置中可以使用它来强制在运行服务器和刚联机的服务器之间达到负载平衡。 值为零（0）会导致共用连接具有最大连接超时。
最大池大小	100	池中允许的最大连接数。 有效值大于或等于 1。 小于 最小池大小 的值将生成错误。
最小池大小	0	池中允许的最小连接数。 有效值大于或等于 0。 此字段中的零（0）表示最初未打开最小连接。 大于 最大池大小 的值将生成错误。
多重活动结果集 -or- MultipleActiveResultSets	false	当 true，应用程序可以维护多个活动结果集（MARS）。 当 false，应用程序必须处理或取消一个批处理中的所有结果集，然后才能在该连接上执行任何其他批处理。 已识别的值为 true 和 false。 有关详细信息，请参阅多个活动结果集（MARS）。
多子网故障转移 -or- 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 对高可用性、灾难恢复的支持。
网络库 -or- 网络 -or- 净额	N/A	用于建立与 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;
数据包大小	8,000	用于与 SQL Server 实例通信的网络数据包的大小（以字节为单位）。 数据包大小可以大于或等于 512，小于或等于 32768。
密码 -or- PWD	N/A	登录的 SQL Server 帐户的密码。 不建议这样做。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential 是指定使用 SQL Server 身份验证的连接凭据的更安全方法。 密码必须为 128 个字符或更少。
保持安全信息 -or- PersistSecurityInfo	'false'	设置为 false 或 no （强烈建议）安全敏感信息（如密码或访问令牌）在连接处于打开状态或以前处于打开状态时不会作为连接的一部分返回。 仅当应用程序需要从已打开的数据库连接中读取密码时，才应将此属性设置为 true 该属性。 默认值 false 为更安全的设置;使用 true 此属性可打开应用程序，面临安全风险，例如意外记录或跟踪数据库密码。 重置连接字符串会重置所有连接字符串值，包括密码。 已识别的值为 true、false、yes 和 no。
池阻塞期 -or- 连接阻塞周期	自动	设置连接池的阻塞期行为。 有关详细信息，请参阅 PoolBlockingPeriod 属性。
池	'true'	当此键的值设置为 true 时，应用程序关闭时，任何新创建的连接都将添加到池中。 在下一次尝试打开同一连接时，将从池中提取该连接。 如果连接具有相同的连接字符串，则被视为相同的连接。 不同的连接具有不同的连接字符串。 此键的值可以是“true”、“false”、“yes”或“no”。
复制	'false'	true 如果连接支持复制，则为 。
服务器 SPN -or- ServerSPN	N/A	数据源的 SPN。 默认值为空字符串，导致 SqlClient 使用默认的驱动程序生成的 SPN。 （仅适用于 v5.0+）
事务绑定	隐式解除绑定	控制与登记事务 System.Transactions 的连接关联。 可能的值为： Transaction Binding=Implicit Unbind; Transaction Binding=Explicit Unbind; 隐式取消绑定会导致连接在事务结束时与事务分离。 分离后，在自动提交模式下对连接执行其他请求。 在 System.Transactions.Transaction.Current 事务处于活动状态时执行请求时，不会检查该属性。 事务结束后，以自动提交模式执行其他请求。 如果系统在最后一个命令完成之前（在 using 块的范围内）结束事务，它将引发 InvalidOperationException。 显式取消绑定会导致连接保持附加到事务，直到连接关闭或调用显式 SqlConnection.TransactionEnlist(null) 。 从 .NET Framework 4.0 开始，对隐式取消绑定的更改会使显式取消绑定过时。 如果InvalidOperationException不是登记的事务，或者登记的事务未处于活动状态，则会引发 anTransaction.Current。
透明网络 IP 解析 -or- 透明网络IP解析	请参阅说明。	如果此密钥的值设置为 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 .database.fabric.microsoft.com Authentication 是“Active Directory 密码”或“Active Directory 集成” true 在所有其他情况下。
信任服务器证书 -or- TrustServerCertificate（信任服务器证书）	'false'	设置为 /> 时，TLS 用于在绕过证书链来验证信任时加密通道。 如果将 TrustServerCertificate 设置为 true “加密 false”，则通道不会加密。 已识别的值为 true、false、yes 和 no。 有关详细信息，请参阅连接字符串语法。
类型系统版本	N/A	一个字符串值，指示应用程序所需的类型系统。 客户端应用程序可用的功能取决于 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 -or- 用户唯一标识 (UID) -or- 用户	N/A	SQL Server 登录帐户。 不建议这样做。 为了保持高级别的安全性，我们强烈建议改用 Integrated Security 或 Trusted_Connection 关键字。 SqlCredential 是指定使用 SQL Server 身份验证的连接凭据的更安全方法。 用户 ID 必须为 128 个字符或更少。
用户实例	'false'	一个值，该值指示是否将连接从默认 SQL Server Express 实例重定向到在调用方帐户下运行的运行时启动的实例。
工作站 ID -or- WSID	本地计算机名称	连接到 SQL Server 的工作站的名称。 ID 必须为 128 个字符或更少。

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

• 连接生存期（或负载均衡超时）

• 争取

• 最大池大小

• 最小池大小

• 池

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

Note

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

Note

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

注意

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