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.
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.
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.
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:
dotnet run --project learn/000-fundamentals/001-hello-actaHello, 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 asbilling, not for an environment or a version. MigrateOnStartup = trueis for your own machine. In production a deploy step runsjobs 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
// 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
}
}