您要打印的文件是：SqlConnection.ConnectionString 属性

SqlConnection.ConnectionString 属性

作者：佚名    转贴自：http://msdn.microsoft.com/zh-tw/library/system.data.sqlclient.sqlconnection.connectionstring.aspx    点击数：169


SqlConnection.ConnectionString 属性

取得或设定用来开启 SQL Server 数据库的字符串。

 

命名空间：  System.Data.SqlClient
组件：  System.Data (在 System.Data.dll 中)
C#
C++
F#
VB
[SettingsBindableAttribute(true)]
public override string ConnectionString { get; set; }

属性值

型别：System.String
连接字符串，包含源数据库名称和其他建立初始连接所需要的参数。 默认值为空字符串。 
 

实作

IDbConnection.ConnectionString
 
例外状况 条件
ArgumentException

提供无效的连接字符串自变量，或未提供必要的连接字符串自变量。

ConnectionString 类似于 OLE DB 连接字符串，但不完全相似。 和 OLE DB 或 ADO 不同，如果 Persist Security Info 值设定为 false (默认值)，则传回的连接字符串和用户设定的ConnectionString 减去安全性信息是相同的。 除非将 Persist Security Info 对 true， SQL Server 的 .NET Framework 数据提供者不会保存或传回在连接字符串中的密码。

您可以使用 ConnectionString 属性以连接至数据库。 下列范例说明一般的连接字符串。

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

请在运行时间使用新的 SqlConnectionStringBuilder 来建构有效的连接字符串。 如需详细信息，请参阅连接字符串产生器。

ConnectionString 属性只可以在连接关闭时设定。 许多连接字符串值具有对应的只读属性。 除了侦测到错误时之外，设定连接字符串时会更新这些属性。 在这种情况下，不会更新任何属性。 SqlConnection 属性只会传回包含 ConnectionString 中的那些设定。

若要连接至本机计算机 (Local Computer)，请为服务器指定 (local) 如果没有指定服务器名称，会尝试与本机计算机上的默认实例连接。

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

连接字符串在被设定之后会立即被剖析。 如果在剖析时找到语法错误，会产生运行时间例外状况，例如 ArgumentException。 只有在尝试开启连接时，才会找到其他错误。

连接字符串的基本格式包括一连串以分号分隔的关键词/值组。 等号 (=) 连接每一个关键词和其值。 若要包括包含分号、单引号字符或双引号字符的值，必须以双引号括住该值。 如果这个值同时包含分号和双引号字符，则必须以单引号括住该值。 如果值是以双引号字符开头，也可以使用单引号。 相反地，如果值是以单引号开头，则也可以使用双引号。 如果值同时包含单引号和双引号字符，则用来包含值的引号字符每次出现在值中时，都必须成对。

