通过

处理 Durable Functions 中的错误 (Azure Functions)

Durable Function 业务流程采用代码实现，并可使用编程语言的错误处理功能。 实际上，不需要学习任何新概念，就可以将错误处理和补偿添加到业务流程中。 但应注意以下事项。

注释

Azure Functions 的 Node.js 编程模型版本 4 已正式发布。 新的 v4 模型旨在为 JavaScript 和 TypeScript 开发人员提供更灵活、更直观的体验。 在迁移指南中详细了解 v3 和 v4 之间的差异。

在以下代码片段中，JavaScript （PM4） 表示编程模型 V4，这是新的体验。

活动函数和子协调流程中的错误

在 Durable Functions 中，活动函数或子业务流程中抛出的未捕获的异常将通过标准化异常类型传递回协调器函数。

例如，请考虑以下业务流程协调程序函数，该函数在两个帐户之间执行资金转移：

在 Durable Functions C# 的进程内，未经处理的异常会引发为 FunctionFailedException。

异常消息通常标识导致失败的活动函数或子业务流程。 若要访问更详细的错误信息，请检查该 InnerException 属性。

[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
            });
    }
}

注释

前面的 C# 示例适用于 Durable Functions 2.x。 对于 Durable Functions 1.x，必须使用 DurableOrchestrationContext 而不是 IDurableOrchestrationContext。 有关版本之间差异的详细信息，请参阅 Durable Functions 版本一文。

如果第一个 CreditAccount 函数调用失败，业务流程协调程序函数将通过把资金退回源帐户来进行补偿。

实体函数中的错误

实体函数的异常处理行为因 Durable Functions 托管模型而异：

在 C# 进程内使用 Durable Functions 时，实体函数抛出的原始异常类型将直接返回给编排器。

[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;
    }
}

失败时自动重试

调用活动函数或子业务流程函数时，可指定自动重试策略。 以下示例尝试调用某个函数多达 3 次，且每次重试之间等待 5 秒：

[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);

    // ...
}

注释

前面的 C# 示例适用于 Durable Functions 2.x。 对于 Durable Functions 1.x，必须使用 DurableOrchestrationContext 而不是 IDurableOrchestrationContext。 有关版本之间差异的详细信息，请参阅 Durable Functions 版本一文。

上例中的活动函数调用接受一个参数，用于配置自动重试策略。 可通过多种选项自定义自动重试策略：

  • 最大尝试次数：尝试的最大次数。 如果设置为 1，则不会重试。
  • 首次重试间隔：首次重试前需要等待的时间。
  • 回退系数：用来确定回退增加速率的系数。 默认值为 1。
  • 最大重试间隔：每次重试之间需要等待的最大时间。
  • 重试超时：执行重试的最大时间。 默认行为是可无限期重试。

自定义重试处理程序

使用 .NET 或 Java 时，你还可以选择在代码中实现重试处理程序。 当声明式重试策略无法充分表达意图时，这会非常有用。 对于不支持自定义重试处理程序的语言，你仍可选择使用循环、异常处理和用于在重试之间注入延迟的计时器来实现重试策略。

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);

函数超时

如果业务流程协调程序内的函数调用耗时太长，建议放弃该函数调用。 当前执行此操作的正确方法是使用“any”任务选择器创建持久计时器，如下例中所示：

[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;
        }
    }
}

注释

前面的 C# 示例适用于 Durable Functions 2.x。 对于 Durable Functions 1.x，必须使用 DurableOrchestrationContext 而不是 IDurableOrchestrationContext。 有关版本之间差异的详细信息，请参阅 Durable Functions 版本一文。

注释

此机制实际上不会终止正在进行的活动函数执行。 它只是允许业务流程协调程序函数忽略结果并继续运行。 有关详细信息，请参阅计时器文档。

未经处理的异常

如果业务流程协调程序函数失败，出现未经处理的异常，则会记录异常的详细信息，且实例的完成状态为 Failed。

包括 FailureDetails 的自定义异常属性（.NET 独立执行环境）

在 .NET 独立模型中运行 Durable Task 工作流时，任务失败会自动序列化为 FailureDetails 对象。 默认情况下，此对象包括标准字段，例如：

  • ErrorType — 异常类型名称
  • 消息 - 异常消息
  • StackTrace — 序列化的堆栈跟踪
  • InnerFailure – 递归内部异常的嵌套 FailureDetails 对象

从 Microsoft.Azure.Functions.Worker.Extensions.DurableTask v1.9.0 开始，可以通过实现从 v1.16.1包开始的 Microsoft.DurableTask.Worker 中定义的 IExceptionPropertiesProvider 来扩展此行为。 此提供程序定义哪些异常类型及其属性应包含在 FailureDetails.Properties 字典中。

注释

  • 此功能仅在 .NET 独立 中可用。 将来的版本中将添加对 Java 的支持。
  • 请确保使用的是 Microsoft.Azure.Functions.Worker.Extensions.DurableTask v1.9.0 或更高版本。
  • 请确保使用的是 Microsoft.DurableTask.Worker v1.16.1 或更高版本。

实现异常属性提供程序

实现自定义 IExceptionPropertiesProvider 来提取和返回所关注的异常的选定属性。 当抛出匹配的异常类型时，返回的字典将被序列化到 FailureDetails 的 Properties 字段中。

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
        };
    }
}

注册提供程序

在 .NET 独立工作主机中注册自定义 IExceptionPropertiesProvider，通常在 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();

注册后，与其中一个已处理类型匹配的任何异常都会在其 FailureDetails 中自动包含配置的属性。

示例故障详情输出

当发生与提供程序配置匹配的异常时，业务流程会收到序列化的 FailureDetails 结构，如下所示：

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

后续步骤

了解永久业务流程

了解如何诊断问题

  • Last updated on