Acta. Durable execution for .NET

learn actatake the first steps

How to run your first job

One [Job] method, one enqueue, and a worker that runs it.

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/001-hello-acta
Read as

1Write the job

A job is a method with [Job("name")] on it, and the record is its input. Acta stores the input as a row and calls the method with it.

hello-acta.csexcerpt
public static class HelloJob
{
    [Job("hello")]
    public static void Handle(Hello input) => Console.WriteLine($"Hello, {input.Name}!");
}

2Register Acta and start a worker

UseSqlite says where the job rows live: one file, no server. Swap it for UsePostgres or UseSqlServer, with that server's connection string, to target a server; later how-tos fold this setup into UseLocalDatabase. Run<HelloActaJobs>("hello-acta") registers every job of the project under the namespace hello-acta and starts a worker for it. HelloActaJobs is generated at build time from the [Job] methods.

hello-acta.csexcerpt
var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseSqlite(sqlite =>
    {
        sqlite.ConnectionString = builder.Configuration.GetConnectionString("acta")
            ?? $"Data Source={Path.Combine(Path.GetTempPath(), "acta-local.db")}";
        sqlite.MigrateOnStartup = true;
    });
    j.Run<HelloActaJobs>("hello-acta");
});

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

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

3Enqueue it

EnqueueAsync writes the job as a row and returns. The type of the input picks the job, so there is no name string to get wrong.

hello-acta.csexcerpt
using var host = builder.Build();
await host.StartAsync();

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

await jobs.EnqueueAsync(new Hello("World"));
Console.WriteLine("Enqueued. The worker is running - press Ctrl+C to stop.");

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

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/001-hello-acta
Its output must contain
Hello, World!

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

Remember

  • The name in [Job("hello")] goes into the database, the dashboard, and alerts. Keep it lowercase with dashes, and treat it as permanent once jobs exist under it.
  • The namespace in Run<HelloActaJobs>("hello-acta") is permanent too: every job is stored under it and there is no rename. Name it for the work the app owns, such as billing, not for an environment or a version.
  • MigrateOnStartup = true is for your own machine. In production a deploy step runs jobs migrate.
  • The process that enqueues can also run the job. You can split the two later without changing the handler.

Check yourself

EnqueueAsync has returned and the worker has not picked the job up yet. Where is the job?

Show the answer

In a row of the SQLite file. The job is a durable row before anything runs it. Stop the process now and the row is still there for the next start.

The whole program

Every file of learn/000-fundamentals/001-hello-acta, as it is compiled.

hello-acta.cs58 lines
hello-acta.cs
// How to run your first job
// One `[Job]` method, one enqueue, and a worker that runs it.
using Acta;
using Acta.Learn.HelloActa;
using Acta.Sqlite;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    // learn: 2. Register Acta and start a worker
    // `UseSqlite` says where the job rows live: one file, no server. Swap it for `UsePostgres` or `UseSqlServer`, with
    // that server's connection string, to target a server; later how-tos fold this setup into `UseLocalDatabase`.
    // `Run<HelloActaJobs>("hello-acta")` registers every job of the project under the namespace `hello-acta` and
    // starts a worker for it. `HelloActaJobs` is generated at build time from the `[Job]` methods.
    j.UseSqlite(sqlite =>
    {
        sqlite.ConnectionString = builder.Configuration.GetConnectionString("acta")
            ?? $"Data Source={Path.Combine(Path.GetTempPath(), "acta-local.db")}";
        sqlite.MigrateOnStartup = true;
    });
    j.Run<HelloActaJobs>("hello-acta");
    // learn: end
});

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

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

// learn: 3. Enqueue it
// `EnqueueAsync` writes the job as a row and returns. The type of the input picks the job, so there is no name
// string to get wrong.
await jobs.EnqueueAsync(new Hello("World"));

// learn: end
Console.WriteLine("Enqueued. The worker is running - press Ctrl+C to stop.");

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

namespace Acta.Learn.HelloActa
{
    public sealed record Hello(string Name);

    public static class HelloJob
    {
        // learn: 1. Write the job
        // A job is a method with `[Job("name")]` on it, and the record is its input. Acta stores the input as a row
        // and calls the method with it.
        [Job("hello")]
        public static void Handle(Hello input) => Console.WriteLine($"Hello, {input.Name}!");
        // learn: end
    }
}

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.