Microsoft.Data.SqlClient 的連線選項

本文列出了 Microsoft.Data.SqlClient 接受的所有 連接字串 關鍵字。 每個關鍵字也都有一個相符 SqlConnectionStringBuilder 的屬性。 關於入門介紹、常見模式與解析規則，請參見 連接字串。

關鍵字和別名並不區分大小寫。 當你透過建商物業設定價值時，建商會在 關鍵字 欄中寫入該標準關鍵字。

用 SqlConnectionStringBuilder 設定選項

從一個包含伺服器、資料庫和認證設定的基礎 連接字串 開始。 然後透過建構者屬性設定特定工作負載的選項。 .NET Framework 分頁使用了 C# 7.3。 若要建立執行樣本的專案，請參閱 「建立專案」。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

輸出為：

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

新連線 SqlCommand 的預設逾時是取 Command Timeout 自其連線關鍵字。

檢查預設值

新一個選項 SqlConnectionStringBuilder 的預設值會被報告。 此程式會列印大多數應用程式會審查的預設值：

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

在 .NET 上，輸出為：

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True 這是選項 Mandatory 。 在 .NET Framework 中，預設應用程式名稱為 Framework Microsoft SqlClient Data Provider。

伺服器與資料庫選項

Keyword Aliases 建商財產 預設 描述
Data Source Server、Address、Addr、Network Address DataSource 空的 要連接的伺服器。 接受主機名稱、host,port、(localdb)\instancehost\instance及或tcp:np:協定前綴。 關於接受的表單，請參見 「指定伺服器與資料庫」。
Initial Catalog Database InitialCatalog 空的 登入後使用的資料庫。 當帳號是空的，伺服器會使用登入的預設資料庫。
AttachDbFilename Extended Properties，Initial File Name AttachDBFilename 空的 主要資料庫檔案的完整路徑，用於 SQL Server Express 與 LocalDB。
User Instance None UserInstance false 將連線導向至 SQL Server Express 使用者實例。 欲了解更多資訊，請參閱 SQL Server Express 使用者實例。
Failover Partner FailoverPartner FailoverPartner 空的 當主要伺服器無法使用時，資料庫鏡像夥伴會嘗試。 資料庫鏡像已被淘汰。 新部署時使用可用性群組。
Current Language Language CurrentLanguage 空的 會話的 SQL Server 語言名稱，例如 us_english。 控制日期格式與系統訊息語言。

應用程式身份選項

Keyword Aliases 建商財產 預設 描述
Application Name App ApplicationName Core Microsoft SqlClient Data Provider 伺服器透過會話視圖及會話檢視時回報 APP_NAME() 的名稱。 每個部署的工作負載都用一個穩定名稱。 不同的數值會產生不同的連結池。
Workstation ID WorkstationID，WSID WorkstationID 本地電腦名稱 伺服器透過 S 回報 HOST_NAME()的用戶端電腦名稱。
Application Intent ApplicationIntent ApplicationIntent ReadWrite ReadOnly 當目標支援時請求讀取意圖路由。 它不會讓語句變成唯讀。 欲了解更多資訊，請參閱 高可用性與災難復原。

要報告是哪個框架或工具開啟了連線，請使用該 RegisteredApplication 屬性。 它沒有 連接字串 關鍵字。 欲了解更多資訊，請參閱 「報告應用程式身份」。

驗證選項

Keyword Aliases 建商財產 預設 描述
Authentication None Authentication 未具體說明 驗證方法。 關於被接受的數值，請參見下表。
Integrated Security Trusted_Connection IntegratedSecurity false true， ， yes， sspi 或使用當前程序的身份。
User ID UID，User UserID 空的 SQL 登入名稱，或 Microsoft Entra ID 的使用者或用戶端識別碼，視 Authentication.
Password PWD Password 空的 密碼或用戶端秘密，適用於接受密碼的方法。
Persist Security Info PersistSecurityInfo PersistSecurityInfo false 當 false時，驅動程式會在連線開啟後移除密碼 SqlConnection.ConnectionString 。 算了 false。
Server SPN ServerSPN ServerSPN 源自伺服器名稱 覆寫用於對主要伺服器進行整合式驗證的服務主體名稱（SPN）。
Failover Partner SPN FailoverPartnerSPN FailoverPartnerSPN 源自合作夥伴名稱 覆蓋用於整合驗證的 SPN 給故障轉移夥伴。

