SqlConnection.ConnectionString 屬性

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

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

[System.Data.DataSysDescription("SqlConnection_ConnectionString")]
public string ConnectionString { get; set; }

public override string ConnectionString { get; set; }

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

[<System.Data.DataSysDescription("SqlConnection_ConnectionString")>]
member this.ConnectionString : string with get, set

member this.ConnectionString : string with get, set

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

Public Property ConnectionString As String

Public Overrides Property ConnectionString As String

屬性值

包含來源資料庫名稱及其他建立初始連線所需的參數的連線字串。 預設值為空字串。

實作

屬性

DataSysDescriptionAttribute SettingsBindableAttribute

例外狀況

範例

以下範例建立 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=|DataDirectory|\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 開始，對隱含解綁的變更使得明確解綁變得過時。 如果InvalidOperationException不是被列入的交易，或該被列入的交易未啟用，則會拋出 ATransaction.Current。
TransparentNetworkIPResolution	請參閱說明。	當此機碼的值設定為 true時，應用程式必須擷取特定 DNS 專案的所有 IP 位址，並嘗試與清單中的第一個 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

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

另請參閱

• ADO.NET 管理供應商與資料集開發中心
• ADO.NET 中的連接字串
• SQL Server 連線共用 （ADO.NET）
• ADO.NET 連接資料來源
• ADO.NET 概觀