Diretrizes de repetição para serviços do AzureRetry guidance for Azure services

A maioria dos serviços do Azure e SDKs do cliente inclui um mecanismo de repetição.Most Azure services and client SDKs include a retry mechanism. No entanto, eles são diferentes porque cada serviço apresenta características e requisitos diferentes, e cada mecanismo de repetição é ajustado para um serviço específico.However, these differ because each service has different characteristics and requirements, and so each retry mechanism is tuned to a specific service. Este guia resume os recursos do mecanismo de repetição para a maioria dos serviços do Azure, além de incluir informações que ajudam a usar, a adaptar ou a estender o mecanismo de repetição para o serviço em questão.This guide summarizes the retry mechanism features for the majority of Azure services, and includes information to help you use, adapt, or extend the retry mechanism for that service.

Para obter orientação geral sobre o tratamento de falhas transitórias e como repetir conexões e operações em serviços e recursos, consulte Diretriz de repetição.For general guidance on handling transient faults, and retrying connections and operations against services and resources, see Retry guidance.

A tabela a seguir resume os recursos de repetição para os serviços do Azure descritos nesta diretriz.The following table summarizes the retry features for the Azure services described in this guidance.

ServiçoService Recursos de repetiçãoRetry capabilities Configuração de políticaPolicy configuration EscopoScope Recursos de telemetriaTelemetry features
Azure Active DirectoryAzure Active Directory Nativo na biblioteca ADALNative in ADAL library Inserido na biblioteca ADALEmbedded into ADAL library InternaInternal NenhumNone
Cosmos DBCosmos DB Nativo no serviçoNative in service Não configurávelNon-configurable GlobalGlobal TraceSourceTraceSource
Repositório Data LakeData Lake Store Nativo no clienteNative in client Não configurávelNon-configurable Operações individuaisIndividual operations NenhumNone
Hubs de EventosEvent Hubs Nativo no clienteNative in client ProgramáticoProgrammatic ClienteClient NenhumNone
Hub IoTIoT Hub Nativo no cliente SDKNative in client SDK ProgramáticoProgrammatic ClienteClient NenhumNone
Cache Redis do AzureAzure Cache for Redis Nativo no clienteNative in client ProgramáticoProgrammatic ClienteClient TextWriterTextWriter
SearchSearch Nativo no clienteNative in client ProgramáticoProgrammatic ClienteClient ETW ou PersonalizadoETW or Custom
Barramento de ServiçoService Bus Nativo no clienteNative in client ProgramáticoProgrammatic Gerenciador de Namespace, Messaging Factory e ClienteNamespace Manager, Messaging Factory, and Client ETWETW
Service FabricService Fabric Nativo no clienteNative in client ProgramáticoProgrammatic ClienteClient NenhumNone
Banco de dados SQL com ADO.NETSQL Database with ADO.NET PollyPolly Programático e declarativoDeclarative and programmatic Instruções ou blocos de código únicosSingle statements or blocks of code PersonalizadoCustom
Banco de dados SQL com o Entity FrameworkSQL Database with Entity Framework Nativo no clienteNative in client ProgramáticoProgrammatic Global por AppDomainGlobal per AppDomain NenhumNone
Banco de dados SQL com Entity Framework CoreSQL Database with Entity Framework Core Nativo no clienteNative in client ProgramáticoProgrammatic Global por AppDomainGlobal per AppDomain NenhumNone
ArmazenamentoStorage Nativo no clienteNative in client ProgramáticoProgrammatic Operações individuais e de clienteClient and individual operations TraceSourceTraceSource

Observação

Para a maioria dos mecanismos de repetição internos do Azure, atualmente não há meios de aplicar uma política de repetição diferente para diversos tipos de erro ou exceção.For most of the Azure built-in retry mechanisms, there is currently no way apply a different retry policy for different types of error or exception. Você deve configurar uma política que fornece o melhor desempenho médio e disponibilidade.You should configure a policy that provides the optimum average performance and availability. Uma maneira de ajustar a política é analisar arquivos de log para determinar o tipo de falha transitória que está ocorrendo.One way to fine-tune the policy is to analyze log files to determine the type of transient faults that are occurring.

Azure Active DirectoryAzure Active Directory

O Azure Active Directory (Azure AD) é uma solução abrangente de nuvem para gerenciamento de acesso e identidade que combina serviços principais de diretório, governança avançada de identidade, segurança e gerenciamento de acesso a aplicativos.Azure Active Directory (Azure AD) is a comprehensive identity and access management cloud solution that combines core directory services, advanced identity governance, security, and application access management. O AD do Azure também oferece aos desenvolvedores uma plataforma de gerenciamento de identidade para fornecer controle de acesso aos respectivos aplicativos, com base nas regras e políticas centralizadas.Azure AD also offers developers an identity management platform to deliver access control to their applications, based on centralized policy and rules.

Observação

Para obter diretrizes sobre a repetição em pontos de extremidade de identidade de serviço gerenciado, veja como usar uma MSI (Identidade de Serviço Gerenciada) de VM do Azure para aquisição de token.For retry guidance on Managed Service Identity endpoints, see How to use an Azure VM Managed Service Identity (MSI) for token acquisition.

Mecanismo de repetiçãoRetry mechanism

Na Biblioteca de autenticação do Active Directory (ADAL) há um mecanismo interno de repetição para o Azure Active Directory.There is a built-in retry mechanism for Azure Active Directory in the Active Directory Authentication Library (ADAL). Para evitar bloqueios inesperados, recomendamos que as bibliotecas de terceiros e o código do aplicativo não repitam as conexões com falha, mas permitem que a Adal manipule novas tentativas.To avoid unexpected lockouts, we recommend that third-party libraries and application code do not retry failed connections, but allow ADAL to handle retries.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao usar o Azure Active Directory:Consider the following guidelines when using Azure Active Directory:

  • Quando possível, use a biblioteca ADAL e o suporte interno para repetições.When possible, use the ADAL library and the built-in support for retries.
  • Se estiver a usar a API REST do Azure Active Directory, tente novamente a operação se o código de resultado for 429 (Muitos Pedidos) ou for um erro no intervalo 5xx.If you are using the REST API for Azure Active Directory, retry the operation if the result code is 429 (Too Many Requests) or an error in the 5xx range. Não repita para nenhum outro erro.Do not retry for any other errors.
  • Para erros 429, somente repita após o horário indicado no cabeçalho tentar novamente .For 429 errors, only retry after the time indicated in the Retry-After header.
  • Para erros 5xx, use retirada exponencial, com a primeira tentativa, pelo menos, 5 segundos após a resposta.For 5xx errors, use exponential back-off, with the first retry at least 5 seconds after the response.
  • Não tente novamente em caso de erros diferentes de 429 e 5xx.Do not retry on errors other than 429 and 5xx.

Mais informaçõesMore information

Cosmos DBCosmos DB

Cosmos DB é um banco de dados multimodelo totalmente gerenciado que dá suporte a dados JSON sem esquema.Cosmos DB is a fully managed multi-model database that supports schemaless JSON data. Ele oferece desempenho configurável e confiável, processamento transacional nativo JavaScript, além de ser criado para a nuvem com escala elástica.It offers configurable and reliable performance, native JavaScript transactional processing, and is built for the cloud with elastic scale.

Mecanismo de repetiçãoRetry mechanism

A classe DocumentClient repete automaticamente tentativas com falha.The DocumentClient class automatically retries failed attempts. Para definir o número de repetições e o tempo de espera máximo, configure ConnectionPolicy.RetryOptions.To set the number of retries and the maximum wait time, configure ConnectionPolicy.RetryOptions. As exceções que o cliente gera excedem a política de repetição ou não são erros transitórios.Exceptions that the client raises are either beyond the retry policy or are not transient errors.

Se o Cosmos DB limitar o cliente, ele retornará um erro HTTP 429.If Cosmos DB throttles the client, it returns an HTTP 429 error. Confira o código de status no DocumentClientException.Check the status code in the DocumentClientException.

Configuração de políticaPolicy configuration

A tabela a seguir mostra as configurações padrão para a classe RetryOptions.The following table shows the default settings for the RetryOptions class.

ConfiguraçãoSetting Valor padrãoDefault value DescriçãoDescription
MaxRetryAttemptsOnThrottledRequestsMaxRetryAttemptsOnThrottledRequests 99 O número máximo de tentativas se a solicitação falhar porque o Cosmos DB aplicou a limitação de taxa ao cliente.The maximum number of retries if the request fails because Cosmos DB applied rate limiting on the client.
MaxRetryWaitTimeInSecondsMaxRetryWaitTimeInSeconds 3030 O tempo máximo de repetição, em segundos.The maximum retry time in seconds.

ExemploExample

DocumentClient client = new DocumentClient(new Uri(endpoint), authKey);
var options = client.ConnectionPolicy.RetryOptions;
options.MaxRetryAttemptsOnThrottledRequests = 5;
options.MaxRetryWaitTimeInSeconds = 15;

TelemetriaTelemetry

As tentativas de repetição são registradas como mensagens de rastreamento não estruturadas por meio de um TraceSource do .NET.Retry attempts are logged as unstructured trace messages through a .NET TraceSource. Você deve configurar um TraceListener para capturar os eventos e gravá-los em um log de destino apropriado.You must configure a TraceListener to capture the events and write them to a suitable destination log.

Por exemplo, se você adicionar o seguinte ao arquivo App.config, rastreamentos serão gerados em um arquivo de texto no mesmo local que o executável:For example, if you add the following to your App.config file, traces will be generated in a text file in the same location as the executable:

<configuration>
  <system.diagnostics>
    <switches>
      <add name="SourceSwitch" value="Verbose"/>
    </switches>
    <sources>
      <source name="DocDBTrace" switchName="SourceSwitch" switchType="System.Diagnostics.SourceSwitch" >
        <listeners>
          <add name="MyTextListener" type="System.Diagnostics.TextWriterTraceListener" traceOutputOptions="DateTime,ProcessId,ThreadId" initializeData="CosmosDBTrace.txt"></add>
        </listeners>
      </source>
    </sources>
  </system.diagnostics>
</configuration>

Hubs de EventosEvent Hubs

Os hubs de eventos do Azure são um serviço de ingestão de telemetria de hiperescala que coleta, transforma e armazena milhões de eventos.Azure Event Hubs is a hyperscale telemetry ingestion service that collects, transforms, and stores millions of events.

Mecanismo de repetiçãoRetry mechanism

O comportamento de repetição na biblioteca de cliente dos Hubs de Eventos do Azure é controlado pela propriedade RetryPolicy na classe EventHubClient.Retry behavior in the Azure Event Hubs Client Library is controlled by the RetryPolicy property on the EventHubClient class. As tentativas de política padrão com retirada exponencial quando o Hub de eventos do Azure retorna um EventHubsException transitório ou um OperationCanceledException.The default policy retries with exponential backoff when Azure Event Hub returns a transient EventHubsException or an OperationCanceledException. A política de repetição padrão para os hubs de eventos é tentar novamente até 9 vezes com um tempo de retirada exponencial de até 30 segundos.Default retry policy for Event Hubs is to retry up to 9 times with an exponential back-off time of up to 30 seconds .

ExemploExample

EventHubClient client = EventHubClient.CreateFromConnectionString("[event_hub_connection_string]");
client.RetryPolicy = RetryPolicy.Default;

Mais informaçõesMore information

Biblioteca de cliente .NET Standard para os hubs de eventos do Azure.NET Standard client library for Azure Event Hubs

Hub IoTIoT Hub

O Hub IoT do Azure é um serviço para conectar, monitorar e gerenciar dispositivos para desenvolver aplicativos IoT (Internet das Coisas).Azure IoT Hub is a service for connecting, monitoring, and managing devices to develop Internet of Things (IoT) applications.

Mecanismo de repetiçãoRetry mechanism

