Partilhar via

Tratamento de erros em funções duráveis (Azure Functions)

As orquestrações de funções duráveis são implementadas em código e podem usar os recursos internos de tratamento de erros da linguagem de programação. Realmente não há novos conceitos que você precise aprender para adicionar tratamento de erros e compensação em suas orquestrações. No entanto, existem alguns comportamentos que você deve estar ciente.

Nota

A versão 4 do modelo de programação Node.js para o Azure Functions está disponível em geral. O novo modelo v4 foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Saiba mais sobre as diferenças entre v3 e v4 no guia de migração.

Nos trechos de código a seguir, JavaScript (PM4) indica o modelo de programação V4, a nova experiência.

Erros nas funções de atividade e sub-orquestrações

Em Funções Duráveis, exceções não tratadas lançadas dentro de funções de atividade ou suborquestrações são encaminhadas de volta para a função orquestradora utilizando tipos de exceção padronizados.

Por exemplo, considere a seguinte função orquestradora que executa uma transferência de fundos entre duas contas:

Em Durable Functions C# em processo, exceções não tratadas são lançadas como FunctionFailedException.

A mensagem de exceção normalmente identifica quais funções de atividade ou suborquestrações causaram a falha. Para acessar informações de erro mais detalhadas, inspecione a InnerException propriedade.

[FunctionName("TransferFunds")]
public static async Task Run([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var transferDetails = context.GetInput<TransferOperation>();

    await context.CallActivityAsync("DebitAccount",
        new
        {
            Account = transferDetails.SourceAccount,
            Amount = transferDetails.Amount
        });

    try
    {
        await context.CallActivityAsync("CreditAccount",
            new
            {
                Account = transferDetails.DestinationAccount,
                Amount = transferDetails.Amount
            });
    }
    catch (FunctionFailedException)
    {
        // Refund the source account.
        // Another try/catch could be used here based on the needs of the application.
        await context.CallActivityAsync("CreditAccount",
            new
            {
                Account = transferDetails.SourceAccount,
                Amount = transferDetails.Amount
            });
    }
}

Nota

Os exemplos anteriores de C# são para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar DurableOrchestrationContext em vez de IDurableOrchestrationContext. Para obter mais informações sobre as diferenças entre versões, consulte o artigo Durable Functions versions .

Se a primeira chamada da função CreditAccount falhar, a função orchestrator compensará creditando os fundos de volta na conta de origem.

Erros em funções de entidade

O comportamento de tratamento de exceções para funções de entidade difere com base no modelo de hospedagem de Funções Duráveis:

Em Durable Functions using C# in-process, os tipos de exceção originais lançados por funções de entidade são retornados diretamente ao orquestrador.

[FunctionName("Function1")]
public static async Task<string> RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    try
    {
        var entityId = new EntityId(nameof(Counter), "myCounter");
        await context.CallEntityAsync(entityId, "Add", 1);
    }
    catch (Exception ex)
    {
        // The exception type will be InvalidOperationException with the message "this is an entity exception".
    }
    return string.Empty;
}

[FunctionName("Counter")]
public static void Counter([EntityTrigger] IDurableEntityContext ctx)
{
    switch (ctx.OperationName.ToLowerInvariant())
    {
        case "add":
            throw new InvalidOperationException("this is an entity exception");
        case "get":
            ctx.Return(ctx.GetState<int>());
            break;
    }
}

Repetição automática em caso de falha

Ao chamar funções de atividade ou funções de suborquestração, você pode especificar uma política de repetição automática. O exemplo a seguir tenta chamar uma função até três vezes e aguarda 5 segundos entre cada nova tentativa:

