Microsoft.Data.SqlClient 的連接字串

Microsoft.Data.SqlClient 連接字串 是一個keyword=value以分號分隔的鍵/值組配對清單。 傳給 SqlConnection 或 SqlConnectionStringBuilder：

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

連接字串 可說明四個問題：

1. 應用程式使用哪台伺服器和資料庫？
2. 應用程式以哪個身份執行？
3. 客戶端如何驗證伺服器憑證？
4. 工作負載需要哪種連線行為？

本文將介紹這些選擇以及驅動程式用來讀取文字的規則。 對於每個關鍵字、其同義詞及預設值，請參見 連線選項。 若要在程式碼中建立和更改連接字串，請參見 連接字串建置器。

選擇一種認證模式

使用符合部署的模式。 將每個佔位符（例如 <server>）替換成你的值。

Environment	Pattern	連接字串
使用網域或本機 Windows 身分識別的 Windows 上 SQL Server	Windows 整合式驗證	Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
託管於 Azure 的應用程式，並連線至 Azure SQL	Microsoft Entra ID 受控識別	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict
連線到 Azure SQL 的開發人員工作站	Microsoft Entra ID 預設認證鏈	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
開發工作站連接 Microsoft Fabric 中的 SQL 資料庫	Microsoft Entra ID 預設認證鏈	Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
連線至 Azure SQL 的互動式桌面工具	Microsoft Entra ID 互動式認證	Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict
需要 SQL 認證的環境	使用者名稱與密碼來自秘密儲存庫	Server=<server>;Database=<database>;User ID=<user>;Password=<password>;Encrypt=true

Windows 整合式驗證會以該程序的身分進行連線。 對於桌面或主控台應用程式，通常是登入使用者。 對於網頁應用程式或 Windows 服務來說，是應用程式池或服務帳號。 模擬可以變更身分。 給你應用程式實際使用的身份授予登入權限和資料庫權限。

這三種 Windows 整合認證形式是等價的：

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

如果字串設定 Integrated Security=true 且 同時設定 User ID 和 Password，驅動程式會使用 Windows 驗證 並忽略使用者名稱和密碼。

Microsoft.Data.SqlClient 7.0 及更新版本需要版本匹配Microsoft.Data.SqlClient.Extensions.Azure套件，才能使用驅動程式提供的 Microsoft Entra ID 認證方法。 當應用程式碼提供存取權杖或存取權杖回調時，你就不需要那個套件。

關於接受 Authentication 的值，請參見 認證選項。 認證也需要在伺服器上設定資料庫使用者、權限，以及身分識別設定。 關於設定步驟，請參見 Microsoft Entra ID 認證與 SQL Server 認證。

指定伺服器與資料庫

Server 以及 Database 是最容易閱讀的關鍵字名稱。 建構者將它們寫成其典範等價物，即 Data Source 和 Initial Catalog。 這四個名稱都可用於 連接字串 中。

設定 Server 為以下其中一種形式：

Form	Example	使用
主機名稱	Server=sql.example.com	位於 1433 埠上的預設實例。
主機名稱與埠口	Server=tcp:sql.example.com,1433	一個特定的 TCP 埠。 用逗號分隔埠，不要用冒號。
具名執行個體	Server=sql.example.com\SALES	具名執行個體。 驅動程式向 UDP 埠 1434 的 SQL Server 瀏覽器服務查詢連接埠。
本地伺服器	Server=(local) 或 Server=.	本機電腦的預設實例。
LocalDB	Server=(localdb)\MSSQLLocalDB	SQL Server Express LocalDB 在 Windows 上。 連線沒有加密，即使有 Encrypt=Mandatory，Encrypt=Strict 仍然失敗。
命名管道	Server=np:\\sql.example.com\pipe\sql\query	Windows 上的具名管道連線。

在生產環境中，請使用 tcp:、完全限定的主機名稱，以及明確指定的連接埠。 請使用與伺服器憑證相符的 DNS 名稱，而非 IP 位址，因為憑證驗證會將 連接字串 中的伺服器名稱與憑證中的名稱進行比較。

當你用 SQL 認證並以 為 的使用者名稱user@servername連接 Azure SQL Database 時，該servername部分必須與 中的Server伺服器相符。

對於可用性群組監聽器或故障轉移叢集實例，也請在連線選項中檢視Multi Subnet Failover。

配置加密與憑證驗證

Encrypt關鍵字接受以下值，無論如何：

Value	建立器值	Meaning
Strict	Strict	使用 TDS 8.0。 登入前加密連線，並且總是驗證伺服器憑證。
Mandatory、true、yes	True	加密連線。 此值為預設值。
Optional、false、no	False	只有當伺服器需要加密時，才會加密整個連線。 當伺服器支援加密但不強制時，只會加密登入封包。

