التعامل مع الأخطاء وإعادة المحاولات في الدوال الدائمة

مهم

سينتهي الدعم للنموذج قيد التنفيذ في 10 نوفمبر 2026. نوصي بشدة بترحيل تطبيقاتك إلى نموذج العامل المعزول للحصول على الدعم الكامل.

أنت تنفذ تنسيقات Durable Functions في الكود، لذا استخدم ميزات معالجة الأخطاء المدمجة في لغتك. التعامل مع الأخطاء والتعويض لا يتطلب مفاهيم جديدة، لكن بعض سلوكيات التنسيق تستحق المعرفة.

ملحوظة

الإصدار الرابع من نموذج البرمجة Node.js ل دالات Azure متوفر بشكل عام. تم تصميم نموذج v4 لتوفير تجربة أكثر مرونة وسهولة لمطوري JavaScript وTypeScript. لمزيد من المعلومات حول الفروقات بين v3 و v4، راجع دليل الهجرة.

في مقتطفات الكود التالية، تشير جافاسكريبت (PM4) إلى نموذج البرمجة v4، وهو التجربة الجديدة.

التطبيقات التي تستخدم خدمات السحابة تحتاج إلى التعامل مع الإخفاقات، وإعادة المحاولات على جانب العميل جزء مهم من التصميم. تتضمن مجموعات تطوير المهام الدائمة دعم معالجة الأخطاء، وإعادة التكرار، وانتهاء المهلات لمساعدتك على بناء سير عمل قوي.

في Durable Functions، يقوم الإطار بتنظيم الاستثناءات غير المدارة التي تم إلقاؤها داخل دوال النشاط أو التنسيقات الفرعية إلى وظيفة المنسق باستخدام أنواع استثناءات موحدة.

تقوم وظيفة المنسق التالية بتحويل الأموال بين حسابين:

نموذج العامل المعزول

في Durable Functions C# Isolated، تظهر الاستثناءات غير المعالجة ك TaskFailedException.

عادة ما تحدد رسالة الاستثناء وظائف النشاط أو التنسيقات الفرعية التي تسببت في الفشل. للوصول إلى معلومات خطأ أكثر تفصيلا، افحص الخاصية FailureDetails .

[FunctionName("TransferFunds")]
public static async Task Run(
    [OrchestrationTrigger] TaskOrchestrationContext context, TransferOperation transferDetails)
{
    await context.CallActivityAsync("DebitAccount",
        new
        {
            Account = transferDetails.SourceAccount,
            Amount = transferDetails.Amount
        });

    try
    {
        await context.CallActivityAsync("CreditAccount",
            new
            {
                Account = transferDetails.DestinationAccount,
                Amount = transferDetails.Amount
            });
    }
    catch (TaskFailedException)
    {
        // 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
            });
    }
}

ملحوظة

عادة ما تحدد رسالة الاستثناء وظائف النشاط أو التنسيقات الفرعية التي تسببت في الفشل. للوصول إلى معلومات أكثر تفصيلا عن الخطأ، افحص الموقع FailureDetails .
بشكل افتراضي، FailureDetails يتضمن نوع الخطأورسالة الخطأوتتبع المكدس وأي استثناءات داخلية متداخلة (يتم تمثيل كل منها ككائن متكرر FailureDetails ). لإضافة خصائص استثناء إضافية في مخرج الفشل، راجع تضمين خصائص الاستثناء المخصصة ل FailureDetails.

مهم

ملاحظة ترحيل (قيد المعالجة إلى معزولة): في النموذج الجاري، FunctionFailedException.InnerException يحتوي على كائن الاستثناء الأصلي الذي يلقى من النشاط، والذي يمكنك إلقائه وفحصه مباشرة. في نموذج العامل المعزول، TaskFailedExceptionلا يحتوي على الاستثناء الأصلي ك .InnerException بدلا من ذلك، تتوفر تفاصيل الخطأ فقط من خلال الخاصية FailureDetails ، التي توفر خصائص قائمة على السلاسل النصية (ErrorType, ErrorMessage, StackTrace). لا يمكنك إرسال أو الوصول إلى كائن الاستثناء الأصلي مباشرة. استخدم FailureDetails.IsCausedBy<T>() للتحقق من نوع الاستثناء الأصلي.

النموذج أثناء العملية

في 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 versions.

نموذج البرمجة V3

const df = require("durable-functions");

module.exports = df.orchestrator(function* (context) {
    const transferDetails = context.df.getInput();

    yield context.df.callActivity("DebitAccount", {
        account: transferDetails.sourceAccount,
        amount: transferDetails.amount,
    });

    try {
        yield context.df.callActivity("CreditAccount", {
            account: transferDetails.destinationAccount,
            amount: transferDetails.amount,
        });
    } catch (error) {
        // Refund the source account.
        // Another try/catch could be used here based on the needs of the application.
        yield context.df.callActivity("CreditAccount", {
            account: transferDetails.sourceAccount,
            amount: transferDetails.amount,
        });
    }
})

نموذج البرمجة V4

const df = require("durable-functions");

