SqlConnection.ConnectionString 屬性

定義

命名空間:

System.Data.SqlClient

組件:

System.Data.SqlClient.dll

套件:

System.Data.SqlClient v4.8.6

取得或設定用來開啟 SQL Server 資料庫的字串。

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

public override string ConnectionString { get; set; }

member this.ConnectionString : string with get, set

Public Overrides Property ConnectionString As String

屬性值

String

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

例外狀況

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 (預設) ，則會減去安全性資訊。 除非您將 [保存安全性資訊true] 設定為 ，否則 .NET Framework data Provider for SQL Server 不會保存或傳回 連接字串 中的密碼。

您可以使用 ConnectionString 屬性來連線到資料庫。 下列範例說明典型的 連接字串。

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

使用 new SqlConnectionStringBuilder 在運行時間建構有效的連接字串。 如需詳細資訊，請參閱連接字串建置器。

ConnectionString只有當連接關閉時，才能設定 屬性。 許多 連接字串 值都有對應的唯讀屬性。 設定 連接字串 時，會更新這些屬性，但偵測到錯誤時除外。 在此情況下，不會更新任何屬性。 SqlConnection 屬性只會傳回 包含在 中的 ConnectionString設定。

若要連線到本機計算機，請為伺服器指定 「 (本機) 」。 如果未指定伺服器名稱，則會嘗試連線到本機計算機上的預設實例。

重設ConnectionString關閉連線上的 會重設所有 連接字串 值， (和相關屬性，) 包括密碼。 例如，如果您設定包含 「Database= AdventureWorks」 的 連接字串，然後將 連接字串 重設為 “Data Source=myserver;整合式安全性=true“，Database屬性不再設定為 ”AdventureWorks“。

設定之後，會立即剖析 連接字串。 如果在剖析時發現語法中的錯誤，就會產生執行時間例外狀況，例如 ArgumentException。 只有在嘗試開啟連線時，才能找到其他錯誤。

連接字串 的基本格式包含一系列以分號分隔的關鍵詞/值組。 等號 (=) 會連接每個關鍵字和其值。 若要包含包含分號、單引號字元或雙引號字元的值，值必須以雙引號括住。 如果值同時包含分號和雙引號字元，則可以以單引號括住此值。 如果值以雙引號字元開頭，單引號也很有用。 相反地，如果值以單引號開頭，則可以使用雙引號。 如果值同時包含單引號和雙引號字元，則每次在值內發生時，用來括住值的引號字元都必須加倍。

