共用方式為

使用 SqlClient 的可設定重試邏輯組態檔

  • 發行項

適用於：.NET Framework .NET .NET Standard

下載 ADO.NET

當安全開關啟用時，SqlConnection 和 SqlCommand 的預設重試方法皆為 SqlConfigurableRetryFactory.CreateNoneRetryProvider。 您可以使用組態檔來指定不同的重試方法。

組態區段

可將下列區段新增至組態檔中的 configSections 區段，來變更應用程式的預設重試邏輯選項：

  • SqlConfigurableRetryLogicConnection：為 SqlConnection 指定預設重試邏輯。
<section name="SqlConfigurableRetryLogicConnection"
        type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
  • SqlConfigurableRetryLogicCommand：為 SqlCommand 指定預設重試邏輯。
<section name="SqlConfigurableRetryLogicCommand"
        type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>
  • AppContextSwitchOverrides：.NET Framework 透過AppCoNtextSwitchOverrides 區段支援 AppContext 參數，而不須明確定義。 若要在 .NET Core 中開啟參數，您必須指定此區段。
<section name="AppContextSwitchOverrides"
        type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>

注意

下列組態應該在 configuration 區段中指定。 宣告這些新區段，以透過應用程式組態檔設定預設重試邏輯。

啟用安全開關

注意

從 Microsoft.Data.SqlClient v4.0 開始，將不再需要應用程式內容參數「Switch.Microsoft.Data.SqlClient.EnableRetryLogic」以使用可設定的重試邏輯功能。 生產現已支援此功能。 此功能的預設行為將維持為非重試原則，必須由用戶端應用程式覆寫此原則才能啟用重試。

您可以透過組態檔啟用安全開關。 若要瞭解如何透過應用程式代碼來啟用，請參閱 啟用可設定重試邏輯。

<runtime>
    <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>
</runtime>
  • .NET Core：支援多個分號 (;) 分隔參數，例如 .NET Framework。
<AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

連線區段

下列屬性可用來指定應用程式中所有 SqlConnection 執行個體的預設重試邏輯：

  • numberOfTries：設定要嘗試的次數。

  • deltaTime：將間隙時間間隔設定為 TimeSpan 物件。

  • minTime：將允許的最小間隙時間間隔設定為 TimeSpan 物件。

  • maxTime：將允許的最大間隙時間間隔設定為 TimeSpan 物件。

  • transientErrors：設定要重試的暫時性錯誤號碼清單。

  • retryMethod：指定重試方法建立者，其可透過 SqlRetryLogicOption 參數接收重試組態，並傳回 SqlRetryLogicBaseProvider 物件。

  • retryLogicType：設定自訂重試邏輯提供者，其中包含提供 retryMethod 的重試方法建立者。 這些方法應符合 retryMethod 的準則。 應使用提供者的完整類型名稱。 如需詳細資訊，請參閱 指定完整類型名稱。

注意

如果您使用內建重試提供者，則不須指定 retryLogicType。 若要尋找內建的重試提供者，請參閱 SqlClient 中的內部重試邏輯提供者。

命令區段

也可為應用程式中的所有 SqlCommand 執行個體設定下列屬性：

  • authorizedSqlCondition：為 SqlCommand.CommandText 設定預先重試規則運算式，以篩選特定的 SQL 陳述式。

注意

規則運算式區分大小寫。

範例

  • 透過使用 SqlConfigurableRetryFactory.CreateFixedRetryProvider 方法與預設暫時性錯誤清單，嘗試建立連線達三次，各嘗試之間的延遲大約為 1 秒：

    <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" 
                                        numberOfTries ="3" deltaTime ="00:00:01"/>

  • 透過使用 SqlConfigurableRetryFactory.CreateExponentialRetryProvider 方法與預設暫時性錯誤清單，嘗試建立連線達五次，各嘗試之間的延遲最長為 45 秒：

    <SqlConfigurableRetryLogicConnection retryMethod ="CreateExponentialRetryProvider" 
                    numberOfTries ="5" deltaTime ="00:00:03" maxTime ="00:00:45"/>

  • 透過使用 SqlConfigurableRetryFactory.CreateIncrementalRetryProvider 方法和預設暫時性錯誤清單，嘗試執行命令達四次，延遲時間為 2 到 30 秒：

    <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider"
                    numberOfTries ="4" deltaTime ="00:00:02" maxTime ="00:00:30"/>

  • 嘗試執行命令達八次，延遲時間從一秒到一分鐘。 僅限包含字詞 SELECT 和例外數字 102 或 997 的 CommandText 命令。 其使用內建的 SqlConfigurableRetryFactory.CreateIncrementalRetryProvider 方法：

    <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" 
                        numberOfTries ="8" deltaTime ="00:00:01" maxTime ="00:01:00"
                        transientErrors="102, 997"
                        authorizedSqlCondition="\b(SELECT)\b"/>

注意

在以下兩個範例中，您可以從 SqlClient 中的可設定重試邏輯核心 API 找到自訂重試邏輯原始程式碼。 假設 CreateCustomProvider 方法定義於應用程式執行目錄中的 CustomCRL_Doc.dll 元件中的 CustomCRL_Doc.CustomRetry 類別中。

  • 嘗試建立最多五次的連線，延遲時間為 3 到 45 秒，清單中的錯誤號碼為 4060、997 和 233，且使用指定的自訂重試提供者：

    <SqlConfigurableRetryLogicConnection retryLogicType ="CustomCRL_Doc.CustomRetry, CustomCRL_Doc, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
                    retryMethod ="CreateCustomProvider" 
                    numberOfTries ="5" deltaTime ="00:00:03" maxTime ="00:00:45"
                    transientErrors ="4060, 997, 233"/>

  • 此範例的行為與上一個範例類似：

    <SqlConfigurableRetryLogicConnection retryLogicType ="CustomCRL_Doc.CustomRetry, CustomCRL_Doc"
                    retryMethod ="CreateCustomProvider" 
                    numberOfTries ="5" deltaTime ="00:00:03" maxTime ="00:00:45"
                    transientErrors ="4060, 997, 233"/>

注意

將於重試邏輯提供者第一次使用連線或命令時進行快取，以供未來在應用程式存留期中使用。

注意

讀取重試邏輯設定的應用程式組態檔時出現的任何錯誤都不會在應用程式中造成錯誤。 將會改用預設值 SqlConfigurableRetryFactory.CreateNoneRetryProvider。

您可使用事件來源追蹤來驗證或疑難排解設定重試邏輯問題。 如需詳細資訊，請參閱 在 SqlClient 中啟用事件追蹤。

另請參閱