1Enqueue each job with a key taken from what it is
The handler can be retried, and a replay runs the whole loop again. With a stable key the replay gets the existing job back instead of a second copy.
// Inject IJobs to fan a big task out into many small durable jobs the worker drains in parallel.
//
// Every enqueued job carries a deduplication key derived from what it is, not from when it was created.
// This handler is retryable, and the fan-out happens before it completes: a crash mid-loop replays
// the whole loop, so without a stable key the album would grow a second copy of every thumbnail
// already enqueued. With one, the replay re-enqueues and Acta returns the existing job instead.
public sealed class MakeAlbumThumbnailsJob(IJobs jobs)
{
[Job("make-album-thumbnails")]
public async Task Handle(MakeAlbumThumbnails input, CancellationToken ct)
{
Console.WriteLine($"fanning out {input.PhotoCount} thumbnail jobs");
for (var i = 1; i <= input.PhotoCount; i++)
{
var photo = i;
await jobs.EnqueueAsync(new MakeThumbnail(photo), o => o.DeduplicationKey($"thumbnail-{input.AlbumId}-{photo}"), ct);
}
}
}2Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/600-job-composition/601-fan-outfanning out 5 thumbnail jobs
made thumbnail for photo #1
made thumbnail for photo #2
made thumbnail for photo #3
made thumbnail for photo #4
made thumbnail for photo #5Checked every release. Before each release, Acta Verify runs this program and checks that its output contains these lines.
This page shows the code. The rules it relies on, starting with the handler running again from its first line, are in the handler contract.
The whole program
Every file of learn/600-job-composition/601-fan-out, 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.
fan-out.cs63 lines
// How to enqueue many independent jobs from a handler
// A handler takes `IJobs` and enqueues many independent jobs, each with a stable deduplication key. Nothing links
// them to the handler's job and nothing waits for them (compare 212's `MapAsync`).
using Acta;
using Acta.Learn.FanOut;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<FanOutJobs>("fan-out");
});
using var host = builder.Build();
await host.StartAsync();
var jobs = host.Services.GetRequiredService<IJobs>();
await jobs.EnqueueAsync(new MakeAlbumThumbnails("summer-2026", 5));
Console.WriteLine("Enqueued. Worker is running - press Ctrl+C to stop.");
await host.WaitForShutdownAsync();
await host.StopAsync();
namespace Acta.Learn.FanOut
{
public sealed record MakeAlbumThumbnails(string AlbumId, int PhotoCount);
public sealed record MakeThumbnail(int PhotoIndex);
// Inject IJobs to fan a big task out into many small durable jobs the worker drains in parallel.
//
// Every enqueued job carries a deduplication key derived from what it is, not from when it was created.
// This handler is retryable, and the fan-out happens before it completes: a crash mid-loop replays
// the whole loop, so without a stable key the album would grow a second copy of every thumbnail
// already enqueued. With one, the replay re-enqueues and Acta returns the existing job instead.
public sealed class MakeAlbumThumbnailsJob(IJobs jobs)
{
[Job("make-album-thumbnails")]
public async Task Handle(MakeAlbumThumbnails input, CancellationToken ct)
{
Console.WriteLine($"fanning out {input.PhotoCount} thumbnail jobs");
// learn: Enqueue each job with a key taken from what it is
// The handler can be retried, and a replay runs the whole loop again. With a stable key the replay gets
// the existing job back instead of a second copy.
for (var i = 1; i <= input.PhotoCount; i++)
{
var photo = i;
await jobs.EnqueueAsync(new MakeThumbnail(photo), o => o.DeduplicationKey($"thumbnail-{input.AlbumId}-{photo}"), ct);
}
// learn: end
}
}
public static class MakeThumbnailJob
{
[Job("make-thumbnail")]
public static void Handle(MakeThumbnail input) => Console.WriteLine($" made thumbnail for photo #{input.PhotoIndex}");
}
}