若要在字串值中包含前面或尾端空格，值必須以單引號或雙引弧括住。 即使以引弧括住，整數、布爾值或列舉值周圍的任何前置或尾端空格都會被忽略。 不過，會保留字串常值關鍵詞或值內的空格。 單引號或雙引號可以在 連接字串 內使用，而不需使用分隔符 (例如數據源= my'Server 或 Data Source= my“Server) ，除非引號字元是值中的第一個或最後一個字符。

關鍵詞不區分大小寫。

下表列出 中 ConnectionString關鍵詞值的有效名稱。

關鍵字	預設	描述
Addr	N/A	數據源的同義字。
位址	N/A	數據源的同義字。
應用程式	N/A	應用程式名稱的同義字。
應用程式名稱	N/A	如果沒有提供應用程式名稱，則為應用程式名稱，或 『.NET SQLClient Data Provider』。 應用程式名稱可以是 128 個字元或更少。
ApplicationIntent	ReadWrite	宣告連接到伺服器時的應用程式工作負載類型。 可能的值是 ReadOnly 和 ReadWrite。 例如： ApplicationIntent=ReadOnly 如需 AlwaysOn 可用性群組的 SqlClient 支援詳細資訊，請參閱高可用性、嚴重損壞修復的 SqlClient 支援。
Asynchronous Processing -或- Async	'false'	當 時 true，啟用異步操作支援。 可辨識的值為 true、false、yes 和 no。 從 .NET Framework 4.5 開始，會忽略這個屬性。 如需異步程序設計之 SqlClient 支援的詳細資訊，請參閱 異步程序設計。
AttachDBFilename -或- 擴充屬性 -或- 初始檔案名稱	N/A	主資料庫檔案的名稱，包括可附加資料庫的完整路徑名稱。 只有副檔名為 .mdf 的主要資料檔才支援 AttachDBFilename。 如果在 連接字串 中指定 AttachDBFileName 機碼的值，則會附加資料庫，並成為連接的預設資料庫。 如果未指定此索引鍵，且先前附加資料庫，將不會重新附加資料庫。 先前附加的資料庫將作為連接的預設資料庫。 如果這個索引鍵與 AttachDBFileName 機碼一起指定，此索引鍵的值將會當做別名使用。 不過，如果名稱已在另一個附加資料庫中使用，則連接將會失敗。 路徑可能是絕對或相對的，方法是使用 DataDirectory 替代字串。 如果使用 DataDirectory，資料庫檔案必須存在於替代字串所指向目錄的子目錄中。 注意： 不支援遠端伺服器、HTTP 和 UNC 路徑名稱。 資料庫名稱必須使用關鍵詞 'database' (或其中一個) 別名來指定，如下列所示： "AttachDbFileName=|DataDirectory|\data\YourDB.mdf;integrated security=true;database=YourDatabase" 如果在與資料檔相同的目錄中有記錄檔存在，則會產生錯誤，而且在附加主要資料檔時會使用 'database' 關鍵字。 在此情形下，請移除此記錄檔。 一旦附加資料庫之後，就會根據實體路徑自動產生新的記錄檔。
驗證	N/A	用於使用 Azure Active Directory 驗證連線至 SQL Database 的驗證方法。 有效值為： Active Directory 整合式、Active Directory 密碼、Sql 密碼。
資料行加密設定	N/A	啟用或停用連線 Always Encrypted 功能。
連接逾時 -或- 連接逾時 -或- 逾時	15	在終止嘗試並產生錯誤之前，) 等候伺服器連線的時間長度，以秒為單位 (。 有效值大於或等於0，且小於或等於2147483647。 開啟與 Azure SQL Database 的連線時，請將連線逾時設定為 30 秒。
連線存留期 -或- Load Balance Timeout	0	當連接傳回集區時，會將其建立時間與目前時間進行比較，如果該時間範圍 (秒) 超過 Connection Lifetime 指定的值，則會損毀連接。 這在叢集組態中很有用，可在執行中伺服器與剛連線的伺服器之間強制負載平衡。 值為零 (0) 會導致集區連線達到最大連線逾時。
ConnectRetryCount	1	控制客戶端識別閑置連線失敗之後的重新連線嘗試次數。 有效值為 0 到 255。 預設值是 1。 0 表示不會嘗試重新連線 (停用連線復原) 。 如需連線復原的詳細資訊，請參閱 連線重試的 .NET SqlConnection 參數 和 技術文章 - 閑置連線復原。
ConnectRetryInterval	10	指定每次連線重試嘗試的時間， (ConnectRetryCount) 。 有效值為 1 到 60 秒， (default=10) ，在第一次重新連線嘗試之後套用。 偵測到中斷的連線時，用戶端會立即嘗試重新連線;這是第一次重新連線嘗試，只有在 ConnectRetryCount 大於 0 時才會發生。 如果第一次重新連線嘗試失敗，且 ConnectRetryCount 大於 1，用戶端會等候 ConnectRetryInterval 嘗試第二次和後續的重新連線嘗試。 如需連線復原的詳細資訊，請參閱 連線重試的 .NET SqlConnection 參數 和 技術文章 - 閑置連線復原。
內容連接	'false'	true如果應該建立與 SQL Server 的行程內連線，則為 。
目前的語言 -或- 語言	N/A	設定用於資料庫伺服器警告或錯誤訊息的語言。 語言名稱可以是 128 個字元或更少。
資料來源 -或- 伺服器 -或- 位址 -或- Addr -或- 網路位址	N/A	要連線之 SQL Server 實例的名稱或網路位址。 您可以在伺服器名稱後面指定連接埠號碼： server=tcp:servername, portnumber 指定本機實例時，一律使用本機 () 。 若要強制通訊協定，請新增下列其中一個前置詞： np:(local), tcp:(local), lpc:(local) 從 .NET Framework 4.5 開始，您也可以連線到 LocalDB 資料庫，如下所示： server=(localdb)\\myInstance 如需 LocalDB 的詳細資訊，請參閱 LocalDB 的 SqlClient 支援。 數據源 必須使用 TCP 格式或命名管道格式。 TCP 格式如下所示： - tcp：<host name\<instance name>> - tcp：<主機名>，<TCP/IP 埠號碼> TCP 格式的開頭必須是前置詞 「tcp」，後面接著資料庫實例，如主機名和實例名稱所指定。 連接到 Azure SQL Database 時，不適用此格式。 未指定任何通訊協定時，會自動選取 TCP 以連線至 Azure SQL Database。 主機名必須以下欄其中一種方式指定： - NetBIOSName - IPv4Address - IPv6Address 實例名稱是用來解析為裝載資料庫實例的特定 TCP/IP 埠號碼。 或者，也允許直接指定 TCP/IP 埠號碼。 如果實例名稱和埠號碼不存在，則會使用預設的資料庫實例。 命名導管格式如下所示： - np：\\<host name>\pipe\pipe 名稱<> 命名管道格式必須以前置詞 “np：” 開頭，後面接著命名管道名稱。 主機名必須以下欄其中一種方式指定： - NetBIOSName - IPv4Address - IPv6Address 管道名稱是用來識別 .NET Framework 應用程式所連接的資料庫實例。 如果指定 網络 密鑰的值，則不應該指定前置詞 “tcp：” 注意：您可以藉由在 連接字串 中的伺服器名稱前面加上 tcp，或使用localhost，強制使用 TCP 而非共用記憶體。
Encrypt	'false'	當 為 時true，如果伺服器已安裝憑證，SQL Server 針對客戶端與伺服器之間傳送的所有數據使用 SSL 加密。 可辨識的值為 true、false、yes 和 no。 如需詳細資訊，請參閱連線字串語法。 從 .NET Framework 4.5 開始，當 為 false 且Encrypt為 true 時TrustServerCertificate，SQL Server SSL 憑證中的伺服器名稱 (或 IP) 位址) 必須完全符合 連接字串 中指定的伺服器名稱 (或 IP 位址。 否則連接嘗試會失敗。
Enlist	'true'	true表示 SQL Server 連線共用器會自動在建立線程的目前交易內容中登記連線。
Failover Partner	N/A	設定資料庫鏡像的故障轉移夥伴伺服器名稱。 如果此機碼的值是 “”，則 初始目錄 必須存在，而且其值不得為 “”。 伺服器名稱可以是 128 個字元或更少。 如果您指定故障轉移夥伴，但未針對資料庫鏡像設定故障轉移夥伴伺服器，而且無法使用 Server 關鍵詞) 指定的主 (伺服器，則連線將會失敗。 如果您指定故障轉移夥伴，且未針對資料庫鏡像設定主伺服器，則如果主伺服器可用，則與伺服器關鍵詞指定的主伺服器 (連線將會成功) 。
初始目錄 -或- 資料庫	N/A	資料庫的名稱。 資料庫名稱可以是 128 個字元或更少。
整合式安全性 -或- Trusted_Connection	'false'	當 時 false，會在連線中指定使用者標識碼和密碼。 當 為 時 true，會使用目前的 Windows 帳戶認證進行驗證。 辨識的值為 true、、、yesno 和 sspi (強烈建議) ，這相當於 truefalse。 如果指定 [使用者標識符] 和 [密碼]，且 [整合式安全性] 設定為 true，則會忽略 [使用者標識符] 和 [密碼]，並使用整合式安全性。 SqlCredential是指定使用 SQL Server 驗證 Integrated Security=false () 之連線的認證更安全的方式。
Max Pool Size	100	集區中允許的連線數目上限。 有效值大於或等於 1。 小於 最小集區大小 的值會產生錯誤。
Min Pool Size	0	集區中允許的最小聯機數目。 有效值大於或等於 0。 此欄位中零 (0) 表示一開始不會開啟最小連線。 大於 最大集區大小 的值會產生錯誤。
MultipleActiveResultSets	'false'	當 為 時 true，應用程式可以維護多個作用中結果集， (MARS) 。 當 為 時 false，應用程式必須先處理或取消一個批次的所有結果集，才能在該聯機上執行任何其他批次。 可辨識的值為 true 和 false。 如需詳細資訊，請參閱 Multiple Active Result Sets (MARS)。
MultiSubnetFailover	FALSE	一律指定multiSubnetFailover=True連線至 SQL Server 2012 (或更新版本) 可用性群組的可用性群組接聽程式，或 SQL Server 2012 (或更新) 版本的故障轉移叢集實例。 multiSubnetFailover=True 會設定 SqlClient，以提供目前) 使用中伺服器之 (的更快速偵測和連線。 可能的值為 Yes 與No、 True 或 False1 或與 。 0 例如： MultiSubnetFailover=True 預設值為 False。 如需 SqlClient 對 Always On AG 支援的詳細資訊，請參閱高可用性、災害復原的 SqlClient 支援。
Network Library -或- 網路 -或- Net	N/A	用來建立與 SQL Server 實例連線的網路連結庫。 支援的值包括： dbnmpntw (命名管道) dbmsrpcn (Multiprotocol、Windows RPC) dbmsadsn (Apple Talk) dbmsgnet (VIA) dbmslpcn (共用記憶體) dbmsspxn (IPX/SPX) dbmssocn (TCP/IP) Dbmsvinn (Banyan Vines) 對應的網路 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	N/A	SQL Server 帳戶登入的密碼。 不建議使用。 為了維持高層級的安全性，強烈建議您改用 Integrated Security 或 Trusted_Connection 關鍵詞。 SqlCredential是指定使用 SQL Server 驗證之連線的認證更安全的方式。 密碼必須是 128 個字元或更少。
保存安全性資訊 -或- PersistSecurityInfo	'false'	當設定為 false 或 no (強烈建議) 時，如果連線已開啟或曾處於開啟狀態，則不會傳回安全性敏感性資訊，例如密碼。 重設 連接字串 重設所有 連接字串 值，包括密碼。 可辨識的值為 true、false、yes 和 no。
PoolBlockingPeriod	自動	設定連接集區的封鎖期間行為。 如需詳細資料，請參閱 PoolBlockingPeriod 。
Pooling	'true'	當此機碼的值設定為 true 時，應用程式關閉時，任何新建立的連接都會新增至集區。 在下一次嘗試開啟相同的連線時，將會從集區繪製該連線。 如果 Connections 具有相同 連接字串，則會視為相同。 不同的連接有不同的連接字串。 此機碼的值可以是 「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： .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。 如需詳細資訊，請參閱連線字串語法。
類型系統版本	N/A	字串值，表示應用程式預期的型別系統。 可供用戶端應用程式使用的功能是根據 SQL Server 版本以及資料庫的相容性層級而定。 如果使用了不同的 SQL Server 版本，則明確設定撰寫用戶端應用程式的目標型別系統版本可避免可能導致應用程式中斷的潛在問題。 注意：在 SQL Server 中執行同進程程式代碼的 Common Language Runtime (CLR) 無法設定類型系統版本。 如需詳細資訊，請參閱 common Language Runtime Integration 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;。
使用者識別碼 -或- UID -或- 使用者	N/A	SQL Server 登入帳戶。 不建議使用。 為了維持高層級的安全性，強烈建議您改用 Integrated Security 或 Trusted_Connection 關鍵詞。 SqlCredential是指定使用 SQL Server 驗證之連線認證的更安全方式。 用戶標識碼必須是 128 個字元或更少。
User Instance	'false'	值，指出是否要將連接從預設 SQL Server Express 實例重新導向至在呼叫端帳戶下執行的運行時間起始實例。
工作站 ID -或- WSID	本機計算機名稱	連接到 SQL Server 的工作站名稱。 標識碼必須是 128 個字元或更少。

下列清單包含 內 ConnectionString連接共用值的有效名稱。 如需詳細資訊，請參閱 SQL Server 連線共用 (ADO.NET) \(機器翻譯\)。

• 線上存留期 (或負載平衡逾時)

• Enlist

• Max Pool Size

• Min Pool Size

• Pooling

當您設定需要布爾值的關鍵詞或連線共用值時，可以使用 'yes' 而不是 'true'，而 'no' 而不是 'false'。 整數值會以字串表示。

注意

.NET Framework data Provider for SQL Server 會使用自己的通訊協定來與 SQL Server 通訊。 因此，連線到 SQL Server 時，不支援使用 ODBC 數據源名稱 (DSN) ，因為它不會新增 ODBC 層。

注意

.NET Framework Data Provider for SQL Server 不支援通用數據連結 (UDL) 檔案。

警告

在此版本中，根據使用者輸入 (建構 連接字串 時，應用程式應該小心，例如從對話框中擷取使用者標識碼和密碼資訊，並將它附加至 連接字串) 。 應用程式應該確定使用者無法在這些值中內嵌其他 連接字串 參數 (，例如輸入密碼為 「validpassword;嘗試附加至不同資料庫) 的 database=somedb” 如果您需要根據使用者輸入建構連接字串，請使用新的 SqlConnectionStringBuilder，以驗證 連接字串 並協助消除此問題。 如需詳細資訊 ，請參閱連接字串產生器 。

另請參閱

• ADO.NET Managed 提供者和DataSet開發人員中心
• ADO.NET 中的連接字串
• SQL Server 連接共用 (ADO.NET)
• 在 ADO.NET 中聯機到數據源
• ADO.NET 概觀 \(部分機器翻譯\)