Authentication 接受這些價值觀。 建構者會寫出不加空格的 ，例如 ActiveDirectoryDefault，而解析器接受這兩種形式。

Value Identity
Sql Password 一個帶有 User IDPassword和 的 SQL 登入。
Active Directory Default 一連串憑證來源，例如環境變數、管理身份及開發者工具登入。
Active Directory Managed Identity 一個受管理身份。 設定 User ID 為使用者指派身份的客戶端 ID。 Active Directory MSI 是個化名。
Active Directory Workload Identity 一個 Kubernetes 工作負載身份。
Active Directory Service Principal 一個應用程式設定 User ID 為客戶端 ID，並 Password 設定為客戶端秘密。
Active Directory Interactive 一位透過瀏覽器提示登入的使用者。
Active Directory Device Code Flow 使用者用代碼在另一台裝置登入。
Active Directory Integrated 登入的 Windows 使用者，透過聯邦或無縫的單一登入配置。
Active Directory Password 用戶名稱和密碼。 這個方法已過時。 用其他方法。

Microsoft Entra ID 的方法需要這個Microsoft.Data.SqlClient.Extensions.Azure套件。 關於設定與範例，請參見 Microsoft Entra ID 認證與 SQL Server 認證。

加密選項

Keyword Aliases 建商財產 預設 描述
Encrypt None Encrypt Mandatory Strict 使用 TDS 8.0，並且總是驗證伺服器憑證。 Mandatory， ， true或 yes 是加密連線。 Optional， ， false， no 或僅在伺服器需要時加密整個連線。 當伺服器支援加密但不強制時，只有登入封包會被加密。
Trust Server Certificate TrustServerCertificate TrustServerCertificate false true 跳過伺服器憑證驗證。 當 Encrypt=Strict 時會被忽略。 不要在生產環境中使用它。
Host Name In Certificate HostNameInCertificate HostNameInCertificate 空的 憑證驗證的備用名稱。 SqlClient 首先會根據伺服器名稱 Data Source驗證憑證。 它只會在名稱不匹配時檢查 Host Name In Certificate ，所以當伺服器名稱已經匹配時，錯誤的值不會導致失敗。 它不會綁定憑證。 若要要求特定憑證，請使用 Server Certificate。 它不會改變網路目的地，也不會繞過信任鏈和到期檢查。 當伺服器名稱已經和證書相符時，保持不設定。
Server Certificate ServerCertificate ServerCertificate 空的 PEM、DER或CER檔案的路徑必須與伺服器憑證完全吻合。 司機只有在驗證憑證時才會檢查匹配，因此使用與 或 Encrypt=StrictTrust Server Certificate=false和 的符號。Encrypt=Mandatory 匹配檔案取代了鏈名和主機名稱驗證，因此它能使用客戶端不信任的自簽憑證。

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

永遠加密選項

Keyword Aliases 建商財產 預設 描述
Column Encryption Setting ColumnEncryption ColumnEncryptionSetting Disabled Enabled 開啟連線時的「始終加密」。
Attestation Protocol None AttestationProtocol 未具體說明 飛地認證協議： AAS、、 HGS或 None。
Enclave Attestation Url None EnclaveAttestationUrl 空的 Always Encrypted with secure enclaves 的認證服務端點。

網路選項

