Acta. Durable execution for .NET

learn actastart jobs

How to label jobs so you can find them

Tags are name and value labels set on the enqueue, for filtering and grouping jobs in queries and in the dashboard.

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/018-tags
Read as

1Tag the job when you enqueue it

Tags are labels for filtering and grouping jobs in queries or a dashboard. Find them with operations.Ledger.ListJobsAsync(new ListJobsQuery(Tags: [new TagFilter("campaign", "spring")])).

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

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

var outcome = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o =>
    o.Tag("campaign", "spring").Tag("channel", "email")
);
Console.WriteLine($"Enqueued job {outcome.JobRef} with tags campaign=spring, channel=email.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

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

2The job it acts on

tags.csexcerpt
public static class WelcomeJob
{
    [Job("send-welcome-email")]
    public static void Handle(SendWelcomeEmail input) => Console.WriteLine($"Sent welcome email to {input.Name} <{input.Email}>");
}

3Run it and check the output

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

Terminal
dotnet run --project learn/000-fundamentals/018-tags
Its output must contain
with tags campaign=spring, channel=email.
Sent welcome email to Sam <[email protected]>

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/018-tags, 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.

tags.cs44 lines
tags.cs
// How to label jobs so you can find them
// Tags are name and value labels set on the enqueue, for filtering and grouping jobs in queries and in the dashboard.
using Acta;
using Acta.Learn.Tags;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

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

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

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

// learn: Tag the job when you enqueue it
// Tags are labels for filtering and grouping jobs in queries or a dashboard. Find them with
// `operations.Ledger.ListJobsAsync(new ListJobsQuery(Tags: [new TagFilter("campaign", "spring")]))`.
var outcome = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o =>
    o.Tag("campaign", "spring").Tag("channel", "email")
);

// learn: end
Console.WriteLine($"Enqueued job {outcome.JobRef} with tags campaign=spring, channel=email.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

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

namespace Acta.Learn.Tags
{
    public sealed record SendWelcomeEmail(string Email, string Name);

    public static class WelcomeJob
    {
        [Job("send-welcome-email")]
        public static void Handle(SendWelcomeEmail input) => Console.WriteLine($"Sent welcome email to {input.Name} <{input.Email}>");
    }
}

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.