共用方式為

SqlConnection.ConnectionString 屬性

定義

命名空間:
System.Data.SqlClient
組件:
System.Data.SqlClient.dll
組件:
System.Data.dll
來源:
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

提供無效的連接字串參數，或未提供所需的連接字串參數。

範例

以下範例建立 a 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的 相同，但若 Persist Security Info 值設為 false （預設值），則會減去安全資訊。 .NET Framework Data Provider for SQL Server 不會持久化或回傳連線字串中的密碼，除非你將 Persist Security Info 設為 true。

你可以利用這個 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.

Keyword 預設值 說明
Addr 不適用 資料來源的同義詞。
Address 不適用 資料來源的同義詞。
App 不適用 應用程式名稱的同義詞。
Application Name 不適用 應用程式名稱，或若未提供應用程式名稱，則稱為「.NET SQLClient Data Provider」。

應用程式名稱可為 128 字元或更短。
ApplicationIntent ReadWrite 宣告連接到伺服器時的應用程式工作負載類型。 可能的值是 ReadOnly 和 ReadWrite。 例如：

ApplicationIntent=ReadOnly

如需 SqlClient 支援 Always On 可用性群組的詳細資訊，請參閱 SqlClient 支援高可用性、災害復原。
Asynchronous Processing
-或-
Async		 'false' 當 true時，能支援非同步操作。 可辨識的值為 true、false、yes 和 no。

此特性自 .NET Framework 4.5 起被忽略。 欲了解更多關於 SqlClient 對非同步程式設計的支援資訊，請參閱 非同步程式設計。
AttachDBFilename
-或-
Extended Properties
-或-
Initial File Name		 不適用 主要資料庫檔案的名稱，包括可附加資料庫的完整路徑名稱。 AttachDBFilename 僅支援具有 .mdf 副檔名的主要資料檔案。

如果 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 不適用 啟用或停用連線的 「始終加密 」功能。
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秒（預設=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

指定本地實例時，請務必使用 （local）。 要強制執行協定，請加入以下其中一個前綴：

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

從 .NET Framework 4.5 開始，你也可以連接以下方式的 LocalDB 資料庫：

server=(localdb)\\myInstance

欲了解更多 LocalDB 資訊，請參閱 LocalDB 的 SqlClient 支援。

資料來源 必須使用 TCP 格式或命名管線格式。

TCP 格式如下：

- TCP：<主機名稱>\<實例名稱>
- tcp：<主機名稱>，TCP</IP 埠號>

TCP 格式必須以前綴「tcp：」開頭，並以主機名稱與實例名稱指定資料庫實例。 此格式在連接 Azure SQL 資料庫時不適用。 當未指定協定時，TCP 會自動被選為連接 Azure SQL 資料庫。

主機名稱必須以以下其中一種方式指定：

- NetBIOSName
- IPv4位址
- IPv6位址

實例名稱用來解析到存放資料庫實例的特定 TCP/IP 埠號。 另外，也可以直接指定 TCP/IP 埠號。 若實例名稱與埠號皆不存在，則使用預設的資料庫實例。

命名管道格式如下：

- NP：\\<主機名稱>\管道<\管道名稱>

命名管道格式必須以前綴「np：」開頭，並接著命名管道名稱。

主機名稱必須以以下其中一種方式指定：

- NetBIOSName
- IPv4位址
- IPv6位址

管線名稱用來識別 .NET Framework 應用程式將連接的資料庫實例。

若指定 網路 金鑰值，則不應指定前綴「tcp：」與「np：」。 註： 你可以強制使用 TCP 取代共享記憶體，方法是在連線字串中以 tcp： 作為伺服器名稱前綴，或使用 localhost。
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字元或以下。

如果你指定了故障轉移夥伴，但故障轉移夥伴伺服器未設定資料庫鏡像，且主要伺服器（以 Server 關鍵字指定）無法使用，那麼連線就會失敗。

