Acta. Durable execution for .NET

learn actastart jobs

How to keep a repeated request from creating a second job

A deduplication key makes an enqueue idempotent: a second enqueue with the same key answers the job that is already there.

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/010-deduplication-key
Read as

1Give the enqueue a key that names the request

Deduplicate(businessKey) on the raw builder stores the key with the job's name in front, so one business key used by two jobs never collides.

deduplication-key.csexcerpt
var jobs = host.Services.GetRequiredService<IJobs>();

var businessKey = $"welcome:{Guid.NewGuid():N}";
var finalKey = DeduplicationKey.ForDefinition("send-welcome-email", businessKey);

var request = JobRequestBuilder
    .Create("deduplication-key", "send-welcome-email")
    .Json(new SendWelcomeEmail("[email protected]", "Sam"))
    .Deduplicate(businessKey)
    .Build();
 
var first = await jobs.EnqueueAsync(request, CancellationToken.None);

var second = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

2Repeat the enqueue and get the same job back

A typed enqueue stores its key exactly as given, so to meet the first job it passes the same composed key. Two typed enqueues need only pass the same string to DeduplicationKey(...). This second enqueue answers the first job, deduplicated.

deduplication-key.csexcerpt
var first = await jobs.EnqueueAsync(request, CancellationToken.None);

var second = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

3The job it acts on

deduplication-key.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}>");
}

4Run it and check the output

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

Terminal
dotnet run --project learn/000-fundamentals/010-deduplication-key
Its output must contain
Same job - deduplicated.
Sent welcome email to Sam <[email protected]>

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

Remember

  • handle.Action says which happened: EnqueueJobAction.Deduplicated when the key matched a job already there, Inserted when this enqueue created it.
  • The key prevents a second job row, not a second side effect. Execution stays at-least-once.
  • Keys keep their case: Order-1 and order-1 are two keys, so lowercase an id yourself when its source ignores case.

The whole program

Every file of learn/000-fundamentals/010-deduplication-key, 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.

deduplication-key.cs65 lines
deduplication-key.cs
// How to keep a repeated request from creating a second job
// A deduplication key makes an enqueue idempotent: a second enqueue with the same key answers the job that is
// already there.
using Acta;
using Acta.Learn.DeduplicationKey;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<DeduplicationKeyJobs>("deduplication-key");
});

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

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

var businessKey = $"welcome:{Guid.NewGuid():N}";
var finalKey = DeduplicationKey.ForDefinition("send-welcome-email", businessKey);

// learn: 1. Give the enqueue a key that names the request
// `Deduplicate(businessKey)` on the raw builder stores the key with the job's name in front, so one business key
// used by two jobs never collides.
var request = JobRequestBuilder
    .Create("deduplication-key", "send-welcome-email")
    .Json(new SendWelcomeEmail("[email protected]", "Sam"))
    .Deduplicate(businessKey)
    .Build();
 
var first = await jobs.EnqueueAsync(request, CancellationToken.None);

// learn: end

// learn: 2. Repeat the enqueue and get the same job back
// A typed enqueue stores its key exactly as given, so to meet the first job it passes the same composed key. Two
// typed enqueues need only pass the same string to `DeduplicationKey(...)`. This second enqueue answers the first
// job, deduplicated.
var second = await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

// learn: end

Console.WriteLine($"first:  job {first.JobRef} ({first.Action})");
Console.WriteLine($"second: job {second.JobRef} ({second.Action})");
Console.WriteLine($"business key: {businessKey}");
Console.WriteLine($"final key:    {finalKey}");
Console.WriteLine(first.JobRef == second.JobRef ? "Same job - deduplicated." : "Different jobs.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

await host.WaitForShutdownAsync();
await host.StopAsync();

namespace Acta.Learn.DeduplicationKey
{
    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}>");
    }
}

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.