當伺服器支援 TDS 8.0 且有客戶端可驗證的憑證時使用 Strict 。 Azure SQL Database 和 Microsoft Fabric 中的 SQL 資料庫都支援它。 LocalDB 連線沒有加密，即使有 Mandatory，而且 Strict 會失敗。

Trust Server Certificate 與 Encrypt 的值組合如下：

加密	信任伺服器證書	Result
Optional	false	當伺服器需要加密時，整個連線都會被加密，且伺服器憑證必須通過驗證。 否則，連線將失敗。 當伺服器支援加密但不強制時，只有登入封包被加密，且驅動程式不會驗證伺服器憑證，除非連線使用 AccessToken 或 AccessTokenCallback。 當伺服器不支援加密時，什麼都不會被加密。
Optional	true	當伺服器需要加密時，整個連線都會被加密。 當伺服器支援加密但不強制時，只有登入封包會被加密。 驅動程式不會驗證伺服器憑證。
Mandatory	false	僅在伺服器憑證通過驗證時才會加密。 否則，連線會失敗。
Mandatory	true	加密總是會發生，但驅動程式不會驗證伺服器憑證。
Strict	已忽略	加密總是會發生，且必須驗證伺服器憑證。 否則，連線就會失敗。

不要設定 Trust Server Certificate=true 來修正正式環境中的連線錯誤。 它會加密頻道，但不會確認伺服器的身份。 限制在沒有可信憑證的開發環境中使用。

當伺服器名稱 Data Source 與憑證不符時，再設 Host Name In Certificate 成憑證名稱。 SqlClient 只有在伺服器名稱不符時才會檢查，且不會釘選憑證。 若要只接受單一特定憑證，請設定 Server Certificate 為 PEM、DER 或 CER 檔案的路徑：

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

完整驗證規則請參見 加密與憑證驗證。

使用連線池化

連線集區預設是開啟的。 當你開啟 SqlConnection時，驅動程式會從集區中取得一個與該連線相符的實體連線。 當你關閉或釋放該連接時，實體連接會回到池中，而不是關閉。 使用連線集區的開啟會跳過網路連線、TLS 握手和登入。

請遵循以下規則：

• 就在你需要前開啟一個連線，完成時立即丟棄，使用 using 或 await using。 未被處理的連接線會保持檢查狀態，泳池可能會耗盡。

• 啟動時建立一次 連接字串 並重複使用。 pool 鍵包含 連接字串 的精確文字，因此不同的關鍵字順序、同義詞或每個請求的值（如請求 ID 或使用者名稱）會建立獨立的 pool 。 建構者寫出一個典範形式。 欲了解更多資訊，請參閱 Keep one Canonical 連接字串。

• 預期每個 Windows 身份在整合驗證SqlCredential下，每個實例和每個AccessToken值都會有一個獨立的 pool 池。 使用驅動程式提供的 Authentication 方法或重複使用的 AccessTokenCallback，而不是在每個連線上設定 AccessToken 。

• 在提高 Max Pool Size 前，先尋找尚未釋放的連線，該值預設為 100。 當池中所有連線都在使用時，Open 最多等待 Connect Timeout，然後拋出 InvalidOperationException：

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• 為每個池規劃伺服器容量。 每個程序，或 .NET Framework 上的每個應用程式定義域，都有自己的池。 連接到伺服器的連線數可 Max Pool Size 乘以每個程序中的池數及應用程式實例數量。

• 不要為了規避集區問題而設定 Pooling=false。 每次開啟後都會執行完整登入。

若要關閉閒置時間過長的共用連線，請參見 「限制連線閒置時間」。 關於池金鑰、大小、清除與交易，請參見 SQL Server 連線池。

分離的連線與指令設定

連線字串控制連線建立與工作階段行為。 指令控制一個 SQL 操作。

需求	設定開啟
有時間建立連線或從池中取得連線	Connect Timeout 關鍵詞
連線指令的預設逾時	Command Timeout 關鍵詞
單一指令的逾時時間	CommandTimeout
由來電者取消	CancellationToken 傳遞給非同步方法
重試開啟連線或執行指令的策略	可設定重試邏輯 於 SqlConnection 或 SqlCommand

越久越久就不是重試的邏輯。 暫停時間限制等待時間。 重試會開始下一次嘗試，且必須有界限且安全才能重複。

回報應用程式識別資訊

Application Name 設定伺服器透過 APP_NAME()回報的名稱。 每個部署的工作負載都用一個穩定名稱。 為應用程式開啟連線的框架與工具，也能透過 RegisteredApplication 屬性回報自身，而該屬性沒有 連接字串 關鍵字。 欲了解更多資訊，請參閱 「回報應用程式識別」。