O SDK do dispositivo IoT do Azure pode detectar erros na rede, protocolo ou aplicativo.The Azure IoT device SDK can detect errors in the network, protocol, or application. Com base no tipo de erro, o SDK verifica se uma nova tentativa deve ser executada.Based on the error type, the SDK checks whether a retry needs to be performed. Se o erro for recuperável, o SDK tentará novamente usando a política de repetição configurada.If the error is recoverable, the SDK begins to retry using the configured retry policy.

A política de repetição padrão é uma retirada exponencial com variação aleatória, mas ela pode ser configurada.The default retry policy is exponential back-off with random jitter, but it can be configured.

Configuração de políticaPolicy configuration

A configuração de política varia segundo o idioma.Policy configuration differs by language. Para obter mais detalhes, consulte Configuração da política de repetição do Hub IoT.For more details, see IoT Hub retry policy configuration.

Mais informaçõesMore information

Cache Redis do AzureAzure Cache for Redis

O cache do Azure para Redis é um serviço de cache de baixa latência e acesso a dados rápido com base no popular cache Redis de software livre.Azure Cache for Redis is a fast data access and low latency cache service based on the popular open-source Redis cache. Ele é seguro, gerenciado pela Microsoft e pode ser acessado de qualquer aplicativo no Azure.It is secure, managed by Microsoft, and is accessible from any application in Azure.

A diretriz nesta seção se baseia em como usar o cliente StackExchange.Redis para acessar o cache.The guidance in this section is based on using the StackExchange.Redis client to access the cache. Uma lista de outros clientes adequados pode ser encontrada no site do Redis, e eles podem ter mecanismos de repetição diferentes.A list of other suitable clients can be found on the Redis website, and these may have different retry mechanisms.

Observe que o cliente StackExchange.Redis usa multiplexação por meio de uma única conexão.Note that the StackExchange.Redis client uses multiplexing through a single connection. O uso recomendado é criar uma instância do cliente na inicialização do aplicativo e usar essa instância para todas as operações no cache.The recommended usage is to create an instance of the client at application startup and use this instance for all operations against the cache. Por esse motivo, a conexão com o cache é feita apenas uma vez e, portanto, todas as diretrizes desta seção estão relacionadas à política de repetição para essa conexão inicial — e não a cada operação que acessa o cache.For this reason, the connection to the cache is made only once, and so all of the guidance in this section is related to the retry policy for this initial connection—and not for each operation that accesses the cache.

Mecanismo de repetiçãoRetry mechanism

O cliente StackExchange.Redis usa uma classe de gerenciador de conexões que é configurada por meio de um conjunto de opções, incluindo:The StackExchange.Redis client uses a connection manager class that is configured through a set of options, including:

  • ConnectRetry.ConnectRetry. O número de vezes que uma conexão com falha para o cache será repetida.The number of times a failed connection to the cache will be retried.
  • ReconnectRetryPolicy.ReconnectRetryPolicy. Usar qual estratégia de repetição.The retry strategy to use.
  • ConnectTimeout.ConnectTimeout. O tempo máximo de espera em milissegundos.The maximum waiting time in milliseconds.

Configuração de políticaPolicy configuration

As políticas de repetição são configuradas de modo programático, definindo as opções para o cliente antes de se conectar ao cache.Retry policies are configured programmatically by setting the options for the client before connecting to the cache. Isso pode ser feito criando uma instância da classe ConfigurationOptions, populando suas propriedades e passando-a para o método Connect.This can be done by creating an instance of the ConfigurationOptions class, populating its properties, and passing it to the Connect method.

As classes internas suportam atraso linear (constante) e retirada exponencial com intervalos de repetição aleatórios.The built-in classes support linear (constant) delay and exponential backoff with randomized retry intervals. Você também pode criar uma política de repetição personalizada se implementar a interface IReconnectRetryPolicy.You can also create a custom retry policy by implementing the IReconnectRetryPolicy interface.

O exemplo a seguir configura uma estratégia de repetição com retirada exponencial.The following example configures a retry strategy using exponential backoff.

var deltaBackOffInMilliseconds = TimeSpan.FromSeconds(5).Milliseconds;
var maxDeltaBackOffInMilliseconds = TimeSpan.FromSeconds(20).Milliseconds;
var options = new ConfigurationOptions
{
    EndPoints = {"localhost"},
    ConnectRetry = 3,
    ReconnectRetryPolicy = new ExponentialRetry(deltaBackOffInMilliseconds, maxDeltaBackOffInMilliseconds),
    ConnectTimeout = 2000
};
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

Como alternativa, você pode especificar as opções como uma cadeia de caracteres e passá-la ao método Connect.Alternatively, you can specify the options as a string, and pass this to the Connect method. A propriedade ReconnectRetryPolicy não pode ser definida dessa forma, somente por meio de código.The ReconnectRetryPolicy property cannot be set this way, only through code.

var options = "localhost,connectRetry=3,connectTimeout=2000";
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

Também é possível especificar opções diretamente ao se conectar ao cache.You can also specify options directly when you connect to the cache.

var conn = ConnectionMultiplexer.Connect("redis0:6380,redis1:6380,connectRetry=3");

Para obter mais informações, confira Configuração do Stack Exchange Redis na documentação do StackExchange.Redis.For more information, see Stack Exchange Redis Configuration in the StackExchange.Redis documentation.

A tabela a seguir mostra as configurações padrão da política de repetição interna.The following table shows the default settings for the built-in retry policy.

ContextoContext ConfiguraçãoSetting Valor padrãoDefault value
(v 1.2.2)(v 1.2.2)
SignificadoMeaning
ConfigurationOptionsConfigurationOptions ConnectRetryConnectRetry

ConnectTimeoutConnectTimeout

SyncTimeoutSyncTimeout

ReconnectRetryPolicyReconnectRetryPolicy
33

Máximo de 5000 ms mais SyncTimeoutMaximum 5000 ms plus SyncTimeout
10001000

LinearRetry 5.000 msLinearRetry 5000 ms
O número de vezes para repetir tentativas de conexão durante a operação de conexão inicial.The number of times to repeat connect attempts during the initial connection operation.
Tempo limite (ms) para operações de conexão.Timeout (ms) for connect operations. Não é um intervalo entre tentativas de repetição.Not a delay between retry attempts.
Tempo (ms) para permitir operações síncronas.Time (ms) to allow for synchronous operations.

Repita a cada 5.000 ms.Retry every 5000 ms.

Observação

Em operações síncronas, SyncTimeout pode adicionar à latência de ponta a ponta, porém definir o valor muito baixo pode causar tempos limite excessivos.For synchronous operations, SyncTimeout can add to the end-to-end latency, but setting the value too low can cause excessive timeouts. Consulte como solucionar problemas do cache do Azure para Redis.See How to troubleshoot Azure Cache for Redis. Em geral, evite usar operações síncronas e use operações assíncronas.In general, avoid using synchronous operations, and use asynchronous operations instead. Para obter mais informações, consulte pipelines e multiplexadores.For more information, see Pipelines and Multiplexers.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao usar o cache do Azure para Redis:Consider the following guidelines when using Azure Cache for Redis:

  • O cliente StackExchange Redis gerencia suas próprias repetições, mas apenas ao estabelecer uma conexão com o cache quando o aplicativo é iniciado pela primeira vez.The StackExchange Redis client manages its own retries, but only when establishing a connection to the cache when the application first starts. Você pode configurar o tempo limite da conexão, o número de repetições e o intervalo entre as repetições para estabelecer esta conexão, porém a política de repetições não se aplica a operações contra o cache.You can configure the connection timeout, the number of retry attempts, and the time between retries to establish this connection, but the retry policy does not apply to operations against the cache.
  • Em vez de usar um grande número de tentativas de repetição, considere fazer fallback acessando a fonte de dados original.Instead of using a large number of retry attempts, consider falling back by accessing the original data source instead.

TelemetriaTelemetry

Você pode coletar informações sobre conexões (mas não outras operações) usando um TextWriter.You can collect information about connections (but not other operations) using a TextWriter.

var writer = new StringWriter();
ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

Um exemplo da saída que isso gera é mostrado abaixo.An example of the output this generates is shown below.

localhost:6379,connectTimeout=2000,connectRetry=3
1 unique nodes specified
Requesting tie-break from localhost:6379 > __Booksleeve_TieBreak...
Allowing endpoints 00:00:02 to respond...
localhost:6379 faulted: SocketFailure on PING
localhost:6379 failed to nominate (Faulted)
> UnableToResolvePhysicalConnection on GET
No masters detected
localhost:6379: Standalone v2.0.0, master; keep-alive: 00:01:00; int: Connecting; sub: Connecting; not in use: DidNotRespond
localhost:6379: int ops=0, qu=0, qs=0, qc=1, wr=0, sync=1, socks=2; sub ops=0, qu=0, qs=0, qc=0, wr=0, socks=2
Circular op-count snapshot; int: 0 (0.00 ops/s; spans 10s); sub: 0 (0.00 ops/s; spans 10s)
Sync timeouts: 0; fire and forget: 0; last heartbeat: -1s ago
resetting failing connections to retry...
retrying; attempts left: 2...
...

ExemplosExamples

O exemplo de código a seguir configura um atraso constante (linear) entre as repetições ao inicializar o cliente StackExchange.Redis.The following code example configures a constant (linear) delay between retries when initializing the StackExchange.Redis client. Este exemplo mostra como definir a configuração usando uma instância de ConfigurationOptions.This example shows how to set the configuration using a ConfigurationOptions instance.

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using StackExchange.Redis;

namespace RetryCodeSamples
{
    class CacheRedisCodeSamples
    {
        public async static Task Samples()
        {
            var writer = new StringWriter();
            {
                try
                {
                    var retryTimeInMilliseconds = TimeSpan.FromSeconds(4).Milliseconds; // delay between retries

                    // Using object-based configuration.
                    var options = new ConfigurationOptions
                                        {
                                            EndPoints = { "localhost" },
                                            ConnectRetry = 3,
                                            ReconnectRetryPolicy = new LinearRetry(retryTimeInMilliseconds)
                                        };
                    ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

                    // Store a reference to the multiplexer for use in the application.
                }
                catch
                {
                    Console.WriteLine(writer.ToString());
                    throw;
                }
            }
        }
    }
}

Este exemplo mostra como definir a configuração especificando as opções como uma cadeia de caracteres.The next example sets the configuration by specifying the options as a string. O tempo limite da conexão é o período máximo de espera por uma conexão para o cache, não o atraso entre tentativas de repetição.The connection timeout is the maximum period of time to wait for a connection to the cache, not the delay between retry attempts. Observe que a propriedade ReconnectRetryPolicy só pode ser definida por código.Note that the ReconnectRetryPolicy property can only be set by code.

using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using StackExchange.Redis;

namespace RetryCodeSamples
{
    class CacheRedisCodeSamples
    {
        public async static Task Samples()
        {
            var writer = new StringWriter();
            {
                try
                {
                    // Using string-based configuration.
                    var options = "localhost,connectRetry=3,connectTimeout=2000";
                    ConnectionMultiplexer redis = ConnectionMultiplexer.Connect(options, writer);

                    // Store a reference to the multiplexer for use in the application.
                }
                catch
                {
                    Console.WriteLine(writer.ToString());
                    throw;
                }
            }
        }
    }
}

Para obter mais exemplos, consulte Configuração no site do projeto.For more examples, see Configuration on the project website.

Mais informaçõesMore information

O Azure Search pode ser usada para adicionar recursos potentes e sofisticados a um site ou aplicativo, ajustar os resultados da pesquisa de maneira rápida e fácil, bem como construir modelos de classificação avançados e ajustados.Azure Search can be used to add powerful and sophisticated search capabilities to a website or application, quickly and easily tune search results, and construct rich and fine-tuned ranking models.

Mecanismo de repetiçãoRetry mechanism

