Arquivo de configuração da lógica de repetição configurável no SqlClient

  • Artigo

Aplicável a: .NET Framework .NET .NET Standard

Baixar ADO.NET

O método de repetição padrão, quando a opção de segurança está habilitada, é o SqlConfigurableRetryFactory.CreateNoneRetryProvider para SqlConnection e para SqlCommand. Você pode especificar um método de repetição diferente usando um arquivo de configuração.

Seções de configuração

As opções de lógica de repetição padrão de um aplicativo podem ser alteradas adicionando as seguintes seções dentro da seção configSections do arquivo de configuração:

  • SqlConfigurableRetryLogicConnection: para especificar a lógica de repetição padrão de SqlConnection.
<section name="SqlConfigurableRetryLogicConnection"
        type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
  • SqlConfigurableRetryLogicCommand: para especificar a lógica de repetição padrão de SqlCommand.
<section name="SqlConfigurableRetryLogicCommand"
        type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>
  • AppContextSwitchOverrides: o .NET Framework dá suporte a opções AppContext por meio de uma seção AppContextSwitchOverrides, que não precisa ser definida explicitamente. Para ativar uma opção no .NET Core, você precisa especificar essa seção.
<section name="AppContextSwitchOverrides"
        type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>

Observação

As configurações a seguir devem ser especificadas dentro da seção configuration. Declare essas novas seções para configurar a lógica de repetição padrão por meio de um arquivo de configuração de aplicativo.

Habilitar a opção de segurança

Observação

A partir do Microsoft.Data.SqlClient v4.0, a alternância de contexto do aplicativo "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" não será mais necessária para usar o recurso lógico de repetição configurável. Agora há suporte para o recurso na produção. O comportamento padrão do recurso continuará sendo uma política de não nova tentativa, que precisará ser substituído por aplicativos cliente para habilitar as recuperações.

Você pode habilitar a opção de segurança por meio de um arquivo de configuração. Para saber como habilitá-la por meio do código do aplicativo, confira Habilitar a lógica de repetição configurável.

<runtime>
    <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>
</runtime>
  • .NET Core: dá suporte a várias opções delimitadas por ponto e vírgula (;), como o .NET Framework.
<AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

Seção de conexão

Os seguintes atributos podem ser usados para especificar a lógica de repetição padrão para todas as instâncias SqlConnection de um aplicativo:

  • numberOfTries: define o número de vezes a tentar.

  • deltaTime: define o intervalo de tempo como um objeto TimeSpan.

  • minTime: define o intervalo de tempo mínimo permitido como um objeto TimeSpan.

  • maxTime: define o intervalo de tempo máximo permitido como um objeto TimeSpan.

  • transientErrors: define a lista de números de erro transitórios a tentar novamente.

  • retryMethod: especifica um criador de método de repetição que recebe a configuração de repetição por meio de um parâmetro SqlRetryLogicOption e retorna um objeto SqlRetryLogicBaseProvider.

  • retryLogicType: define um provedor de lógica de repetição personalizado, que contém os criadores de método de repetição que fornecem o retryMethod. Esses métodos devem atender aos critérios de retryMethod. O nome do tipo totalmente qualificado do provedor deve ser usado. Para obter mais informações, confira Especificando nomes de tipo totalmente qualificados.

Observação

Não será necessário especificar retryLogicType se você usar os provedores de repetição internos. Para localizar os provedores internos de repetição, confira Provedores internos de lógica de repetição no SqlClient.

Seção de comando

O atributo a seguir também pode ser definido para todas as instâncias SqlCommand de um aplicativo:

  • authorizedSqlCondition: define uma expressão regular de repetição prévia para SqlCommand.CommandText a fim de filtrar instruções SQL específicas.

Observação

A expressão regular diferencia maiúsculas de minúsculas.

Exemplos

  • Tenta até três vezes estabelecer uma conexão, com um atraso aproximado de 1 segundo entre as tentativas, usando o método SqlConfigurableRetryFactory.CreateFixedRetryProvider e a lista de erros transitórios padrão:

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

  • Tenta até cinco vezes estabelecer uma conexão, com um atraso de até 45 segundos entre as tentativas, usando o método SqlConfigurableRetryFactory.CreateExponentialRetryProvider e a lista de erros transitórios padrão:

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

  • Tenta executar um comando até quatro vezes com um atraso de 2 a 30 segundos usando o método SqlConfigurableRetryFactory.CreateIncrementalRetryProvider e a lista de erros transitórios padrão:

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

  • Tenta executar um comando até oito vezes com um atraso de um segundo a um minuto. Limita-se a comandos com CommandText contendo a palavra SELECT e os números de exceção 102 ou 997. Usa o método interno SqlConfigurableRetryFactory.CreateIncrementalRetryProvider:

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

Observação

Nos próximos dois exemplos, você pode encontrar o código-fonte da lógica de repetição personalizada das APIs principais da lógica de repetição configurável no SqlClient. Supõe-se que o método CreateCustomProvider esteja definido na classe CustomCRL_Doc.CustomRetry no assembly CustomCRL_Doc.dll que está no diretório em execução do aplicativo.

  • Tenta estabelecer uma conexão até cinco vezes, com um atraso de 3 a 45 segundos, números de erro 4060, 997 e 233 na lista e usando o provedor de repetição personalizado especificado:

    <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"/>

  • Este exemplo se comporta como o anterior:

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

Observação

Os provedores de lógica de repetição serão armazenados em cache no primeiro uso em uma conexão ou em um comando para uso futuro durante o tempo de vida de um aplicativo.

Observação

Eventuais erros ao ler um arquivo de configuração de aplicativo para as configurações de lógica de repetição não causarão erros no aplicativo. O SqlConfigurableRetryFactory.CreateNoneRetryProvider padrão será usado em vez disso.

Você pode usar o rastreamento da origem do evento para verificar ou solucionar problemas com a configuração da lógica de repetição. Para obter mais informações, confira Habilitar o rastreamento de eventos no SqlClient.

Veja também