Acta. Durable execution for .NET

learn actadecide what happens when work fails

How to limit how many times a job retries

MaxAttempts on the job is its retry budget. When the last attempt fails, the job ends as Failed.

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/016-max-attempts
Read as

1Set the retry budget on the job

MaxAttempts caps attempts, the first included; "0s" skips backoff. After the last attempt the job ends Failed.

max-attempts.csexcerpt
public static class FlakyWorkJob
{
    [Job("flaky-work", MaxAttempts = 3, Backoff = "0s")]
    public static Task Handle(FlakyWork input) => throw new InvalidOperationException($"Could not process {input.Item}.");
}

2Read how the job ended

The handler always throws; Acta makes up to MaxAttempts attempts, then transitions the job to Failed. The program sleeps long enough for its three instant attempts; an application waits for the end with await handle.WaitAsync().

max-attempts.csexcerpt
var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<MaxAttemptsJobs>("max-attempts");
});

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

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

var outcome = await jobs.EnqueueAsync(new FlakyWork("widget"));
await Task.Delay(1500);
var snapshot = await jobs.GetAsync(outcome);
Console.WriteLine($"status={snapshot!.Status} failureCount={snapshot.FailureCount}");

await host.StopAsync();

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/016-max-attempts
Its output must contain
status=Failed failureCount=3

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

Remember

  • FailureCount counts the attempts that failed since the job last succeeded, a crash included. It reads 0 again when the job succeeds; the events keep every failure.
  • A crash spends an attempt: the attempt a dead worker held is reclaimed as a failed one.
  • With no MaxAttempts, a job gets 15 attempts, backing off from a minute to a day.

The whole program

Every file of learn/000-fundamentals/016-max-attempts, 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.

max-attempts.cs46 lines
max-attempts.cs
// How to limit how many times a job retries
// `MaxAttempts` on the job is its retry budget. When the last attempt fails, the job ends as `Failed`.
using Acta;
using Acta.Learn.MaxAttempts;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<MaxAttemptsJobs>("max-attempts");
});

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

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

// learn: 2. Read how the job ended
// The handler always throws; Acta makes up to MaxAttempts attempts, then transitions the job to Failed. The program
// sleeps long enough for its three instant attempts; an application waits for the end with
// `await handle.WaitAsync()`.
var outcome = await jobs.EnqueueAsync(new FlakyWork("widget"));
await Task.Delay(1500);
var snapshot = await jobs.GetAsync(outcome);
Console.WriteLine($"status={snapshot!.Status} failureCount={snapshot.FailureCount}");

// learn: end

await host.StopAsync();

namespace Acta.Learn.MaxAttempts
{
    public sealed record FlakyWork(string Item);

    public static class FlakyWorkJob
    {
        // learn: 1. Set the retry budget on the job
        // MaxAttempts caps attempts, the first included; "0s" skips backoff. After the last attempt the job ends Failed.
        [Job("flaky-work", MaxAttempts = 3, Backoff = "0s")]
        public static Task Handle(FlakyWork input) => throw new InvalidOperationException($"Could not process {input.Item}.");
        // 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.