df.app.orchestration("transferFunds", function* (context) {
    const transferDetails = context.df.getInput();

    yield context.df.callActivity("debitAccount", {
        account: transferDetails.sourceAccount,
        amount: transferDetails.amount,
    });

    try {
        yield context.df.callActivity("creditAccount", {
            account: transferDetails.destinationAccount,
            amount: transferDetails.amount,
        });
    } catch (error) {
        // Refund the source account.
        // Another try/catch could be used here based on the needs of the application.
        yield context.df.callActivity("creditAccount", {
            account: transferDetails.sourceAccount,
            amount: transferDetails.amount,
        });
    }
});

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    transfer_details = context.get_input()

    yield context.call_activity('DebitAccount', {
         'account': transfer_details['sourceAccount'],
         'amount' : transfer_details['amount']
    })

    try:
        yield context.call_activity('CreditAccount', {
                'account': transfer_details['destinationAccount'],
                'amount': transfer_details['amount'],
            })
    except Exception:
        yield context.call_activity('CreditAccount', {
            'account': transfer_details['sourceAccount'],
            'amount': transfer_details['amount']
        })

main = df.Orchestrator.create(orchestrator_function)

افتراضيا، لا ترفع أوامر PowerShell استثناءات يمكن أن تلتقط كتل المحاولة/القبض عليها. لتغيير هذا السلوك، استخدم أحد الخيارات التالية:

استخدم العلامة -ErrorAction Stop عند استدعاء أوامر cmdlets، مثل Invoke-DurableActivity.
قم بتعيين $ErrorActionPreferenceمتغير التفضيل إلى "Stop" في دالة المنسق قبل استدعاء أوامر cmdlets.

param($Context)

$ErrorActionPreference = "Stop"

$transferDetails = $Context.Input

Invoke-DurableActivity -FunctionName 'DebitAccount' -Input @{ account = $transferDetails.sourceAccount; amount = $transferDetails.amount }

try {
    Invoke-DurableActivity -FunctionName 'CreditAccount' -Input @{ account = $transferDetails.destinationAccount; amount = $transferDetails.amount }
} catch {
    Invoke-DurableActivity -FunctionName 'CreditAccount' -Input @{ account = $transferDetails.sourceAccount; amount = $transferDetails.amount }
}

لمزيد من المعلومات حول معالجة الأخطاء في PowerShell، راجع وثائق Try-Catch-Final PowerShell.

@FunctionName("TransferFunds")
public void transferFunds(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    TransferOperation transfer = ctx.getInput(TransferOperation.class);
    ctx.callActivity(
        "DebitAccount", 
        new OperationArgs(transfer.sourceAccount, transfer.amount)).await();
    try {
        ctx.callActivity(
            "CreditAccount", 
            new OperationArgs(transfer.destinationAccount, transfer.amount)).await();
    } catch (TaskFailedException ex) {
        // Refund the source account on failure
        ctx.callActivity(
            "CreditAccount", 
            new OperationArgs(transfer.sourceAccount, transfer.amount)).await();
    }
}

إذا فشل استدعاء دالة CreditAccount الأول، فإن دالة المنسق تعوض عن طريق إعادة رصيد الأموال إلى الحساب المصدر.

في مجموعات تطوير المهام الدائمة، يتم إعادة الاستثناءات غير المدارة التي تلقى ضمن الأنشطة أو التنسيقات الفرعية إلى المنسق الذي يستخدم هذا TaskFailedException النوع. توفر خاصية الاستثناء FailureDetails معلومات مفصلة عن الفشل.

using Microsoft.DurableTask;

[DurableTask(nameof(TransferFundsOrchestration))]
public class TransferFundsOrchestration : TaskOrchestrator<TransferOperation, string>
{
    public override async Task<string> RunAsync(
        TaskOrchestrationContext context, TransferOperation transfer)
    {
        await context.CallActivityAsync(
            nameof(DebitAccountActivity),
            new AccountOperation { Account = transfer.SourceAccount, Amount = transfer.Amount });

        try
        {
            await context.CallActivityAsync(
                nameof(CreditAccountActivity),
                new AccountOperation { Account = transfer.DestinationAccount, Amount = transfer.Amount });
        }
        catch (TaskFailedException ex)
        {
            // Log the failure details
            var details = ex.FailureDetails;

            // Compensate by refunding the source account
            await context.CallActivityAsync(
                nameof(CreditAccountActivity),
                new AccountOperation { Account = transfer.SourceAccount, Amount = transfer.Amount });

            return $"Transfer failed: {details.ErrorMessage}. Compensation completed.";
        }

        return "Transfer completed successfully";
    }
}

import { OrchestrationContext, TOrchestrator } from "@microsoft/durabletask-js";

const transferFundsOrchestrator: TOrchestrator = async function* (
  ctx: OrchestrationContext
): any {
  const transfer = ctx.getInput() as {
    sourceAccount: string;
    destinationAccount: string;
    amount: number;
  };

  yield ctx.callActivity(debitAccount, {
    account: transfer.sourceAccount,
    amount: transfer.amount,
  });

  try {
    yield ctx.callActivity(creditAccount, {
      account: transfer.destinationAccount,
      amount: transfer.amount,
    });
  } catch (error) {
    // Compensate by refunding the source account
    yield ctx.callActivity(creditAccount, {
      account: transfer.sourceAccount,
      amount: transfer.amount,
    });
    return `Transfer failed. Compensation completed.`;
  }

  return "Transfer completed successfully";
};

from durabletask import task

