Acta. Durable execution for .NET

learn actamake work survive a crash

How to report how far along a job is

SetProgressAsync stores how far the job has come as the checkpoint sys.progress, which the dashboard lists while the job runs.

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/208-progress
Read as

1Store the progress as the work advances

Each call replaces the last value. The dashboard shows it with the job's checkpoints; a page of your own reads a variable instead (415).

progress.csexcerpt
[Job("import-file")]
public async Task Handle(ImportFile input, JobContext context, CancellationToken ct)
{
    for (var row = 1; row <= input.Rows; row++)
    {
        await Task.Delay(100, ct);

        var percent = row * 100 / input.Rows;

        await context.SetProgressAsync(percent, ct);

        var filled = percent / 10;
        Console.Write($"\r[{input.Name}] [{new string('#', filled)}{new string('-', 10 - filled)}] {percent, 3}%");
    }

    Console.WriteLine();
    Console.WriteLine($"[{input.Name}] import complete");
}

2Run 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/208-progress
Its output must contain
[customers.csv] [##########] 100%
[customers.csv] import complete

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

Remember

  • SetProgressAsync keeps one value, last write wins, as the checkpoint sys.progress. A value your own screen reads goes in a variable.

The whole program

Every file of learn/200-durable-execution/208-progress, 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.

progress.cs57 lines
progress.cs
// How to report how far along a job is
// `SetProgressAsync` stores how far the job has come as the checkpoint `sys.progress`, which the dashboard lists
// while the job runs.
using Acta;
using Acta.Learn.Progress;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ProgressJobs>("progress");
});

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

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

await jobs.EnqueueAsync(new ImportFile("customers.csv", 20));
Console.WriteLine("Enqueued. Worker is running - press Ctrl+C to stop.");

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

namespace Acta.Learn.Progress
{
    public sealed record ImportFile(string Name, int Rows);

    public sealed class ImportFileJob
    {
        [Job("import-file")]
        public async Task Handle(ImportFile input, JobContext context, CancellationToken ct)
        {
            for (var row = 1; row <= input.Rows; row++)
            {
                await Task.Delay(100, ct);

                var percent = row * 100 / input.Rows;

                // learn: Store the progress as the work advances
                // Each call replaces the last value. The dashboard shows it with the job's checkpoints; a page of your
                // own reads a variable instead (415).
                await context.SetProgressAsync(percent, ct);
                // learn: end

                var filled = percent / 10;
                Console.Write($"\r[{input.Name}] [{new string('#', filled)}{new string('-', 10 - filled)}] {percent, 3}%");
            }

            Console.WriteLine();
            Console.WriteLine($"[{input.Name}] import complete");
        }
    }
}

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.