Azure Functions Intermediate

Durable Functions: orchestrators and activities

Durable Functions lets you write long-running, stateful workflows as ordinary C# code. An orchestrator calls activities, waits for results or events, and the framework saves its progress so it survives restarts.

How an orchestration runs
  1. StartClient starts instanceAn HTTP call schedules RunOnboarding.
  2. Step 2Orchestrator runsIt schedules CreateAccount and pauses.
  3. Step 3Activity completesThe result is saved to history.
  4. Step 4Orchestrator replaysHistory returns the result; the next step runs.
  5. EndInstance completesStatus and output are stored.

Replay is why orchestrator code must be deterministic.

The three kinds of function

  • Client function: starts orchestrations and queries them, for example from an HTTP or queue trigger.
  • Orchestrator function: the workflow. It decides what runs next and in what order.
  • Activity function: does the real work, such as calling an API, writing to a database or sending an email.

A first orchestration

C#
public static class Onboarding
{
    [Function(nameof(StartOnboarding))]
    public static async Task<HttpResponseData> StartOnboarding(
        [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req,
        [DurableClient] DurableTaskClient client)
    {
        var user = await req.ReadFromJsonAsync<NewUser>();
        string id = await client.ScheduleNewOrchestrationInstanceAsync(nameof(RunOnboarding), user);
        return await client.CreateCheckStatusResponseAsync(req, id);
    }

    [Function(nameof(RunOnboarding))]
    public static async Task<string> RunOnboarding([OrchestrationTrigger] TaskOrchestrationContext context)
    {
        var user = context.GetInput<NewUser>()!;
        await context.CallActivityAsync(nameof(CreateAccount), user);
        await context.CallActivityAsync(nameof(SendWelcomeEmail), user.Email);
        return "done";
    }

    [Function(nameof(CreateAccount))]
    public static Task CreateAccount([ActivityTrigger] NewUser user) => Task.CompletedTask;

    [Function(nameof(SendWelcomeEmail))]
    public static Task SendWelcomeEmail([ActivityTrigger] string email) => Task.CompletedTask;
}

Replay and the determinism rules

The orchestrator does not stay in memory while it waits. Each time an activity finishes, the framework replays the orchestrator from the start, using the saved history to return results it already has. That is why orchestrator code must give the same decisions every time it runs.

  • Use context.CurrentUtcDateTime, not DateTime.UtcNow.
  • Use context.NewGuid(), not Guid.NewGuid().
  • No I/O in the orchestrator: no HTTP, database or file calls. Put them in activities.
  • Use context.CreateTimer for delays, never Task.Delay or Thread.Sleep.
  • Log with context.CreateReplaySafeLogger so logs are not repeated on replay.

State and status

Progress is stored by a storage provider: Azure Storage by default, or others such as the Durable Task Scheduler or Microsoft SQL. CreateCheckStatusResponseAsync returns 202 with URLs to check status, send events or terminate the instance.

Interview question

Why must Durable Functions orchestrator code be deterministic?

Because the orchestrator is replayed from the start every time it resumes. The framework uses the recorded history to return results of completed activities, so the code must make the same calls in the same order each time. Non-deterministic calls like DateTime.UtcNow, Guid.NewGuid, random numbers or direct I/O would break the replay, so I use the context APIs and put I/O in activities.

Your progress is saved only in this browser.

Want the full details? Read the official Microsoft documentation for this topic.