Repita a orientação para serviços específicosRetry guidance for specific services

A maioria dos serviços do Azure e dos SDKs do cliente incluem um mecanismo de repetição.Most Azure services and client SDKs include a retry mechanism. No entanto, estes diferem uma vez que cada serviço tem características e requisitos diferentes e, por isso, cada mecanismo de repetição é otimizado 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 as funcionalidades do mecanismo de repetição para a maioria dos serviços do Azure e inclui informações para ajudá-lo a utilizar, adaptar ou ampliar o mecanismo de repetição desses serviços.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ções gerais sobre o processamento de falhas transitórias e a repetição de ligações, assim como operações referentes a serviços e recursos, veja Orientações do mecanismo de repetição.For general guidance on handling transient faults, and retrying connections and operations against services and resources, see Retry guidance.

A tabela seguinte resume as funcionalidades de repetição dos serviços do Azure descritas nestas orientações.The following table summarizes the retry features for the Azure services described in this guidance.

ServiçoService Capacidades de repetiçãoRetry capabilities Configuração da políticaPolicy configuration ÂmbitoScope Funcionalidades de telemetriaTelemetry features
Azure Active DirectoryAzure Active Directory Nativo na biblioteca ADALNative in ADAL library Incorporada na biblioteca ADALEmbeded into ADAL library InternoInternal NenhumaNone
Cosmos DBCosmos DB Nativo no serviçoNative in service Não configurávelNon-configurable GlobalGlobal TraceSourceTraceSource
Data Lake StoreData Lake Store Nativo no clienteNative in client Não configurávelNon-configurable Operações individuaisIndividual operations NenhumaNone
Hubs de eventosEvent Hubs Nativo no clienteNative in client ProgramáticaProgrammatic ClienteClient NenhumaNone
IoT HubIoT Hub Nativo no SDK do clienteNative in client SDK ProgramáticaProgrammatic ClienteClient NenhumaNone
Redis CacheRedis Cache Nativo no clienteNative in client ProgramáticaProgrammatic ClienteClient TextWriterTextWriter
PesquisaSearch Nativo no clienteNative in client ProgramáticaProgrammatic ClienteClient ETW ou personalizadaETW or Custom
Service BusService Bus Nativo no clienteNative in client ProgramáticaProgrammatic Gestor de Espaço de Nome, Fábrica de Mensagens e ClienteNamespace Manager, Messaging Factory, and Client ETWETW
Service FabricService Fabric Nativo no clienteNative in client ProgramáticaProgrammatic ClienteClient NenhumaNone
Base de Dados SQL com ADO.NETSQL Database with ADO.NET PollyPolly Declarativa e programáticaDeclarative and programmatic Instruções únicas ou blocos de códigoSingle statements or blocks of code PersonalizadoCustom
Base de Dados SQL com o Entity FrameworkSQL Database with Entity Framework Nativo no clienteNative in client ProgramáticaProgrammatic Global por AppDomainGlobal per AppDomain NenhumaNone
Base de Dados SQL com o Entity Framework CoreSQL Database with Entity Framework Core Nativo no clienteNative in client ProgramáticaProgrammatic Global por AppDomainGlobal per AppDomain NenhumaNone
ArmazenamentoStorage Nativo no clienteNative in client ProgramáticaProgrammatic Operações individuais e do clienteClient and individual operations TraceSourceTraceSource

Nota

Para os mecanismos de repetição da maioria dos incorporados do Azure, é atualmente uma forma de aplicar uma política de repetição diferentes para diferentes 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. Deve configurar uma política que fornece o desempenho ideal de média e a disponibilidade.You should configure a policy that provides the optimum average performance and availability. Uma forma de otimizar a política consiste em analisar os ficheiros de registo para determinar o tipo de falhas transitórias que estão a ocorrer.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 na cloud de gestão de acessos e identidades completa que combina serviços de diretório centrais, governação de identidade avançada, segurança e gestão de acesso da aplicação.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 Azure AD também oferece aos programadores uma plataforma de gestão de identidades para proporcionar controlo de acesso às aplicações, com base em 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.

Nota

Para obter orientações de repetição nos pontos finais de identidade do serviço gerido, veja como utilizar um Azure VM Managed Service Identity (MSI) para a aquisição do 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

Existe um mecanismo de repetição incorporado para o Azure Active Directory na Active Directory Authentication Library (ADAL).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 e o código de aplicações de terceiros não repitam ligações falhadas, ficando a ADAL responsável pelo processamento das repetições.To avoid unexpected lockouts, we recommend that third party libraries and application code do not retry failed connections, but allow ADAL to handle retries.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes quando utilizar o Azure Active Directory:Consider the following guidelines when using Azure Active Directory:

  • Sempre que possível, utilize a biblioteca ADAL e o suporte incorporado para repetições.When possible, use the ADAL library and the built-in support for retries.
  • Se estiver a utilizar a API REST do Azure Active Directory, repita a operação se o código de resultado é 429 (demasiados pedidos) ou 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 realize repetições para outros erros.Do not retry for any other errors.
  • É recomendado utilizar uma política de término exponencial em cenários de lote com o Azure Active Directory.An exponential back-off policy is recommended for use in batch scenarios with Azure Active Directory.

Considere iniciar com as seguintes definições para repetir operações.Consider starting with the following settings for retrying operations. Estas são as definições de fins gerais e deve monitorizar as operações e ajustar os valores de acordo com o seu cenário.These are general purpose settings, and you should monitor the operations and fine tune the values to suit your own scenario.

ContextoContext Destino de exemplo E2E
latência máx.
Sample target E2E
max latency
Estratégia de repetiçãoRetry strategy DefiniçõesSettings ValoresValues Como funcionaHow it works
Interativo, IUInteractive, UI,
ou primeiro planoor foreground
2 s2 sec FixedIntervalFixedInterval Contagem de repetiçõesRetry count
Intervalo de repetiçõesRetry interval
Primeira repetição rápidaFirst fast retry
33
500 ms500 ms
truetrue
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de 500 msAttempt 2 - delay 500 ms
Tentativa 3 – atraso de 500 msAttempt 3 - delay 500 ms
Segundo plano ouBackground or
lotebatch
60 s60 sec ExponentialBackoffExponentialBackoff Contagem de repetiçõesRetry count
Término mín.Min back-off
Término máx.Max back-off
Término deltaDelta back-off
Primeira repetição rápidaFirst fast retry
55
0 s0 sec
60 s60 sec
2 s2 sec
falsefalse
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de ~2 sAttempt 2 - delay ~2 sec
Tentativa 3 – atraso de ~6 sAttempt 3 - delay ~6 sec
Tentativa 4 – atraso de ~14 sAttempt 4 - delay ~14 sec
Tentativa 5 – atraso de ~30 sAttempt 5 - delay ~30 sec

Mais informaçõesMore information

BD do CosmosCosmos DB

A Cosmos DB é uma base de dados com múltiplos modelos completamente gerida que suporta dados JSON sem esquema.Cosmos DB is a fully-managed multi-model database that supports schema-less JSON data. Oferece um desempenho configurável e fiável, processamento transacional de JavaScript nativo e é criado para a cloud com dimensionamento flexível.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 as repetições falhadas.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 geradas pelo cliente vão além da 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 a Cosmos BD limitar o cliente, devolverá um erro de HTTP 429.If Cosmos DB throttles the client, it returns an HTTP 429 error. Verifique o código de estado na DocumentClientException.Check the status code in the DocumentClientException.

Configuração da políticaPolicy configuration

