Microsoft。Data.SqlClient 連線選項控制驅動程式如何建立、識別、路由、重試及連線池化。 可在連線字串或對應的 SqlConnectionStringBuilder 屬性中設定它們。
關於 Microsoft Entra ID 認證，請參見 Microsoft Entra ID 認證。 關於 TLS 設定，請參見 加密與憑證驗證。
用 SqlConnectionStringBuilder 設定選項
請使用建構器，而不要串接連線字串片段：
var builder = new SqlConnectionStringBuilder
{
DataSource = "tcp:sql.example.com,1433",
InitialCatalog = "Orders",
IntegratedSecurity = true,
Encrypt = SqlConnectionEncryptOption.Mandatory,
ApplicationName = "Orders.Worker",
ConnectTimeout = 30,
ConnectRetryCount = 3,
ConnectRetryInterval = 10,
MultiSubnetFailover = true,
};
該法規使用建商物業名稱。 表格使用常見的連線字串寫法。 驅動程式也支援文件中記載的別名。
暫停選項
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Connect Timeout |
15 秒 | 限制建立連結的時間。 當連線集區為 Max Pool Size 時，也會為等候可用的集區連線時間設下上限。
Connection Timeout 以及 Timeout 這些都是別名。 |
所有 Microsoft.Data.SqlClient 版本 |
Command Timeout |
30 秒 | 設定與該連線相關聯的命令預設逾時時間。 當某個操作需要不同限制時，設定 CommandTimeout 在指令上。 值為 0 時沒有時間限制，且可能使工作無限期處於等待狀態。 |
Microsoft。Data.SqlClient 2.1 及後續版本 |
連線逾時與指令逾時衡量的是不同類型的作業。
Connect Timeout 不會限制查詢的執行。
Command Timeout 這不會限制認證或等待共用連線的時間。
A CancellationToken 是獨立於兩個設定的。 將其傳遞給 OpenAsync、命令執行和讀取方法，讓呼叫端可以在逾時發生前停止等待。
工作負載識別與路由選項
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Application Name |
提供者定義名稱 | 識別 SQL Server 會話、稽核及診斷中的工作負載。 為每個已部署的工作負載使用一個穩定且低基數的單一名稱。 | 所有 Microsoft.Data.SqlClient 版本 |
Application Intent |
ReadWrite |
ReadOnly 當目標與可用性群組已設定時，請求讀取意圖路由。 它不會將 SQL 陳述式設為唯讀。 |
所有 Microsoft.Data.SqlClient 版本 |
Application Intent=ReadOnly 通常與可用性群組監聽器或支援讀取路由的服務端點配對。 參見 高可用性與災難復原。
網路與封包選項
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Packet Size |
8,000 位元組 | 設定表格資料串流（TDS）網路封包大小。 支援的數值為 512 至 32,768 位元組。 除非工作負載測量和伺服器設定有需要更改，否則仍保留預設。 | 所有 Microsoft.Data.SqlClient 版本 |
MultiSubnetFailover |
false |
使用平行進行的 TCP 連線嘗試，連線至多位址端點所回傳的 IP 位址。 針對 Azure SQL 端點、可用性群組監聽器，以及透過 TCP 連線的故障轉移叢集執行個體，請將其設為 true。 |
所有 Microsoft.Data.SqlClient 版本 |
MultiSubnetFailover=true 不支援命名實例、非 TCP 協定、資料庫鏡像，或配置超過 64 個 IP 位址的端點。 它對單一 IP TCP 端點來說是安全的。
Microsoft.Data.SqlClient 7.0 也提供了一個整個處理程序層級的 AppContext 切換開關，可讓所有連線的行為都如同 MultiSubnetFailover=true。 當該開關未啟用時，連接字串 預設值仍維持false不變。 請參考 SqlClient 中的 AppContext 切換。
池化選項
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Pooling |
true |
重用符合連線組態的實體連線。 只在診斷或無法安全合併的測量工作負載時關閉。 | 所有 Microsoft.Data.SqlClient 版本 |
Min Pool Size |
0 |
在池子建立後，至少保留這麼多實體連線。 正數值可讓資料庫工作階段保持開啟，直到集區或處理程序結束。 | 所有 Microsoft.Data.SqlClient 版本 |
Max Pool Size |
100 |
將實體連線限制在同一個池中。 請求會等 Connect Timeout 到池子滿了才會被通知。 |
所有 Microsoft.Data.SqlClient 版本 |
Load Balance Timeout |
0 秒 |
當連線回到池中時，若其年齡超過此值，則會丟棄該連線。
Connection Lifetime 是個化名。
0 會停用依據年齡移除的功能。 |
所有 Microsoft.Data.SqlClient 版本 |
Pool Blocking Period |
Auto |
控制集區是否會暫時重新擲回已快取的登入失敗。
Auto禁用已識別 Azure SQL 端點的阻擋期，並啟用其他端點的阻擋期。 |
所有 Microsoft.Data.SqlClient 版本 |
Enlist |
true |
會自動在環境 System.Transactions 交易中啟用一個已開啟的連線。 |
所有 Microsoft.Data.SqlClient 版本 |
池的設定會套用到每個獨立的池，而不是整個程序或資料庫伺服器。 在建立 Max Pool Size之前，請確認連線與讀取器已被迅速處理，且資料庫能接受每個應用程式實例的總和。
如需了解集區索引鍵、權杖行為、封鎖期間、清除和診斷，請參閱 SQL Server 連線集區。
連線恢復選項
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Connect Retry Count |
1 |
設定在初始連線期間發生符合條件的暫時性失敗時，以及在還原已中斷的閒置連線時的重試次數。 實際上預設是2用於認可的 Azure SQL 端點，以及5已認可的 Azure Synapse 和按需端點。
0 關閉這些重試。 |
所有 Microsoft.Data.SqlClient 版本 |
Connect Retry Interval |
10 秒 | 設定後續初始連線或閒置恢復嘗試前的延遲。 有效數值為1至60秒。 | 所有 Microsoft.Data.SqlClient 版本 |
連線恢復期間的第一次重試是立即發生的。
Connect Retry Interval 會在後續嘗試之前套用。 若要針對單一作業略過內建的首次開啟重試機制，請使用包含 OpenWithoutRetry 的 open 多載。
這些關鍵字不會重新執行在執行期間失敗的指令。 使用 可設定的重試邏輯 來自訂開啟或指令政策。 只有在可安全重複其效果時，才重試指令。
伺服器身份與憑證選項
這些選項解決了特定的憑證或 Kerberos 命名需求。 它們並不能取代一般的認證和憑證驗證。
| Keyword | 預設 | 行為 | 版本 |
|---|---|---|---|
Host Name In Certificate |
伺服器主機名稱 | 當連線使用的 DNS 別名與憑證不同時，提供預期的通用名稱（CN）或主體替代名稱（SAN）。 | Microsoft。Data.SqlClient 5.0 及後續版本 |
Server Certificate |
空的 | 提供 PEM、DER 或 CER 檔案，在 Encrypt=Strict 或 Encrypt=Mandatory 時，該檔案必須與伺服器憑證完全相符。 |
Microsoft。Data.SqlClient 5.1 及更新版本 |
Server SPN |
源自伺服器名稱 | 覆寫用於對主要伺服器進行整合式驗證的服務主體名稱（SPN）。 只有在所部署的 Kerberos 命名方式需要明確指定 SPN 時，才設定此項。 | Microsoft。Data.SqlClient 5.0 及後續版本 |
Failover Partner SPN |
由故障切換夥伴推導而來 | 覆寫資料庫鏡像容錯移轉夥伴的 SPN。 資料庫鏡像已被淘汰。 新部署時使用可用性群組。 | Microsoft。Data.SqlClient 5.0 及後續版本 |
Host Name In Certificate 更改用於憑證匹配的名稱。 它不信任不受信任的發行機構。
Server Certificate 會釘選特定的憑證檔案，當該憑證輪替時，就需要更新應用程式。
錯誤的 SPN 覆寫可能會阻止 Kerberos 的認證或削弱預期的身份驗證。 如果可行，請修正 DNS 和 SPN 註冊，而不要設定覆寫。
保持連接字串簡短。 只有當你能說明它改變了哪個行為，以及工作負載如何驗證該行為時，才加入選項。
審查選項變更
在生產環境中更改選項前：
- 記錄目前的 連接字串、驅動程式版本、端點類型及觀察到的問題。
- 一次改變一個行為。
- 測試連線建立、認證、憑證驗證、池化、故障轉移、取消及查詢執行。
- 衡量實體連線次數、連線池等待時間、連線延遲時間和錯誤數量。
- 在每個部署的實例上確認設定。
連接串是池鍵的一部分。 分階段部署可以暫時建立舊有與新資料庫，增加實體資料庫連線的總數。