Keyword Aliases 建商財產 預設 描述
Multi Subnet Failover MultiSubnetFailover MultiSubnetFailover false 嘗試平行處理伺服器名稱解析的所有 IP 位址。 它用於可用性群組監聽器和透過 TCP 連線的故障轉移叢集實例。 資料庫鏡像不支援。 命名實例依據網路實作而定。 受管理實作（.NET 在 Linux 和 macOS 以及 Windows 上啟用管理網路時）支援命名實例，並會平行地將 SQL Server 瀏覽器請求傳送到每個已解析的位址。 Windows 的原生實作可以拒絕帶有 SNI 錯誤 48 的命名實例。
IP Address Preference IPAddressPreference IPAddressPreference IPv4First 嘗試解析位址的順序為： IPv4First、、 IPv6First或 UsePlatformDefault。
Packet Size PacketSize PacketSize 8000 表格資料串流（TDS）封包大小（位元組）從 512 到 32,768。

一個全程序的 AppContext 開關可以將預設值 Multi Subnet Failover 改為 true。 欲了解更多資訊，請參閱 SqlClient 中的 AppContext 切換。

暫停選項

Keyword Aliases 建商財產 預設 描述
Connect Timeout Connection Timeout、ConnectTimeout、Timeout ConnectTimeout 15 等待連線的時間是幾秒鐘，包括當連線池滿時等待池連線的時間。 0 無限期等待。
Command Timeout None CommandTimeout 30 連線上產生的指令預設 CommandTimeout 秒數。 0 無限期等待。

Connect Timeout 不會限制查詢的執行。 Command Timeout 這不會限制登入或等待共用連線的時間。 將 A CancellationToken 傳給非同步通話，讓呼叫者能在任一逾時前停止等待。

連線恢復選項

Keyword Aliases 建商財產 預設 描述
Connect Retry Count ConnectRetryCount ConnectRetryCount 1 在第一次開放時發生排位短暫故障後，以及恢復故障怠速連線時的重試。 0 關閉重試。 有效值為 0 到 255。
Connect Retry Interval ConnectRetryInterval ConnectRetryInterval 10 重試之間的間隔。 有效數值為1到60。

當 Connect Retry Count 是 1，這是預設值，驅動程式會用來處理 Azure SQL 端點，而5對於 Azure Synapse Analytics 的無伺服器 SQL 池端點，當它恢復壞掉的閒置連線時。2 第一次開啟會使用設定值，因此預設允許每個端點重試一次。 驅動程式在兩種情況下都使用設定的其他值。

這些關鍵字不會重新執行在執行期間失敗的指令。 若要跳過一個開啟的內建重試，請呼叫 Open 一個帶有 OpenWithoutRetry的超載。 關於自訂政策，請參見 可配置重試邏輯。 只有在安全重複指令時才重試。

池化選項

Keyword Aliases 建商財產 預設 描述
Pooling None Pooling true 重用實體連線以匹配連接串。
Min Pool Size None MinPoolSize 0 池建立後仍保持開啟的實體連線。
Max Pool Size None MaxPoolSize 100 最多實體連線集中在同一池子裡。 必須至少為 1。
Connection Idle Timeout None IdleTimeout 300 連線可以在池子關閉前保持閒置的秒數。 0 關閉怠速過期。 只有當 Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext 開關為 false時才會強制執行。 預設為true。
Load Balance Timeout Connection Lifetime LoadBalanceTimeout 0 連線後的最大年齡（秒數）會回到池中。 一個較舊的連線已關閉。 0 關閉限制。
Pool Blocking Period PoolBlockingPeriod PoolBlockingPeriod Auto 是否池會短暫重拋快取登入失敗： Auto、、 AlwaysBlock或 NeverBlock。 Auto關閉 Azure SQL 端點的阻擋。

每個不同的 連接字串 都有自己的 pool 。 關於池金鑰、清除與閒置時間，請參見 SQL Server 連線池。

交易與會話選項