[FunctionName("TimerOrchestratorWithRetry")]
public static async Task Run([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var retryOptions = new RetryOptions(
        firstRetryInterval: TimeSpan.FromSeconds(5),
        maxNumberOfAttempts: 3);

    await context.CallActivityWithRetryAsync("FlakyFunction", retryOptions, null);

    // ...
}

Nota

Os exemplos anteriores de C# são para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar DurableOrchestrationContext em vez de IDurableOrchestrationContext. Para obter mais informações sobre as diferenças entre versões, consulte o artigo Durable Functions versions .

A chamada de função de atividade no exemplo anterior usa um parâmetro para configurar uma política de repetição automática. Há várias opções para personalizar a política de repetição automática:

  • Número máximo de tentativas: o número máximo de tentativas. Se definido como 1, não haverá nova tentativa.
  • Primeiro intervalo de tentativas: o tempo de espera antes da primeira tentativa.
  • Coeficiente de backoff: O coeficiente usado para determinar a taxa de aumento de backoff. O padrão é 1.
  • Intervalo máximo de repetição: o tempo máximo de espera entre as tentativas de repetição.
  • Tempo limite de repetição: a quantidade máxima de tempo para fazer tentativas. O comportamento padrão é tentar novamente indefinidamente.

Manipuladores de repetição personalizados

Ao usar o .NET ou Java, você também tem a opção de implementar manipuladores de repetição no código. Isso é útil quando as políticas declarativas de repetição não são expressivas o suficiente. Para idiomas que não oferecem suporte a manipuladores de repetição personalizados, você ainda tem a opção de implementar políticas de repetição usando loops, tratamento de exceções e temporizadores para injetar atrasos entre tentativas.

RetryOptions retryOptions = new RetryOptions(
    firstRetryInterval: TimeSpan.FromSeconds(5),
    maxNumberOfAttempts: int.MaxValue)
    {
        Handle = exception =>
        {
            // True to handle and try again, false to not handle and throw.
            if (exception is TaskFailedException failure)
            {
                // Exceptions from TaskActivities are always this type. Inspect the
                // inner Exception to get more details.
            }

            return false;
        };
    }

await ctx.CallActivityWithRetryAsync("FlakeyActivity", retryOptions, null);

Tempos limite de função

Você pode querer abandonar uma chamada de função dentro de uma função orchestrator se ela estiver demorando muito para ser concluída. A maneira correta de fazer isso hoje é criando um temporizador durável com um seletor de tarefas "qualquer", como no exemplo a seguir:

[FunctionName("TimerOrchestrator")]
public static async Task<bool> Run([OrchestrationTrigger] IDurableOrchestrationContext context)
{
    TimeSpan timeout = TimeSpan.FromSeconds(30);
    DateTime deadline = context.CurrentUtcDateTime.Add(timeout);

    using (var cts = new CancellationTokenSource())
    {
        Task activityTask = context.CallActivityAsync("FlakyFunction");
        Task timeoutTask = context.CreateTimer(deadline, cts.Token);

        Task winner = await Task.WhenAny(activityTask, timeoutTask);
        if (winner == activityTask)
        {
            // success case
            cts.Cancel();
            return true;
        }
        else
        {
            // timeout case
            return false;
        }
    }
}

Nota

Os exemplos anteriores de C# são para Durable Functions 2.x. Para Durable Functions 1.x, você deve usar DurableOrchestrationContext em vez de IDurableOrchestrationContext. Para obter mais informações sobre as diferenças entre versões, consulte o artigo Durable Functions versions .

Nota

Na verdade, esse mecanismo não encerra a execução da função de atividade em andamento. Em vez disso, ele simplesmente permite que a função orquestradora ignore o resultado e siga em frente. Para obter mais informações, consulte a documentação dos temporizadores .

Exceções não processadas

Se uma função orchestrator falhar com uma exceção não tratada, os detalhes da exceção serão registrados e a instância será concluída com um Failed status.

Incluir propriedades de exceção personalizadas para FailureDetails (.NET isolado)

Ao executar fluxos de trabalho de Tarefa Durável no modelo Isolado do .NET, as falhas de tarefa são serializadas automaticamente em um objeto FailureDetails. Por padrão, esse objeto inclui campos padrão, como:

  • ErrorType — o nome do tipo de exceção
  • Mensagem — a mensagem de exceção
  • StackTrace — o traço de pilha serializado
  • InnerFailure – um objeto FailureDetails aninhado para excepções internas e recursivas

A partir de Microsoft.Azure.Functions.Worker.Extensions.DurableTask v1.9.0, você pode estender esse comportamento implementando um IExceptionPropertiesProvider (definido no pacote Microsoft.DurableTask.Worker a partir do v1.16.1). Esse provedor define quais tipos de exceção e quais de suas propriedades devem ser incluídas no dicionário FailureDetails.Properties.

Nota

  • Esse recurso está disponível somente no .NET Isolado . O suporte para Java será adicionado em uma versão futura.
  • Certifique-se de que está a utilizar Microsoft.Azure.Functions.Worker.Extensions.DurableTask v1.9.0 ou posterior.
  • Certifique-se de que está a utilizar Microsoft.DurableTask.Worker v1.16.1 ou posterior.

Implementar um provedor de propriedades de exceção

Implemente um IExceptionPropertiesProvider personalizado para extrair e retornar propriedades selecionadas para as exceções que lhe interessam. O dicionário retornado será serializado no campo Properties de FailureDetails quando um tipo de exceção correspondente for lançado.

using Microsoft.DurableTask.Worker;

public class CustomExceptionPropertiesProvider : IExceptionPropertiesProvider
{
    public IDictionary<string, object?>? GetExceptionProperties(Exception exception)
    {
        return exception switch
        {
            ArgumentOutOfRangeException e => new Dictionary<string, object?>
            {
                ["ParamName"] = e.ParamName,
                ["ActualValue"] = e.ActualValue
            },
            InvalidOperationException e => new Dictionary<string, object?>
            {
                ["CustomHint"] = "Invalid operation occurred",
                ["TimestampUtc"] = DateTime.UtcNow
            },
            _ => null // Other exception types not handled
        };
    }
}

Registar o Fornecedor

Registre seu IExceptionPropertiesProvider personalizado em seu host de trabalho isolado do .NET, normalmente em Program.cs:

using Microsoft.DurableTask.Worker;
using Microsoft.Extensions.DependencyInjection;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(builder =>
    {
        // Register custom exception properties provider
        builder.Services.AddSingleton<IExceptionPropertiesProvider, CustomExceptionPropertiesProvider>();
    })
    .Build();

host.Run();

Uma vez registrada, qualquer exceção que corresponda a um dos tipos manipulados incluirá automaticamente as propriedades configuradas em seus FailureDetails.

Exemplo de FalhaSaída de Detalhes

Quando ocorre uma exceção que corresponde à configuração do seu provedor, a orquestração recebe uma estrutura FailureDetails serializada como esta:

{
  "errorType": "TaskFailedException",
  "message": "Activity failed with an exception.",
  "stackTrace": "...",
  "innerFailure": {
    "errorType": "ArgumentOutOfRangeException",
    "message": "Specified argument was out of range.",
    "properties": {
      "ParamName": "count",
      "ActualValue": 42
    }
  }
}

Próximos passos

Saiba mais sobre orquestrações eternas

Saiba como diagnosticar problemas

  • Last updated on