若要在字符串值中包括前端或后端空格，则必须以单引号或双引号括住该值。 会忽略整数、布尔值 (Boolean) 或列举值前后的任何前端或后端空格 (即使以引号括住也是一样)。 但是会保留字符串常值 (String Literal) 关键词或值中的空白。 单引号或双引号可以在连接字符串中使用，而不需要使用分隔符 (例如，数据源 = my'Server 或 Data Source = My Server)，，除非引号字符是第一个或最后一个值。

关键词不区分大小写。

下列表格列出 ConnectionString 内关键词数值的有效名称。

 

Keyword

Default

描述

Addr

N/A

Data Source. data-guid=19aa393b521e7eecf916d1ff155739f8>数据源的同义字。

Address

N/A

Data Source. data-guid=19aa393b521e7eecf916d1ff155739f8>数据源的同义字。

App

N/A

Application Name. data-guid=9b4ee3d681cf49ad27967da260ec6652>应用程序名称的同义字。

应用程序名称

N/A

应用程序的名称，如果没有提供应用程序名称，则为 '.NET SQLClient Data Provider'。

应用程序名称可以有 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

N/A

主数据库档案的名称，包括可附加数据库的完整路径名称。 只有具有 .mdf 扩展名的主要数据文件才能支持 AttachDBFilename。

如果在连接字符串中指定了 AttachDBFileName 索引键的值，则会附加数据库，而且数据库会变成联机的默认数据库。

如果不指定此索引键，且若先前已附加数据库，该不会重新附加此数据库。 先前附加的数据库会做为连接的默认数据库。

如果和 AttachDBFileName 索引键一同指定此索引键，会以此索引键的值为别名。 但是，如果另一个附加的数据库已使用该名称，则联机会失败。

藉由使用 DataDirectory 替换字符串，路径可以是绝对或相对路径。 如果使用 DataDirectory，则数据库档案必须存在于替换字符串指向之目录的子目录。

注意事项注意事项
不支持远程服务器、HTTP 和 UNC 路径名称。

必须使用关键词 'database' (或其中一个别名 (Alias)) 指定数据库名称，如下所示：

AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase

如果记录文件出现在与数据文件相同的目录中，而且在尝试附加主要数据文件时使用了 'database' 关键词，便会产生错误。 在这种情况下，请移除该记录文件。 附加数据库之后，便会自动依据实体路径来产生新的记录文件。

Connect Timeout

-或-

Connection Timeout

-或-

Timeout

15

在终止尝试并产生错误之前，要等待服务器连接的时间长度 (以秒为单位)。

有效的值会大于或等于 0，而且小于或等于 2147483647。

当开启与 Azure SQL 数据库的连接，设定连接超时为 30 秒。

Connection Lifetime

-或-

Load Balance Timeout

0

当连接传回集区时，其建立时间会与目前时间相比较，如果该时间 (以秒为单位) 超过 Connection Lifetime 指定的值，则会终结连接。 这有助于在丛集组态中强制进行执行中服务器和刚上线服务器之间的负载平衡 (Load Balancing)。

零 (0) 的值会导致共享连接产生连接上限逾时的状况。

Context Connection

'false'

true ，如果与 SQL Server 的同进程连接应该建置。

Current Language

-或-

语言

N/A

设定用于数据库服务器警告或错误讯息的语言。

语言名称可以有 128 个 (含) 以下的字符。

Data Source

-或-

服务器

-或-

Address

-或-

Addr

-或-

Network Address

N/A

SQL Server 实例名称或网络地址的连接。 可在服务器名称后指定通讯端口编号：

server=tcp:servername, portnumber

指定本机实例时，永远使用 (local)。 若要强制通讯协议，请加入下列其中一个前置词：

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

从 .NET Framework 4.5开始，您也可以连接到 LocalDB 数据库如下:

server=(localdb)\\myInstance

如需LocalDB的详细信息，请参阅LocalDB 的 SqlClient 支援。

Data Source must use the TCP format or the Named Pipes format. data-guid=ef28a24434f03c48b2e88c3705a86569>数据源必须使用 TCP 格式或命名管道格式。

TCP 格式如下：

  • tcp:<主机名>\<实例名称>

  • tcp:<主机名>,<TCP/IP 端口号码>

TCP 格式必须是以前置词 tcp: 开头，后面接着数据库实例，如主机名和实例名称所指定。

主机名必须以下列其中一种方式指定：

  • NetBIOSName

  • IPv4Address

  • IPv6Address

实例名称用于解析为数据库实例装载所在的特定 TCP/IP 端口号码。 或者，也可以直接指定 TCP/IP 端口号码。 如果两个实例名称和端口号码都不存在，则会使用默认的数据库实例。

命名管道的格式如下：

  • np:\\<主机名>\pipe\<管道名称>

命名管道格式必须以前置词 np: 开头，后面跟着命名管道名称。

主机名必须以下列其中一种方式指定：

  • NetBIOSName

  • IPv4Address

  • IPv6Address

管道名称用于识别 .NET Framework 连接目标的数据库实例。

如果指定了 Network 索引键的值，不应指定前置词 tcp: 与 np:。

注意事项注意事项
您可以强制使用 TCP 来取代共享内存，无论是传递给 tcp 前置词:对服务器名称在连接字符串，或是使用 localhost。

Encrypt

'false'

当 true， SQL Server 提供所有数据使用 SSL 加密。在客户端和服务器之间，如果服务器已安装凭证。 可辨认的值为true、false、yes 和 no。 如需详细信息，请参阅连接字符串语法。

从 .NET Framework 4.5开始，，当 TrustServerCertificate 为 false 时，且 Encrypt 为 true 时，服务器名称 (或 IP 地址) 在 SQL Server SSL 凭证必须完全符合连接字符串 (或 IP 地址) 指定的服务器名称。 否则，连接尝试会失败。 如需支持的讯息本文开始通配符的凭证 (*)，请 服务器证书的接受的通配符用于服务器验证参阅。

Enlist

'true'

true indicates that the SQL Server connection pooler automatically enlists the connection in the creation thread's current transaction context. data-guid=f2ebda066bc6797c072e2ff25e7c0e56>true 表示 SQL Server 连接登记在建立线程的流动交易内容中自动登记连接。

Failover Partner

N/A

故障转移合作伙伴的名称，其中设定数据库镜像。

如果此索引键的值是 ，则初始目录必须存在，并且它的值不能为 。

服务器名称可以有 128 个 (含) 以下的字符。

如果您指定故障转移合作伙伴，但未对合作伙伴服务器进行数据库镜射设定，且主服务器不可用，则会联机失败。

如果您指定故障转移合作伙伴，且未对主服务器进行数据库镜射设定，若主服务器可用，则可成功连接主服务器 (以 Server 关键词指定)。

Initial Catalog

-或-

数据库

N/A

数据库的名称。

数据库名称可以有 128 个 (含) 以下的字符。

Integrated Security

-或-

Trusted_Connection

'false'

如果为 false，则会在连接中指定使用者 ID 和密码。 如果为 true，则会使用目前的 Windows 账户认证进行验证。

可辨认的值为 true、false、yes、no 和 sspi (建议使用)，其相当于 true。

如果用户标识符和密码已指定，且整合安全性设定设为 true，则会略过用户标识符和密码，并使用整合式安全性。

SqlCredential 是一个更安全的方式为使用 SQL Server 验证的连接指定认证 (Integrated Security=false)。

Max Pool Size

100

集区中允许的最大连接数目。

有效值大于或等于 1。 Min Pool Size generate an error. data-guid=2268ebdd9a80ae5fca5cdefba20fd476>小于 Min Pool Size 的值会产生错误。

Min Pool Size

0

集区中允许连接的最小数目。

有效值大于或等于 0。 在这个字段中的零 (0) 表示最初未开启最小连接数目。

Max Pool Size generate an error. data-guid=bbbae219a0df5f116e121f876708344c>大于 Max Pool Size 的值会产生错误。

MultipleActiveResultSets

'false'

如果为 true，则应用程序可维护 Multiple Active Result Set (MARS)。 如果为 false，则应用程序必须处理或取消一个批次的所有结果集，才能够执行该连接的其他批次。

辨认的值为 true 和 false。

如需详细信息，请参阅 Multiple Active Result Sets (MARS)。

MultiSubnetFailover

FALSE

请指定 multiSubnetFailover=True ，连接到 可用性群组或 故障转移丛集实例的可用性群组接听程序。multiSubnetFailover=True 设定 SqlClient 更快速的与 () 目前使用中的服务器侦测和连接。 可能的值为 Yes 、 No、 True 、 False、 1 和 0。 例如：

MultiSubnetFailover=True

默认值为 False。 SqlClient Support for High Availability, Disaster Recovery. data-guid=09c30d0f134ec06cddaa08dad76b7c0f>如需 SqlClient 支持的详细信息永远开启 AGs，请参阅 高可用性、严重损坏修复的 SqlClient 支援。

Network Library

-或-

网络

-或-

Net

N/A

用于的网络链接库建立 SQL Server实例的连接。 支持的值包含：

dbnmpntw (命名管道)

dbmsrpcn (多重通讯协议、Windows RPC)

dbmsadsn (Apple Talk)

dbmsgnet (VIA)

dbmslpcn (共享内存)

dbmsspxn (IPX/SPX)

dbmssocn (TCP/IP)

Dbmsvinn (Banyan Vines)

对应的网络 DLL 必须安装在您连接的系统上。 如果您没有指定网络而且使用本地服务器 (例如 . 或 (local))，则会使用共享内存。 在这个范例中，网络链接库是 Win32 Winsock TCP/IP (dbmssocn)，1433 则是使用的通讯端口。

Network Library=dbmssocn;Data Source=000.000.000.000,1433;

Packet Size

8192

大小用于网络封包的字节与 SQL Server的实例通讯。

封包大小可以大于或等于 512，并且小于或等于 32768。

密码

-或-

PWD

N/A

SQL Server 帐户登入的密码。 不建议使用。 为了维持高安全性等级，强烈建议您改为使用 Integrated Security 或Trusted_Connection 关键词。 SqlCredential 是一个更安全的方式为使用 SQL Server 验证的连接指定认证。

密码必须在 128 个字符 (含) 以下。

Persist Security Info

-或-

PersistSecurityInfo

'false'

当设定为 false 或 no (建议使用) 时，如果连接开启或曾经处于开启状态，则不会将安全性相关信息 (如密码) 当做连接的一部分传回。 重设连接字符串会将所有包含密码的连接字符串值重设。 可辨认的值为 true、false、yes 和 no。

Pooling

'true'

当此索引键的值设定为 true 时，任何新建立的连接会在由应用程序关闭时加入至集区。 下次尝试开启同一个联机时，会从集区撷取该联机。

如果这些联机具有相同的连接字符串，则视为相同。 不同的联机会有不同的连接字符串。

此索引键的值可以是 true、false、yes 或 no。

Replication

'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 开始，对 Implicit Unbind (隐含解除系结) 有所变更，造成 Explicit Unbind (明确解除系结) 已经过时。 如果Transaction.Current 不是已登记的交易或如果已登记的交易不是作用中时，便会掷回 InvalidOperationException。

TrustServerCertificate

'false'

设为 true 时，SSL 会用来加密通道，但略过验证信任的凭证链结查核。 如果 TrustServerCertificate 设定为 true 且 Encrypt 设定为false，则不会加密通道。 可辨认的值为 true、false、yes 和 no。 如需详细信息，请参阅连接字符串语法。

Type System Version

N/A

字符串值，表示应用程序预期的型别系统。 客户端应用程序的功能与 SQL Server 版本的兼容性层级和数据库。 明确设定型别系统版本客户端应用程序的撰写为避免可能造成应用程序中断的潜在问题，如果使用 SQL Server 不同的版本。

注意事项注意事项
无法针对 SQL Server 中同进程 (In-Process) 执行的 Common Language Runtime (CLR) 程序代码设定型别系统版本。如需详细信息，请参阅SQL Server Common Language Runtime 整合。

可能值为：

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; 指定应用程序需要 Microsoft.SqlServer.Types.dll 版本 11.0.0.0。 其他 Type System Version 设定需要 Microsoft.SqlServer.Types.dll 版本 10.0.0.0。

Latest 已经过时，而且不应该使用。 Latest 相当于 Type System Version=SQL Server 2008;。

User ID

-或-

UID

-或-

 

N/A

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' 以及 'no' 代替 'false'。 整数值会以字符串来表示。

注意事项注意事项

.NET Framework Data Provider for SQL Server 会使用自己的通讯协议与 SQL Server 通讯。 因此，，因为它不会将 ODBC 层，它不支持使用 ODBC 数据源名称 (DSN)，连接到 SQL Server 。

注意事项注意事项

Universal Data Link (UDL) 档案未针对 SQL Server的 .NET Framework 数据提供者支持。

注意事项警告

在这个版本中，根据用户输入建构连接字符串时 (例如，从对话框中撷取用户 ID 和密码信息，并且附加至连接字符串)，应用程序应该提出警告。 应用程序应确保用户无法在这些值中嵌入额外的连接字符串参数 (例如，输入密码为 validpassword;database=somedb，以尝试连接至不同的数据库)。 如果您需要根据使用者输入来建构连接字符串，请使用新的 SqlConnectionStringBuilder，它会验证连接字符串，并协助您排除这个问题。 如需详细信息，请参阅 连接字符串产生器。

下列范例会建立 SqlConnection，并在开启连接前设定 ConnectionString 属性。

C#
VB
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;;
}

.NET Framework

支持版本：4.5、4、3.5、3.0、2.0、1.1、1.0
 

.NET Framework Client Profile

支持版本：4、3.5 SP1
 

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (不支持服务器核心角色), Windows Server 2008 R2 (SP1 (含) 以后版本支持服务器核心角色，不支持 Itanium)

 

 

.NET Framework 并不支持各种平台的所有版本。如需支持的版本的清单，请参阅.NET Framework 系统需求。