安全建立連接線

當程式碼新增或變更值時使用 SqlConnectionStringBuilder 。 不要將不受信任的文字合併成 連接字串，因為該文字中的分號可能會新增或替換關鍵字。 建構器會驗證值，將同義詞對應到典型關鍵字，並為每個值加上引號，讓該值無法新增關鍵字。 相關範例請參見 連接串建構器。

將連線資訊儲存在程式碼外

載入應用程式設定系統中的連接字串。 .NET 應用程式通常使用環境變數、用於本機開發的使用者祕密、Azure 應用程式組態 和 Azure Key Vault。

請遵循以下規則：

• 不要提交密碼、客戶端秘密、存取權杖或生產連線字串。
• 偏好不需要在 連接字串 輸入密碼的認證方式。
• 限制對設定來源的存取。
• 輪替儲存的密鑰，並重新啟動或刷新快取這些密鑰的應用程式。
• 不要把連線字串寫入日誌、例外、追蹤或遙測。
• 保持 Persist Security Info=false，維持預設值，這樣已開啟的連線就不會透過其 ConnectionString 屬性暴露密碼。

關於 .NET 設定提供者，請參見 .NET 中的設定。 如需更多控制項，請參見 保護連線資訊。

解析規則

駕駛人適用以下規則：

• 關鍵字不區分大小寫。 DATABASE、Database 和 database 是同一個關鍵字。
• 許多關鍵字都有同義詞。 Server 和 Data Source 設為相同的數值。 連線選項文章列出了每個關鍵字的同義詞。
• 當關鍵字出現超過一次時，最後一個值會勝出。 同義詞也算作同一個關鍵字。
• 驅動程式會忽略關鍵字周圍的空格和未加引號的值周圍的空格。
• 末尾分號為可選。
• 驅動程式無法識別的關鍵字會擲回 ArgumentException，並顯示訊息 Keyword not supported。

值是否區分大小寫，取決於關鍵字。 密碼是區分大小寫的。 Encrypt=STRICT 兩者 Encrypt=strict 相同。

此程式展示建構器如何正規化關鍵字、處理重複項目及引用特殊字元。 .NET Framework 分頁使用 C# 7.3。 若要建立執行樣本的專案，請參閱「建立專案」。

.NET

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

.NET 架構

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

輸出為：

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

第一行顯示每個同義詞被其典範關鍵字取代：server由 Data Source、 DATABASEInitial Catalog、 timeoutuidUser IDConnect Timeout、 和 。

報價

當值包含分號、以空格開頭或結尾，或以引號開頭或結尾時，則以雙引號（"）或單引號（'）包圍。 在引號值內，將包圍的引號寫兩次。

Value	連接串形式
a;b	Password="a;b"
abc'	Password="abc'"
say "hi"	Password='say "hi"'
a;b'c"d	Password="a;b'c""d"

引用規則很容易出錯。 透過物業設定價值 SqlConnectionStringBuilder ，讓建商報價。 更多資訊請參見 「安全建構連接字串」。

指定布林值

取布林值的關鍵字無論如何都接受 true、 false、 yesno和 。 Integrated Security 也接受 sspi，即 true。 建構者寫 True 為 或 False。

使用其他駕駛者的關鍵字

Microsoft.Data.SqlClient 不接受 ODBC 或 OLE DB 關鍵字，如 Driver 和 Provider。 當你從另一個驅動程式移動 連接字串 時，請移除這些關鍵字。 System.Data.SqlClient連接字串在 Microsoft 中運作。Data.SqlClient，但有以下差異：

• Encrypt預設為 Mandatory 在 Microsoft 中。Data.SqlClient。 沒有受信任憑證的伺服器會無法通過憑證驗證。 在伺服器上安裝一個受信任的憑證。
• 在 .NET 上，Network Library、Connection Reset 和 Transparent Network IP Resolution 都不受支援。 請將其移除。
• 不支援 Context Connection=true。
• Asynchronous Processing 不是支援的關鍵字，並會引發 ArgumentException。 把它拿掉。 非同步方法即使沒有它也能運作。
• 不支援 Type System Version=SQL Server 2000。 建立連線時會拋出 ArgumentException。 使用 Latest、 SQL Server 2012、 SQL Server 2008或 SQL Server 2005。

相關內容

• 在 .NET 應用程式中使用 Microsoft.Data.SqlClient
• 連線選項
• 連接字串建立器
• 連接到資料來源
• SQL Server 連線共用
• Microsoft Entra ID 驗證
• 加密和憑證驗證
• SQL Server Express 使用者執行個體
• SqlClient 驅動程式支援生命週期