A tabela seguinte mostra as predefinições da política classe RetryOptions.The following table shows the default settings for the RetryOptions class.

DefiniçãoSetting Valor predefinidoDefault value DescriçãoDescription
MaxRetryAttemptsOnThrottledRequestsMaxRetryAttemptsOnThrottledRequests 99 O número máximo de repetições caso o pedido falhe porque a Cosmos DB aplicou a limitação de velocidade ao cliente.The maximum number of retries if the request fails because Cosmos DB applied rate limiting on the client.
MaxRetryWaitTimeInSecondsMaxRetryWaitTimeInSeconds 3030 O tempo de repetição máximo em milissegundos.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 registadas como mensagens de rastreio não estruturadas através de um .NET TraceSource.Retry attempts are logged as unstructured trace messages through a .NET TraceSource. Tem de configurar um TraceListener para capturar os eventos e escrevê-los num registo de destino adequado.You must configure a TraceListener to capture the events and write them to a suitable destination log.

Por exemplo, se adicionar o seguinte ao ficheiro App.config, serão gerados rastreios num ficheiro de texto na mesma localização 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 recolhe, transforma e armazena milhões de eventos.Azure Event Hubs is a hyper-scale 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. A política predefinida é repetida com um término exponencial quando o Hub de Eventos do Azure devolve uma EventHubsException transitória ou uma OperationCanceledException.The default policy retries with exponential backoff when Azure Event Hub returns a transient EventHubsException or an OperationCanceledException.

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

IoT HubIoT Hub

O IoT Hub do Azure é um serviço para estabelecer ligação, monitorização e gestão de dispositivos para desenvolver aplicativos de Internet das coisas (IoT).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 de dispositivo do IoT do Azure pode detetar erros na rede, protocolo ou aplicação.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 repetição tem de ser efetuada.Based on the error type, the SDK checks whether a retry needs to be performed. Se o erro é recuperável, o SDK começa a voltar a tentar com a política de repetição configurado.If the error is recoverable, the SDK begins to retry using the configured retry policy.

A política de repetição predefinida é término exponencial com interferência aleatória, mas pode ser configurada.The default retry policy is exponential back-off with random jitter, but it can be configured.

Configuração da políticaPolicy configuration

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

Mais informaçõesMore information

Cache de Redis do AzureAzure Redis Cache

A Cache de Redis do Azure é um serviço de acesso de dados rápido e de cache de latência baixa com base na popular Cache de Redis de código aberto.Azure Redis Cache is a fast data access and low latency cache service based on the popular open source Redis Cache. É segura, gerida pela Microsoft e é acessível a partir de qualquer aplicação no Azure.It is secure, managed by Microsoft, and is accessible from any application in Azure.

As orientações nesta secção baseiam-se na utilização do cliente StackExchange.Redis para aceder à 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 estes 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.

Tenha em atenção que o cliente StackExchange.Redis utiliza a multiplexação através de uma ligação única.Note that the StackExchange.Redis client uses multiplexing through a single connection. A utilização recomendada consiste em criar uma instância do cliente durante o arranque da aplicação e utilizar esta instância para todas as operações na 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 este motivo, a ligação à cache é realizada apenas uma vez e, por isso, todas as orientações nesta secção estão relacionadas com a política de repetição para esta ligação inicial (e não para cada operação que acede à 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 utiliza uma classe de Gestor de ligação que está 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 falha de ligação à cache será repetida.The number of times a failed connection to the cache will be retried.
  • ReconnectRetryPolicy.ReconnectRetryPolicy. A estratégia de repetição a utilizar.The retry strategy to use.
  • ConnectTimeout.ConnectTimeout. O tempo de espera máximo em milissegundos.The maximum waiting time in milliseconds.

Configuração da políticaPolicy configuration

As políticas de repetição são configuradas através de programação ao definir as opções para o cliente antes de ligar à cache.Retry policies are configured programmatically by setting the options for the client before connecting to the cache. Tal pode ser feito através da criação de uma instância da classe ConfigurationOptions, o preenchimento das suas propriedades e a transmissão desta 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 incorporadas suportam um atraso linear (constante) e um término exponencial com intervalos de repetição aleatórios.The built-in classes support linear (constant) delay and exponential backoff with randomized retry intervals. Também pode criar uma política de repetição personalizada ao 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 término 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);

Em alternativa, pode especificar as opções como uma cadeia e transmiti-la ao método Connect.Alternatively, you can specify the options as a string, and pass this to the Connect method. Tenha em atenção que a propriedade ReconnectRetryPolicy não pode ser definida desta forma, apenas através de código.Note that 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 pode especificar opções diretamente ao ligar à 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, veja Stack Exchange Redis Configuration (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 seguinte mostra as predefinições da política de repetição incorporada.The following table shows the default settings for the built-in retry policy.

ContextoContext DefiniçãoSetting Default value (Valor predefinido)Default 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 de 5000 msLinearRetry 5000 ms
O número de vezes para repetir tentativas de ligação durante a operação de ligação inicial.The number of times to repeat connect attempts during the initial connection operation.
Tempo limite (ms) para operações de ligação.Timeout (ms) for connect operations. Sem atraso entre as 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.

Repetição a cada 5000 ms.Retry every 5000 ms.

Nota

Para operações síncronas, SyncTimeout pode adicionar a latência de ponto a ponto, porém, a definição demasiado baixa do valor pode provocar 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. Veja Como resolver problemas do Cache de Redis do Azure.See How to troubleshoot Azure Redis Cache. Em geral, evitar utilizar operações síncronas e, em alternativa, utilize operações assíncronas.In general, avoid using synchronous operations, and use asynchronous operations instead. Para obter mais informações, veja Pipelines e Multiplexadores.For more information see Pipelines and Multiplexers.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao utilizar a Cache de Redis do Microsoft Azure:Consider the following guidelines when using Azure Redis Cache:

  • O cliente StackExchange Redis gere as suas próprias repetições, mas apenas ao estabelecer uma ligação à cache quando a aplicação é iniciada 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. Pode configurar o tempo limite da ligação, o número de tentativas de repetição e o tempo entre as repetições para estabelecer esta ligação, mas a política de repetição não é aplicável a operações na 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.
  • Ao invés de utilizar um grande número de tentativas de repetição, considere reverter ao aceder antes à origem de dados original.Instead of using a large number of retry attempts, consider falling back by accessing the original data source instead.

TelemetriaTelemetry

Pode recolher informações sobre ligações (mas não sobre outras operações) com 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 do resultado gerado é 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 seguinte configura um atraso constante (linear) entre 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 com uma instância 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;
                }
            }
        }
    }
}

O exemplo seguinte define a configuração ao especificar as opções como uma cadeia.The next example sets the configuration by specifying the options as a string. O tempo limite da ligação é o período máximo de tempo para aguardar por uma ligaçã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. Tenha em atenção 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, veja Configuração no site do projeto.For more examples, see Configuration on the project website.

Mais informaçõesMore information

O Azure Search pode ser utilizado para adicionar capacidades de pesquisa potentes e sofisticadas para um site ou uma aplicação, resultados de pesquisa otimizados de forma rápida e fácil e construir modelos de classificação otimizado e ricos.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 predefinida é repetida com um término exponencial quando o Azure Search devolve uma resposta 5xx ou 408 (Tempo Limite do Pedido).The default policy retries with exponential backoff when Azure Search returns a 5xx or 408 (Request Timeout) response.

TelemetriaTelemetry

Utilize o ETW para controlar ou registar um fornecedor de rastreio personalizado.Trace with ETW or by registering a custom trace provider. Para obter mais informações, veja a Documentação do AutoRest.For more information, see the AutoRest documentation.

