1End the job as failed where retrying cannot help
FailAsync ends the job as Failed now (no retry); a thrown exception retries to MaxAttempts.
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:
dotnet run --project learn/300-failure-and-recovery/301-fail-jobstatus=Failed, failureCount=0Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.
Remember
FailAsyncends the job by throwing, so nothing after it runs. The compiler cannot see that: in a handler that returns a value, writereturnorthrowafter it.- A job ended this way reads
FailedwithFailureCount0: 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
// 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");
}
}
}