O comportamento de repetição no SDK do Azure Search é controlado pelo método SetRetryPolicy nas classes SearchServiceClient e SearchIndexClient.Retry behavior in the Azure Search SDK is controlled by the SetRetryPolicy method on the SearchServiceClient and SearchIndexClient classes. A política padrão tenta novamente com retirada exponencial quando o Azure Search retorna uma resposta 5xx ou 408 (Tempo Limite da Solicitação).The default policy retries with exponential backoff when Azure Search returns a 5xx or 408 (Request Timeout) response.

TelemetriaTelemetry

Rastreamento com o ETW ou por meio de registro de um provedor de rastreamento personalizado.Trace with ETW or by registering a custom trace provider. Para obter mais informações, confira Documentação do AutoRest.For more information, see the AutoRest documentation.

Barramento de ServiçoService Bus

O Barramento de Serviço é uma plataforma de mensagens na nuvem que fornece troca de mensagens flexivelmente acoplada com escala e resiliência melhoradas para componentes de um aplicativo, se hospedado na nuvem ou no local.Service Bus is a cloud messaging platform that provides loosely coupled message exchange with improved scale and resiliency for components of an application, whether hosted in the cloud or on-premises.

Mecanismo de repetiçãoRetry mechanism

O barramento de serviço implementa repetições usando implementações da classe abstrata RetryPolicy .Service Bus implements retries using implementations of the abstract RetryPolicy class. O namespace e alguns dos detalhes de configuração dependem de qual pacote SDK do cliente do barramento de serviço é usado:The namespace and some of the configuration details depend on which Service Bus client SDK package is used:

PacotePackage DescriçãoDescription NamespaceNamespace
Microsoft. Azure. ServiceBusMicrosoft.Azure.ServiceBus Biblioteca de cliente do barramento de serviço do Azure para .NET Standard.Azure Service Bus client library for .NET Standard. Microsoft.ServiceBus
WindowsAzure.ServiceBusWindowsAzure.ServiceBus Este pacote é a biblioteca de cliente mais antiga do barramento de serviço.This package is the older Service Bus client library. Ele requer o .NET Framework 4.5.2.It requires .Net Framework 4.5.2. Microsoft.Azure.ServiceBus

Ambas as versões da biblioteca de cliente fornecem as seguintes implementações internas do RetryPolicy :Both versions of the client library provide the following built-in implementations of RetryPolicy:

  • RetryExponential.RetryExponential. Implementa retirada exponencial.Implements exponential backoff.

  • Sem repetição.NoRetry. Não executa repetições.Does not perform retries. Use essa classe quando não precisar de novas tentativas no nível da API do barramento de serviço, por exemplo, quando outro processo gerencia novas tentativas como parte de uma operação de lote ou de várias etapas.Use this class when you don't need retries at the Service Bus API level, for example when another process manages retries as part of a batch or multistep operation.

A RetryPolicy.Default propriedade retorna uma política padrão do tipo RetryExponential .The RetryPolicy.Default property returns a default policy of type RetryExponential. Este objeto de política tem as seguintes configurações:This policy object has the following settings:

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
MinimalBackoffMinimalBackoff 00 O intervalo mínimo de retirada.Minimum back-off interval. Adicionado ao intervalo de repetição computado de deltaBackoff .Added to the retry interval computed from deltaBackoff.
MaximumBackoffMaximumBackoff 30 segundos30 seconds O intervalo máximo de retirada.Maximum back-off interval.
DeltaBackoffDeltaBackoff 3 Segundos3 seconds Intervalo de retirada entre repetições.Back-off interval between retries. Múltiplos desse TimeSpan são usados para tentativas de repetição subsequentes.Multiples of this timespan are used for subsequent retry attempts.
MaxRetryCountMaxRetryCount 55 O número máximo de repetições.The maximum number of retries. (O valor padrão é 10 no WindowsAzure.ServiceBus pacote.)(Default value is 10 in the WindowsAzure.ServiceBus package.)

Além disso, a seguinte propriedade é definida no pacote mais antigo WindowsAzure.ServiceBus :In addition, the following property is defined in the older WindowsAzure.ServiceBus package:

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
TerminationTimeBufferTerminationTimeBuffer 5 segundos5 seconds As tentativas de repetição serão abandonadas se o tempo restante for menor que esse valor.Retry attempts will be abandoned if the remaining time is less than this value.

As ações do barramento de serviço podem retornar um intervalo de exceções, listado em exceções de mensagens do barramento de serviço.Service Bus actions can return a range of exceptions, listed in Service Bus messaging exceptions. As exceções retornadas do barramento de serviço expõem a propriedade istransitória que indica se o cliente deve repetir a operação.Exceptions returned from Service Bus expose the IsTransient property that indicates whether the client should retry the operation. A política interna RetryExponential verifica essa propriedade antes de tentar novamente.The built-in RetryExponential policy checks this property before retrying.

Se a última exceção encontrada for ServerBusyException, a política RetryExponential adicionará 10 segundos ao intervalo de repetição computado.If the last exception encountered was ServerBusyException, the RetryExponential policy adds 10 seconds to the computed retry interval. Esse valor não pode ser alterado.This value cannot be changed.

Implementações personalizadas podem usar uma combinação do tipo de exceção e da propriedade istransitória para fornecer controle mais refinado sobre as ações de repetição.Custom implementations could use a combination of the exception type and the IsTransient property to provide more fine-grained control over retry actions. Por exemplo, é possível detectar um QuotaExceededException e tomar providências para diminuir a fila antes de tentar enviar novamente uma mensagem para ela.For example, you could detect a QuotaExceededException and take action to drain the queue before retrying sending a message to it.

O código a seguir define a política de repetição em um cliente do barramento de serviço usando a Microsoft.Azure.ServiceBus biblioteca:The following code sets the retry policy on a Service Bus client using the Microsoft.Azure.ServiceBus library:

const string QueueName = "queue1";
const string ServiceBusConnectionString = "<your_connection_string>";

var policy = new RetryExponential(
    minimumBackoff: TimeSpan.FromSeconds(10),
    maximumBackoff: TimeSpan.FromSeconds(30),
    maximumRetryCount: 3);
var queueClient = new QueueClient(ServiceBusConnectionString, QueueName, ReceiveMode.PeekLock, policy);

A política de repetição não pode ser definida no nível de operação individual.The retry policy cannot be set at the individual operation level. Ele se aplica a todas as operações do cliente.It applies to all operations for the client.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao usar o Barramento de Serviço:Consider the following guidelines when using Service Bus:

  • Ao usar a implementação RetryExponential interna, não implemente uma operação de fallback, pois a política reage às exceções de Servidor Ocupado e alterna automaticamente para um modo de repetição apropriado.When using the built-in RetryExponential implementation, do not implement a fallback operation as the policy reacts to Server Busy exceptions and automatically switches to an appropriate retry mode.
  • O barramento de serviço dá suporte a um recurso chamado namespaces emparelhados que implementa o failover automático para uma fila de backup em um namespace separado se a fila no namespace primário falhar.Service Bus supports a feature called Paired Namespaces that implements automatic failover to a backup queue in a separate namespace if the queue in the primary namespace fails. As mensagens da fila secundária podem ser enviadas de volta para a fila primária quando esta se recuperar.Messages from the secondary queue can be sent back to the primary queue when it recovers. Esse recurso ajuda a corrigir falhas transitórias.This feature helps to address transient failures. Para saber mais, consulte Padrões de mensagens assíncronas e alta disponibilidade.For more information, see Asynchronous Messaging Patterns and High Availability.

Considere começar com as seguintes configurações para operações de repetição.Consider starting with the following settings for retrying operations. Essas configurações são de finalidade geral e você deve monitorar as operações e ajustar os valores para se adequar a seu próprio cenário.These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

ContextoContext Exemplo de latência máximaExample maximum latency Política de RepetiçãoRetry policy ConfiguraçõesSettings Como ele funcionaHow it works
Interativo, interface do usuário ou primeiro planoInteractive, UI, or foreground 2 segundos*2 seconds* ExponencialExponential MinimumBackoff = 0MinimumBackoff = 0
MaximumBackoff = 30 sMaximumBackoff = 30 sec.
DeltaBackoff = 300 msDeltaBackoff = 300 msec.
TimeBuffer = 300 msTimeBuffer = 300 msec.
MaxRetryCount = 2MaxRetryCount = 2
1ª tentativa: atraso 0 sAttempt 1: Delay 0 sec.
2ª tentativa: atraso ~300 msAttempt 2: Delay ~300 msec.
3ª tentativa: atraso ~900 msAttempt 3: Delay ~900 msec.
Segundo plano ou loteBackground or batch 30 segundos30 seconds ExponencialExponential MinimumBackoff = 1MinimumBackoff = 1
MaximumBackoff = 30 sMaximumBackoff = 30 sec.
DeltaBackoff = 1,75 seg.DeltaBackoff = 1.75 sec.
TimeBuffer = 5 seg.TimeBuffer = 5 sec.
MaxRetryCount = 3MaxRetryCount = 3
1ª tentativa: atraso de ~1 sAttempt 1: Delay ~1 sec.
2ª tentativa: atraso de ~3 sAttempt 2: Delay ~3 sec.
3ª tentativa: atraso ~6 msAttempt 3: Delay ~6 msec.
4ª tentativa: atraso ~13 msAttempt 4: Delay ~13 msec.

*Não incluindo atraso que será adicionado se uma resposta Servidor Ocupado for recebida.* Not including additional delay that is added if a Server Busy response is received.

TelemetriaTelemetry

O Barramento de Serviço registra as repetições como eventos ETW usando um EventSource.Service Bus logs retries as ETW events using an EventSource. Você deve anexar um EventListener à origem do evento para capturar os eventos e exibi-los no Visualizador de Desempenho ou gravá-los em um log de destino apropriado.You must attach an EventListener to the event source to capture the events and view them in Performance Viewer, or write them to a suitable destination log. Os eventos de repetição são da seguinte forma:The retry events are of the following form:

Microsoft-ServiceBus-Client/RetryPolicyIteration
ThreadID="14,500"
FormattedMessage="[TrackingId:] RetryExponential: Operation Get:https://retry-tests.servicebus.windows.net/TestQueue/?api-version=2014-05 at iteration 0 is retrying after 00:00:00.1000000 sleep because of Microsoft.ServiceBus.Messaging.MessagingCommunicationException: The remote name could not be resolved: 'retry-tests.servicebus.windows.net'.TrackingId:6a26f99c-dc6d-422e-8565-f89fdd0d4fe3, TimeStamp:9/5/2014 10:00:13 PM."
trackingId=""
policyType="RetryExponential"
operation="Get:https://retry-tests.servicebus.windows.net/TestQueue/?api-version=2014-05"
iteration="0"
iterationSleep="00:00:00.1000000"
lastExceptionType="Microsoft.ServiceBus.Messaging.MessagingCommunicationException"
exceptionMessage="The remote name could not be resolved: 'retry-tests.servicebus.windows.net'.TrackingId:6a26f99c-dc6d-422e-8565-f89fdd0d4fe3,TimeStamp:9/5/2014 10:00:13 PM"

ExemplosExamples

O código de exemplo a seguir mostra como definir a política de repetição para:The following code example shows how to set the retry policy for:

  • Um gerenciador de namespaces.A namespace manager. A política se aplica a todas as operações nesse gerenciador e não pode ser substituída para operações individuais.The policy applies to all operations on that manager, and cannot be overridden for individual operations.
  • Uma fábrica de mensagens.A messaging factory. A política se aplica a todos os clientes criados nessa fábrica e não pode ser substituída durante a criação de clientes individuais.The policy applies to all clients created from that factory, and cannot be overridden when creating individual clients.
  • Um cliente de mensagens individual.An individual messaging client. Depois que um cliente tiver sido criado, você poderá definir a política de repetição para esse cliente.After a client has been created, you can set the retry policy for that client. A política se aplica a todas as operações nesse cliente.The policy applies to all operations on that client.
