Acta. Durable execution for .NET

learn actatake the first steps

How to start a job from an HTTP endpoint and poll it

A POST stores the job and answers 202 with its ref; a GET reads the status and, once the job has finished, the result.

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

Checked every release learn/000-fundamentals/024-aspnet-enqueue-api
Read as

1Enqueue in the POST and answer 202 with the job's ref

The job is a durable row before the response leaves, and the worker runs it after the request has ended. The ref goes into the address the client polls.

Program.csexcerpt
// POST writes a durable job and returns 202; the import runs on the worker after the request ends.
// DeduplicationKey dedupes a retry with the same tenant/import id onto the same job.
app.MapPost("/imports", async (StartImportRequest request, HttpContext http, IJobs jobs, CancellationToken ct) =>
{
    var businessKey = $"import:{request.Tenant}:{request.ImportId}";
    var deduplicationKey = DeduplicationKey.ForDefinition("import-csv", businessKey);
    var correlationKey = http.TraceIdentifier;

    var job = await jobs.EnqueueAsync(
        new ImportCsv(request.Tenant, request.ImportId, request.FileName),
        o => o.DeduplicationKey(deduplicationKey).CorrelationKey(correlationKey).Tag("tenant", request.Tenant).Tag("kind", "csv"),
        ct
    );
 
    var statusUrl = $"/imports/{job.JobRef}";
 
    return Results.Accepted(statusUrl, new StartImportResponse(job.JobRef, job.Action.ToString(), statusUrl, correlationKey));
});

2Read the status, and the result once the job has finished

GetAsync answers null for a ref that names no job. A result exists only once the job has succeeded, so the endpoint reads it only when the status is terminal; neither read waits. parsed is the route's text turned into a JobRef by JobRef.TryParse.

Program.csexcerpt
if (!JobRef.TryParse(jobRef, out var parsed))
{
    return Results.BadRequest(new { error = "Invalid job ref." });
}

var snapshot = await jobs.GetAsync(parsed, ct);
if (snapshot is null)
{
    return Results.NotFound();
}
 
ImportResult? result = null;
if (snapshot.Status.IsFinished)
{
    (_, result) = await jobs.TryGetResultAsync<ImportResult>(parsed, ct);
}

3The job it acts on

Program.csexcerpt
public static class ImportCsvJob
{
    [Job("import-csv")]
    public static async Task<ImportResult> Handle(ImportCsv input, CancellationToken ct)
    {
        Console.WriteLine($"[{input.Tenant}] importing {input.FileName} ({input.ImportId})");
        await Task.Delay(750, ct);
        return new ImportResult(RowsImported: 42);
    }
}

4Run it and check the output

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

Terminal
dotnet run --project learn/000-fundamentals/024-aspnet-enqueue-api
Its output must contain
Then poll GET /imports/{jobRef}

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/000-fundamentals/024-aspnet-enqueue-api, 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.

Program.cs111 lines
Program.cs
// How to start a job from an HTTP endpoint and poll it
// A POST stores the job and answers 202 with its ref; a GET reads the status and, once the job has finished, the
// result.
using Acta;
using Acta.Learn.AspNetEnqueueApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<AspNetEnqueueApiJobs>("aspnet-enqueue-api");
});

var app = builder.Build();

// POST writes a durable job and returns 202; the import runs on the worker after the request ends.
// DeduplicationKey dedupes a retry with the same tenant/import id onto the same job.
app.MapPost("/imports", async (StartImportRequest request, HttpContext http, IJobs jobs, CancellationToken ct) =>
{
    var businessKey = $"import:{request.Tenant}:{request.ImportId}";
    var deduplicationKey = DeduplicationKey.ForDefinition("import-csv", businessKey);
    var correlationKey = http.TraceIdentifier;

    // learn: 1. Enqueue in the POST and answer 202 with the job's ref
    // The job is a durable row before the response leaves, and the worker runs it after the request has ended. The
    // ref goes into the address the client polls.
    var job = await jobs.EnqueueAsync(
        new ImportCsv(request.Tenant, request.ImportId, request.FileName),
        o => o.DeduplicationKey(deduplicationKey).CorrelationKey(correlationKey).Tag("tenant", request.Tenant).Tag("kind", "csv"),
        ct
    );
 
    var statusUrl = $"/imports/{job.JobRef}";
 
    return Results.Accepted(statusUrl, new StartImportResponse(job.JobRef, job.Action.ToString(), statusUrl, correlationKey));
    // learn: end
});

// GET polls the public JobRef; the result is read back only once the job is terminal.
app.MapGet("/imports/{jobRef}", async (string jobRef, IJobs jobs, CancellationToken ct) =>
{
    if (!JobRef.TryParse(jobRef, out var parsed))
    {
        return Results.BadRequest(new { error = "Invalid job ref." });
    }

    // learn: 2. Read the status, and the result once the job has finished
    // `GetAsync` answers null for a ref that names no job. A result exists only once the job has succeeded, so the
    // endpoint reads it only when the status is terminal; neither read waits. `parsed` is the route's text turned
    // into a `JobRef` by `JobRef.TryParse`.
    var snapshot = await jobs.GetAsync(parsed, ct);
    if (snapshot is null)
    {
        return Results.NotFound();
    }
 
    ImportResult? result = null;
    if (snapshot.Status.IsFinished)
    {
        (_, result) = await jobs.TryGetResultAsync<ImportResult>(parsed, ct);
    }
    // learn: end

    return Results.Ok(
        new ImportStatusResponse(
            snapshot.JobRef,
            snapshot.Status.ToString(),
            snapshot.DeduplicationKey,
            snapshot.CreatedAtUtc,
            snapshot.ModifiedAtUtc,
            result
        )
    );
});

Console.WriteLine("POST /imports with { \"tenant\": \"acme\", \"importId\": \"2026-06\", \"fileName\": \"customers.csv\" }");
Console.WriteLine("Then poll GET /imports/{jobRef}");

await app.RunAsync();

namespace Acta.Learn.AspNetEnqueueApi
{
    public sealed record StartImportRequest(string Tenant, string ImportId, string FileName);

    public sealed record StartImportResponse(JobRef JobRef, string Action, string StatusUrl, string CorrelationKey);

    public sealed record ImportStatusResponse(
        JobRef JobRef,
        string Status,
        string? DeduplicationKey,
        DateTime CreatedAtUtc,
        DateTime ModifiedAtUtc,
        ImportResult? Result
    );

    public sealed record ImportCsv(string Tenant, string ImportId, string FileName);

    public sealed record ImportResult(int RowsImported);

    public static class ImportCsvJob
    {
        [Job("import-csv")]
        public static async Task<ImportResult> Handle(ImportCsv input, CancellationToken ct)
        {
            Console.WriteLine($"[{input.Tenant}] importing {input.FileName} ({input.ImportId})");
            await Task.Delay(750, ct);
            return new ImportResult(RowsImported: 42);
        }
    }
}

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.