Service BusService Bus

O Service Bus é uma plataforma de mensagens na cloud que fornece a troca de mensagens vagamente conjugadas com um dimensionamento e uma resiliência melhorados para os componentes de uma aplicação, esteja alojada na cloud 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 Service Bus implementa repetições com implementações da classe base RetryPolicy.Service Bus implements retries using implementations of the RetryPolicy base class. Todos os clientes do Service Bus expõem uma propriedade RetryPolicy que pode ser definida como uma das implementações da classe base RetryPolicy.All of the Service Bus clients expose a RetryPolicy property that can be set to one of the implementations of the RetryPolicy base class. As implementações incorporadas são:The built-in implementations are:

  • O classe RetryExponential.The RetryExponential class. Expõe propriedades que controlam o intervalo de término, a contagem de repetições e a propriedade TerminationTimeBuffer utilizada para limitar o tempo total até à conclusão da operação.This exposes properties that control the back-off interval, the retry count, and the TerminationTimeBuffer property that is used to limit the total time for the operation to complete.

  • O classe NoRetry.The NoRetry class. É utilizada quando não são necessárias repetições ao nível da API do Service Bus, tal como quando as repetições são geridas por outro processo como parte de um lote ou uma operação de vários passos.This is used when retries at the Service Bus API level are not required, such as when retries are managed by another process as part of a batch or multiple step operation.

Ações do Service Bus podem devolver um intervalo de exceções, tal como indicado na exceções de mensagens do Service Bus.Service Bus actions can return a range of exceptions, as listed in Service Bus messaging exceptions. A lista fornece informações sobre quais destas indicam que a repetição da operação não é adequada.The list provides information about which if these indicate that retrying the operation is appropriate. Por exemplo, uma ServerBusyException indica que o cliente deve aguardar um período de tempo e, em seguida, repetir a operação.For example, a ServerBusyException indicates that the client should wait for a period of time, then retry the operation. A ocorrência de uma ServerBusyException também faz com que o Service Bus mude para um modo diferente, no qual é adicionado um atraso adicional de 10 segundos aos atrasos de repetição calculados.The occurrence of a ServerBusyException also causes Service Bus to switch to a different mode, in which an extra 10-second delay is added to the computed retry delays. Este modo é reposto após um curto período de tempo.This mode is reset after a short period.

As exceções devolvidas do Service Bus expõem a propriedade IsTransient que indica se o cliente deve repetir a operação.The exceptions returned from Service Bus expose the IsTransient property that indicates if the client should retry the operation. A política RetryExponential incorporada depende da propriedade IsTransient na classe MessagingException, que é a classe base para todas as exceções do Service Bus.The built-in RetryExponential policy relies on the IsTransient property in the MessagingException class, which is the base class for all Service Bus exceptions. Se criar implementações personalizadas da classe base RetryPolicy, poderá utilizar uma combinação do tipo de exceções e a propriedade IsTransient para fornecer um controlo mais preciso das ações de repetição.If you create custom implementations of the RetryPolicy base class you could use a combination of the exception type and the IsTransient property to provide more fine-grained control over retry actions. Por exemplo, pode detetar uma QuotaExceededException e tomar medidas para drenar a fila antes de repetir o envio de uma mensagem.For example, you could detect a QuotaExceededException and take action to drain the queue before retrying sending a message to it.

Configuração da políticaPolicy configuration

As políticas de repetição são definidas através de programação e podem ser definidas como uma política predefinida para uma NamespaceManager e uma MessagingFactory ou individualmente para cada cliente de mensagens.Retry policies are set programmatically, and can be set as a default policy for a NamespaceManager and for a MessagingFactory, or individually for each messaging client. Para definir a política de repetição predefinida para uma sessão de mensagens, defina a RetryPolicy da NamespaceManager.To set the default retry policy for a messaging session you set the RetryPolicy of the NamespaceManager.

namespaceManager.Settings.RetryPolicy = new RetryExponential(minBackoff: TimeSpan.FromSeconds(0.1),
                                                                maxBackoff: TimeSpan.FromSeconds(30),
                                                                maxRetryCount: 3);

Para definir a política de repetição predefinida para todos os clientes criados a partir de uma fábrica de mensagens, defina a RetryPolicy da MessagingFactory.To set the default retry policy for all clients created from a messaging factory, you set the RetryPolicy of the MessagingFactory.

messagingFactory.RetryPolicy = new RetryExponential(minBackoff: TimeSpan.FromSeconds(0.1),
                                                    maxBackoff: TimeSpan.FromSeconds(30),
                                                    maxRetryCount: 3);

Para definir a política de repetição para um cliente de mensagens ou para substituir a política predefinida, defina a propriedade RetryPolicy com uma instância da classe de política necessária:To set the retry policy for a messaging client, or to override its default policy, you set its RetryPolicy property using an instance of the required policy class:

client.RetryPolicy = new RetryExponential(minBackoff: TimeSpan.FromSeconds(0.1),
                                            maxBackoff: TimeSpan.FromSeconds(30),
                                            maxRetryCount: 3);

A política de repetição não pode ser definida ao nível da operação individual.The retry policy cannot be set at the individual operation level. Esta aplica-se a todas as operações do cliente de mensagens.It applies to all operations for the messaging client. A tabela seguinte mostra as predefinições da política de repetição incorporada.The following table shows the default settings for the built-in retry policy.

DefiniçãoSetting Valor predefinidoDefault value SignificadoMeaning
PolíticaPolicy ExponencialExponential Término exponencial.Exponential back-off.
MinimalBackoffMinimalBackoff 00 Intervalo de término mínimo.Minimum back-off interval. Este valor é adicionado ao intervalo de repetições calculado a partir de deltaBackoff.This is added to the retry interval computed from deltaBackoff.
MaximumBackoffMaximumBackoff 30 segundos30 seconds Intervalo de término máximo.Maximum back-off interval. O MaximumBackoff será utilizado se o intervalo de repetições calculado for superior ao MaxBackoff.MaximumBackoff is used if the computed retry interval is greater than MaxBackoff.
DeltaBackoffDeltaBackoff 3 segundos3 seconds Intervalo de término entre repetições.Back-off interval between retries. Serão utilizados múltiplos destes períodos de tempo para as tentativas de repetição subsequentes.Multiples of this timespan will be used for subsequent retry attempts.
TimeBufferTimeBuffer 5 segundos5 seconds A memória intermédia do tempo de término associada à repetição.The termination time buffer associated with the retry. As tentativas de repetição serão abandonadas se o tempo restante for inferior ao TimeBuffer.Retry attempts will be abandoned if the remaining time is less than TimeBuffer.
MaxRetryCountMaxRetryCount 1010 O número máximo de repetições.The maximum number of retries.
ServerBusyBaseSleepTimeServerBusyBaseSleepTime 10 segundos10 seconds Se a última exceção encontrada tiver sido ServerBusyException, este valor será adicionado ao intervalo de repetições calculado.If the last exception encountered was ServerBusyException, this value will be added to the computed retry interval. Este valor não pode ser alterado.This value cannot be changed.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes quando utilizar o Service Bus:Consider the following guidelines when using Service Bus:

  • Quando utilizar a implementação RetryExponential incorporada, não implemente uma operação de contingência, uma vez que a política reage às exceções de Servidor Ocupado e alterna automaticamente para um modo de repetição adequado.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 Service Bus suporta uma funcionalidade denominada Espaço de Nomes Emparelhado, que implementa a ativação pós-falha automática numa fila de cópia de segurança num espaço de nomes separado, caso a fila no espaço de nomes primário falhe.Service Bus supports a feature called Paired Namespaces, which 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 recupera.Messages from the secondary queue can be sent back to the primary queue when it recovers. Esta funcionalidade ajuda-o a abordar falhas transitórias.This feature helps to address transient failures. Para obter mais informações, veja Padrões de Mensagens Assíncronas e Elevada Disponibilidade.For more information, see Asynchronous Messaging Patterns and High Availability.