using System;
using System.Threading.Tasks;
using Microsoft.ServiceBus;
using Microsoft.ServiceBus.Messaging;

namespace RetryCodeSamples
{
    class ServiceBusCodeSamples
    {
        private const string connectionString =
            @"Endpoint=sb://[my-namespace].servicebus.windows.net/;
                SharedAccessKeyName=RootManageSharedAccessKey;
                SharedAccessKey=C99..........Mk=";

        public async static Task Samples()
        {
            const string QueueName = "TestQueue";

            ServiceBusEnvironment.SystemConnectivity.Mode = ConnectivityMode.Http;

            var namespaceManager = NamespaceManager.CreateFromConnectionString(connectionString);

            // The namespace manager will have a default exponential policy with 10 retry attempts
            // and a 3 second delay delta.
            // Retry delays will be approximately 0 sec, 3 sec, 9 sec, 25 sec and the fixed 30 sec,
            // with an extra 10 sec added when receiving a ServiceBusyException.

            {
                // Set different values for the retry policy, used for all operations on the namespace manager.
                namespaceManager.Settings.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(0),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);

                // Policies cannot be specified on a per-operation basis.
                if (!await namespaceManager.QueueExistsAsync(QueueName))
                {
                    await namespaceManager.CreateQueueAsync(QueueName);
                }
            }

            var messagingFactory = MessagingFactory.Create(
                namespaceManager.Address, namespaceManager.Settings.TokenProvider);
            // The messaging factory will have a default exponential policy with 10 retry attempts
            // and a 3 second delay delta.
            // Retry delays will be approximately 0 sec, 3 sec, 9 sec, 25 sec and the fixed 30 sec,
            // with an extra 10 sec added when receiving a ServiceBusyException.

            {
                // Set different values for the retry policy, used for clients created from it.
                messagingFactory.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(1),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);


                // Policies cannot be specified on a per-operation basis.
                var session = await messagingFactory.AcceptMessageSessionAsync();
            }

            {
                var client = messagingFactory.CreateQueueClient(QueueName);
                // The client inherits the policy from the factory that created it.


                // Set different values for the retry policy on the client.
                client.RetryPolicy =
                    new RetryExponential(
                        minBackoff: TimeSpan.FromSeconds(0.1),
                        maxBackoff: TimeSpan.FromSeconds(30),
                        maxRetryCount: 3);

                // Policies cannot be specified on a per-operation basis.
                var session = await client.AcceptMessageSessionAsync();
            }
        }
    }
}

Mais informaçõesMore information

Service FabricService Fabric

Distribuir serviços confiáveis em um cluster do Service Fabric protege contra a maioria das falhas transitórias potenciais discutidas neste artigo.Distributing reliable services in a Service Fabric cluster guards against most of the potential transient faults discussed in this article. No entanto, algumas falhas transitórias ainda podem acontecer.Some transient faults are still possible, however. Por exemplo, se o serviço de nomeação recebe uma solicitação no meio de uma alteração de roteamento, ele pode lançar uma exceção.For example, the naming service might be in the middle of a routing change when it gets a request, causing it to throw an exception. No entanto, se a mesma solicitação vier 100 milissegundos mais tarde, ela provavelmente terá êxito.If the same request comes 100 milliseconds later, it will probably succeed.

Internamente, o Service Fabric gerencia esse tipo de falha transitória.Internally, Service Fabric manages this kind of transient fault. Você pode definir algumas configurações usando a classe OperationRetrySettings ao configurar seus serviços.You can configure some settings by using the OperationRetrySettings class while setting up your services. O código a seguir mostra um exemplo.The following code shows an example. Na maioria dos casos, isso não deve ser necessário e as configurações padrão são suficientes.In most cases, this should not be necessary, and the default settings will be fine.

FabricTransportRemotingSettings transportSettings = new FabricTransportRemotingSettings
{
    OperationTimeout = TimeSpan.FromSeconds(30)
};

var retrySettings = new OperationRetrySettings(TimeSpan.FromSeconds(15), TimeSpan.FromSeconds(1), 5);

var clientFactory = new FabricTransportServiceRemotingClientFactory(transportSettings);

var serviceProxyFactory = new ServiceProxyFactory((c) => clientFactory, retrySettings);

var client = serviceProxyFactory.CreateServiceProxy<ISomeService>(
    new Uri("fabric:/SomeApp/SomeStatefulReliableService"),
    new ServicePartitionKey(0));

Mais informaçõesMore information

Banco de Dados SQL usando o ADO.NETSQL Database using ADO.NET

O Banco de Dados SQL é um banco de dados SQL disponível em vários tamanhos e como um serviço padrão (compartilhado) e premium (não compartilhado).SQL Database is a hosted SQL database available in a range of sizes and as both a standard (shared) and premium (non-shared) service.

Mecanismo de repetiçãoRetry mechanism

O Banco de Dados SQL não tem suporte interno para repetições quando acessado usando o ADO.NET.SQL Database has no built-in support for retries when accessed using ADO.NET. No entanto, os códigos de retorno das solicitações podem ser usados para determinar por que uma solicitação falhou.However, the return codes from requests can be used to determine why a request failed. Para obter mais informações sobre a limitação do banco de dados SQL, confira Limites de recursos do banco de dados SQL do Azure.For more information about SQL Database throttling, see Azure SQL Database resource limits. Para obter uma lista de códigos de erro relevantes, consulte códigos de erro do SQL para aplicativos cliente do banco de dados SQL.For a list of relevant error codes, see SQL error codes for SQL Database client applications.

Você pode usar a biblioteca Polly para implementar tentativas para o banco de dados SQL.You can use the Polly library to implement retries for SQL Database. Confira Falha transitória manipulando com a Polly.See Transient fault handling with Polly.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao acessar o Banco de Dados SQL usando o ADO.NET:Consider the following guidelines when accessing SQL Database using ADO.NET:

  • Escolha a opção de serviço apropriada (compartilhada ou premium).Choose the appropriate service option (shared or premium). Uma instância compartilhada pode sofrer atrasos e limitação de conexão mais longos que o normal devido ao uso por outros locatários do servidor compartilhado.A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. Se forem necessárias mais operações confiáveis de baixa latência e desempenho previsível, considere a escolha da opção premium.If more predictable performance and reliable low latency operations are required, consider choosing the premium option.
  • Garanta a execução de repetições no nível ou escopo apropriado para evitar operações não idempotentes que causem inconsistência nos dados.Ensure that you perform retries at the appropriate level or scope to avoid non-idempotent operations causing inconsistency in the data. De modo ideal, todas as operações devem ser idempotentes para que possam ser repetidas sem causar inconsistência.Ideally, all operations should be idempotent so that they can be repeated without causing inconsistency. Quando não for esse o caso, a repetição deverá ser realizada em um nível ou escopo que permita que todas as alterações relacionadas sejam desfeitas, caso uma operação falhe; por exemplo, em um escopo transacional.Where this is not the case, the retry should be performed at a level or scope that allows all related changes to be undone if one operation fails; for example, from within a transactional scope. Para saber mais, consulte Camada de acesso a dados dos conceitos básicos do serviço de nuvem — tratamento de falhas transitórias.For more information, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • Uma estratégia de intervalo fixo não é recomendada para uso com o Banco de Dados SQL do Azure, exceto em cenários interativos em que há apenas algumas repetições em intervalos muito curtos.A fixed interval strategy is not recommended for use with Azure SQL Database except for interactive scenarios where there are only a few retries at very short intervals. Em vez disso, considere usar uma estratégia de retirada exponencial para a maioria dos cenários.Instead, consider using an exponential back-off strategy for the majority of scenarios.
  • Escolha um valor adequado para os tempos limite de conexão e comando ao definir conexões.Choose a suitable value for the connection and command timeouts when defining connections. Um tempo limite muito curto pode resultar em falhas prematuras de conexões quando o banco de dados estiver ocupado.Too short a timeout may result in premature failures of connections when the database is busy. Um tempo limite muito longo pode impedir que a lógica de repetição funcione corretamente, aguardando tempo demais para detectar uma conexão com falha.Too long a timeout may prevent the retry logic working correctly by waiting too long before detecting a failed connection. O valor do tempo limite é um componente da latência de ponta a ponta; ele é efetivamente adicionado ao intervalo de repetição especificado na política de repetição para cada tentativa de repetição.The value of the timeout is a component of the end-to-end latency; it is effectively added to the retry delay specified in the retry policy for every retry attempt.
  • Feche a conexão após um determinado número de repetições, mesmo ao usar uma lógica de repetição de retirada exponencial, e repita a operação em uma nova conexão.Close the connection after a certain number of retries, even when using an exponential back off retry logic, and retry the operation on a new connection. Repetir a mesma operação várias vezes na mesma conexão pode ser um fator que contribui para problemas de conexão.Retrying the same operation multiple times on the same connection can be a factor that contributes to connection problems. Para obter um exemplo dessa técnica, consulte Camada de acesso a dados dos conceitos básicos do serviço de nuvem — tratamento de falhas transitórias.For an example of this technique, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • Quando o pool de conexões está em uso (o padrão), é provável que a mesma conexão seja escolhida no pool, mesmo depois de fechar e reabrir uma conexão.When connection pooling is in use (the default) there is a chance that the same connection will be chosen from the pool, even after closing and reopening a connection. Se for esse o caso, uma técnica para resolver isso é chamar o método ClearPool da classe SqlConnection para marcar a conexão como não reutilizável.If this is the case, a technique to resolve it is to call the ClearPool method of the SqlConnection class to mark the connection as not reusable. No entanto, isso deve ser feito somente depois que várias tentativas de conexão tiverem falhado, e somente ao encontrar a classe específica de falhas transitórias, como tempos limite de SQL (código de erro -2), relacionada às conexões com falha.However, you should do this only after several connection attempts have failed, and only when encountering the specific class of transient failures such as SQL timeouts (error code -2) related to faulty connections.
  • Se o código de acesso a dados usar transações iniciadas como instâncias TransactionScope , a lógica de repetição deverá reabrir a conexão e iniciar um novo escopo de transação.If the data access code uses transactions initiated as TransactionScope instances, the retry logic should reopen the connection and initiate a new transaction scope. Por esse motivo, o bloco de código com nova tentativa deve englobar o escopo inteiro da transação.For this reason, the retryable code block should encompass the entire scope of the transaction.

Considere começar com as seguintes configurações para operações de repetição.Consider starting with the following settings for retrying operations. Essas configurações são de finalidade geral e você deve monitorar as operações e ajustar os valores para se adequar a seu próprio cenário.These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

ContextoContext Exemplo de latênciaE2E
máxima de destino
Sample target E2E
max latency
Estratégia de repetiçãoRetry strategy ConfiguraçõesSettings ValoresValues Como ele funcionaHow it works
Interativo, interface de usuárioInteractive, UI,
ou primeiro planoor foreground
2 s2 sec FixedIntervalFixedInterval Contagem de repetiçãoRetry count
Intervalo de repetiçãoRetry interval
Primeira repetição rápidaFirst fast retry
33
500 ms500 ms
truetrue
1ª tentativa — intervalo de 0 sAttempt 1 - delay 0 sec
2ª tentativa — intervalo de 500 msAttempt 2 - delay 500 ms
3ª tentativa — intervalo de 500 msAttempt 3 - delay 500 ms
Tela de fundoBackground
ou loteor batch
30 s30 sec ExponentialBackoffExponentialBackoff Contagem de repetiçãoRetry count
Retirada mín.Min back-off
Retirada máx.Max back-off
Retirada deltaDelta back-off
Primeira repetição rápidaFirst fast retry
55
0 s0 sec
60 s60 sec
2 s2 sec
falsefalse
1ª tentativa — intervalo de 0 sAttempt 1 - delay 0 sec
2ª tentativa — intervalo de ~2 sAttempt 2 - delay ~2 sec
3ª tentativa — intervalo de ~6 sAttempt 3 - delay ~6 sec
4ª tentativa — intervalo de ~14 sAttempt 4 - delay ~14 sec
5ª tentativa — intervalo de ~30 sAttempt 5 - delay ~30 sec

