SqlClient 提供的可配置重试逻辑配置文件

适用于: .NET Framework .NET .NET Standard

下载 ADO.NET

SqlConfigurableRetryFactory.CreateNoneRetryProvider 中为 SqlConnectionSqlCommand 启用了安全开关时的默认重试方法。 可以使用配置文件指定不同的重试方法。

配置部分

可以在配置文件的 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.CustomRetry 类中定义的,该类位于应用程序执行目录的 CustomCRL_Doc.dll 程序集中。

  • 在 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 中启用事件跟踪

另请参阅