Acta. Durable execution for .NET

learn actamake work survive a crash

How to feed one step's result into the next

A step can return a value. Each result is recorded once, so the next step takes it as its input and a replay rebuilds the chain from the records.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/200-durable-execution/206-step-chain
Read as

1Return a value from a step

Typed durable steps: each result is recorded once, so on replay the chain rebuilds from recorded outputs and no step re-runs. A body that returns null, or a result over MaxInlinePayloadBytes, fails the job for good, since a retry would run the finished body again.

step-chain.csexcerpt
var fetched = await context.RunStepAsync(
    "fetch",
    async inner =>
    {
        await Task.Delay(50, inner);
        Console.WriteLine($"[{doc.DocId}] fetched");
        return new FetchedDocument(doc.DocId, 4096);
    },
    ct
);

2Use it in the next step

step-chain.csexcerpt
var extracted = await context.RunStepAsync(
    "extract-text",
    async inner =>
    {
        await Task.Delay(50, inner);
        Console.WriteLine($"[{doc.DocId}] extracted text from {fetched.Bytes} bytes");
        return new ExtractedText(doc.DocId, 600);
    },
    ct
);

3Run it and check the output

From a clone of the Acta repository, with the .NET 10 SDK:

Terminal
dotnet run --project learn/200-durable-execution/206-step-chain
Its output must contain
[guide.pdf] done -> 4096 bytes, 600 words, summary "600-word digest"

Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.

This page shows the code. The rules it relies on, starting with the handler running again from its first line, are in the handler contract.

The whole program

Every file of learn/200-durable-execution/206-step-chain, as it is compiled.

UseLocalDatabase is a helper of the Acta repository, not of the packages. In your own app, register the database with UseSqlite, UsePostgres or UseSqlServer, as in how to run your first job.

step-chain.cs86 lines
step-chain.cs
// How to feed one step's result into the next
// A step can return a value. Each result is recorded once, so the next step takes it as its input and a replay
// rebuilds the chain from the records.
using Acta;
using Acta.Learn.StepChain;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<StepChainJobs>("step-chain");
});

using var host = builder.Build();
await host.StartAsync();

var jobs = host.Services.GetRequiredService<IJobs>();

await jobs.EnqueueAsync(new IndexDocument("guide.pdf"));
Console.WriteLine("Enqueued. Worker is running - press Ctrl+C to stop.");

await host.WaitForShutdownAsync();
await host.StopAsync();

namespace Acta.Learn.StepChain
{
    public sealed record IndexDocument(string DocId);

    public sealed record FetchedDocument(string DocId, int Bytes);

    public sealed record ExtractedText(string DocId, int Words);

    public sealed record Summary(string DocId, string Text);

    public sealed class IndexDocumentJob
    {
        [Job("index-document")]
        public async Task Handle(IndexDocument doc, JobContext context, CancellationToken ct)
        {
            // learn: 1. Return a value from a step
            // Typed durable steps: each result is recorded once, so on replay the chain rebuilds from recorded outputs
            // and no step re-runs. A body that returns null, or a result over `MaxInlinePayloadBytes`, fails the job
            // for good, since a retry would run the finished body again.
            var fetched = await context.RunStepAsync(
                "fetch",
                async inner =>
                {
                    await Task.Delay(50, inner);
                    Console.WriteLine($"[{doc.DocId}] fetched");
                    return new FetchedDocument(doc.DocId, 4096);
                },
                ct
            );
            // learn: end

            // learn: 2. Use it in the next step
            var extracted = await context.RunStepAsync(
                "extract-text",
                async inner =>
                {
                    await Task.Delay(50, inner);
                    Console.WriteLine($"[{doc.DocId}] extracted text from {fetched.Bytes} bytes");
                    return new ExtractedText(doc.DocId, 600);
                },
                ct
            );
            // learn: end

            var summary = await context.RunStepAsync(
                "summarize",
                async inner =>
                {
                    await Task.Delay(50, inner);
                    Console.WriteLine($"[{doc.DocId}] summarized {extracted.Words} words");
                    return new Summary(doc.DocId, $"{extracted.Words}-word digest");
                },
                ct
            );

            Console.WriteLine($"[{doc.DocId}] done -> {fetched.Bytes} bytes, {extracted.Words} words, summary \"{summary.Text}\"");
        }
    }
}

Where to go next

New to Acta?

Acta is durable execution for .NET: workflows and jobs that survive restarts, as a library inside your application with its durable state in your SQL database.