Observação

A latência de ponta a ponta visa o tempo limite padrão de conexões com o serviço.The end-to-end latency targets assume the default timeout for connections to the service. Se você especificar tempos limite de conexão mais longos, a latência de ponta a ponta será estendida por esse tempo adicional para cada tentativa de repetição.If you specify longer connection timeouts, the end-to-end latency will be extended by this additional time for every retry attempt.

ExemplosExamples

Esta seção mostra como você pode usar a Polly para acessar o banco de dados SQL do Azure usando um conjunto de políticas de repetição configurado na classe Policy.This section shows how you can use Polly to access Azure SQL Database using a set of retry policies configured in the Policy class.

O código a seguir mostra um método de extensão na classe SqlCommand que chama ExecuteAsync com retirada exponencial.The following code shows an extension method on the SqlCommand class that calls ExecuteAsync with exponential backoff.

public async static Task<SqlDataReader> ExecuteReaderWithRetryAsync(this SqlCommand command)
{
    GuardConnectionIsNotNull(command);

    var policy = Policy.Handle<Exception>().WaitAndRetryAsync(
        retryCount: 3, // Retry 3 times
        sleepDurationProvider: attempt => TimeSpan.FromMilliseconds(200 * Math.Pow(2, attempt - 1)), // Exponential backoff based on an initial 200 ms delay.
        onRetry: (exception, attempt) =>
        {
            // Capture some information for logging/telemetry.
            logger.LogWarn($"ExecuteReaderWithRetryAsync: Retry {attempt} due to {exception}.");
        });

    // Retry the following call according to the policy.
    await policy.ExecuteAsync<SqlDataReader>(async token =>
    {
        // This code is executed within the Policy

        if (conn.State != System.Data.ConnectionState.Open) await conn.OpenAsync(token);
        return await command.ExecuteReaderAsync(System.Data.CommandBehavior.Default, token);

    }, cancellationToken);
}

Esse método de extensão assíncrono pode ser usado da seguinte maneira.This asynchronous extension method can be used as follows.

var sqlCommand = sqlConnection.CreateCommand();
sqlCommand.CommandText = "[some query]";

using (var reader = await sqlCommand.ExecuteReaderWithRetryAsync())
{
    // Do something with the values
}

Mais informaçõesMore information

Para orientação geral sobre como obter o máximo do banco de dados SQL, confira Desempenho do Banco de Dados SQL do Azure e guia de elasticidade.For general guidance on getting the most from SQL Database, see Azure SQL Database performance and elasticity guide.

Banco de Dados SQL usando o Entity Framework 6SQL Database using Entity Framework 6

O Banco de Dados SQL é um banco de dados SQL disponível em vários tamanhos e como um serviço padrão (compartilhado) e premium (não compartilhado).SQL Database is a hosted SQL database available in a range of sizes and as both a standard (shared) and premium (non-shared) service. O Entity Framework é um mapeador relacional de objeto que permite aos desenvolvedores do .NET trabalhar com dados relacionais usando objetos específicos de domínio.Entity Framework is an object-relational mapper that enables .NET developers to work with relational data using domain-specific objects. Com ele, não há a necessidade da maioria dos códigos de acesso a dados que os desenvolvedores geralmente precisam para escrever.It eliminates the need for most of the data-access code that developers usually need to write.

Mecanismo de repetiçãoRetry mechanism

O suporte à repetição é fornecido durante o acesso ao Banco de Dados SQL usando o Entity Framework 6.0 e versões posteriores por meio de um mecanismo chamado Lógica de Repetição/Resiliência de Conexão.Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher through a mechanism called Connection resiliency / retry logic. Os principais recursos do mecanismo de repetição são:The main features of the retry mechanism are:

  • A abstração primária é a interface IDbExecutionStrategy .The primary abstraction is the IDbExecutionStrategy interface. Essa interface:This interface:
    • Define métodos de execução síncronos e assíncronos.Defines synchronous and asynchronous Execute methods.
    • Define classes que podem ser usadas diretamente ou podem ser configuradas em um contexto de banco de dados como uma estratégia padrão, mapeadas para nome do provedor ou para um nome de provedor e nome de servidor.Defines classes that can be used directly or can be configured on a database context as a default strategy, mapped to provider name, or mapped to a provider name and server name. Quando configuradas em um contexto, as repetições ocorrem no nível de operações de banco de dados individuais, das quais pode haver várias de uma determinada operação de contexto.When configured on a context, retries occur at the level of individual database operations, of which there might be several for a given context operation.
    • Define quando repetir uma conexão com falha, e como.Defines when to retry a failed connection, and how.
  • Incluem várias implementações internas da interface IDbExecutionStrategy :It includes several built-in implementations of the IDbExecutionStrategy interface:
    • Padrão: sem repetição.Default: no retrying.
    • Padrão para banco de dados SQL (automático): sem repetição, mas inspeciona exceções e as encapsula com sugestão para usar a estratégia do banco de dados SQL.Default for SQL Database (automatic): no retrying, but inspects exceptions and wraps them with suggestion to use the SQL Database strategy.
    • Padrão para o banco de dados SQL: exponencial (herdado da classe base) mais lógica de detecção do banco de dados SQL.Default for SQL Database: exponential (inherited from base class) plus SQL Database detection logic.
  • Implementam uma estratégia de retirada exponencial que inclui aleatoriedade.It implements an exponential back-off strategy that includes randomization.
  • As classes de repetição internas são com estado e não são thread-safe.The built-in retry classes are stateful and are not thread-safe. No entanto, elas podem ser reutilizadas depois que a operação atual for concluída.However, they can be reused after the current operation is completed.
  • Se a contagem de repetição especificada for excedida, os resultados serão encapsulados em uma nova exceção.If the specified retry count is exceeded, the results are wrapped in a new exception. A exceção atual não é exibida.It does not bubble up the current exception.

Configuração de políticaPolicy configuration

O suporte à repetição é fornecido durante o acesso ao Banco de Dados SQL usando o Entity Framework 6.0 e versões superiores.Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher. As políticas de repetição são configuradas de modo programático.Retry policies are configured programmatically. A configuração não pode ser alterada por operação.The configuration cannot be changed on a per-operation basis.

Ao configurar uma estratégia no contexto como o padrão, você especifica uma função que cria uma nova estratégia sob demanda.When configuring a strategy on the context as the default, you specify a function that creates a new strategy on demand. O código a seguir mostra como você pode criar uma classe de configuração de repetição que estende a classe base DbConfiguration .The following code shows how you can create a retry configuration class that extends the DbConfiguration base class.

public class BloggingContextConfiguration : DbConfiguration
{
  public BlogConfiguration()
  {
    // Set up the execution strategy for SQL Database (exponential) with 5 retries and 4 sec delay
    this.SetExecutionStrategy(
         "System.Data.SqlClient", () => new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(4)));
  }
}

Depois isso pode ser especificado como a estratégia de repetição padrão para todas as operações usando o método SetConfiguration da instância DbConfiguration quando o aplicativo é iniciado.You can then specify this as the default retry strategy for all operations using the SetConfiguration method of the DbConfiguration instance when the application starts. Por padrão, o EF vai descobrir e usar automaticamente a classe de configuração.By default, EF will automatically discover and use the configuration class.

DbConfiguration.SetConfiguration(new BloggingContextConfiguration());

Você pode especificar a classe de configuração de repetição para um contexto anotando a classe de contexto com um atributo DbConfigurationType .You can specify the retry configuration class for a context by annotating the context class with a DbConfigurationType attribute. No entanto, se você tiver apenas uma classe de configuração, o EF a usará sem a necessidade de anotar o contexto.However, if you have only one configuration class, EF will use it without the need to annotate the context.

[DbConfigurationType(typeof(BloggingContextConfiguration))]
public class BloggingContext : DbContext

Se precisar usar estratégias de repetição diferentes para operações específicas ou desabilitar repetições para operações específicas, você poderá criar uma classe de configuração que permita suspender ou trocar estratégias, definindo um sinalizador no CallContext.If you need to use different retry strategies for specific operations, or disable retries for specific operations, you can create a configuration class that allows you to suspend or swap strategies by setting a flag in the CallContext. A classe de configuração pode usar esse sinalizador para alternar estratégias ou desabilitar a estratégia fornecida por você e usar uma estratégia padrão.The configuration class can use this flag to switch strategies, or disable the strategy you provide and use a default strategy. Para saber mais, confira Suspender a estratégia de execução (EF6 em diante).For more information, see Suspend Execution Strategy (EF6 onwards).

Outra técnica para usar estratégias de repetição específicas para operações individuais é criar uma instância da classe de estratégia necessária e fornecer as configurações desejadas por meio de parâmetros.Another technique for using specific retry strategies for individual operations is to create an instance of the required strategy class and supply the desired settings through parameters. Você então chama o método ExecuteAsync .You then invoke its ExecuteAsync method.

var executionStrategy = new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(4));
var blogs = await executionStrategy.ExecuteAsync(
    async () =>
    {
        using (var db = new BloggingContext("Blogs"))
        {
            // Acquire some values asynchronously and return them
        }
    },
    new CancellationToken()
);

A maneira mais simples de usar uma classe DbConfiguration é colocá-la no mesmo assembly da classe DbContext.The simplest way to use a DbConfiguration class is to locate it in the same assembly as the DbContext class. No entanto, isso não é apropriado quando o mesmo contexto é necessário em cenários diferentes, como diferentes estratégias de repetição interativas e em segundo plano.However, this is not appropriate when the same context is required in different scenarios, such as different interactive and background retry strategies. Se os diferentes contextos forem executados em AppDomains separados, você poderá usar o suporte interno para especificar classes de configuração no arquivo de configuração ou defini-las explicitamente usando código.If the different contexts execute in separate AppDomains, you can use the built-in support for specifying configuration classes in the configuration file or set it explicitly using code. Se os diferentes contextos devem ser executados no mesmo AppDomain, será necessária uma solução personalizada.If the different contexts must execute in the same AppDomain, a custom solution will be required.

Para obter mais informações, consulte Configuração baseada em código (EF6 em diante).For more information, see Code-Based Configuration (EF6 onwards).

