Acta. Durable execution for .NET

learn actastart jobs

How to find a job by its deduplication key

JobLookup.ByDeduplicationKey finds a job by the key it was enqueued with, when you did not keep its ref.

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/014-read-by-deduplication-key
Read as

1Enqueue with a key you can build again later

A typed enqueue stores its key exactly as given. This one puts the job's name in front with DeduplicationKey.ForDefinition; whatever key you choose, build it the same way where you look the job up.

read-by-deduplication-key.csexcerpt
using var host = builder.Build();
await host.StartAsync();

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

var businessKey = "welcome:sam";
var finalKey = DeduplicationKey.ForDefinition("send-welcome-email", businessKey);
await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

var snapshot = await jobs.GetAsync(JobLookup.ByDeduplicationKey("read-by-deduplication-key", finalKey));
Console.WriteLine($"Found job {snapshot!.JobRef} by deduplication key '{snapshot.DeduplicationKey}', status {snapshot.Status}.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

2Look the job up by that key

The first argument is the namespace the job was enqueued in, the name given to Run<...>; the second is the key exactly as stored. The lookup composes nothing from a business key.

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

var businessKey = "welcome:sam";
var finalKey = DeduplicationKey.ForDefinition("send-welcome-email", businessKey);
await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

var snapshot = await jobs.GetAsync(JobLookup.ByDeduplicationKey("read-by-deduplication-key", finalKey));
Console.WriteLine($"Found job {snapshot!.JobRef} by deduplication key '{snapshot.DeduplicationKey}', status {snapshot.Status}.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

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

3The job it acts on

read-by-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/014-read-by-deduplication-key
Its output must contain
by deduplication key 'send-welcome-email:welcome:sam'
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.

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/000-fundamentals/014-read-by-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.

read-by-deduplication-key.cs51 lines
read-by-deduplication-key.cs
// How to find a job by its deduplication key
// `JobLookup.ByDeduplicationKey` finds a job by the key it was enqueued with, when you did not keep its ref.
using Acta;
using Acta.Learn.ReadByDeduplicationKey;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

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

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

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

// learn: 1. Enqueue with a key you can build again later
// A typed enqueue stores its key exactly as given. This one puts the job's name in front with
// `DeduplicationKey.ForDefinition`; whatever key you choose, build it the same way where you look the job up.
var businessKey = "welcome:sam";
var finalKey = DeduplicationKey.ForDefinition("send-welcome-email", businessKey);
await jobs.EnqueueAsync(new SendWelcomeEmail("[email protected]", "Sam"), o => o.DeduplicationKey(finalKey));

// learn: end

// learn: 2. Look the job up by that key
// The first argument is the namespace the job was enqueued in, the name given to `Run<...>`; the second is the key
// exactly as stored. The lookup composes nothing from a business key.
var snapshot = await jobs.GetAsync(JobLookup.ByDeduplicationKey("read-by-deduplication-key", finalKey));

// learn: end
Console.WriteLine($"Found job {snapshot!.JobRef} by deduplication key '{snapshot.DeduplicationKey}', status {snapshot.Status}.");
Console.WriteLine("Worker is running - press Ctrl+C to stop.");

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

namespace Acta.Learn.ReadByDeduplicationKey
{
    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.