SqlClient 的內建重試邏輯提供者

適用於： .NET Framework .NET .NET 標準

下載 ADO.NET

Microsoft.Data.SqlClient.SqlConfigurableRetryFactory 建立常見重試排程的提供者。 可設定重試邏輯預設是關閉的。 將提供者指派給 SqlConnection.RetryLogicProvider 或 SqlCommand.RetryLogicProvider，即可為該物件啟用。

選擇重試提供者

固定、增量和指數提供者會在每個間隔中加入隨機抖動。 抖動可在許多用戶端遭遇相同服務中斷時，減少同步重試潮。

NumberOfTries 是包含初始運算的總嘗試次數。 例如，允許 NumberOfTries = 3 初次嘗試，最多可重試兩次。 其有效範圍為1至60。

內建瞬態錯誤清單

當 SqlRetryLogicOption.TransientErrors 為 null 時，內建提供者會依失敗來源分組，重試 SqlConfigurableRetryFactory.BaselineTransientErrors 中的 20 個錯誤編號：

每個錯誤會在接下來的章節中說明。

在 Microsoft。Data.SqlClient 7.0 將SqlConfigurableRetryFactory.BaselineTransientErrors內建清單以唯讀集合形式揭露。 利用它來擴展基準線，而不會從驅動程式來源複製錯誤號碼：

var transientErrors = SqlConfigurableRetryFactory.BaselineTransientErrors
    .Append(12345)
    .ToArray();

var options = new SqlRetryLogicOption
{
    NumberOfTries = 5,
    DeltaTime = TimeSpan.FromSeconds(2),
    MaxTimeInterval = TimeSpan.FromSeconds(30),
    TransientErrors = transientErrors,
};

對於較舊版的驅動程式，請建立一個由應用程式擁有的集合，其中包含您所需的基準錯誤以及其他錯誤。 在複製基準資料前，先選擇與你已安裝套件版本相符的 SqlClient 來源標籤 並檢查 SqlConfigurableRetryFactory.cs。 main 分支上的清單可能會在你的套件發布後變更。

連線建立時的錯誤

以下錯誤可在內建清單中重試，或值得在內建清單上方新增 TransientErrors 。

以下錯誤若發生於建立連線期間或向伺服器傳送要求時，可能只是暫時性的。 以短暫且有上限的退避間隔進行重試。 重複幾次後仍持續的錯誤通常表示設定問題，例如伺服器錯誤、權限遺失、加密設定不相容，或配額用盡，重試無法解決。

語句層級錯誤不在此列表中，因為它們會在連線建立後觸發，且失敗後會讓會話仍可用。 最常見的可重試語句錯誤是 1205（死鎖受害者）和 1222（鎖-請求逾時）。 請重試整個交易作業，而不是只重試失敗的單一陳述式。

錯誤訊息內容來自 Azure SQL 暫時性連線錯誤。 這些錯誤可在 SQL Server、Azure SQL Database、Azure SQL 受控執行個體、Microsoft Fabric 中的 SQL 資料庫，以及 Azure Synapse Analytics 的專用 SQL 池中重試。

指令執行時的錯誤

以下錯誤發生在連線建立後，指令執行時。 重試整筆交易，不要重試個別對帳單。 在交易中重試其中一個陳述式，可能會重複先前已完成的工作，或違反該交易的順序保證。

反映批次或結構問題的語句層級錯誤（例如 102 語法錯誤、 207 無效欄位、 2812 遺失儲存程序）並非暫時性。 修正查詢文字或結構綁定;重試沒用。

錯誤訊息文字來自 sys.messages 目錄檢視。 這些錯誤來自 SQL Server 引擎，因此無論是在 SQL Server、Azure SQL Database、Azure SQL 受控執行個體、Microsoft Fabric 中的 SQL 資料庫，還是 Azure Synapse Analytics 中的專用 SQL 集區，其編號都相同，且不論使用哪一種驅動程式皆然。

驅動程式而非引擎顯示客戶端的陳述式逾時與取消錯誤（例如，Microsoft。Data.SqlClient -2 逾時），所以這些錯誤不在內建清單中。 如果您的應用程式分開攔截這些錯誤，請在與先前所述引擎錯誤相同的交易邊界內處理它們。

指令與交易行為

內建的服務程式會在指令在 TransactionScope 環境中執行或有 SqlTransaction 附加條件時跳過重試。 指令執行一次且不重試邏輯。 在交易中重試單一語句可能會重複先前的工作，或違反交易的預期順序。

使用 SqlRetryLogicOption.AuthorizedSqlCondition 將命令重試限制於您的應用程式可安全重複執行的作業。 述詞接受指令文字。 若謂詞回傳 false，該指令執行一次且不重試邏輯。

範例

完整的連線與指令範例，請參見：

• SqlConnection.RetryLogicProvider
• SqlCommand.RetryLogicProvider

相關內容

• 為 SqlClient 建立自訂重試提供者
• SqlClient 中可設定的重試邏輯
• Microsoft.Data.SqlClient for SQL Server