def transfer_funds_orchestrator(ctx: task.OrchestrationContext, transfer: dict) -> str:
    """
    Orchestrator that demonstrates error handling with compensation.
    """
    source_account = transfer.get("source_account")
    destination_account = transfer.get("destination_account")
    amount = transfer.get("amount")

    # Debit the source account
    yield ctx.call_activity("debit_account", input={
        "account": source_account,
        "amount": amount
    })

    try:
        # Credit the destination account
        yield ctx.call_activity("credit_account", input={
            "account": destination_account,
            "amount": amount
        })
    except task.TaskFailedError as ex:
        # Compensate by refunding the source account
        yield ctx.call_activity("credit_account", input={
            "account": source_account,
            "amount": amount
        })
        return f"Transfer failed: {ex}. Compensation completed."

    return "Transfer completed successfully"

import com.microsoft.durabletask.*;

public TaskOrchestration createTransferOrchestration() {
    return ctx -> {
        TransferOperation transfer = ctx.getInput(TransferOperation.class);

        ctx.callActivity("DebitAccount",
            new AccountOperation(transfer.sourceAccount, transfer.amount)).await();

        try {
            ctx.callActivity("CreditAccount",
                new AccountOperation(transfer.destinationAccount, transfer.amount)).await();
        } catch (TaskFailedException ex) {
            // Compensate by refunding the source account
            ctx.callActivity("CreditAccount",
                new AccountOperation(transfer.sourceAccount, transfer.amount)).await();

            ctx.complete("Transfer failed: " + ex.getMessage() + ". Compensation completed.");
            return;
        }

        ctx.complete("Transfer completed successfully");
    };
}

إذا فشل نشاط حساب الائتمان ، يكتشف المنسق الاستثناء ويعوض ذلك بإعادة الأموال إلى الحساب المصدر.

التعامل مع الأخطاء التي تحتوي على عدة استدعاءات نشاط (خروج المروحة/المروحة الداخلية)

عندما تستخدم Task.WhenAll لتشغيل عدة استدعاءات نشاط بالتوازي (نمط خروج المروحة/المروحة الداخلية) وتفشل نشاط أو أكثر، await فإنه يظهر الاستثناء الأول فقط. للوصول إلى جميع الأعطال، افحص الخاصية Exception على المرجع Task المعاد بواسطة Task.WhenAll.

نموذج العامل المعزول

var tasks = new[]
{
    context.CallActivityAsync("Activity1", input1),
    context.CallActivityAsync("Activity2", input2),
    context.CallActivityAsync("Activity3", input3),
};

var allTask = Task.WhenAll(tasks);
try
{
    await allTask;
}
catch (TaskFailedException)
{
    // 'await' rethrows only the first exception. To inspect all failures,
    // check allTask.Exception, which is an AggregateException.
    if (allTask.Exception != null)
    {
        foreach (var inner in allTask.Exception.InnerExceptions)
        {
            if (inner is TaskFailedException taskFailed)
            {
                // Use taskFailed.FailureDetails to inspect error details
                var errorType = taskFailed.FailureDetails.ErrorType;
                var errorMessage = taskFailed.FailureDetails.ErrorMessage;
            }
        }
    }
}

النموذج أثناء العملية

var tasks = new[]
{
    context.CallActivityAsync("Activity1", input1),
    context.CallActivityAsync("Activity2", input2),
    context.CallActivityAsync("Activity3", input3),
};

var allTask = Task.WhenAll(tasks);
try
{
    await allTask;
}
catch (FunctionFailedException)
{
    // 'await' rethrows only the first exception. To inspect all failures,
    // check allTask.Exception, which is an AggregateException.
    if (allTask.Exception != null)
    {
        foreach (var inner in allTask.Exception.InnerExceptions)
        {
            if (inner is FunctionFailedException funcFailed)
            {
                // Use funcFailed.InnerException to access the original exception
            }
        }
    }
}

التعامل مع الأخطاء في دوال الكيان

يعتمد التعامل مع الاستثناءات في دوال الكيان على نموذج استضافة Durable Functions:

نموذج العامل المعزول

في Durable Functions معزولة في C# ، يلف وقت التشغيل استثناءات دالة الكيان في EntityOperationFailedException. للحصول على تفاصيل الاستثناء الأصلية، قم بفحص العقار FailureDetails .

[Function(nameof(MyOrchestrator))]
public static async Task<List<string>> MyOrchestrator(
   [Microsoft.Azure.Functions.Worker.OrchestrationTrigger] TaskOrchestrationContext context)
{
    var entityId = new Microsoft.DurableTask.Entities.EntityInstanceId(nameof(Counter), "myCounter");
    try
    {
        await context.Entities.CallEntityAsync(entityId, "Add", 1);
    }
    catch (EntityOperationFailedException ex)
    {
        // Add your error handling
    }

    return new List<string>();
}

النموذج أثناء العملية

في Durable Functions مع C# قيد العملية، تعيد وظائف الكيان أنواع الاستثناءات الأصلية إلى المنسق.

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

df.app.orchestration("counterOrchestration", function* (context) {
    const entityId = new df.EntityId(counterEntityName, "myCounter");

    try {
        const currentValue = yield context.df.callEntity(entityId, "get");
        if (currentValue < 10) {
            yield context.df.callEntity(entityId, "add", 1);
        }
    } catch (err) {
        context.log(`Entity call failed: ${err.message ?? err}`);
    }
});

@myApp.orchestration_trigger(context_name="context")
def run_orchestrator(context):
    try:
        entityId = df.EntityId("Counter", "myCounter")
        yield context.call_entity(entityId, "get")
        return "finished"
    except Exception as e:
        # Add your error handling

عند استدعاء دوال النشاط أو دوال التنسيق الفرعي، حدد سياسة إعادة محاولة تلقائية. المثال التالي يستدعي دالة حتى ثلاث مرات وينتظر خمس ثوان بين محاولات:

نموذج العامل المعزول

[FunctionName("TimerOrchestratorWithRetry")]
public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext context)
{
    var options = TaskOptions.FromRetryPolicy(new RetryPolicy(
        maxNumberOfAttempts: 3,
        firstRetryInterval: TimeSpan.FromSeconds(5)));

    await context.CallActivityAsync("FlakyFunction", options: options);

    // ...
}

النموذج أثناء العملية

[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 versions.

نموذج البرمجة V3

const df = require("durable-functions");

module.exports = df.orchestrator(function*(context) {
    const firstRetryIntervalInMilliseconds = 5000;
    const maxNumberOfAttempts = 3;

    const retryOptions = 
        new df.RetryOptions(firstRetryIntervalInMilliseconds, maxNumberOfAttempts);

    yield context.df.callActivityWithRetry("FlakyFunction", retryOptions);

    // ...
});

نموذج البرمجة V4

const df = require("durable-functions");

df.app.orchestration("callActivityWithRetry", function* (context) {
    const firstRetryIntervalInMilliseconds = 5000;
    const maxNumberOfAttempts = 3;

    const retryOptions = new df.RetryOptions(firstRetryIntervalInMilliseconds, maxNumberOfAttempts);

    yield context.df.callActivityWithRetry("FlakyFunction", retryOptions);

    // ...
});

import azure.functions as func
import azure.durable_functions as df

def orchestrator_function(context: df.DurableOrchestrationContext):
    first_retry_interval_in_milliseconds = 5000
    max_number_of_attempts = 3

    retry_options = df.RetryOptions(first_retry_interval_in_milliseconds, max_number_of_attempts)

    yield context.call_activity_with_retry('FlakyFunction', retry_options)

main = df.Orchestrator.create(orchestrator_function)

param($Context)

$retryOptions = New-DurableRetryOptions `
                    -FirstRetryInterval (New-TimeSpan -Seconds 5) `
                    -MaxNumberOfAttempts 3

Invoke-DurableActivity -FunctionName 'FlakyFunction' -RetryOptions $retryOptions

@FunctionName("TimerOrchestratorWithRetry")
public void timerOrchestratorWithRetry(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    final int maxAttempts = 3;
    final Duration firstRetryInterval = Duration.ofSeconds(5);
    RetryPolicy policy = new RetryPolicy(maxAttempts, firstRetryInterval);
    TaskOptions options = new TaskOptions(policy);
    ctx.callActivity("FlakyFunction", options).await();
    // ...
}

استدعاء دالة النشاط في المثال السابق يستخدم معاملة لتكوين سياسة إعادة محاولة تلقائية. خصص الوثيقة بهذه الخيارات:

الحد الأقصى للمحاولات: الحد الأقصى لعدد المحاولات. إذا تم ضبطه على 1، لا تحدث أي محاولات جديدة.
الفاصل الزمني الأول لإعادة المحاولة: مقدار الوقت المطلوب الانتظار قبل محاولة إعادة المحاولة الأولى.
معامل التراجع: المعامل المستخدم لتحديد معدل زيادة التراجع. الإعدادات الافتراضية إلى 1.
أقصى فترة إعادة محاولة: أقصى مدة زمنية للانتظار بين محاولات إعادة المحاولة.
إعادة المحاولة: أقصى وقت يمكن قضاؤه في إعادة المحاولة. افتراضيا، تستمر المحاولات المتكررة إلى أجل غير مسمى.

تتضمن مجموعات تطوير المهام الدائمة طرق جدولة بديلة تعيد محاولة الأنشطة الفاشلة بناء على سياسة مقدمة. هذه الطرق مفيدة للأنشطة التي تقرأ البيانات من خدمات الويب أو تقوم بكتابة idempotent إلى قاعدة البيانات.

using Microsoft.DurableTask;

[DurableTask(nameof(OrchestratorWithRetry))]
public class OrchestratorWithRetry : TaskOrchestrator<string, string>
{
    public override async Task<string> RunAsync(
        TaskOrchestrationContext context, string input)
    {
        // Configure retry policy
        var retryPolicy = new RetryPolicy(
            maxNumberOfAttempts: 3,
            firstRetryInterval: TimeSpan.FromSeconds(5),
            backoffCoefficient: 2.0,
            maxRetryInterval: TimeSpan.FromMinutes(1),
            retryTimeout: TimeSpan.FromMinutes(5));

        var options = TaskOptions.FromRetryPolicy(retryPolicy);

        // Call activity with automatic retry
        string result = await context.CallActivityAsync<string>(
            nameof(UnreliableActivity), input, options);

        return result;
    }
}

import {
  OrchestrationContext,
  TOrchestrator,
  RetryPolicy,
} from "@microsoft/durabletask-js";

const retryPolicyOrchestrator: TOrchestrator = async function* (
  ctx: OrchestrationContext
): any {
  const retryPolicy = new RetryPolicy({
    maxNumberOfAttempts: 3,
    firstRetryIntervalInMilliseconds: 5000,
    backoffCoefficient: 2.0,
    maxRetryIntervalInMilliseconds: 60000,
  });

  const result: string = yield ctx.callActivity(
    unreliableActivity,
    ctx.getInput(),
    { retry: retryPolicy }
  );

  return result;
};

from durabletask import task
from durabletask.task import RetryPolicy

def orchestrator_with_retry(ctx: task.OrchestrationContext, input_data: str) -> str:
    """
    Orchestrator that demonstrates automatic retry on activity failure.
    """
    # Configure retry policy
    retry_policy = RetryPolicy(
        first_retry_interval=5,        # seconds
        max_number_of_attempts=3,
        backoff_coefficient=2.0,
        max_retry_interval=60,         # seconds
        retry_timeout=300              # seconds
    )

    # Call activity with automatic retry
    result = yield ctx.call_activity(
        "unreliable_activity",
        input=input_data,
        retry_policy=retry_policy
    )

    return result

import com.microsoft.durabletask.*;
import java.time.Duration;

public TaskOrchestration createOrchestratorWithRetry() {
    return ctx -> {
        String input = ctx.getInput(String.class);

        // Configure retry policy
        RetryPolicy retryPolicy = new RetryPolicy(
            3,                              // maxNumberOfAttempts
            Duration.ofSeconds(5),          // firstRetryInterval
            2.0,                            // backoffCoefficient
            Duration.ofMinutes(1),          // maxRetryInterval
            Duration.ofMinutes(5)           // retryTimeout
        );

        TaskOptions options = new TaskOptions(retryPolicy);

        // Call activity with automatic retry
        String result = ctx.callActivity(
            "UnreliableActivity", input, options, String.class).await();

        ctx.complete(result);
    };
}

خيارات سياسة إعادة المحاولة هي:

الحد الأقصى لعدد المحاولات: الحد الأقصى لمحاولات إعادة المحاولة. إذا تم ضبطه على 1، لا تحدث أي محاولات جديدة.
الفاصل الزمني الأول لإعادة المحاولة: مقدار الوقت المطلوب الانتظار قبل محاولة إعادة المحاولة الأولى.
معامل التراجع: المعامل المستخدم لتحديد معدل زيادة التراجع. الإعدادات الافتراضية إلى 1.
أقصى فترة إعادة محاولة: أقصى مدة زمنية للانتظار بين محاولات إعادة المحاولة.
مهلة إعادة المحاولة:الحد الأقصى لمقدار الوقت الذي تقضيه في إجراء عمليات إعادة المحاولة.

معالجات إعادة المحاولة المخصصة

في .NET و Java، ينفذ معالجات إعادة المحاولة في الكود عندما لا تكون سياسات إعادة المحاولة التصريحية معبرة بما فيه الكفاية. في لغات أخرى، نفذ منطق إعادة المحاولة باستخدام الحلقات، والتعامل مع الاستثناءات، والمؤقتات لتأخير المحاولات بين المحاولات.

نموذج العامل المعزول

TaskOptions retryOptions = TaskOptions.FromRetryHandler(retryContext =>
{
    // Don't retry anything that derives from ApplicationException
    if (retryContext.LastFailure.IsCausedBy<ApplicationException>())
    {
        return false;
    }

    // Quit after N attempts
    return retryContext.LastAttemptNumber < 3;
});

try
{
    await ctx.CallActivityAsync("FlakeyActivity", options: retryOptions);
}
catch (TaskFailedException)
{
    // Case when the retry handler returns false...
}

النموذج أثناء العملية

RetryOptions retryOptions = new RetryOptions(
    firstRetryInterval: TimeSpan.FromSeconds(5),
    maxNumberOfAttempts: int.MaxValue)
{
    Handle = exception =>
    {
        // Return true to handle and retry, or false to throw.
        if (exception is TaskFailedException failure)
        {
            // Exceptions from task activities are always this type. Inspect the
            // inner exception for more details.
        }

        return false;
    }
};

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

RetryHandler retryHandler = retryCtx -> {
    // Don't retry anything that derives from RuntimeException
    if (retryCtx.getLastFailure().isCausedBy(RuntimeException.class)) {
        return false;
    }

    // Quit after N attempts
    return retryCtx.getLastAttemptNumber() < 3;
};

TaskOptions options = new TaskOptions(retryHandler);
try {
    ctx.callActivity("FlakeyActivity", options).await();
} catch (TaskFailedException ex) {
    // Case when the retry handler returns false...
}

معالجات إعادة المحاولة المخصصة

في .NET و Java، نفذ معالجات إعادة المحاولة في الكود للتحكم في منطق إعادة المحاولة. هذا النهج مفيد عندما لا تكون سياسات إعادة المحاولة التصريحية معبرة بما فيه الكفاية.

using Microsoft.DurableTask;

[DurableTask(nameof(OrchestratorWithCustomRetry))]
public class OrchestratorWithCustomRetry : TaskOrchestrator<string, string>
{
    public override async Task<string> RunAsync(
        TaskOrchestrationContext context, string input)
    {
        // Custom retry handler with conditional logic
        TaskOptions retryOptions = TaskOptions.FromRetryHandler(retryContext =>
        {
            // Don't retry if it's a validation error
            if (retryContext.LastFailure.IsCausedBy<ArgumentException>())
            {
                return false;
            }

            // Retry up to 5 times for transient errors
            return retryContext.LastAttemptNumber < 5;
        });

        try
        {
            return await context.CallActivityAsync<string>(
                nameof(UnreliableActivity), input, retryOptions);
        }
        catch (TaskFailedException)
        {
            // All retries exhausted
            return "Operation failed after all retries";
        }
    }
}

import {
  OrchestrationContext,
  TOrchestrator,
} from "@microsoft/durabletask-js";
import type { RetryHandler, RetryContext } from "@microsoft/durabletask-js";

const customRetryHandlerOrchestrator: TOrchestrator = async function* (
  ctx: OrchestrationContext
): any {
  const maxAttempts = 4;

  const customRetryHandler: RetryHandler = (retryCtx: RetryContext) => {
    if (retryCtx.lastAttemptNumber >= maxAttempts) {
      return false; // give up
    }
    // Only retry transient errors
    if (!retryCtx.lastFailure.message?.includes("TransientError")) {
      return false;
    }
    return true; // retry immediately
  };

  const result: string = yield ctx.callActivity(
    unreliableActivity,
    ctx.getInput(),
    { retry: customRetryHandler }
  );

  return result;
};

معالجات إعادة المحاولة المخصصة غير مدعومة في Python. نفذ منطق إعادة المحاولة المخصص باستخدام الحلقات، والتعامل مع الاستثناءات، والمؤقتات:

import datetime
from durabletask import task

def orchestrator_with_custom_retry(ctx: task.OrchestrationContext, input_data: str) -> str:
    """
    Orchestrator that demonstrates custom retry logic.
    """
    max_attempts = 5
    retry_interval_seconds = 5

    for attempt in range(1, max_attempts + 1):
        try:
            result = yield ctx.call_activity("unreliable_activity", input=input_data)
            return result
        except task.TaskFailedError as ex:
            if attempt >= max_attempts:
                return f"Operation failed after {max_attempts} attempts"

            # Wait before retrying
            next_retry = ctx.current_utc_datetime + datetime.timedelta(seconds=retry_interval_seconds)
            yield ctx.create_timer(next_retry)

    return "Unexpected error"

import com.microsoft.durabletask.*;

public TaskOrchestration createOrchestratorWithCustomRetry() {
    return ctx -> {
        String input = ctx.getInput(String.class);

        // Custom retry handler with conditional logic
        RetryHandler retryHandler = retryContext -> {
            // Don't retry validation errors
            if (retryContext.getLastFailure().isCausedBy(IllegalArgumentException.class)) {
                return false;
            }

            // Retry up to 5 times for transient errors
            return retryContext.getLastAttemptNumber() < 5;
        };

        TaskOptions options = new TaskOptions(retryHandler);

        try {
            String result = ctx.callActivity("UnreliableActivity", input, options, String.class).await();
            ctx.complete(result);
        } catch (TaskFailedException ex) {
            // All retries exhausted
            ctx.complete("Operation failed after all retries");
        }
    };
}

مهلات الدوال

إذا استغرقت استدعاء الوظيفة وقتا طويلا، قم بإيقاف الوقت في وظيفة المنسق. أنشئ مؤقتا متينا باستخدام any محدد مهام، كما في المثال التالي:

نموذج العامل المعزول

[Function("TimerOrchestrator")]
public static async Task<bool> Run([OrchestrationTrigger] TaskOrchestrationContext 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;
        }
    }
}