Considere iniciar com as seguintes definições para repetir operações.Consider starting with following settings for retrying operations. Estas são as definições de fins gerais e deve monitorizar as operações e ajustar os valores de acordo com o seu cenário.These are general purpose settings, and you should monitor the operations and fine tune the values to suit your own scenario.

ContextoContext Latência máxima de exemploExample maximum latency Política de repetiçãoRetry policy DefiniçõesSettings Como funcionaHow it works
Interativo, IU 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
Tentativa 1 – Atraso de 0 s.Attempt 1: Delay 0 sec.
Tentativa 2 – Atraso de ~ 300 MSAttempt 2: Delay ~300 msec.
Tentativa 3 – Atraso de ~ 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 sDeltaBackoff = 1.75 sec.
TimeBuffer = 5 sTimeBuffer = 5 sec.
MaxRetryCount = 3MaxRetryCount = 3
Tentativa 1 – Atraso de ~ 1 s.Attempt 1: Delay ~1 sec.
Tentativa 2 – Atraso de ~ 3 s.Attempt 2: Delay ~3 sec.
Tentativa 3 – Atraso de ~ 6 MS.Attempt 3: Delay ~6 msec.
Tentativa 4: Atraso de ~ 13 MSAttempt 4: Delay ~13 msec.

* Não incluindo o atraso adicional que foi adicionado caso seja recebida uma resposta de Servidor Ocupado.* Not including additional delay that is added if a Server Busy response is received.

TelemetriaTelemetry

O Service Bus regista as repetições como eventos ETW com um EventSource.Service Bus logs retries as ETW events using an EventSource. Deve anexar um EventListener à origem do evento para capturar os eventos e visualizá-los no Visualizador de Desempenho ou escrevê-los num registo de destino adequado.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 têm o seguinte formato: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 exemplo de código seguinte mostra como definir a política de repetição para:The following code example shows how to set the retry policy for:

  • Um gestor de espaço de nomes.A namespace manager. A política aplica-se a todas as operações nesse gestor 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 aplica-se a todos os clientes criados a partir dessa 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 de um cliente ter sido criado, pode 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 aplica-se a todas as operações no 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

A distribuição de serviços fiáveis num cluster do Service Fabric protege contra a maioria das potenciais falhas transitórias abordadas neste artigo.Distributing reliable services in a Service Fabric cluster guards against most of the potential transient faults discussed in this article. Porém, algumas falhas transitórias são ainda possíveis.Some transient faults are still possible, however. Por exemplo, o serviço de nomenclatura pode estar no meio de uma alteração de encaminhamento quando obtém um pedido, o que leva à criação de 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. Se o mesmo pedido chegar 100 milissegundos mais tarde, provavelmente será bem-sucedido.If the same request comes 100 milliseconds later, it will probably succeed.

Internamente, o Service Fabric gere este tipo de falhas transitórias.Internally, Service Fabric manages this kind of transient fault. Pode configurar algumas definições com a classe OperationRetrySettings ao configurar os serviços.You can configure some settings by using the OperationRetrySettings class while setting up your services. O código seguinte mostra um exemplo.The following code shows an example. Na maioria dos casos, isto não deve ser necessário e as predefinições serão adequadas.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

Base de dados do SQL usando o ADO.NETSQL Database using ADO.NET

A Base de Dados SQL é uma base de dados SQL alojada disponível num intervalo de tamanhos e como um serviço standard (partilhado) e premium (não partilhado).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

A Base de Dados SQL não possui suporte incorporado para repetições quando acedida com o ADO.NET.SQL Database has no built-in support for retries when accessed using ADO.NET. No entanto, os códigos de retorno dos pedidos podem ser utilizados para determinar o motivo da falha de um pedido.However, the return codes from requests can be used to determine why a request failed. Para obter mais informações sobre a limitação da Base de Dados SQL, veja Limites de recursos da Base de Dados SQL do Microsoft Azure.For more information about SQL Database throttling, see Azure SQL Database resource limits. Para obter uma lista de códigos de erro relevantes, veja Códigos de erro SQL para aplicações cliente da Base de Dados SQL.For a list of relevant error codes, see SQL error codes for SQL Database client applications.

Pode utilizar a biblioteca do Polly para implementar repetições na Base de Dados SQL.You can use the Polly library to implement retries for SQL Database. Veja Processamento de falhas transitórias com o Polly.See Transient fault handling with Polly.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao aceder à Base de Dados SQL com o ADO.NET:Consider the following guidelines when accessing SQL Database using ADO.NET:

  • Escolha a opção de serviço apropriada (partilhada ou premium).Choose the appropriate service option (shared or premium). Uma instância partilhada pode ser afetada com atrasos e limitações da ligação mais longos do que o habitual, uma vez que estão a ser utilizados por outros inquilinos do servidor partilhado.A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. Se necessitar de um desempenho mais previsível e operações de latência baixa fiáveis, considere escolher a opção premium.If more predictable performance and reliable low latency operations are required, consider choosing the premium option.
  • Confirme que realiza as repetições ao nível ou âmbito adequado para evitar operações não idempotentes que podem causar a inconsistência dos dados.Ensure that you perform retries at the appropriate level or scope to avoid non-idempotent operations causing inconsistency in the data. Idealmente, todas as operações devem ser idempotentes para que possam ser repetidas sem causar qualquer inconsistência.Ideally, all operations should be idempotent so that they can be repeated without causing inconsistency. Se não for este o caso, as repetições devem ser realizadas num nível ou âmbito que permita que todas as alterações relacionadas sejam anuladas caso uma operação falhe, por exemplo, a partir de um âmbito 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 obter mais informações, veja Cloud Service Fundamentals Data Access Layer – Transient Fault Handling (Camada de Acesso de Dados Fundamentais do Serviço Cloud – Processamento de Falhas Transitórias).For more information, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • Não é recomendado utilizar uma estratégia de intervalos fixos com a Base de Dados SQL do Microsoft Azure, exceto com cenários interativos em que existem 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 utilizar uma estratégia de término 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 da ligação e do comando quando definir as ligações.Choose a suitable value for the connection and command timeouts when defining connections. Um tempo limite demasiado curto pode levar falhas prematuras nas ligações quando a base de dados está ocupada.Too short a timeout may result in premature failures of connections when the database is busy. Um tempo limite demasiado longo pode impedir que a lógica de repetição funcione corretamente ao aguardar demasiado antes de detetar uma falha de ligação.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 ponto a ponto. Este é adicionado efetivamente ao atraso 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 ligação após um determinado número de repetições, mesmo quando está a utilizar uma lógica de repetição de término exponencial e repete a operação numa ligação nova.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. A repetição da mesma operação várias vezes na mesma ligação pode acarretar problemas de ligação.Retrying the same operation multiple times on the same connection can be a factor that contributes to connection problems. Para obter um exemplo desta técnica, veja Cloud Service Fundamentals Data Access Layer – Transient Fault Handling (Camada de Acesso de Dados Fundamentais do Serviço Cloud – Processamento de Falhas Transitórias).For an example of this technique, see Cloud Service Fundamentals Data Access Layer – Transient Fault Handling.
  • Quando o agrupamento de ligações está a ser utilizado (a predefinição), há uma hipótese de a mesma ligação ser selecionada do conjunto, mesmo depois de fechar e reabrir uma ligaçã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 este o caso, uma técnica para resolver este assunto consistirá em chamar o método ClearPool da classe SqlConnection para marcar a ligaçã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, deve realizar este procedimento apenas após várias tentativas de ligação sem sucesso e apenas quando encontrar a classe específica das falhas transitórias, tal como tempos limite de SQL (código de erro -2) relacionados a ligaçõ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 de dados utilizar transações iniciadas como instâncias TransactionScope, a lógica de repetição deverá reabrir a ligação e iniciar um novo âmbito 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 este motivo, o bloco de código de repetição deve abranger o âmbito completo da transação.For this reason, the retryable code block should encompass the entire scope of the transaction.