A tabela a seguir mostra as configurações padrão para a política de repetição interna ao usar o EF6.The following table shows the default settings for the built-in retry policy when using EF6.

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
PolíticaPolicy ExponencialExponential Retirada exponencial.Exponential back-off.
MaxRetryCountMaxRetryCount 55 O número máximo de repetições.The maximum number of retries.
MaxDelayMaxDelay 30 segundos30 seconds O atraso máximo entre as repetições.The maximum delay between retries. Esse valor não afeta como a série de atrasos é computada.This value does not affect how the series of delays are computed. Ele apenas define um limite superior.It only defines an upper bound.
DefaultCoefficientDefaultCoefficient 1 segundo1 second O coeficiente para o cálculo de retirada exponencial.The coefficient for the exponential back-off computation. Esse valor não pode ser alterado.This value cannot be changed.
DefaultRandomFactorDefaultRandomFactor 1,11.1 O multiplicador usado para adicionar um atraso aleatório a cada entrada.The multiplier used to add a random delay for each entry. Esse valor não pode ser alterado.This value cannot be changed.
DefaultExponentialBaseDefaultExponentialBase 22 O multiplicador usado para calcular o próximo atraso.The multiplier used to calculate the next delay. Esse valor não pode ser alterado.This value cannot be changed.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao acessar o Banco de Dados SQL usando o EF6:Consider the following guidelines when accessing SQL Database using EF6:

  • Escolha a opção de serviço apropriada (compartilhada ou premium).Choose the appropriate service option (shared or premium). Uma instância compartilhada pode sofrer atrasos e limitação de conexão mais longos que o normal devido ao uso por outros locatários do servidor compartilhado.A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. Se forem necessárias operações confiáveis de baixa latência e desempenho previsível, considere a escolha da opção premium.If predictable performance and reliable low latency operations are required, consider choosing the premium option.

  • Uma estratégia de intervalo fixo não é recomendada para ser usada com o Banco de Dados SQL do Azure.A fixed interval strategy is not recommended for use with Azure SQL Database. Em vez disso, use uma estratégia de retirada exponencial, pois o serviço pode estar sobrecarregado e intervalos mais longos permitem mais tempo para a recuperação.Instead, use an exponential back-off strategy because the service may be overloaded, and longer delays allow more time for it to recover.

  • Escolha um valor adequado para os tempos limite de conexão e comando ao definir conexões.Choose a suitable value for the connection and command timeouts when defining connections. Baseie o tempo limite no seu design de lógica de negócios e por meio de teste.Base the timeout on both your business logic design and through testing. Talvez seja necessário modificar esse valor ao longo do tempo, uma vez que os volumes de dados ou os processos de negócios mudam.You may need to modify this value over time as the volumes of data or the business processes change. Um tempo limite muito curto pode resultar em falhas prematuras de conexões quando o banco de dados estiver ocupado.Too short a timeout may result in premature failures of connections when the database is busy. Um tempo limite muito longo pode impedir que a lógica de repetição funcione corretamente, aguardando tempo demais para detectar uma conexão com falha.Too long a timeout may prevent the retry logic working correctly by waiting too long before detecting a failed connection. O valor do tempo limite é um componente da latência de ponta a ponta, embora você não possa determinar facilmente quantos comandos serão executados ao salvar o contexto.The value of the timeout is a component of the end-to-end latency, although you cannot easily determine how many commands will execute when saving the context. Você pode alterar o tempo limite padrão definindo a propriedade CommandTimeout da instância DbContext.You can change the default timeout by setting the CommandTimeout property of the DbContext instance.

  • O Entity Framework oferece suporte às configurações de repetição definidas em arquivos de configuração.Entity Framework supports retry configurations defined in configuration files. No entanto, para máxima flexibilidade no Azure, você deve considerar a criação da configuração de modo programático dentro do aplicativo.However, for maximum flexibility on Azure you should consider creating the configuration programmatically within the application. Os parâmetros específicos das políticas de repetição, como o número de repetições e os intervalos da repetição, podem ser armazenados no arquivo de configuração de serviço e usados no runtime para criar as políticas apropriadas.The specific parameters for the retry policies, such as the number of retries and the retry intervals, can be stored in the service configuration file and used at runtime to create the appropriate policies. Isso permite que as configurações sejam alteradas sem precisar reiniciar o aplicativo.This allows the settings to be changed without requiring the application to be restarted.

Considere começar com as seguintes configurações para operações de repetição.Consider starting with the following settings for retrying operations. Você não pode especificar o intervalo entre tentativas de repetição (ele é fixo e gerado como uma sequência exponencial).You cannot specify the delay between retry attempts (it is fixed and generated as an exponential sequence). Você pode especificar apenas os valores máximo, conforme mostrado aqui, a menos que você crie uma estratégia de repetição personalizada.You can specify only the maximum values, as shown here; unless you create a custom retry strategy. Essas configurações são de finalidade geral e você deve monitorar as operações e ajustar os valores para se adequar a seu próprio cenário.These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

ContextoContext Exemplo de latênciaE2E
máxima de destino
Sample target E2E
max latency
Política de RepetiçãoRetry policy ConfiguraçõesSettings ValoresValues Como ele funcionaHow it works
Interativo, interface de usuárioInteractive, UI,
ou primeiro planoor foreground
2 segundos2 seconds ExponencialExponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
33
750 ms750 ms
1ª tentativa — intervalo de 0 sAttempt 1 - delay 0 sec
2ª tentativa — intervalo de 750 msAttempt 2 - delay 750 ms
3ª tentativa — intervalo de 750 msAttempt 3 – delay 750 ms
Tela de fundoBackground
ou loteor batch
30 segundos30 seconds ExponencialExponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
55
12 segundos12 seconds
1ª tentativa — intervalo de 0 sAttempt 1 - delay 0 sec
2ª tentativa — intervalo de ~1 sAttempt 2 - delay ~1 sec
3ª tentativa — intervalo de ~3 sAttempt 3 - delay ~3 sec
4ª tentativa — intervalo de ~7 sAttempt 4 - delay ~7 sec
5ª tentativa — intervalo de 12 sAttempt 5 - delay 12 sec

Observação

A latência de ponta a ponta visa o tempo limite padrão de conexões com o serviço.The end-to-end latency targets assume the default timeout for connections to the service. Se você especificar tempos limite de conexão mais longos, a latência de ponta a ponta será estendida por esse tempo adicional para cada tentativa de repetição.If you specify longer connection timeouts, the end-to-end latency will be extended by this additional time for every retry attempt.

ExemplosExamples

O exemplo de código a seguir define uma solução de acesso a dados simples que usa o Entity Framework.The following code example defines a simple data access solution that uses Entity Framework. Ele estabelece uma estratégia de repetição específica definindo uma instância de uma classe chamada BlogConfiguration que estende DbConfiguration.It sets a specific retry strategy by defining an instance of a class named BlogConfiguration that extends DbConfiguration.

using System;
using System.Collections.Generic;
using System.Data.Entity;
using System.Data.Entity.SqlServer;
using System.Threading.Tasks;

namespace RetryCodeSamples
{
    public class BlogConfiguration : DbConfiguration
    {
        public BlogConfiguration()
        {
            // Set up the execution strategy for SQL Database (exponential) with 5 retries and 12 sec delay.
            // These values could be loaded from configuration rather than being hard-coded.
            this.SetExecutionStrategy(
                    "System.Data.SqlClient", () => new SqlAzureExecutionStrategy(5, TimeSpan.FromSeconds(12)));
        }
    }

    // Specify the configuration type if more than one has been defined.
    // [DbConfigurationType(typeof(BlogConfiguration))]
    public class BloggingContext : DbContext
    {
        // Definition of content goes here.
    }

    class EF6CodeSamples
    {
        public async static Task Samples()
        {
            // Execution strategy configured by DbConfiguration subclass, discovered automatically or
            // or explicitly indicated through configuration or with an attribute. Default is no retries.
            using (var db = new BloggingContext("Blogs"))
            {
                // Add, edit, delete blog items here, then:
                await db.SaveChangesAsync();
            }
        }
    }
}

Mais exemplos de como usar o mecanismo de repetição de Entity Framework podem ser encontrados na lógica de recuperação/resiliência de conexão.More examples of using the Entity Framework retry mechanism can be found in Connection resiliency / retry logic.

Mais informaçõesMore information

Banco de Dados SQL usando o Entity Framework CoreSQL Database using Entity Framework Core

O Entity Framework Core é um mapeador relacional de objeto que permite aos desenvolvedores do .NET Core trabalhar com dados usando objetos específicos de domínio.Entity Framework Core is an object-relational mapper that enables .NET Core developers to work with data using domain-specific objects. Com ele, não há a necessidade da maioria dos códigos de acesso a dados que os desenvolvedores geralmente precisam para escrever.It eliminates the need for most of the data-access code that developers usually need to write. Esta versão do Entity Framework foi criada a partir do zero e não herda todos os recursos do EF6.x automaticamente.This version of Entity Framework was written from the ground up, and doesn't automatically inherit all the features from EF6.x.

Mecanismo de repetiçãoRetry mechanism

O suporte à repetição é fornecido durante o acesso ao Banco de Dados SQL usando o Entity Framework Core por meio de um mecanismo chamado resiliência de conexão.Retry support is provided when accessing SQL Database using Entity Framework Core through a mechanism called connection resiliency. A resiliência de conexão foi introduzida no EF Core 1.1.0.Connection resiliency was introduced in EF Core 1.1.0.

A abstração primária é a interface IExecutionStrategy.The primary abstraction is the IExecutionStrategy interface. A estratégia de execução para o SQL Server, incluindo o SQL Azure, está ciente dos tipos de exceção que podem ser repetidos e tem padrões específicos para o número máximo de tentativas, atrasos entre as repetições e assim por diante.The execution strategy for SQL Server, including SQL Azure, is aware of the exception types that can be retried and has sensible defaults for maximum retries, delay between retries, and so on.

ExemplosExamples

O código a seguir permite novas tentativas automáticas ao configurar o objeto DbContext, que representa uma sessão com o banco de dados.The following code enables automatic retries when configuring the DbContext object, which represents a session with the database.

protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
{
    optionsBuilder
        .UseSqlServer(
            @"Server=(localdb)\mssqllocaldb;Database=EFMiscellaneous.ConnectionResiliency;Trusted_Connection=True;",
            options => options.EnableRetryOnFailure());
}

O código a seguir mostra como executar uma transação com novas tentativas automáticas, usando uma estratégia de execução.The following code shows how to execute a transaction with automatic retries, by using an execution strategy. A transação é definida em um representante.The transaction is defined in a delegate. Se ocorrer uma falha transitória, a estratégia de execução invocará o representante novamente.If a transient failure occurs, the execution strategy will invoke the delegate again.

using (var db = new BloggingContext())
{
    var strategy = db.Database.CreateExecutionStrategy();

    strategy.Execute(() =>
    {
        using (var transaction = db.Database.BeginTransaction())
        {
            db.Blogs.Add(new Blog { Url = "https://blogs.msdn.com/dotnet" });
            db.SaveChanges();

            db.Blogs.Add(new Blog { Url = "https://blogs.msdn.com/visualstudio" });
            db.SaveChanges();

            transaction.Commit();
        }
    });
}

Armazenamento do AzureAzure Storage

Os serviços de armazenamento do Azure incluem armazenamento de BLOBs, arquivos e filas de armazenamento.Azure Storage services include blob storage, files, and storage queues.

BLOBs, filas e arquivosBlobs, Queues and Files

A classe Clientoptions é o tipo base para todos os tipos de opção de cliente e expõe várias opções de cliente comuns, como diagnóstico, repetição, transporte.The ClientOptions Class is the base type for all client option types and exposes various common client options like Diagnostics, Retry, Transport. Para fornecer as opções de configuração do cliente para se conectar à fila, ao blob e ao armazenamento de arquivos do Azure, você deve usar o tipo derivado correspondente.To provide the client configuration options for connecting to Azure Queue, Blob, and File Storage you must use the corresponding derived type. No próximo exemplo, você usa a classe QueueClientOptions (derivada de Clientoptions) para configurar um cliente para se conectar ao serviço fila do Azure.In the next example, you use the QueueClientOptions class (derived from ClientOptions) to configure a client to connect to Azure Queue Service. A Propriedade Retry é o conjunto de opções que podem ser especificadas para influenciar como as tentativas de repetição são feitas e como uma falha está qualificada para ser repetida.The Retry property is the set of options that can be specified to influence how retry attempts are made, and how a failure is eligible to be retried.

using System;
using System.Threading;
using Azure.Core;
using Azure.Identity;
using Azure.Storage;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;

namespace RetryCodeSamples
{
    class AzureStorageCodeSamples {

