Acta. Durable execution for .NET

learn actastart jobs

How to enqueue a job by its name

An EnqueueJobRequest names the namespace and the job as strings, for a caller that does not have the job's types.

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/020-raw-enqueue
Read as

1Name the namespace and the job in a request

Raw request names (namespace, job) explicitly, for a caller without the manifest, such as a gateway relaying a request body. An in-process caller with an ambiguous input type uses the generated call instead (023). A caller that holds only the JSON text passes it as it came, JobPayload.CopyBytes(JobPayloadFormat.Json, bytes): JobPayload.Json(text) would store the text as one JSON string.

raw-enqueue.csexcerpt
using var host = builder.Build();
await host.StartAsync();

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

var request = new EnqueueJobRequest(
    JobNamespace: "raw-enqueue",
    JobName: "send-welcome-email",
    Input: JobPayload.Json(new SendWelcomeEmail("[email protected]", "Sam"))
);

var enqueued = await jobs.EnqueueAsync(request, CancellationToken.None);
Console.WriteLine($"Enqueued job {enqueued.JobRef} by name. Worker is running - press Ctrl+C to stop.");

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

2Enqueue the request

The explicit CancellationToken picks the raw-request overload over the typed EnqueueAsync<T>.

raw-enqueue.csexcerpt
var request = new EnqueueJobRequest(
    JobNamespace: "raw-enqueue",
    JobName: "send-welcome-email",
    Input: JobPayload.Json(new SendWelcomeEmail("[email protected]", "Sam"))
);

var enqueued = await jobs.EnqueueAsync(request, CancellationToken.None);
Console.WriteLine($"Enqueued job {enqueued.JobRef} by name. Worker is running - press Ctrl+C to stop.");

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

3The job it acts on

raw-enqueue.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/020-raw-enqueue
Its output must contain
by name.
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/020-raw-enqueue, 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.

raw-enqueue.cs53 lines
raw-enqueue.cs
// How to enqueue a job by its name
// An `EnqueueJobRequest` names the namespace and the job as strings, for a caller that does not have the job's types.
using Acta;
using Acta.Learn.RawEnqueue;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<RawEnqueueJobs>("raw-enqueue");
});

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

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

// learn: 1. Name the namespace and the job in a request
// Raw request names (namespace, job) explicitly, for a caller without the manifest, such as a gateway relaying
// a request body. An in-process caller with an ambiguous input type uses the generated call instead (023). A caller
// that holds only the JSON text passes it as it came, `JobPayload.CopyBytes(JobPayloadFormat.Json, bytes)`:
// `JobPayload.Json(text)` would store the text as one JSON string.
var request = new EnqueueJobRequest(
    JobNamespace: "raw-enqueue",
    JobName: "send-welcome-email",
    Input: JobPayload.Json(new SendWelcomeEmail("[email protected]", "Sam"))
);

// learn: end

// learn: 2. Enqueue the request
// The explicit CancellationToken picks the raw-request overload over the typed EnqueueAsync<T>.
var enqueued = await jobs.EnqueueAsync(request, CancellationToken.None);

// learn: end
Console.WriteLine($"Enqueued job {enqueued.JobRef} by name. Worker is running - press Ctrl+C to stop.");

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

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

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.