Provedores de lógica de repetição integrados ao SqlClient

Aplica-se a: .NET Framework .NET .NET Standard

Baixar ADO.NET

Microsoft.Data.SqlClient.SqlConfigurableRetryFactory cria provedores para cronogramas de tentativa de reexecução comuns. A lógica de repetição configurável fica desabilitada por padrão. Atribua um provedor para SqlConnection.RetryLogicProvider ou SqlCommand.RetryLogicProvider para habilitá-lo para esse objeto.

Escolha um provedor de nova tentativa

Os provedores fixo, incremental e exponencial adicionam jitter aleatório a cada intervalo. O jitter reduz rajadas sincronizadas de novas tentativas quando muitos clientes enfrentam a mesma interrupção.

NumberOfTries é o número total de tentativas, incluindo a operação inicial. Por exemplo, NumberOfTries = 3 permite a tentativa inicial e até duas tentativas. Seu alcance válido é de 1 a 60.

Lista de erros transitórios embutida

Quando SqlRetryLogicOption.TransientErrors é null, os provedores embutidos tentam novamente os 20 números de erro em SqlConfigurableRetryFactory.BaselineTransientErrors, agrupados por onde a falha se origina:

Cada erro é descrito nas seções seguintes.

No Microsoft.Data.SqlClient 7.0, SqlConfigurableRetryFactory.BaselineTransientErrors expõe a lista interna como uma coleção somente de leitura. Use-o para estender a linha de base sem copiar números de erro da fonte do driver:

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

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

Para versões anteriores de drivers, crie uma coleção própria do aplicativo que contenha os erros básicos necessários e seus erros adicionais. Antes de copiar uma linha base, selecione a tag de origem SqlClient que corresponde à versão do seu pacote instalado e inspecione SqlConfigurableRetryFactory.cs. A lista no branch main pode mudar após o lançamento do seu pacote.

Erros durante o estabelecimento da conexão

Os erros a seguir podem ser tentados novamente (estão na lista integrada) ou vale a pena adicioná-los a TransientErrors acima da lista integrada.

Os seguintes erros podem ser transitórios quando ocorrem durante o estabelecimento da conexão ou ao enviar uma solicitação para o servidor. Tente novamente em uma retirada curta e limitada. Erros que persistem além de algumas tentativas geralmente indicam um problema de configuração, como servidor errado, permissões faltando, configurações de criptografia incompatíveis ou cota esgotada, que a tentativa não vai corrigir.

Os erros no nível da instrução não estão nessa lista porque são disparados depois que a conexão é estabelecida e a falha deixa a sessão utilizável. Os erros de instrução passíveis de repetição mais comuns são 1205 (vítima de deadlock) e 1222 (tempo limite da solicitação de bloqueio). Repita a transação inteira em vez da única instrução com falha.

O texto da mensagem de erro vem de erros transitórios de conexão do SQL do Azure. Esses erros podem ser repetidos no SQL Server, no Banco de Dados SQL do Azure, no Instância Gerenciada de SQL do Azure, no Banco de Dados SQL no Microsoft Fabric e em pools SQL dedicados no Azure Synapse Analytics.

Erros durante a execução de comandos

Os seguintes erros ocorrem após a conexão ser estabelecida, enquanto um comando está sendo executado. Repita a transação inteira, não a instrução individual. Tentar novamente uma instrução dentro de uma transação pode duplicar o trabalho realizado anteriormente ou violar as garantias de ordenação da transação.

Erros em nível de instrução que refletem um problema em lote ou esquema (por exemplo, 102 erros de sintaxe, 207 coluna inválida, 2812 procedimento armazenado ausente) não são transitórios. Corrija o texto da consulta ou a vinculação ao esquema; tentar novamente não ajuda.

O texto da mensagem de erro é proveniente da exibição de catálogo sys.messages. Esses erros são gerados pelo mecanismo do SQL Server, portanto seus números de erro são os mesmos no SQL Server, no Banco de Dados SQL do Azure, no Instância Gerenciada de SQL do Azure, no banco de dados SQL do Microsoft Fabric e nos pools de SQL dedicados do Azure Synapse Analytics, independentemente do driver.

É o driver, e não o mecanismo, que expõe representações no lado do cliente de erros de tempo limite (timeout) e cancelamento de instruções (por exemplo, o tempo limite do Microsoft.Data.SqlClient -2); portanto, esses erros não constam na lista integrada. Se sua aplicação detectar esses erros separadamente, trate-os na mesma fronteira de transação dos erros do motor descritos anteriormente.

Comportamento de comandos e transações

Os provedores integrados ignoram a nova tentativa quando um comando é executado dentro de um ambiente TransactionScope ou tem um SqlTransaction anexado. O comando é executado uma vez, sem lógica de nova tentativa. Tentar novamente uma única instrução dentro de uma transação pode duplicar o trabalho realizado anteriormente ou violar a ordem pretendida da transação.

Use SqlRetryLogicOption.AuthorizedSqlCondition para limitar as tentativas de comando a operações que sua aplicação pode repetir com segurança. O predicado recebe o texto do comando. Se o predicado retornar false, o comando é executado uma vez, sem lógica de repetição.

Exemplo

Para exemplos completos de conexão e comando, veja:

• SqlConnection.RetryLogicProvider
• SqlCommand.RetryLogicProvider

Conteúdo relacionado

• Crie um provedor de retentativas personalizado para o SqlClient
• Lógica de repetição configurável no SqlClient
• Microsoft. Data.SqlClient para SQL Server