Acta. Durable execution for .NET

learn actasplit work across child jobs

How to chain jobs into a pipeline

Each stage is a job of its own that enqueues the next one, with a deduplication key so a replayed handoff starts no second pipeline.

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

Checked every release learn/600-job-composition/602-chained-jobs
Read as

1Enqueue the next stage as the last act of this one

The enqueue happens before this stage completes, so a replay repeats it. The key, taken from the document, makes the repeat answer the existing job.

chained-jobs.csexcerpt
public sealed class IngestDocumentJob(IJobs jobs)
{
    [Job("ingest-document")]
    public async Task Handle(IngestDocument input, CancellationToken ct)
    {
        Console.WriteLine($"ingested {input.FileName}");
        await jobs.EnqueueAsync(new RenderPdf(input.FileName), o => o.DeduplicationKey($"render-{input.FileName}"), ct);
    }
}

2Let the next stage hand on the same way

Every stage enqueues the one after it under a key of its own; the last stage enqueues nothing.

chained-jobs.csexcerpt
public sealed class RenderPdfJob(IJobs jobs)
{
    [Job("render-pdf")]
    public async Task Handle(RenderPdf input, CancellationToken ct)
    {
        Console.WriteLine($"rendered {input.FileName} -> PDF");
        await jobs.EnqueueAsync(new ArchiveFile(input.FileName), o => o.DeduplicationKey($"archive-{input.FileName}"), ct);
    }
}

3Run it and check the output

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

Terminal
dotnet run --project learn/600-job-composition/602-chained-jobs
Its output must contain
ingested report.md
rendered report.md -> PDF
archived report.md - pipeline done

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/600-job-composition/602-chained-jobs, 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.

chained-jobs.cs76 lines
chained-jobs.cs
// How to chain jobs into a pipeline
// Each stage is a job of its own that enqueues the next one, with a deduplication key so a replayed handoff starts
// no second pipeline.
using Acta;
using Acta.Learn.ChainedJobs;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ChainedJobsManifest>("chained-jobs");
});

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

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

await jobs.EnqueueAsync(new IngestDocument("report.md"));
Console.WriteLine("Enqueued the first stage. Worker is running - press Ctrl+C to stop.");

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

namespace Acta.Learn.ChainedJobs
{
    // Each stage enqueues the next. Unlike 206's in-handler step chain, every stage is its own durable
    // job, so a crash mid-pipeline re-runs only the in-flight stage; stages already finished are not
    // re-executed.
    //
    // What a crash CAN repeat is the handoff itself. The enqueue happens before the stage completes,
    // so a replay enqueues the next stage again. Each handoff therefore carries a deduplication key
    // derived from the document, which makes the replay return the existing job rather than a second
    // pipeline running beside the first.
    public sealed record IngestDocument(string FileName);

    public sealed record RenderPdf(string FileName);

    public sealed record ArchiveFile(string FileName);

    public sealed class IngestDocumentJob(IJobs jobs)
    {
        [Job("ingest-document")]
        public async Task Handle(IngestDocument input, CancellationToken ct)
        {
            Console.WriteLine($"ingested {input.FileName}");
            // learn: 1. Enqueue the next stage as the last act of this one
            // The enqueue happens before this stage completes, so a replay repeats it. The key, taken from the
            // document, makes the repeat answer the existing job.
            await jobs.EnqueueAsync(new RenderPdf(input.FileName), o => o.DeduplicationKey($"render-{input.FileName}"), ct);
            // learn: end
        }
    }

    public sealed class RenderPdfJob(IJobs jobs)
    {
        [Job("render-pdf")]
        public async Task Handle(RenderPdf input, CancellationToken ct)
        {
            Console.WriteLine($"rendered {input.FileName} -> PDF");
            // learn: 2. Let the next stage hand on the same way
            // Every stage enqueues the one after it under a key of its own; the last stage enqueues nothing.
            await jobs.EnqueueAsync(new ArchiveFile(input.FileName), o => o.DeduplicationKey($"archive-{input.FileName}"), ct);
            // learn: end
        }
    }

    public static class ArchiveFileJob
    {
        [Job("archive-file")]
        public static void Handle(ArchiveFile input) => Console.WriteLine($"archived {input.FileName} - pipeline done");
    }
}

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.