Acta. Durable execution for .NET

learn actawatch and control running work

How to show where each job is on your own page

IJobs reads one job for a page of your own: its status, a value the handler keeps for the screen, and a sentence that says why the job is where it is.

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

Checked every release learn/400-observability-and-alerts/415-own-status-page
Read as

1Keep what the screen shows in a variable

The status says where the job is in Acta's terms. What it is doing in your terms is a variable the handler writes as the work advances, inside the step, so a replay does not write it again.

own-status-page.csexcerpt
[Job("prepare-order", MaxAttempts = 3, Backoff = "2s")]
public async Task Handle(PrepareOrder order, JobContext ctx, CancellationToken ct)
{
    await ctx.RunStepAsync(
        "charge",
        async inner =>
        {
            await ctx.SetVariableAsync("stage", "charging", inner);
            if (ctx.ExecutionNumber == 1)
            {
                throw new InvalidOperationException("the payment provider timed out");
            }
        },
        ct
    );

    await ctx.RunStepAsync("hand-to-warehouse", async inner => await ctx.SetVariableAsync("stage", "packing", inner), ct);
    await ctx.WaitSignalAsync("packed", ct);
    await ctx.SetVariableAsync("stage", "shipped", ct);
}

2Read the job, its stage, and the sentence that says why

GetAsync answers the job's row, GetVariableOrDefaultAsync the value its handler keeps for the screen, and ExplainAsync a sentence a person can read. Each is a read of what the database holds now; none waits.

own-status-page.csexcerpt
await host.StopAsync();

async Task ShowAsync()
{
    var job = (await jobs.GetAsync(order))!;
    var stage = await jobs.GetVariableOrDefaultAsync<string>(order, "stage");
    var why = (await jobs.ExplainAsync(order))!;

    var shown = job.Status switch
    {
        JobStatusCode.Suspended => "waiting",
        JobStatusCode.Ready when job.FailureCount > 0 => "retrying",
        JobStatusCode.Executing when job.LeaseLapsed => "interrupted",
        JobStatusCode.Executing => "running",
        _ => job.Status.Code,
    };
    Console.WriteLine($"{shown, -9} | stage: {stage, -8} | {why.Headline}");
}

3Say the status in the page's own words

A waiting job is healthy, a ready job that has failed before is between retries, and Executing means claimed, not that a process is alive: LeaseLapsed is true for a job whose worker stopped heartbeating.

own-status-page.csexcerpt
async Task ShowAsync()
{
    var job = (await jobs.GetAsync(order))!;
    var stage = await jobs.GetVariableOrDefaultAsync<string>(order, "stage");
    var why = (await jobs.ExplainAsync(order))!;

    var shown = job.Status switch
    {
        JobStatusCode.Suspended => "waiting",
        JobStatusCode.Ready when job.FailureCount > 0 => "retrying",
        JobStatusCode.Executing when job.LeaseLapsed => "interrupted",
        JobStatusCode.Executing => "running",
        _ => job.Status.Code,
    };
    Console.WriteLine($"{shown, -9} | stage: {stage, -8} | {why.Headline}");
}

4Run it and check the output

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

Terminal
dotnet run --project learn/400-observability-and-alerts/415-own-status-page
Its output must contain
retrying  | stage: charging
waiting   | stage: packing
succeeded | stage: shipped

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

Remember

  • executing means claimed, not that a process is alive: LeaseLapsed is true for an executing job whose worker stopped heartbeating.
  • A sleeping job reads ready with a future NextRunAtUtc; a job waiting for a signal or a child reads suspended. Both are healthy.
  • ExecutionNumber counts every claim of the job, each resume after a wait and each bounce off a full concurrency key included. Show FailureCount as the tries.
  • The text of a status is job.Status.Code, such as suspended. ToString() gives the C# name, Suspended.
  • Write the screen's value inside a step. A bare write before a wait runs again when the handler is entered again, and the page would step back for a moment.
  • These calls read one job. To find many, list and page through jobs.

Check yourself

A job reads executing, its worker was killed, and its lease has run out. What should the page show?

