SqlConnection.ConnectionString 屬性

定義

命名空間:

System.Data.SqlClient

組件:

System.Data.SqlClient.dll

組件:

System.Data.dll

取得或設定用來開啟 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

已提供無效的連接字串引數，或尚未提供必要的連接字串引數。

範例

下列範例會建立 ， 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 ，否則SQL Server的.NET Framework Data Provider不會保存或傳回連接字串中的密碼。

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

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

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

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

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

重設 ConnectionString 關閉連線上的 會重設所有連接字串值， (和相關屬性) 包括密碼。 例如，如果您設定包含 「Database= AdventureWorks」 的連接字串，然後將連接字串重設為 「Data Source=myserver;Integrated Security=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 表示不會嘗試重新連線 (停用連線復原) 。 如需閒置連線恢復功能的詳細資訊，請參閱技術文章 - 閒置連線恢復功能。
ConnectRetryInterval	10	指定每次連線重試嘗試的時間， (ConnectRetryCount) 。 有效值為 1 到 60 秒， (default=10) ，在第一次重新連線嘗試之後套用。 偵測到中斷的連線時，用戶端會立即嘗試重新連線;這是第一次重新連線嘗試，只有在 ConnectRetryCount 大於 0 時才會發生。 如果第一次重新連線嘗試失敗，且 ConnectRetryCount 大於 1，用戶端會等候 ConnectRetryInterval 嘗試第二次和後續的重新連線嘗試。 如需閒置連線恢復功能的詳細資訊，請參閱技術文章 - 閒置連線恢復功能。
內容連接	'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的詳細資訊，請參閱sqlClient 支援 LocalDB。 資料來源 必須使用 TCP 格式或具名管道格式。 TCP 格式如下所示： - tcp： <host name> \<實例名稱> - tcp： <host name> ，<TCP/IP port number> TCP 格式的開頭必須是前置詞 「tcp：」，後面接著資料庫實例，如主機名稱和實例名稱所指定。 連線至Azure SQL Database時，不適用此格式。 未指定通訊協定時，會自動選取 TCP 以Azure SQL Database連線。 主機名稱必須以下列其中一種方式指定： - NetBIOSName - IPv4Address - IPv6Address 實例名稱是用來解析為裝載資料庫實例的特定 TCP/IP 埠號碼。 或者，也允許直接指定 TCP/IP 埠號碼。 如果實例名稱和埠號碼不存在，則會使用預設的資料庫實例。 具名管道格式如下所示： - np： \ \<主機名稱 > \pipe<管道 \ 名稱> 具名管道格式必須以前置詞 「np：」 開頭，後面接著具名管道名稱。 主機名稱必須以下列其中一種方式指定： - NetBIOSName - IPv4Address - IPv6Address 管道名稱是用來識別.NET Framework應用程式所連接的資料庫實例。 如果指定 網路 金鑰的值，則不應該指定前置詞 「tcp：」 和 「np：」。 注意： 您可以藉由在 連接字串 中的伺服器名稱前面加上 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 、 false 、、 no yes 和 sspi (強烈建議) ，這相當於 true 。 如果指定 [使用者識別碼] 和 [密碼]，且 [整合式安全性] 設定為 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 和 False 或 1 和 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 Authentication 之連線認證的更安全方式。 密碼必須是 128 個字元或更少。
保存安全性資訊 -或- PersistSecurityInfo	'false'	當設定為 false 或 no (強烈建議) 時，如果連接已開啟或曾處於開啟狀態，則不會傳回安全性敏感性資訊，例如密碼。 重設連接字串重設所有連接字串值，包括密碼。 可辨識的值為 true、false、yes 和 no。
PoolBlockingPeriod	自動	設定連接集區的封鎖期間行為。 如需詳細資料，請參閱 PoolBlockingPeriod 。
Pooling	'true'	當此索引鍵的值設定為 true 時，任何新建立的連接都會在應用程式關閉時新增至集區。 在下一次嘗試開啟相同的連線時，該連接將會從集區繪製。 如果連線具有相同的連接字串，則會視為相同。 不同的連接有不同的連接字串。 此機碼的值可以是 「true」、「false」、「yes」 或 「no」。
複寫	'false'	true 如果使用連接支援複寫，則為 。
Transaction Binding	Implicit Unbind	控制與編列交易的連接 System.Transactions 關聯。 可能的值包括： Transaction Binding=Implicit Unbind; Transaction Binding=Explicit Unbind; 隱含解除系結會導致連接在交易結束時中斷連結。 在中斷連結之後，連接上的其他要求會以自動認可模式執行。 當異動為使用中狀態時，執行要求時不會檢查 System.Transactions.Transaction.Current 屬性。 在此交易結束之後，其他要求會以自動認可模式執行。 如果系統在最後一個命令完成之前，在 using 區塊) 的範圍內結束交易 (，則會擲回 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 -或- User	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'。 整數值會以字串表示。

注意

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

注意

(UDL) 檔案的通用資料連結不支援 .NET Framework Data Provider SQL Server。

警告

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

另請參閱

• ADO.NET Managed 提供者和DataSet開發人員中心
• ADO.NET 中的連接字串
• SQL Server 連接共用 (ADO.NET)
• 在 ADO.NET 中連接至資料來源
• ADO.NET 概觀