النموذج أثناء العملية

[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 versions.

نموذج البرمجة V3

const df = require("durable-functions");
const moment = require("moment");

module.exports = df.orchestrator(function*(context) {
    const deadline = moment.utc(context.df.currentUtcDateTime).add(30, "s");

    const activityTask = context.df.callActivity("FlakyFunction");
    const timeoutTask = context.df.createTimer(deadline.toDate());

    const winner = yield context.df.Task.any([activityTask, timeoutTask]);
    if (winner === activityTask) {
        // success case
        timeoutTask.cancel();
        return true;
    } else {
        // timeout case
        return false;
    }
});

نموذج البرمجة V4

const df = require("durable-functions");
const { DateTime } = require("luxon");

df.app.orchestration("timerOrchestrator", function* (context) {
    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime).plus({ seconds: 30 });

    const activityTask = context.df.callActivity("FlakyFunction");
    const timeoutTask = context.df.createTimer(deadline.toJSDate());

    const winner = yield context.df.Task.any([activityTask, timeoutTask]);
    if (winner === activityTask) {
        // success case
        timeoutTask.cancel();
        return true;
    } else {
        // timeout case
        return false;
    }
});

import azure.functions as func
import azure.durable_functions as df
from datetime import datetime, timedelta

def orchestrator_function(context: df.DurableOrchestrationContext):
    deadline = context.current_utc_datetime + timedelta(seconds = 30)

    activity_task = context.call_activity('FlakyFunction')
    timeout_task = context.create_timer(deadline)

    winner = yield context.task_any([activity_task, timeout_task])
    if winner == activity_task:
        timeout_task.cancel()
        return True
    else:
        return False

