Acta. Durable execution for .NET

learn actatake the first steps

How to read a job's status

GetAsync answers a snapshot of the job: its ref, its name and namespace, its status, and when it was created.

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/012-read-status
Read as

1Read the job with GetAsync

GetAsync returns a snapshot of the job's current state, or null when there is no such job. The handle that EnqueueAsync returned names the job; so does its JobRef.

read-status.csexcerpt
var jobs = host.Services.GetRequiredService<IJobs>();

var handle = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"));
await handle.WaitAsync();

var snapshot = await jobs.GetAsync(handle);
Console.WriteLine($"job={snapshot!.JobRef} name={snapshot.JobName} ns={snapshot.JobNamespace}");
Console.WriteLine($"status={snapshot.Status} created={snapshot.CreatedAtUtc:O}");

await host.StopAsync();

2The job it acts on

read-status.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/012-read-status
Its output must contain
status=Succeeded

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

Remember

  • 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.
  • A sleeping job reads ready with a future NextRunAtUtc; a job waiting for a signal or a child reads suspended. Both are healthy.
  • executing means claimed, not that a process is alive: LeaseLapsed is true for an executing job whose worker stopped heartbeating.
  • The text of a status is job.Status.Code, such as suspended. ToString() gives the C# name, Suspended.

The whole program

Every file of learn/000-fundamentals/012-read-status, 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.

read-status.cs44 lines
read-status.cs
// How to read a job's status
// `GetAsync` answers a snapshot of the job: its ref, its name and namespace, its status, and when it was created.
using Acta;
using Acta.Learn.ReadStatus;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ReadStatusJobs>("read-status");
});

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

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

var handle = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"));
await handle.WaitAsync();

// learn: Read the job with GetAsync
// `GetAsync` returns a snapshot of the job's current state, or null when there is no such job. The handle that
// `EnqueueAsync` returned names the job; so does its `JobRef`.
var snapshot = await jobs.GetAsync(handle);
Console.WriteLine($"job={snapshot!.JobRef} name={snapshot.JobName} ns={snapshot.JobNamespace}");
Console.WriteLine($"status={snapshot.Status} created={snapshot.CreatedAtUtc:O}");

// learn: end

await host.StopAsync();

namespace Acta.Learn.ReadStatus
{
    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.