Microsoft.Data.SqlClient 的連接字串

一個 Microsoft.Data.SqlClient 連接字串 告訴驅動程式應該使用哪個 SQL Server 相容端點和資料庫，如何認證，以及如何設定連線。 傳給 SqlConnection 或 SqlConnectionStringBuilder。

從四個決定開始：

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

當所選的認證方法支援該設計時，請將憑證和存取權杖排除在 連接字串 之外。

選擇一種認證模式

使用最符合部署需求的最窄模式。

Environment 偏好模式 核心連線字串
Windows 上的 SQL Server 在網域或本地 Windows 身份下 Windows 整合式驗證 Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
開發工作站連接 Microsoft Fabric 中的 SQL 資料庫 Microsoft Entra ID 預設認證鏈 Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict
託管於 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
連線至 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_id>;Password=<password>;Encrypt=true

Microsoft。Data.SqlClient 7.0 及後續版本需要版本匹配Microsoft.Data.SqlClient.Extensions.Azure套件以實現驅動程式提供的 Microsoft Entra ID 認證模式。 當應用程式碼提供存取權杖或存取權杖回撥時，你就不需要那個擴充功能。

認證也需要資料庫端的使用者、權限及身份設定。 完整的選擇矩陣與設定，請參閱 Microsoft Entra ID 認證與 SQL Server 認證。

指定伺服器與資料庫

使用 Server 和 Database 作為官方關鍵字名稱。 此驅動程式也接受別名，例如將 Data Source 作為 Server 的別名，以及將 Initial Catalog 作為 Database 的別名。

常見的伺服器形式包括：

Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB

對於正式環境中的 TCP 連線，建議明確指定通訊協定、主機名稱和連接埠。 使用與伺服器憑證相符的穩定 DNS 名稱，而非 IP 位址。

對於可用性群組監聽器、故障轉移群組、Azure SQL 端點或其他多位址 TCP 端點，也請在 Connection options 中檢視MultiSubnetFailover。

配置加密與憑證驗證

Microsoft.Data.SqlClient 4.0 及更新版本將 Encrypt 預設為 true。 Microsoft.Data.SqlClient 5.0 及更新版本也支援用於協商 TDS 8.0 的伺服器的 Encrypt=Strict。

使用：

  • Encrypt=Strict 當伺服器支援 TDS 8.0 並持有憑證時，客戶端可以進行驗證。
  • Encrypt=true 用於與其他支援伺服器的加密連線。
  • TrustServerCertificate=false，預設，用於產生憑證驗證。

不要把它 TrustServerCertificate=true 當作一般的連線修復方法。 它會加密通道，但跳過伺服器身份驗證。 將其限制於沒有可用受信任憑證的受控開發環境。

關於伺服器需求、版本行為及憑證選項，請參見 加密與憑證驗證。

了解連接字串語法

連接字串 是一個以分號分隔的關鍵字與值對清單：

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

請遵循以下規則：

  • 關鍵字名稱不區分大小寫。
  • 數值可以區分大小寫。
  • 最後一個分號是可選的。
  • 當值包含分號或前置或後置空白時，請用單引號或雙引號引用。
  • 將包住值的引號重複一次，以逸出該引號。
  • 不要使用重複的關鍵字。 解析器使用最後一個值，這使得有效配置難以檢視。

被接受的關鍵字與別名集合屬於提供者所有。 Microsoft.Data.SqlClient 可接受的連線字串，可能無法搭配 System.Data.SqlClient 或其他資料提供者使用。

安全建立連接線

當程式碼需要新增、驗證或替換數值時使用 SqlConnectionStringBuilder 。 不要將不受信任的值串接到連線字串中。

string baseConnectionString =
    configuration.GetConnectionString("Orders")
    ?? throw new InvalidOperationException(
        "Connection string 'Orders' wasn't configured.");

var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
    ApplicationName = "Orders.Api",
    ConnectTimeout = 30,
};

string connectionString = builder.ConnectionString;

建築商：

  • 拒絕不支援的關鍵字和無效值。
  • 將別名映射到典範屬性。
  • 必要時將值加上引號。
  • 防止某個值注入另一個關鍵字。

建構者在密碼或令牌進入程序記憶體後不會保護它。 它也不會決定伺服器、身份或憑證設定是否安全。

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

載入應用程式所使用的配置系統中的連接字串。 目前的 .NET 應用程式通常使用環境變數、本地開發的使用者秘密、Azure 應用程式組態 以及 Azure Key Vault 支援的配置。

遵守以下規則：

  • 不要提交密碼、客戶端秘密、存取權杖或生產連線字串。
  • 建議使用不需要在連線字串中包含密碼的身分識別型驗證方法。
  • 限制對設定來源的存取。
  • 輪換已儲存的密碼，並重新啟動或重新整理會快取這些密碼的應用程式。
  • 不要把連線字串寫入日誌、例外、追蹤或遙測。
  • 保持 Persist Security Info=false為預設值，這樣開啟的連線不會透過其 連接字串 暴露安全敏感值。

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

保持泳池鑰匙穩定

連線集區會將精確的連線組態作為其集區索引鍵的一部分。 等效字串在文字內容不同時，可能會建立個別的集區，包括關鍵字出現順序不同的情況。

在應用程式啟動時建立一個典型的 連接字串 並重複使用。 不要在字串中加入請求 ID、使用者名稱、存取權杖或其他每個請求的值。 完整關鍵規則請參見 SQL Server 連線池。

分離的連線與指令設定

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

需求 設定開啟
建立連線或從池中取得連線的時間 Connect Timeout 連接選項
預設指令執行逾時時間 Command Timeout 連線選項（驅動程式版本支援時）
單一指令的逾時時間 CommandTimeout
由來電者取消 CancellationToken 傳遞給非同步 API
開啟連線或執行指令的重試原則 可在 SqlConnection 或 SqlCommand 上設定的重試邏輯

不要把較長的逾時時間當作重試邏輯。 暫停時間限制等待時間。 重試會再次進行嘗試，且必須受到限制，並能安全地重複執行。

檢視與版本相關的行為

驅動程式版本 連線字串變更
4.0 Encrypt 預設為 true。
5.0 Encrypt=Strict和HostNameInCertificate可供使用。 SqlConnectionStringBuilder.Encrypt 使用 SqlConnectionEncryptOption。
5.1 ServerCertificate 可以將伺服器憑證與檔案比對。
5.2 AccessTokenCallback 適用於可續期的應用程式提供的代幣。
7.0 由驅動程式提供的 Microsoft Entra ID 驗證將移至 Microsoft.Data.SqlClient.Extensions.Azure。
7.0.2 核心驅動程式及其配套套件使用對齊版本。

使用支援的穩定驅動版本，並在更新前閱讀發佈說明。 有關目前版本，請參閱 SqlClient 驅動程式支援生命週期。

相關內容

  • Last updated on