main = df.Orchestrator.create(orchestrator_function)

param($Context)

$expiryTime = New-TimeSpan -Seconds 30

$activityTask = Invoke-DurableActivity -FunctionName 'FlakyFunction' -NoWait
$timerTask = Start-DurableTimer -Duration $expiryTime -NoWait

$winner = Wait-DurableTask -Task @($activityTask, $timerTask) -NoWait

if ($winner -eq $activityTask) {
    Stop-DurableTimerTask -Task $timerTask
    return $True
}
else {
    return $False
}

@FunctionName("TimerOrchestrator")
public boolean timerOrchestrator(
        @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {
    Task<Void> activityTask = ctx.callActivity("FlakyFunction");
    Task<Void> timeoutTask = ctx.createTimer(Duration.ofSeconds(30));

    Task<?> winner = ctx.anyOf(activityTask, timeoutTask).await();
    if (winner == activityTask) {
        // success case
        return true;
    } else {
        // timeout case
        return false;
    }
}

ملحوظة

هذه الآلية لا تنهي تنفيذ دالة النشاط التي هي جارية بالفعل. يسمح لوظيفة التنسيق بتجاهل النتيجة والمضي قدما. لمزيد من المعلومات، راجع المؤقتات.

مهلات النشاط

إذا استغرقت مكالمة النشاط وقتا طويلا، يمكنك التوقف عن انتظارها. أنشئ مؤقتا متيما وتنافس عليه مع مهمة النشاط.

using Microsoft.DurableTask;
using System;
using System.Threading;
using System.Threading.Tasks;

[DurableTask(nameof(OrchestratorWithTimeout))]
public class OrchestratorWithTimeout : TaskOrchestrator<string, bool>
{
    public override async Task<bool> RunAsync(
        TaskOrchestrationContext context, string input)
    {
        TimeSpan timeout = TimeSpan.FromSeconds(30);
        DateTime deadline = context.CurrentUtcDateTime.Add(timeout);

        using var cts = new CancellationTokenSource();
        Task activityTask = context.CallActivityAsync(nameof(SlowActivity), input);
        Task timeoutTask = context.CreateTimer(deadline, cts.Token);

        Task winner = await Task.WhenAny(activityTask, timeoutTask);
        if (winner == activityTask)
        {
            // Activity completed in time - cancel the timer
            cts.Cancel();
            return true;
        }
        else
        {
            // Timeout occurred
            return false;
        }
    }
}

import {
  OrchestrationContext,
  TOrchestrator,
} from "@microsoft/durabletask-js";

const orchestratorWithTimeout: TOrchestrator = async function* (
  ctx: OrchestrationContext
): any {
  const timeoutSeconds = 30;

  // Start both the activity and a timeout timer
  const activityTask = ctx.callActivity(slowActivity, ctx.getInput());
  const timeoutTask = ctx.createTimer(timeoutSeconds);

  // Wait for whichever completes first
  const winner = yield ctx.whenAny([activityTask, timeoutTask]);

  if (winner === activityTask) {
    // Activity completed in time
    return true;
  } else {
    // Timeout occurred
    return false;
  }
};

import datetime
from durabletask import task

def orchestrator_with_timeout(ctx: task.OrchestrationContext, input_data: str) -> bool:
    """
    Orchestrator that demonstrates activity timeout using a timer.
    """
    timeout_seconds = 30
    deadline = ctx.current_utc_datetime + datetime.timedelta(seconds=timeout_seconds)

    # Create both tasks
    activity_task = ctx.call_activity("slow_activity", input=input_data)
    timeout_task = ctx.create_timer(deadline)

    # Wait for whichever completes first
    winner = yield task.when_any([activity_task, timeout_task])

    if winner == activity_task:
        # Activity completed in time
        return True
    else:
        # Timeout occurred
        return False

import com.microsoft.durabletask.*;
import java.time.Duration;

public TaskOrchestration createOrchestratorWithTimeout() {
    return ctx -> {
        String input = ctx.getInput(String.class);

        // Create activity task
        Task<String> activityTask = ctx.callActivity("SlowActivity", input, String.class);

        // Create timeout timer (30 seconds)
        Task<Void> timeoutTask = ctx.createTimer(Duration.ofSeconds(30));

        // Wait for whichever completes first
        Task<?> winner = ctx.anyOf(activityTask, timeoutTask).await();

        if (winner == activityTask) {
            // Activity completed in time
            ctx.complete(true);
        } else {
            // Timeout occurred
            ctx.complete(false);
        }
    };
}

ملحوظة

هذه الآلية لا تنهي تنفيذ النشاط الذي هو بالفعل جار. يسمح للموزع بتجاهل النتيجة والمضي قدما. لمزيد من المعلومات، راجع وثائق Timers.

استثناء غير معالج

إذا فشلت وظيفة المنسق مع استثناء غير معالج، يسجل وقت التشغيل تفاصيل الاستثناء، ويكتمل المثيل بحالة معينة Failed .

تضمين خصائص الاستثناءات المخصصة ل FailureDetails

في سير عمل المهام الدائمة، يتم تسلسل فشل المهام إلى FailureDetails كائن. افتراضيا، يتضمن الكائن هذه الحقول:

ErrorType—اسم نوع الاستثناء
Message—رسالة الاستثناء
StackTrace—تتبع المكدس المتسلسل
InnerFailure—كائن متداخل FailureDetails للاستثناءات الداخلية

يمكنك توسيع هذا السلوك ليشمل خصائص استثناءات إضافية ومخصصة في القاموس FailureDetails.Properties عن طريق تسجيل مزود خصائص الاستثناءات المخصصة.

ملحوظة

هذه الميزة متوفرة بصيغة .NET المعزولةوجافا سكريبت فقط. دعم Python وPowerShell وJava غير متوفر بعد.

بدءا من مايكروسوفت. Azure. Functions.Worker.Extensions.DurableTask v1.9.0، يمكنك توسيع هذا السلوك بتنفيذ IExceptionPropertiesProvider (المعرفة في حزمة Microsoft.DurableTask.Worker بدءا من v1.16.1). يحدد هذا المزود أنواع الاستثناءات والخصائص التي يجب تضمينها في FailureDetails.Properties القاموس.

ملحوظة

تأكد من أنك تستخدم Microsoft. Azure. Functions.Worker.Extensions.DurableTask v1.9.0 أو أحدث.
تأكد من أنك تستخدم Microsoft.DurableTask.Worker v1.16.1 أو أحدث.

تنفيذ مزود خصائص الاستثناء

نفذ تخصيصا IExceptionPropertiesProvider لاستخراج وإرجاع الخصائص المختارة للاستثناءات التي تهمك. يتم تسلسل القاموس المرتجع إلى Properties حقل عندما FailureDetails يتم رمي نوع استثناء مطابق.

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

سجل المزود

في Program.cs، سجل IExceptionPropertiesProvider المخصص في مضيف العامل المعزول .NET الخاص بك:

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

في نموذج البرمجة V4 Node.js، يمكنك توسيع هذا السلوك عن طريق تسجيل مزود خصائص الاستثناء العالمية ب df.app.setExceptionPropertiesProvider(...). يستخرج المزود حقول مختارة من الاستثناءات المرمية، وينشرها عامل الدائم على FailureDetails.Properties القاموس. ارجع undefined للانسحاب بسبب خطأ معين.

ملحوظة

df.app.setExceptionPropertiesProvider تتطلب واجهة برمجة التطبيقات إصدار 3.4.0 أو إصدار أحدث من durable-functions حزمة npm والإصدار 3.13.0 أو الإصدار اللاحق من Microsoft.Azure.WebJobs.Extensions.DurableTask الامتداد. حتى تتوفر النسخة 3.13.0 في حزم الإضافات، قم بتثبيت الامتداد يدويا.

انظر متى تتوفر إصدارات الإصدار لحزمة الامتدادات.

سجل المزود

حدد نوع استثناء مخصص يحمل الحقول المهيكلة، وسجل مزود عالمي يعرض تلك الحقول، والتقاط الموزع TaskFailedError في التنسيق للوصول إلى الخصائص المخصصة.

const { app } = require("@azure/functions");
const df = require("durable-functions");
const { TaskFailedError } = df;

// Custom exception carrying structured properties.
class BusinessValidationException extends Error {
    constructor(
        message,
        stringProperty,
        intProperty,
        longProperty,
        dateTimeProperty,
        dictionaryProperty,
        listProperty,
        nullProperty
    ) {
        super(message);
        this.name = "BusinessValidationException";
        // Fix the prototype chain (necessary when extending built-ins).
        Object.setPrototypeOf(this, new.target.prototype);
        this.stringProperty = stringProperty;
        this.intProperty = intProperty;
        this.longProperty = longProperty;
        this.dateTimeProperty = dateTimeProperty;
        this.dictionaryProperty = dictionaryProperty;
        this.listProperty = listProperty;
        this.nullProperty = nullProperty;
    }
}

// Register a global provider that surfaces custom properties from thrown
// exceptions into FailureDetails.Properties. Return `undefined` to opt out
// for a particular error.
df.app.setExceptionPropertiesProvider({
    getExceptionProperties(error) {
        if (error instanceof BusinessValidationException) {
            return {
                StringProperty: error.stringProperty,
                IntProperty: error.intProperty,
                LongProperty: error.longProperty,
                DateTimeProperty: error.dateTimeProperty,
                DictionaryProperty: error.dictionaryProperty,
                ListProperty: error.listProperty,
                NullProperty: error.nullProperty,
            };
        }
        return undefined;
    },
});

// Activity: throws an exception carrying custom properties.
df.app.activity("businessActivity", {
    handler: () => {
        throw new BusinessValidationException(
            "Business logic validation failed",
            "validation-error-123",
            100,
            999999999,
            "2025-10-15T14:30:00.000Z",
            {
                error_code: "VALIDATION_FAILED",
                retry_count: 3,
                is_critical: true,
            },
            ["error1", "error2", 500, null],
            null
        );
    },
});

// Orchestrator: calls the activity, catches the propagated TaskFailedError,
// and returns its FailureDetails (which includes the custom Properties).
df.app.orchestration("orchestrationWithCustomException", function* (context) {
    try {
        yield context.df.callActivity("businessActivity");
    } catch (e) {
        if (e instanceof TaskFailedError) {
            return e.failureDetails;
        }
        throw e;
    }
    // Should never reach here — the activity always throws.
    return null;
});

فشل العينةتفاصيل المخرجات

عندما يرمي النشاط استثناء يطابق مزود الخدمة الخاص بك، يتلقى التنسيق كائنا FailureDetails يحمل properties القيم المخصصة:

{
  "errorType": "BusinessValidationException",
  "errorMessage": "Business logic validation failed",
  "properties": {
    "StringProperty": "validation-error-123",
    "IntProperty": 100,
    "LongProperty": 999999999,
    "DateTimeProperty": "2025-10-15T14:30:00.000Z",
    "DictionaryProperty": {
      "error_code": "VALIDATION_FAILED",
      "retry_count": 3,
      "is_critical": true
    },
    "ListProperty": ["error1", "error2", 500, null],
    "NullProperty": null
  }
}

استثناء غير معالج

إذا فشل الأوركستراتور بسبب استثناء لم يتم التعامل معه، يقوم وقت التشغيل بتسجيل تفاصيل الاستثناء، وتكتمل الحالة بالحالة Failed . يحتوي على TaskFailedException خاصية FailureDetails تتضمن نوع الخطأ، الرسالة، وتتبع المكدس.

التوزيع الأبدي

مشاكل التشخيص

ابدأ مع مجموعات تطوير المهام الدائمة