如果你指定了故障轉移夥伴，但主伺服器沒有設定資料庫鏡像，那麼只要主伺服器可用，連接就會成功。
Initial Catalog
-或-
Database		 不適用 資料庫的名稱。

資料庫名稱可為 128 字元或更短。
Integrated Security
-或-
Trusted_Connection		 'false' 當 false，連線中會指定使用者 ID 和密碼。 當 true時，會使用目前的 Windows 帳號憑證來進行驗證。

公認的值為 true、 false、 yesno、 和 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（或更新版本）可用性群組或 SQL Server 2012（或更新版本）故障轉移叢集實例的可用性群組監聽器時，請務必指定 multiSubnetFailover=True 。 multiSubnetFailover=True 配置 SqlClient 以提供更快的偵測與連線（目前）活躍伺服器。 可能的值為 Yes 和 No， True 或 False10和 。 例如：

MultiSubnetFailover=True

預設值為 False。 欲了解更多關於 SqlClient 對 Always On AG 支援的資訊，請參閱 SqlClient 高可用性與災難復原支援。
Network Library
-或-
Network
-或-
Net		 不適用 網路函式庫用於建立與 SQL Server 實例的連線。 支援的值包括：

dbnmpntw（命名管）

dbmsrpcn（多協定，Windows RPC）

dbmsadsn（Apple Talk）

dbmsgnet（經由）

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 8000 網路封包的大小（以位元組計）與 SQL Server 實例通訊。

封包大小可大於或等於 512，也可以小於或等於 32768。
Password
-或-
PWD		 不適用 SQL Server 帳號登入時的密碼。 不推薦。 為了維持高安全性，我們強烈建議您改用 Integrated Security or 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 屬性。 交易結束後，會以自動提交模式執行額外請求。

如果系統在最後一個指令完成前結束交易（在使用區塊範圍內），就會拋出 InvalidOperationException。

明確解綁會使連線一直連接到交易，直到連線關閉或 SqlConnection.TransactionEnlist(null) 明確呼叫。 從 .NET Framework 4 開始，對隱含解綁的變更使得明確解綁變得過時。 如果Transaction.Current不是被列入的交易，或該被列入的交易未啟用，則會拋出 AInvalidOperationException。
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。 如需詳細資訊，請參閱連線字串語法。
Type System Version 不適用 一個字串值，表示應用程式所期望的型別系統。 用戶端應用程式可用的功能取決於 SQL Server 版本及資料庫的相容性等級。 明確設定用戶端應用程式所撰寫的系統版本類型，可避免因使用不同版本 SQL Server 而導致應用程式故障的問題。 註： 無法設定系統版本用於在 SQL Server 中執行的通用語言執行時（CLR）程式碼。 欲了解更多資訊，請參閱 SQL Server 通用語言執行時整合（Common Language Runtime Integration）。

可能的值為：

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
-或-
User		 不適用 SQL Server 登入帳號。 不推薦。 為了維持高安全性，我們強烈建議您改用 Integrated Security OR 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

當你設定關鍵字或連線池值需要布林值時，可以用 代替 true，也falseno用 yes 代替 。 整數值以字串表示。

備註

.NET Framework 的 SQL Server 資料提供者使用自己的協定與 SQL Server 通訊。 因此，它不支援在連接 SQL Server 時使用 ODBC 資料來源名稱（DSN），因為它並未新增 ODBC 層。

備註

.NET Framework 資料提供者 for SQL Server 不支援通用資料連結（UDL）檔案。

謹慎

根據使用者輸入建構連接字串時要特別小心（例如從對話框取得使用者 ID 和密碼資訊，並將其附加到連接字串中）。 確保使用者無法在這些值中嵌入額外的連接字串參數（例如輸入密碼為「validpassword」;database=somedb」試圖連接到另一個資料庫）。 如果你需要根據使用者輸入建構連接字串，可以使用 SqlConnectionStringBuilder，它能驗證連接字串並幫助消除這個問題。 如需詳細資訊，請參閱連接字串建置器。

適用於

另請參閱