Considere iniciar com as seguintes definições para repetir operações.Consider starting with following settings for retrying operations. Estas são as definições de fins gerais e deve monitorizar as operações e ajustar os valores de acordo com o seu cenário.These are general purpose settings, and you should monitor the operations and fine tune the values to suit your own scenario.

ContextoContext Destino de exemplo E2E
latência máx.
Sample target E2E
max latency
Estratégia de repetiçãoRetry strategy DefiniçõesSettings ValoresValues Como funcionaHow it works
Interativo, IUInteractive, UI,
ou primeiro planoor foreground
2 s2 sec FixedIntervalFixedInterval Contagem de repetiçõesRetry count
Intervalo de repetiçõesRetry interval
Primeira repetição rápidaFirst fast retry
33
500 ms500 ms
truetrue
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de 500 msAttempt 2 - delay 500 ms
Tentativa 3 – atraso de 500 msAttempt 3 - delay 500 ms
Segundo planoBackground
ou loteor batch
30 s30 sec ExponentialBackoffExponentialBackoff Contagem de repetiçõesRetry count
Término mín.Min back-off
Término máx.Max back-off
Término deltaDelta back-off
Primeira repetição rápidaFirst fast retry
55
0 s0 sec
60 s60 sec
2 s2 sec
falsefalse
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de ~2 sAttempt 2 - delay ~2 sec
Tentativa 3 – atraso de ~6 sAttempt 3 - delay ~6 sec
Tentativa 4 – atraso de ~14 sAttempt 4 - delay ~14 sec
Tentativa 5 – atraso de ~30 sAttempt 5 - delay ~30 sec

Nota

Os destinos de latência de ponto a ponto assumem o tempo limite predefinido para as ligações ao serviço.The end-to-end latency targets assume the default timeout for connections to the service. Se especificar tempos limite de ligação mais longos, a latência de ponto a ponto será expandida com esse tempo adicional em 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 secção mostra como pode utilizar o Polly para aceder à Base de Dados SQL do Microsoft Azure com 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 seguinte mostra um método de extensão na classe SqlCommand que chama ExecuteAsync com o término 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 200ms delay.
        onRetry: (exception, attempt) =>
        {
            // Capture some info 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);
}

Este método de extensão assíncrono pode ser utilizado da seguinte forma.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 obter orientações gerais sobre como obter o máximo partido da base de dados SQL, veja guia de elasticidade de desempenho de base de dados do Azure SQL e.For general guidance on getting the most from SQL Database, see Azure SQL Database performance and elasticity guide.

Base de dados SQL com o Entity Framework 6SQL Database using Entity Framework 6

A Base de Dados SQL é uma base de dados SQL alojada disponível num intervalo de tamanhos e como um serviço standard (partilhado) e premium (não partilhado).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 de objetos relacionais que permite aos programadores .NET trabalhar com dados relacionais com 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. Elimina a necessidade da maior parte do código de acesso a dados que os programadores normalmente têm de escrever.It eliminates the need for most of the data-access code that developers usually need to write.

Mecanismo de repetiçãoRetry mechanism

Suporte de repetição é fornecido ao aceder à base de dados do SQL usando o Entity Framework 6.0 e superior através de um mecanismo chamado resiliência de ligação / lógica de repetição.Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher through a mechanism called Connection resiliency / retry logic. As principais funcionalidades do mecanismo de repetição são:The main features of the retry mechanism are:

  • A abstração principal é a interface IDbExecutionStrategy.The primary abstraction is the IDbExecutionStrategy interface. Esta interface:This interface:
    • Define os métodos Executar* síncronos e assíncronos.Defines synchronous and asynchronous Execute* methods.
    • Define as classes que podem ser utilizadas diretamente ou podem ser configuradas num contexto de base de dados como uma estratégia predefinida, mapeadas para o nome do fornecedor ou mapeadas para um nome de fornecedor e o nome do 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 configurada num contexto, as repetições ocorrem ao nível das operações da base de dados individual, das quais podem existir várias para 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 deve repetir uma ligação falhada e como.Defines when to retry a failed connection, and how.
  • Inclui várias implementações incorporadas da interface IDbExecutionStrategy:It includes several built-in implementations of the IDbExecutionStrategy interface:
    • Predefinição – nenhuma repetição.Default - no retrying.
    • Predefinição para a Base de Dados SQL (automático) – sem repetição, mas inspeciona as exceções e encapsula-as num wrapper com a sugestão de utilização da estratégia da Base de Dados SQL.Default for SQL Database (automatic) - no retrying, but inspects exceptions and wraps them with suggestion to use the SQL Database strategy.
    • Predefinição para a Base de Dados SQL – exponencial (herdada da classe base) juntamente com a lógica de deteção da Base de Dados SQL.Default for SQL Database - exponential (inherited from base class) plus SQL Database detection logic.
  • Implementa uma estratégia de término exponencial que inclui aleatoriedade.It implements an exponential back-off strategy that includes randomization.
  • As classes de repetição incorporadas têm estado e não são seguras para threads.The built-in retry classes are stateful and are not thread safe. No entanto, podem ser reutilizadas depois de concluída a operação atual.However, they can be reused after the current operation is completed.
  • Se a contagem de repetições especificada for excedida, os resultados serão encapsulados num wrapper numa nova exceção.If the specified retry count is exceeded, the results are wrapped in a new exception. Não se propaga na exceção atual.It does not bubble up the current exception.

Configuração da políticaPolicy configuration

O suporte de repetição é fornecido ao aceder à Base de Dados SQL com o Entity Framework 6.0 e superior.Retry support is provided when accessing SQL Database using Entity Framework 6.0 and higher. As políticas de repetição são configuradas através de programação.Retry policies are configured programmatically. A configuração não pode ser alterada individualmente para cada operação.The configuration cannot be changed on a per-operation basis.

Quando configurar uma estratégia no contexto como predefinição, deve especificar uma função para criar uma nova estratégia a pedido.When configuring a strategy on the context as the default, you specify a function that creates a new strategy on demand. O código seguinte mostra como pode criar uma classe de configuração da repetição que expande 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)));
  }
}

Em seguida, pode especificar esta como a estratégia de repetição predefinida para todas as operações, com o método SetConfiguration da instância DbConfiguration quando a aplicação inicia.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 predefinição, o EF deteta e utiliza automaticamente a classe de configuração.By default, EF will automatically discover and use the configuration class.

DbConfiguration.SetConfiguration(new BloggingContextConfiguration());

