Acta. Durable execution for .NET

learn actadecide what happens when work fails

How to fail a job for good, with no retry

FailAsync ends the job as Failed at once, whatever its retry budget. A thrown exception would be retried.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/300-failure-and-recovery/301-fail-job
Read as

1End the job as failed where retrying cannot help

FailAsync ends the job as Failed now (no retry); a thrown exception retries to MaxAttempts.

fail-job.csexcerpt
public sealed class ProcessUploadJob
{
    // FailAsync is terminal even with MaxAttempts = 5: it ends the job, it does not retry.
    [Job("process-upload", MaxAttempts = 5)]
    public async Task Handle(ProcessUpload upload, JobContext context, CancellationToken ct)
    {
        if (upload.Corrupt)
        {
            await context.FailAsync("file is corrupt and cannot be processed", ct);
        }

        Console.WriteLine($"[{upload.FileName}] file processed");
    }
}

2Run it and check the output

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

Terminal
dotnet run --project learn/300-failure-and-recovery/301-fail-job
Its output must contain
status=Failed, failureCount=0

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

Remember

  • FailAsync ends the job by throwing, so nothing after it runs. The compiler cannot see that: in a handler that returns a value, write return or throw after it.
  • A job ended this way reads Failed with FailureCount 0: no attempt failed, the handler ended it.

The whole program

Every file of learn/300-failure-and-recovery/301-fail-job, 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.

fail-job.cs54 lines
fail-job.cs
// How to fail a job for good, with no retry
// `FailAsync` ends the job as `Failed` at once, whatever its retry budget. A thrown exception would be retried.
using Acta;
using Acta.Learn.FailJob;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<FailJobJobs>("fail-job");
});

// Quiet the framework's failure logging; the job fails on purpose.
builder.Logging.AddFilter("Acta", LogLevel.Error);

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

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

var outcome = await jobs.EnqueueAsync(new ProcessUpload("photo.jpg", Corrupt: true));
await Task.Delay(500);

var snapshot = await jobs.GetAsync(outcome);
Console.WriteLine($"status={snapshot!.Status}, failureCount={snapshot.FailureCount}");

await host.StopAsync();

namespace Acta.Learn.FailJob
{
    public sealed record ProcessUpload(string FileName, bool Corrupt);

    public sealed class ProcessUploadJob
    {
        // FailAsync is terminal even with MaxAttempts = 5: it ends the job, it does not retry.
        [Job("process-upload", MaxAttempts = 5)]
        public async Task Handle(ProcessUpload upload, JobContext context, CancellationToken ct)
        {
            if (upload.Corrupt)
            {
                // learn: End the job as failed where retrying cannot help
                // FailAsync ends the job as Failed now (no retry); a thrown exception retries to MaxAttempts.
                await context.FailAsync("file is corrupt and cannot be processed", ct);
                // learn: end
            }

            Console.WriteLine($"[{upload.FileName}] file processed");
        }
    }
}

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.