Show the answer

Interrupted. executing says a worker claimed the job, not that the worker is alive. LeaseLapsed is true once its lease has run out, and recovery brings the job back by itself; nothing has failed.

The whole program

Every file of learn/400-observability-and-alerts/415-own-status-page, 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.

own-status-page.cs105 lines
own-status-page.cs
// How to show where each job is on your own page
// `IJobs` reads one job for a page of your own: its status, a value the handler keeps for the screen, and a sentence
// that says why the job is where it is.
using Acta;
using Acta.Learn.OwnStatusPage;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<OwnStatusPageJobs>("own-status-page");
});

// The first attempt fails on purpose, to show a job between retries; quiet the framework's warning for it.
builder.Logging.AddFilter("Acta", LogLevel.Error);

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

var jobs = host.Services.GetRequiredService<IJobs>();
var order = await jobs.EnqueueAsync(new PrepareOrder("order-7"));

// The page is read three times: between two attempts, while the job waits for the warehouse, and when it is done.
await UntilAsync(job => job.Status == JobStatusCode.Ready && job.FailureCount > 0);
await ShowAsync();

await UntilAsync(job => job.Status == JobStatusCode.Suspended);
await ShowAsync();

await jobs.RaiseSignalAsync(order, "packed", JobPayload.None);
await order.WaitAsync();
await ShowAsync();

await host.StopAsync();

async Task ShowAsync()
{
    // learn: 2. Read the job, its stage, and the sentence that says why
    // `GetAsync` answers the job's row, `GetVariableOrDefaultAsync` the value its handler keeps for the screen, and
    // `ExplainAsync` a sentence a person can read. Each is a read of what the database holds now; none waits.
    var job = (await jobs.GetAsync(order))!;
    var stage = await jobs.GetVariableOrDefaultAsync<string>(order, "stage");
    var why = (await jobs.ExplainAsync(order))!;
    // learn: end

    // learn: 3. Say the status in the page's own words
    // A waiting job is healthy, a ready job that has failed before is between retries, and `Executing` means claimed,
    // not that a process is alive: `LeaseLapsed` is true for a job whose worker stopped heartbeating.
    var shown = job.Status switch
    {
        JobStatusCode.Suspended => "waiting",
        JobStatusCode.Ready when job.FailureCount > 0 => "retrying",
        JobStatusCode.Executing when job.LeaseLapsed => "interrupted",
        JobStatusCode.Executing => "running",
        _ => job.Status.Code,
    };
    // learn: end
    Console.WriteLine($"{shown, -9} | stage: {stage, -8} | {why.Headline}");
}

async Task UntilAsync(Func<GetJobResponse, bool> reached)
{
    using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30));
    while (await jobs.GetAsync(order, timeout.Token) is not { } job || !reached(job))
    {
        await Task.Delay(50, timeout.Token);
    }
}

namespace Acta.Learn.OwnStatusPage
{
    public sealed record PrepareOrder(string OrderId);

    public sealed class PrepareOrderJob
    {
        [Job("prepare-order", MaxAttempts = 3, Backoff = "2s")]
        public async Task Handle(PrepareOrder order, JobContext ctx, CancellationToken ct)
        {
            await ctx.RunStepAsync(
                "charge",
                async inner =>
                {
                    // learn: 1. Keep what the screen shows in a variable
                    // The status says where the job is in Acta's terms. What it is doing in your terms is a variable
                    // the handler writes as the work advances, inside the step, so a replay does not write it again.
                    await ctx.SetVariableAsync("stage", "charging", inner);
                    // learn: end
                    if (ctx.ExecutionNumber == 1)
                    {
                        throw new InvalidOperationException("the payment provider timed out");
                    }
                },
                ct
            );

            await ctx.RunStepAsync("hand-to-warehouse", async inner => await ctx.SetVariableAsync("stage", "packing", inner), ct);
            await ctx.WaitSignalAsync("packed", ct);
            await ctx.SetVariableAsync("stage", "shipped", ct);
        }
    }
}

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.