Pode especificar a classe de configuração de repetição para um contexto ao anotar 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 tiver apenas uma classe de configuração, o EF vai utilizá-la sem que seja preciso 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 de utilizar estratégias de repetição diferentes para operações específicas, ou desativar as repetições para operações específicas, poderá criar uma classe de configuração que lhe permite suspender ou trocar as estratégias ao definir um sinalizador em 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 utilizar este sinalizador para alternar estratégias ou desativar a estratégia que forneceu e utilizar uma estratégia predefinida.The configuration class can use this flag to switch strategies, or disable the strategy you provide and use a default strategy. Para obter mais informações, consulte suspender a estratégia de execução (EF6 em diante).For more information, see Suspend Execution Strategy (EF6 onwards).

Outra técnica para utilizar estratégias de repetição específicas para operações individuais consiste em criar uma instância da classe de estratégia necessária e fornecer as definições pretendidas através 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. Em seguida, invoque 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 forma mais simples de utilizar uma classe DbConfiguration é localizá-la na mesma assemblagem que a classe DbContext.The simplest way to use a DbConfiguration class is to locate it in the same assembly as the DbContext class. No entanto, tal não é adequado quando o mesmo contexto é preciso em cenários diferentes, tal como diferentes estratégias de repetição interativos 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, poderá utilizar o suporte incorporado para especificar classes de configuração no ficheiro de configuração ou defini-lo explicitamente com o 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 tiverem de ser executados no mesmo AppDomain, será fornecida 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 seguinte mostra as predefinições da política de repetição incorporada quando utiliza o EF6.The following table shows the default settings for the built-in retry policy when using EF6.

DefiniçãoSetting Valor predefinidoDefault value SignificadoMeaning
PolíticaPolicy ExponencialExponential Término 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 repetições.The maximum delay between retries. Este valor não afeta a forma como a série de atrasos é calculada.This value does not affect how the series of delays are computed. Apenas define um limite superior.It only defines an upper bound.
DefaultCoefficientDefaultCoefficient 1 segundo1 second O coeficiente para o cálculo do término exponencial.The coefficient for the exponential back-off computation. Este valor não pode ser alterado.This value cannot be changed.
DefaultRandomFactorDefaultRandomFactor 1.11.1 O multiplicador utilizado para adicionar um atraso aleatório para cada entrada.The multiplier used to add a random delay for each entry. Este valor não pode ser alterado.This value cannot be changed.
DefaultExponentialBaseDefaultExponentialBase 22 O multiplicador utilizado para calcular o próximo atraso.The multiplier used to calculate the next delay. Este valor não pode ser alterado.This value cannot be changed.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes ao aceder à Base de Dados SQL com o EF6:Consider the following guidelines when accessing SQL Database using EF6:

  • Escolha a opção de serviço apropriada (partilhada ou premium).Choose the appropriate service option (shared or premium). Uma instância partilhada pode ser afetada com atrasos e limitações da ligação mais longos do que o habitual, uma vez que estão a ser utilizados por outros inquilinos do servidor partilhado.A shared instance may suffer longer than usual connection delays and throttling due to the usage by other tenants of the shared server. Se necessitar de um desempenho previsível e operações de latência baixa fiáveis, considere optar pela 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 a Base de Dados SQL do Microsoft Azure.A fixed interval strategy is not recommended for use with Azure SQL Database. Em alternativa, utilize uma estratégia de término exponencial, pois o serviço pode ficar sobrecarregado e os atrasos mais longos permitem mais tempo de 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 da ligação e do comando quando definir as ligações.Choose a suitable value for the connection and command timeouts when defining connections. Baseie o tempo limite na criação da lógica de negócio e em testes.Base the timeout on both your business logic design and through testing. Pode ter de modificar este valor ao longo do tempo à medida que os volumes de dados ou os processos de negócio se alteram.You may need to modify this value over time as the volumes of data or the business processes change. Um tempo limite demasiado curto pode levar falhas prematuras nas ligações quando a base de dados está ocupada.Too short a timeout may result in premature failures of connections when the database is busy. Um tempo limite demasiado longo pode impedir que a lógica de repetição funcione corretamente ao aguardar demasiado antes de detetar uma falha de ligação.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 ponto a ponto, apesar de não poder determinar facilmente o número de comandos que vão ser executados ao guardar 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. Pode alterar o tempo limite predefinido ao definir 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 suporta configurações de repetição definidas nos ficheiros de configuração.Entity Framework supports retry configurations defined in configuration files. No entanto, para obter uma flexibilidade máxima no Azure, deve considerar criar a configuração através de programação na aplicação.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 de repetição, podem ser armazenados no ficheiro de configuração do serviço e utilizados no tempo de execução para criar as políticas adequadas.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. Tal permite que as definições sejam alteradas sem a necessidade de reiniciar a aplicação.This allows the settings to be changed without requiring the application to be restarted.

Considere iniciar com as seguintes definições para repetir operações.Consider starting with the following settings for retrying operations. Não pode especificar o atraso entre tentativas de repetição (é um valor 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). Pode especificar apenas os valores máximos, conforme mostrado aqui; a menos que 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. Estas são as definições de fins gerais e deve monitorizar as operações e ajustar os valores de acordo com o seu cenário.These are general purpose settings, and you should monitor the operations and fine tune the values to suit your own scenario.

ContextoContext Destino de exemplo E2E
latência máx.
Sample target E2E
max latency
Política de repetiçãoRetry policy DefiniçõesSettings ValoresValues Como funcionaHow it works
Interativo, IUInteractive, UI,
ou primeiro planoor foreground
2 segundos2 seconds ExponencialExponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
33
750 ms750 ms
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de 750 msAttempt 2 - delay 750 ms
Tentativa 3 – atraso 750 msAttempt 3 – delay 750 ms
Segundo planoBackground
ou loteor batch
30 segundos30 seconds ExponencialExponential MaxRetryCountMaxRetryCount
MaxDelayMaxDelay
55
12 segundos12 seconds
Tentativa 1 – atraso de 0 sAttempt 1 - delay 0 sec
Tentativa 2 – atraso de ~1 sAttempt 2 - delay ~1 sec
Tentativa 3 – atraso de ~3 sAttempt 3 - delay ~3 sec
Tentativa 4 – atraso de ~7 sAttempt 4 - delay ~7 sec
Tentativa 5 – atraso de ~12 sAttempt 5 - delay 12 sec

Nota

Os destinos de latência de ponto a ponto assumem o tempo limite predefinido para as ligações ao serviço.The end-to-end latency targets assume the default timeout for connections to the service. Se especificar tempos limite de ligação mais longos, a latência de ponto a ponto será expandida com esse tempo adicional em 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 seguinte define uma solução de acesso de dados simples que utiliza o Entity Framework.The following code example defines a simple data access solution that uses Entity Framework. Define uma estratégia de repetição específica através da definição de uma instância de uma classe denominada BlogConfiguration que expande a 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();
            }
        }
    }
}

Encontre mais exemplos da utilização do mecanismo de repetição do Entity Framework em Connection Resiliency/Retry Logic (Resiliência de Ligação/Lógica de Repetição).More examples of using the Entity Framework retry mechanism can be found in Connection Resiliency / Retry Logic.

Mais informaçõesMore information

Base de dados SQL com o Entity Framework CoreSQL Database using Entity Framework Core

O Entity Framework Core é um mapeador de objetos relacionais que permite aos programadores .NET Core trabalhar com dados com 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. Elimina a necessidade da maior parte do código de acesso a dados que os programadores normalmente têm de 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 escrita a partir do zero e não herda automaticamente todas as funcionalidades do EF6.x.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