Keyword Aliases 建商財產 預設 描述
Enlist None Enlist true 當交易開啟時，會將連線列入環境 System.Transactions 交易中。
Transaction Binding None TransactionBinding Implicit Unbind Implicit Unbind 當入伍交易結束時，該連線會被斷開。 Explicit Unbind 保持連接狀態直到連線關閉或程式碼將其分離。
Multiple Active Result Sets MultipleActiveResultSets MultipleActiveResultSets false 允許在同一條連線上同時有多個活躍批次。
Type System Version None TypeSystemVersion Latest 驅動程式所暴露的伺服器型系統。 接受 Latest、 SQL Server 2012、 SQL Server 2008和 SQL Server 2005。 請留在 Latest。
Replication None Replication false 將連線識別為複寫連線。

僅限 .NET Framework 的選項

這些關鍵字僅在 .NET Framework 上被接受。 在 .NET 上，建造者不斷NotSupportedExceptionSqlConnectionArgumentException拋出 。

Keyword Aliases 建商財產 預設 描述
Network Library Net，Network NetworkLibrary 空的 網路圖書館。 不要把它和 a tcp: 或 np: 前綴 Data Source合併，因為連線會失敗。 在 .NET 上，前Data Source綴要用 tcp: 或 np: 取代。
Connection Reset None ConnectionReset true Obsolete.
Transparent Network IP Resolution TransparentNetworkIPResolution TransparentNetworkIPResolution true Obsolete.

不支援關鍵字

Keyword Result
Context Connection Context Connection=true 投擲 InvalidOperationException。 Microsoft。Data.SqlClient 不支援 SQL CLR 上下文連線。
Asynchronous Processing 拋出 ArgumentException: Keyword not supported。 非同步方法則不需要它也能運作。
Driver，Provider 拋出 ArgumentException: Keyword not supported。 這些關鍵字屬於 ODBC 和 OLE DB。

驗證規則

SqlConnectionStringBuilder 當你設定時，會拒絕未知關鍵字和許多無效值。 SqlConnection當你設定它的 連接字串 時，會進行更多檢查，包括建構者接受的單一值和關鍵字組合。 建商接受的線條在建立連接時仍可能失效。

建構者與連接拒絕這些值，當 ：ArgumentException

  • Connect Timeout， Command Timeout， Load Balance Timeout， Connection Idle Timeout， 或 Min Pool Size 小於 0。
  • Max Pool Size 少於1。
  • Packet Size 512 外，32,768。
  • Connect Retry Count 從0到255。
  • Connect Retry Interval 1至60區外側。
  • 這個關鍵字這篇文章中沒有提到。

SqlConnection 也拒絕這些值， ArgumentException儘管建構者接受：

  • Type System Version 除了 Latest、 SQL Server 2012、 SQL Server 2008、 或 SQL Server 2005之外。
  • Transaction Binding 除了 Implicit Unbind 或 Explicit Unbind之外。
  • 一個比 、 Data SourcePasswordAttachDBFilenameCurrent LanguageWorkstation IDFailover PartnerUser IDInitial Catalog或 的 TDS 限制Application Name更長的值。

SqlConnection也拒絕這些組合，且：ArgumentException

  • Min Pool Size 大於 Max Pool Size。
  • Failover Partner 沒有 Initial Catalog。
  • Failover Partner 搭配 Multi Subnet Failover=true、User Instance=true或 Application Intent=ReadOnly。
  • Authentication 與 Integrated Security=true。
  • Password 其中 Active Directory Integrated、 Active Directory Interactive、 Active Directory Managed Identity、 Active Directory MSI、 Active Directory Default或 Active Directory Workload Identity。
  • User ID或 Password 。Active Directory Device Code Flow

審查選項變更

在你更改生產選項之前：

  1. 記錄目前的 連接字串、驅動程式版本、端點類型，以及你要解決的問題。
  2. 一次只改變一個選項。
  3. 測試連線建立、認證、憑證驗證、池化、故障轉移、取消及查詢執行。
  4. 測量連線延遲、池等待時間和錯誤數字。
  5. 在每個部署的實例上確認設定。

變更的 連接字串 會建立一個新的 pool 。 在分階段部署期間，舊池與新池會同時存在，因此伺服器的實體連線總數可能會增加。

相關內容

  • 上次更新時間：