        public async static Task Samples() {

               // Provide the client configuration options for connecting to Azure Queue Storage
                QueueClientOptions queueClientOptions = new QueueClientOptions()
                {
                    Retry = {
                    Delay = TimeSpan.FromSeconds(2),     //The delay between retry attempts for a fixed approach or the delay on which to base 
                                                         //calculations for a backoff-based approach
                    MaxRetries = 5,                      //The maximum number of retry attempts before giving up
                    Mode = RetryMode.Exponential,        //The approach to use for calculating retry delays
                    MaxDelay = TimeSpan.FromSeconds(10)  //The maximum permissible delay between retry attempts
                    },

                    GeoRedundantSecondaryUri = new Uri("https://...")
                    // If the GeoRedundantSecondaryUri property is set, the secondary Uri will be used for GET or HEAD requests during retries.
                    // If the status of the response from the secondary Uri is a 404, then subsequent retries for the request will not use the
                    // secondary Uri again, as this indicates that the resource may not have propagated there yet.
                    // Otherwise, subsequent retries will alternate back and forth between primary and secondary Uri.
                };


                Uri queueServiceUri = new Uri("https://storageaccount.queue.core.windows.net/");
                string accountName = "Storage account name";
                string accountKey = "storage account key";

                // Create a client object for the Queue service, including QueueClientOptions.
                QueueServiceClient serviceClient = new QueueServiceClient(queueServiceUri, new DefaultAzureCredential(), queueClientOptions);

                CancellationTokenSource source = new CancellationTokenSource();
                CancellationToken cancellationToken = source.Token;

                // Return an async collection of queues in the storage account.
                var queues = serviceClient.GetQueuesAsync(QueueTraits.None, null, cancellationToken);

Suporte a tabelasTable Support

Observação

O pacote NuGet WindowsAzure. Storage foi preterido.WindowsAzure.Storage Nuget Package has been deprecated. Para obter suporte a tabelas do Azure, consulte pacote NuGet Microsoft. Azure. Cosmos. TableFor Azure table support, see Microsoft.Azure.Cosmos.Table Nuget Package

Mecanismo de repetiçãoRetry mechanism

As repetições ocorrem no nível de operação REST individuais e são uma parte integrante da implementação da API do cliente.Retries occur at the individual REST operation level and are an integral part of the client API implementation. O SDK do armazenamento do cliente usa classes que implementam a Interface IExtendedRetryPolicy.The client storage SDK uses classes that implement the IExtendedRetryPolicy Interface.

As classes internas fornecem suporte a intervalos lineares (constantes) e exponenciais com intervalos de repetição de aleatoriedade.The built-in classes provide support for linear (constant delay) and exponential with randomization retry intervals. Também não há uma política de repetição a ser usada quando outro processo está tratando repetições em um nível mais alto.There is also a no retry policy for use when another process is handling retries at a higher level. No entanto, você pode implementar suas próprias classes de repetição caso haja requisitos não fornecidos pelas classes internas.However, you can implement your own retry classes if you have specific requirements not provided by the built-in classes.

As repetições alternativas serão alternadas entre o local do serviço de armazenamento primário e secundário se você estiver usando o RA-GRS (armazenamento com redundância geográfica com acesso de leitura) e o resultado da solicitação for um erro que pode ser repetido.Alternate retries switch between primary and secondary storage service location if you are using read access geo-redundant storage (RA-GRS) and the result of the request is a retryable error. Consulte Opções de redundância de armazenamento do Azure para saber mais.See Azure Storage Redundancy Options for more information.

Configuração de políticaPolicy configuration

As políticas de repetição são configuradas de modo programático.Retry policies are configured programmatically. Um procedimento comum é criar e popular uma instância TableRequestOptions, BlobRequestOptions, FileRequestOptions ou QueueRequestOptions.A typical procedure is to create and populate a TableRequestOptions, BlobRequestOptions, FileRequestOptions, or QueueRequestOptions instance.

TableRequestOptions interactiveRequestOption = new TableRequestOptions()
{
  RetryPolicy = new LinearRetry(TimeSpan.FromMilliseconds(500), 3),
  // For Read-access geo-redundant storage, use PrimaryThenSecondary.
  // Otherwise set this to PrimaryOnly.
  LocationMode = LocationMode.PrimaryThenSecondary,
  // Maximum execution time based on the business use case.
  MaximumExecutionTime = TimeSpan.FromSeconds(2)
};

A instância das opções de solicitação pode ser definida no cliente e todas as operações com o cliente usarão as opções de solicitação especificadas.The request options instance can then be set on the client, and all operations with the client will use the specified request options.

client.DefaultRequestOptions = interactiveRequestOption;
var stats = await client.GetServiceStatsAsync();

É possível substituir as opções de solicitação de cliente passando uma instância populada da classe de opções de solicitação como um parâmetro para os métodos de operação.You can override the client request options by passing a populated instance of the request options class as a parameter to operation methods.

var stats = await client.GetServiceStatsAsync(interactiveRequestOption, operationContext: null);

Você usa uma instância OperationContext para especificar o código a ser executado quando uma repetição ocorrer e quando uma operação tiver sido concluída.You use an OperationContext instance to specify the code to execute when a retry occurs and when an operation has completed. Esse código pode coletar informações sobre a operação para uso em logs e telemetria.This code can collect information about the operation for use in logs and telemetry.

// Set up notifications for an operation
var context = new OperationContext();
context.ClientRequestID = "some request id";
context.Retrying += (sender, args) =>
{
    // Collect retry information
};
context.RequestCompleted += (sender, args) =>
{
    // Collect operation completion information
};
var stats = await client.GetServiceStatsAsync(null, context);

Além de indicar se uma falha é adequada para repetição, as políticas estendidas de repetição retornam um objeto RetryContext que indica o número de repetições, os resultados da última solicitação e se a próxima repetição acontecerá no local primário ou secundário (consulte a tabela abaixo para obter detalhes).In addition to indicating whether a failure is suitable for retry, the extended retry policies return a RetryContext object that indicates the number of retries, the results of the last request, whether the next retry will happen in the primary or secondary location (see table below for details). As propriedades do objeto RetryContext podem ser usadas para decidir se e quando tentar uma repetição.The properties of the RetryContext object can be used to decide if and when to attempt a retry. Para obter mais informações, consulte o método IExtendedRetryPolicy. Evaluate.For more information, see IExtendedRetryPolicy.Evaluate Method.

As tabelas a seguir mostram as configurações padrão para as políticas de repetição internas.The following tables show the default settings for the built-in retry policies.

Opções de solicitação:Request options:

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
MaximumExecutionTimeMaximumExecutionTime NenhumNone Tempo máximo de execução para a solicitação, incluindo todas as tentativas de repetição potenciais.Maximum execution time for the request, including all potential retry attempts. Se não for especificada, a quantidade de tempo que uma solicitação pode levar é ilimitada.If it is not specified, then the amount of time that a request is permitted to take is unlimited. Em outras palavras, a solicitação pode parar de responder.In other words, the request might stop responding.
ServerTimeoutServerTimeout NenhumNone O intervalo do tempo limite do servidor para a solicitação (o valor é arredondado para segundos).Server timeout interval for the request (value is rounded to seconds). Se não for especificado, será usado o valor padrão para todas as solicitações ao servidor.If not specified, it will use the default value for all requests to the server. Normalmente, a melhor opção é omitir essa configuração para que o padrão de servidor seja usado.Usually, the best option is to omit this setting so that the server default is used.
LocationModeLocationMode NenhumNone Se a conta de armazenamento for criada com a opção de replicação RA-GRS (armazenamento com redundância geográfica com acesso de leitura), você poderá usar o modo de local para indicar qual local deve receber a solicitação.If the storage account is created with the Read access geo-redundant storage (RA-GRS) replication option, you can use the location mode to indicate which location should receive the request. Por exemplo, se PrimaryThenSecondary for especificado, as solicitações sempre serão enviadas para o local primário primeiro.For example, if PrimaryThenSecondary is specified, requests are always sent to the primary location first. Se uma solicitação falhar, ela será enviada para o local secundário.If a request fails, it is sent to the secondary location.
RetryPolicyRetryPolicy ExponentialPolicyExponentialPolicy Veja abaixo os detalhes de cada opção.See below for details of each option.

Política exponencial:Exponential policy:

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
maxAttemptmaxAttempt 33 Número de tentativas de repetição.Number of retry attempts.
deltaBackoffdeltaBackoff 4 segundos4 seconds Intervalo de retirada entre repetições.Back-off interval between retries. Múltiplos desse período de tempo, incluindo um elemento aleatório, serão usados para tentativas de repetição subsequentes.Multiples of this timespan, including a random element, will be used for subsequent retry attempts.
MinBackoffMinBackoff 3 Segundos3 seconds Adicionado a todos os intervalos de repetição calculados de deltaBackoff.Added to all retry intervals computed from deltaBackoff. Esse valor não pode ser alterado.This value cannot be changed.
MaxBackoffMaxBackoff 120 segundos120 seconds MaxBackoff será usado se o intervalo de repetição calculado for maior que MaxBackoff.MaxBackoff is used if the computed retry interval is greater than MaxBackoff. Esse valor não pode ser alterado.This value cannot be changed.

Política linear:Linear policy:

ConfiguraçãoSetting Valor padrãoDefault value SignificadoMeaning
maxAttemptmaxAttempt 33 Número de tentativas de repetição.Number of retry attempts.
deltaBackoffdeltaBackoff 30 segundos30 seconds Intervalo de retirada entre repetições.Back-off interval between retries.

Diretriz de uso de repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao acessar serviços de armazenamento do Azure usando a API do cliente de armazenamento:Consider the following guidelines when accessing Azure storage services using the storage client API:

  • Use as políticas de repetição internas do namespace Microsoft. Azure. Storage. RetryPolicies, onde são apropriadas para seus requisitos.Use the built-in retry policies from the Microsoft.Azure.Storage.RetryPolicies namespace where they are appropriate for your requirements. Na maioria dos casos, essas políticas serão suficientes.In most cases, these policies will be sufficient.

  • Use a política ExponentialRetry em operações em lote, tarefas em segundo plano ou cenários não interativos.Use the ExponentialRetry policy in batch operations, background tasks, or non-interactive scenarios. Nesses cenários, você geralmente pode permitir mais tempo para que o serviço se recupere — com uma chance, uma vez maior, da operação, eventualmente com sucesso.In these scenarios, you can typically allow more time for the service to recover—with a consequently increased chance of the operation eventually succeeding.

  • Considere especificar a propriedade MaximumExecutionTime do parâmetro RequestOptions para limitar o tempo de execução total, mas leve em consideração o tipo e o tamanho da operação ao escolher um valor de tempo limite.Consider specifying the MaximumExecutionTime property of the RequestOptions parameter to limit the total execution time, but take into account the type and size of the operation when choosing a timeout value.

  • Se você precisar implementar uma repetição personalizada, evite criar wrappers em torno das classes do cliente de armazenamento.If you need to implement a custom retry, avoid creating wrappers around the storage client classes. Em vez disso, use os recursos para estender as políticas existentes por meio da interface IExtendedRetryPolicy .Instead, use the capabilities to extend the existing policies through the IExtendedRetryPolicy interface.

  • Se você estiver usando RA-GRS (armazenamento com redundância geográfica com acesso de leitura), será possível usar o LocationMode para especificar que as tentativas de repetição acessarão a cópia secundária somente leitura do repositório caso o acesso primário falhe.If you are using read access geo-redundant storage (RA-GRS) you can use the LocationMode to specify that retry attempts will access the secondary read-only copy of the store should the primary access fail. No entanto, ao usar essa opção, você deve garantir que seu aplicativo possa trabalhar perfeitamente com dados que talvez estejam obsoletos, se a replicação do repositório primário ainda não tiver sido concluída.However, when using this option you must ensure that your application can work successfully with data that may be stale if the replication from the primary store has not yet completed.

Considere começar com as seguintes configurações para operações de repetição.Consider starting with the following settings for retrying operations. Essas configurações são de finalidade geral e você deve monitorar as operações e ajustar os valores para se adequar a seu próprio cenário.These settings are general purpose, and you should monitor the operations and fine-tune the values to suit your own scenario.

ContextoContext Exemplo de latênciaE2E
máxima de destino
Sample target E2E
max latency
Política de RepetiçãoRetry policy ConfiguraçõesSettings ValoresValues Como ele funcionaHow it works
Interativo, interface de usuárioInteractive, UI,
ou primeiro planoor foreground
2 segundos2 seconds LinearLinear maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
33
500 ms500 ms
1ª tentativa — intervalo de 500 msAttempt 1 - delay 500 ms
2ª tentativa — intervalo de 500 msAttempt 2 - delay 500 ms
3ª tentativa — intervalo de 500 msAttempt 3 - delay 500 ms
Tela de fundoBackground
ou loteor batch
30 segundos30 seconds ExponencialExponential maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
55
4 segundos4 seconds
1ª tentativa — intervalo de ~3 sAttempt 1 - delay ~3 sec
2ª tentativa — intervalo de ~7 sAttempt 2 - delay ~7 sec
3ª tentativa — intervalo de ~15 sAttempt 3 - delay ~15 sec

TelemetriaTelemetry

As tentativas de repetição são registradas em um TraceSource.Retry attempts are logged to a TraceSource. Você deve configurar um TraceListener para capturar os eventos e gravá-los em um log de destino apropriado.You must configure a TraceListener to capture the events and write them to a suitable destination log. É possível usar o TextWriterTraceListener ou XmlWriterTraceListener para gravar os dados em um arquivo de log, o EventLogTraceListener para gravar no Log de Eventos do Windows ou o EventProviderTraceListener para gravar dados de rastreamento no subsistema ETW.You can use the TextWriterTraceListener or XmlWriterTraceListener to write the data to a log file, the EventLogTraceListener to write to the Windows Event Log, or the EventProviderTraceListener to write trace data to the ETW subsystem. Você também pode configurar a liberação autoliberada do buffer e o detalhamento dos eventos que serão registrados (por exemplo, erro, aviso, informativo e detalhado).You can also configure autoflushing of the buffer, and the verbosity of events that will be logged (for example, Error, Warning, Informational, and Verbose). Para saber mais, consulte Registro em log no lado do cliente com a biblioteca do cliente de armazenamento para .NET.For more information, see Client-side Logging with the .NET Storage Client Library.

As operações podem receber uma instância OperationContext, que expõe um evento Retrying que pode ser usado para anexar a lógica personalizada de telemetria.Operations can receive an OperationContext instance, which exposes a Retrying event that can be used to attach custom telemetry logic. Para saber mais, consulte Evento OperationContext.Retrying.For more information, see OperationContext.Retrying Event.

ExemplosExamples

O exemplo de código a seguir mostra como criar duas instâncias TableRequestOptions com diferentes configurações de repetição; uma para solicitações interativas e outra para solicitações em segundo plano.The following code example shows how to create two TableRequestOptions instances with different retry settings; one for interactive requests and one for background requests. O exemplo define essas duas políticas de repetição no cliente para que elas sejam aplicadas a todas as solicitações, assim como define a estratégia interativa em uma solicitação específica de modo que ela substitua as configurações padrão aplicadas ao cliente.The example then sets these two retry policies on the client so that they apply for all requests, and also sets the interactive strategy on a specific request so that it overrides the default settings applied to the client.

using System;
using System.Threading.Tasks;
using Microsoft.Azure.Cosmos.Table;

namespace RetryCodeSamples
{
    class AzureStorageCodeSamples
    {
        private const string connectionString = "UseDevelopmentStorage=true";

        public async static Task Samples()
        {
            var storageAccount = CloudStorageAccount.Parse(connectionString);

            TableRequestOptions interactiveRequestOption = new TableRequestOptions()
            {
                RetryPolicy = new LinearRetry(TimeSpan.FromMilliseconds(500), 3),
                // For Read-access geo-redundant storage, use PrimaryThenSecondary.
                // Otherwise set this to PrimaryOnly.
                LocationMode = LocationMode.PrimaryThenSecondary,
                // Maximum execution time based on the business use case.
                MaximumExecutionTime = TimeSpan.FromSeconds(2)
            };

            TableRequestOptions backgroundRequestOption = new TableRequestOptions()
            {
                // Client has a default exponential retry policy with 4 sec delay and 3 retry attempts
                // Retry delays will be approximately 3 sec, 7 sec, and 15 sec
                MaximumExecutionTime = TimeSpan.FromSeconds(30),
                // PrimaryThenSecondary in case of Read-access geo-redundant storage, else set this to PrimaryOnly
                LocationMode = LocationMode.PrimaryThenSecondary
            };

            var client = storageAccount.CreateCloudTableClient();
            // Client has a default exponential retry policy with 4 sec delay and 3 retry attempts
            // Retry delays will be approximately 3 sec, 7 sec, and 15 sec
            // ServerTimeout and MaximumExecutionTime are not set

            {
                // Set properties for the client (used on all requests unless overridden)
                // Different exponential policy parameters for background scenarios
                client.DefaultRequestOptions = backgroundRequestOption;
                // Linear policy for interactive scenarios
                client.DefaultRequestOptions = interactiveRequestOption;
            }

            {
                // set properties for a specific request
                var stats = await client.GetServiceStatsAsync(interactiveRequestOption, operationContext: null);
            }

            {
                // Set up notifications for an operation
                var context = new OperationContext();
                context.ClientRequestID = "some request id";
                context.Retrying += (sender, args) =>
                {
                    // Collect retry information
                };
                context.RequestCompleted += (sender, args) =>
                {
                    // Collect operation completion information
                };
                var stats = await client.GetServiceStatsAsync(null, context);
            }
        }
    }
}

Mais informaçõesMore information

Diretrizes gerais de repetição e RESTGeneral REST and retry guidelines

Considere o seguinte ao acessar serviços do Azure ou de terceiros:Consider the following when accessing Azure or third-party services:

  • Use uma abordagem sistemática para gerenciar repetições, talvez como código reutilizável, para que você possa aplicar uma metodologia consistente em todos os clientes e soluções.Use a systematic approach to managing retries, perhaps as reusable code, so that you can apply a consistent methodology across all clients and all solutions.

  • Considere o uso de uma estrutura de repetição, como Polly, para gerenciar as repetições de tentativa se o cliente ou serviço de destino não tiver nenhum mecanismo de repetição interno.Consider using a retry framework such as Polly to manage retries if the target service or client has no built-in retry mechanism. Isso ajudará você a implementar um comportamento de repetição consistente, bem como pode fornecer uma estratégia de repetição padrão adequada para o serviço de destino.This will help you implement a consistent retry behavior, and it may provide a suitable default retry strategy for the target service. No entanto, talvez seja necessário criar um código de repetição personalizado para serviços que têm comportamento não padrão, que não dependem de exceções para indicar falhas transitórias, ou se você quiser usar uma resposta de repetição de resposta para gerenciar o comportamento de repetição.However, you may need to create custom retry code for services that have nonstandard behavior, that do not rely on exceptions to indicate transient failures, or if you want to use a Retry-Response reply to manage retry behavior.

  • A lógica de detecção transitória dependerá da API de cliente real que você usa para invocar as chamadas REST.The transient detection logic will depend on the actual client API you use to invoke the REST calls. Alguns clientes, como a classe mais recente HttpClient , não lançam exceções para solicitações concluídas com um código de status HTTP sem sucesso.Some clients, such as the newer HttpClient class, will not throw exceptions for completed requests with a non-success HTTP status code.

  • O código de status HTTP retornado do serviço pode ajudar a indicar se a falha é transitória.The HTTP status code returned from the service can help to indicate whether the failure is transient. Talvez seja necessário examinar as exceções geradas por um cliente ou pela estrutura de repetição para acessar o código de status ou determinar o tipo de exceção equivalente.You may need to examine the exceptions generated by a client or the retry framework to access the status code or to determine the equivalent exception type. Os seguintes códigos HTTP geralmente indicam que uma repetição é apropriada:The following HTTP codes typically indicate that a retry is appropriate:

    • 408 Tempo Limite da Solicitação408 Request Timeout
    • 429 Número excessivo de solicitações429 Too Many Requests
    • Erro interno de servidor 500500 Internal Server Error
    • 502 Gateway Incorreto502 Bad Gateway
    • 503 Serviço Indisponível503 Service Unavailable
    • 504 Tempo Limite do Gateway504 Gateway Timeout
  • Se você basear suas lógica de repetição em exceções, geralmente o que se segue indica uma falha transitória onde nenhuma conexão pode ser estabelecida:If you base your retry logic on exceptions, the following typically indicate a transient failure where no connection could be established:

    • WebExceptionStatus.ConnectionClosedWebExceptionStatus.ConnectionClosed
    • WebExceptionStatus.ConnectFailureWebExceptionStatus.ConnectFailure
    • WebExceptionStatus.TimeoutWebExceptionStatus.Timeout
    • WebExceptionStatus.RequestCanceledWebExceptionStatus.RequestCanceled
  • No caso de um status de serviço indisponível, o serviço pode indicar o atraso apropriado antes de tentar a repetição no cabeçalho da resposta Retry-After ou em um cabeçalho personalizado diferente.In the case of a service unavailable status, the service might indicate the appropriate delay before retrying in the Retry-After response header or a different custom header. Os serviços também podem enviar informações adicionais como cabeçalhos personalizados ou inseridos no conteúdo da resposta.Services might also send additional information as custom headers, or embedded in the content of the response.

  • Não repita os códigos de status que representam erros de cliente (erros no intervalo 4xx), exceto para um tempo limite de solicitação 408 e 429 muitas solicitações.Do not retry for status codes representing client errors (errors in the 4xx range) except for a 408 Request Timeout and 429 Too Many Requests.

  • Teste minuciosamente seus mecanismos e estratégias de repetição sob diversas condições, como estado diferente de rede e cargas variáveis de sistema.Thoroughly test your retry strategies and mechanisms under a range of conditions, such as different network states and varying system loadings.

Estratégias de repetiçãoRetry strategies

Veja a seguir os tipos comuns de intervalo de estratégias de repetição:The following are the typical types of retry strategy intervals:

  • Exponencial.Exponential. Uma política de repetição que executa um determinado número de repetições usando uma abordagem de retirada exponencial aleatória para determinar o intervalo entre as repetições.A retry policy that performs a specified number of retries, using a randomized exponential back off approach to determine the interval between retries. Por exemplo:For example:

    var random = new Random();
    
    var delta = (int)((Math.Pow(2.0, currentRetryCount) - 1.0) *
                random.Next((int)(this.deltaBackoff.TotalMilliseconds * 0.8),
                (int)(this.deltaBackoff.TotalMilliseconds * 1.2)));
    var interval = (int)Math.Min(checked(this.minBackoff.TotalMilliseconds + delta),
                    this.maxBackoff.TotalMilliseconds);
    retryInterval = TimeSpan.FromMilliseconds(interval);
    
  • Incremental.Incremental. Uma estratégia de repetição com um número especificado de tentativas de repetição e um intervalo de tempo incremental entre entradas.A retry strategy with a specified number of retry attempts and an incremental time interval between retries. Por exemplo:For example:

    retryInterval = TimeSpan.FromMilliseconds(this.initialInterval.TotalMilliseconds +
                    (this.increment.TotalMilliseconds * currentRetryCount));
    
  • LinearRetry.LinearRetry. Uma política de repetição que executa um número especificado de repetições usando um intervalo de tempo fixo especificado entre as repetições.A retry policy that performs a specified number of retries, using a specified fixed time interval between retries. Por exemplo:For example:

    retryInterval = this.deltaBackoff;
    

Falha transitória manipulada com a PollyTransient fault handling with Polly

Polly é uma biblioteca para lidar programaticamente com as repetições e estratégias de disjuntor .Polly is a library to programmatically handle retries and circuit breaker strategies. O projeto Polly é um membro da Fundação .NET.The Polly project is a member of the .NET Foundation. Para serviços em que o cliente não oferece suporte a novas tentativas, a Polly é uma alternativa válida e evita a necessidade de escrever código de repetição personalizado, que pode ser difícil de implementar corretamente.For services where the client does not natively support retries, Polly is a valid alternative and avoids the need to write custom retry code, which can be hard to implement correctly. A Polly também fornece uma maneira de rastrear erros, para que você possa fazer novas tentativas.Polly also provides a way to trace errors when they occur, so that you can log retries.

Mais informaçõesMore information