Suporte de repetição é fornecido quando aceder à base de dados do SQL usando o Entity Framework Core através de um mecanismo chamado resiliência de ligação.Retry support is provided when accessing SQL Database using Entity Framework Core through a mechanism called connection resiliency. A resiliência de ligaçã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 do SQL Server, incluindo o SQL Azure, é compatível com os tipos de exceção que podem ser repetidos e possui predefinições sensíveis para o máximo de repetições, atraso entre repetições, entre outros.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 seguinte código permite repetições automáticas ao configurar o objeto DbContext, que representa uma sessão com a base 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=EFMiscellanous.ConnectionResiliency;Trusted_Connection=True;",
            options => options.EnableRetryOnFailure());
}

O código seguinte mostra como executar uma transação com repetições automáticas, ao utilizar 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 num delegado.The transaction is defined in a delegate. Se ocorrer uma falha transitória, a estratégia de execução invocará o delegado 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();
        }
    });
}

Storage do AzureAzure Storage

Serviços de armazenamento do Azure incluem armazenamento de tabelas e BLOBs, ficheiros e filas de armazenamento.Azure Storage services include table and blob storage, files, and storage queues.

Mecanismo de repetiçãoRetry mechanism

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

Existem diferentes implementações da interface.There are different implementations of the interface. Os clientes de armazenamento podem escolher dentre políticas especificamente concebidas para aceder a tabelas, blobs e filas.Storage clients can choose from policies specifically designed for accessing tables, blobs, and queues. Cada implementação utiliza uma estratégia de repetição diferente que define essencialmente o intervalo de repetições e outros detalhes.Each implementation uses a different retry strategy that essentially defines the retry interval and other details.

As classes incorporadas fornecem suporte para a estratégia linear (atraso constante) e exponencial com intervalos de repetição aleatórios.The built-in classes provide support for linear (constant delay) and exponential with randomization retry intervals. Existe também uma política de não repetição para utilizar quando outro processo está a processar as repetições num nível superior.There is also a no retry policy for use when another process is handling retries at a higher level. No entanto, poderá implementar as suas próprias classes de repetição se tiver requisitos específicos não fornecidos pelas classes incorporadas.However, you can implement your own retry classes if you have specific requirements not provided by the built-in classes.

Se estiver a utilizar o armazenamento georredundante com acesso de leitura (RA-GRS), as repetições alternarão entre a localização de serviço de armazenamento primário e secundário, e o resultado do pedido será um erro recuperável.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. Para obter mais informações, veja Opções de Redundância do Armazenamento do Microsoft Azure.See Azure Storage Redundancy Options for more information.

Configuração da políticaPolicy configuration

As políticas de repetição são configuradas através de programação.Retry policies are configured programmatically. Um procedimento típico consiste na criação e no preenchimento de 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 de opções de pedido pode, em seguida, ser definida no cliente e todas as operações com o cliente vão utilizar as opções de pedido 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();

Pode substituir as opções de pedido do cliente ao transmitir uma instância preenchida da classe de opções de pedido 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);

Utilize uma instância OperationContext para especificar o código a executar quando ocorrer uma nova repetição e quando uma operação for concluída.You use an OperationContext instance to specify the code to execute when a retry occurs and when an operation has completed. Este código pode recolher informações sobre a operação para utilizar em registos 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 de repetição expandida devolvem um objeto RetryContext que indica o número de repetições, os resultados do último pedido e se a próxima repetição vai ocorrer na localização primária ou secundária (veja 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 utilizadas para decidir se e quando realizar uma nova repetição.The properties of the RetryContext object can be used to decide if and when to attempt a retry. Para obter mais detalhes, veja IExtendedRetryPolicy.Evaluate Method (Método IExtendedRetryPolicy.Evaluate).For more details, see IExtendedRetryPolicy.Evaluate Method.

A tabela seguinte mostra as predefinições das políticas de repetição incorporadas.The following tables show the default settings for the built-in retry policies.

Opções de pedido:Request options:

DefiniçãoSetting Default value (Valor predefinido)Default value SignificadoMeaning
MaximumExecutionTimeMaximumExecutionTime NenhumaNone Tempo de execução máximo do pedido, incluindo todas as potenciais tentativas de repetição.Maximum execution time for the request, including all potential retry attempts. Se não for especificada, em seguida, a quantidade de tempo que um pedido é permitido para tirar é ilimitada.If it is not specified, then the amount of time that a request is permitted to take is unlimited. Em outras palavras, poderá bloquear o pedido.In other words, the request might hang.
ServerTimeoutServerTimeout NenhumaNone Intervalo de tempo limite do servidor para o pedido (o valor é arredondado para segundos).Server timeout interval for the request (value is rounded to seconds). Se não for especificado, utilizará o valor predefinido para todos os pedidos para o servidor.If not specified, it will use the default value for all requests to the server. Normalmente, a melhor opção é omitir esta definição para que o servidor predefinido seja utilizado.Usually, the best option is to omit this setting so that the server default is used.
LocationModeLocationMode NenhumaNone Se a conta de armazenamento tiver sido criada com a opção de replicação do armazenamento georredundante de acesso de leitura (RA-GRS), poderá utilizar o modo de localização para indicar a localização que deve receber o pedido.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, os pedidos serão sempre enviados primeiro para a localização primária.For example, if PrimaryThenSecondary is specified, requests are always sent to the primary location first. Se um pedido falhar, será enviado para a localização secundária.If a request fails, it is sent to the secondary location.
RetryPolicyRetryPolicy ExponentialPolicyExponentialPolicy Veja abaixo para obter detalhes sobre cada opção.See below for details of each option.

Política exponencial:Exponential policy:

DefiniçãoSetting Default value (Valor predefinido)Default value SignificadoMeaning
maxAttemptmaxAttempt 33 Número de tentativas de repetição.Number of retry attempts.
deltaBackoffdeltaBackoff 4 segundos4 seconds Intervalo de término entre repetições.Back-off interval between retries. Serão utilizados múltiplos destes períodos de tempo, incluindo um elemento aleatório, para as 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 para todos os intervalos de repetição calculados a partir de deltaBackoff.Added to all retry intervals computed from deltaBackoff. Este valor não pode ser alterado.This value cannot be changed.
MaxBackoffMaxBackoff 120 Segundos120 seconds O MaxBackoff será utilizado se o intervalo de repetições calculado for superior ao MaxBackoff.MaxBackoff is used if the computed retry interval is greater than MaxBackoff. Este valor não pode ser alterado.This value cannot be changed.

Política linear:Linear policy:

DefiniçãoSetting Default value (Valor predefinido)Default value SignificadoMeaning
maxAttemptmaxAttempt 33 Número de tentativas de repetição.Number of retry attempts.
deltaBackoffdeltaBackoff 30 segundos30 seconds Intervalo de término entre repetições.Back-off interval between retries.

Orientações sobre a utilização da repetiçãoRetry usage guidance

Considere as seguintes diretrizes quando aceder aos serviços de armazenamento do Azure com a API cliente de armazenamento:Consider the following guidelines when accessing Azure storage services using the storage client API:

  • Utilize as políticas de repetição incorporadas do espaço de nomes Microsoft.WindowsAzure.Storage.RetryPolicies, se forem adequadas às suas necessidades.Use the built-in retry policies from the Microsoft.WindowsAzure.Storage.RetryPolicies namespace where they are appropriate for your requirements. Na maioria dos casos, estas políticas serão suficientes.In most cases, these policies will be sufficient.

  • Utilize a política ExponentialRetry em operações de lote, tarefas em segundo plano ou cenários não interativos.Use the ExponentialRetry policy in batch operations, background tasks, or non-interactive scenarios. Nestes cenários, por norma, pode conceder mais tempo para a recuperação do serviço, com uma hipótese consequentemente maior de a operação ser eventualmente bem-sucedida.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 tenha 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 precisar de implementar uma repetição personalizada, evite criar wrappers em torno das classes de clientes de armazenamento.If you need to implement a custom retry, avoid creating wrappers around the storage client classes. Em vez disso, utilize as capacidades para expandir as políticas existentes através da interface IExtendedRetryPolicy.Instead, use the capabilities to extend the existing policies through the IExtendedRetryPolicy interface.

  • Se estiver a utilizar o armazenamento georredundante com acesso de leitura (RA-GRS), poderá utilizar o LocationMode para especificar quais as tentativas de repetição que terão acesso à cópia só de leitura secundária do arquivo, 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 utilizar esta opção, deve garantir que a aplicação funciona corretamente com dados que podem ser obsoletos, caso a replicação do arquivo primário ainda não tenha 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 iniciar com as seguintes definições para repetir operações.Consider starting with following settings for retrying operations. Estas são as definições de fins gerais e deve monitorizar as operações e ajustar os valores de acordo com o seu cenário.These are general purpose settings, and you should monitor the operations and fine tune the values to suit your own scenario.

ContextoContext Destino de exemplo E2E
latência máx.
Sample target E2E
max latency
Política de repetiçãoRetry policy DefiniçõesSettings ValoresValues Como funcionaHow it works
Interativo, IUInteractive, UI,
ou primeiro planoor foreground
2 segundos2 seconds LinearLinear maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
33
500 ms500 ms
Tentativa 1 – atraso de 500 msAttempt 1 - delay 500 ms
Tentativa 2 – atraso de 500 msAttempt 2 - delay 500 ms
Tentativa 3 – atraso de 500 msAttempt 3 - delay 500 ms
Segundo planoBackground
ou loteor batch
30 segundos30 seconds ExponencialExponential maxAttemptmaxAttempt
deltaBackoffdeltaBackoff
55
4 segundos4 seconds
Tentativa 1 – atraso de ~3 sAttempt 1 - delay ~3 sec
Tentativa 2 – atraso de ~7 sAttempt 2 - delay ~7 sec
Tentativa 3 – atraso de ~15 sAttempt 3 - delay ~15 sec

TelemetriaTelemetry

As tentativas de repetição são registadas num TraceSource.Retry attempts are logged to a TraceSource. Tem de configurar um TraceListener para capturar os eventos e escrevê-los num registo de destino adequado.You must configure a TraceListener to capture the events and write them to a suitable destination log. Pode utilizar o TextWriterTraceListener ou XmlWriterTraceListener para escrever os dados num ficheiro de registo, o EventLogTraceListener para escrever no Registo de Eventos do Windows ou o EventProviderTraceListener para escrever dados de rastreio no subsistema do 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. Também pode configurar a limpeza automática da memória intermédia e a verbosidade dos eventos que vão ser registados (por exemplo, Erro, Aviso, Informativo e Verboso).You can also configure auto-flushing of the buffer, and the verbosity of events that will be logged (for example, Error, Warning, Informational, and Verbose). Para obter mais informações, veja Client-side Logging with the .NET Storage Client Library (Registo do Lado do Cliente com a Biblioteca de Clientes de Armazenamento .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 Repetição que pode ser utilizado para anexar uma lógica de telemetria personalizada.Operations can receive an OperationContext instance, which exposes a Retrying event that can be used to attach custom telemetry logic. Para obter mais informações, veja OperationContext.Retrying Event (Evento OperationContext.Retrying).For more information, see OperationContext.Retrying Event.

ExemplosExamples

O exemplo de código seguinte mostra como criar duas instâncias TableRequestOptions com definições de repetição diferentes; uma para pedidos interativos e outra para pedidos 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. Em seguida, o exemplo define estas duas políticas de repetição no cliente para que sejam aplicadas em todos os pedidos e, também, define a estratégia interativa de um pedido específico para que substitua as predefinições 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.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.RetryPolicies;
using Microsoft.WindowsAzure.Storage.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ções e RESTGeneral REST and retry guidelines

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

  • Utilize uma abordagem sistemática para gerir várias repetições, talvez como código reutilizável, para que possa aplicar uma metodologia consistente em todos os clientes e todas as 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 a utilização de uma arquitetura de repetição, tal como Polly polly para gerir o mecanismo de repetição de tentativas, se o cliente ou serviço de destino tem não incorporado.Consider using a retry framework such as Polly to manage retries if the target service or client has no built-in retry mechanism. Tal ajudará a implementar um comportamento de repetição consistente e pode fornecer uma estratégia de repetição predefinida adequada ao 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, pode ter de criar um código de repetição personalizado com um comportamento não padrão, que não se baseia em exceções para indicar falhas transitórias, ou se quiser utilizar uma resposta Retry-Response para gerir o comportamento da repetição.However, you may need to create custom retry code for services that have non-standard 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 deteção transitória vai depender da API de cliente atual que utiliza 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, tal como a mais recente classe HttpClient, não geram exceções para pedidos concluídos com um código de estado 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 estado HTTP devolvido 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. Pode ter de examinar as exceções geradas por um cliente ou a estrutura de repetição para aceder ao código de estado ou para 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 normalmente indicam que uma repetição é adequada:The following HTTP codes typically indicate that a retry is appropriate:

    • 408 Tempo Limite do Pedido408 Request Timeout
    • 429 demasiados pedidos429 Too Many Requests
    • 500 Erro de Servidor Interno500 Internal Server Error
    • 502 Gateway Incorreto502 Bad Gateway
    • 503 Serviço Indisponível503 Service Unavailable
    • 504 Tempo Limite do Gateway504 Gateway Timeout
  • Se basear a sua lógica de repetição em exceções, o seguinte normalmente indicará uma falha transitória quando não for possível estabelecer ligação: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 estado de serviço indisponível, o serviço pode indicar o atraso adequado antes de repetir no cabeçalho de resposta Retry-After ou num 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 incorporados 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 estado que representam os erros do cliente (erros no intervalo 4xx), exceto para um 408 Tempo Limite do Pedido.Do not retry for status codes representing client errors (errors in the 4xx range) except for a 408 Request Timeout.

  • Teste cuidadosamente as estratégias de repetição e os mecanismos numa série de condições, por exemplo, estados de rede diferentes e carregamentos de sistema variáveis.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

Seguem-se os habituais tipos de intervalos de estratégia de repetição:The following are the typical types of retry strategy intervals:

  • Exponencial.Exponential. Uma política de repetição que executa um número especificado de repetições, com um término exponencial aleatória abordagem para determinar o intervalo entre 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 repetições.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, com um intervalo de tempo fixo especificado entre 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;
    

Processamento de falhas transitórias com o PollyTransient fault handling with Polly

Polly polly é uma biblioteca para manipular programaticamente as repetições e disjuntor estratégias.Polly is a library to programatically handle retries and circuit breaker strategies. O projeto Polly é um membro da .NET Foundation.The Polly project is a member of the .NET Foundation. Para os serviços onde o cliente não suporta nativamente as repetições, o Polly é uma alternativa válida e evita a necessidade de escrever código personalizado de repetição, o qual 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. O Polly também fornece uma forma de controlar os erros quando estes ocorrem, para que possa registar as repetições.Polly also provides a way to trace errors when they occur, so that you can log retries.

Mais informaçõesMore information