Acta. Durable execution for .NET

learn actawatch and control running work

How to cancel a running job from outside

CancelAsync on a job's handle cancels it from outside its handler. Any process that holds an IJobs can do it, and a running handler's CancellationToken trips.

A how-to for Acta, durable execution for .NET. New to Acta? Run your first durable job in five minutes.

Checked every release learn/300-failure-and-recovery/305-operator-cancel
Read as

1Cancel the job from outside

Operator cancel from outside the handler: any process holding an IJobs trips a running job's CancellationToken.

operator-cancel.csexcerpt
var jobs = host.Services.GetRequiredService<IJobs>();

var handle = await jobs.EnqueueAsync(new BigExport("export-1"));
await Task.Delay(500); // let it start running
Console.WriteLine($"status while running: {(await handle.GetStatusAsync())?.Status}");

var result = await handle.CancelAsync("operator aborted the export");
Console.WriteLine($"cancel result: {result.Action}");

await handle.WaitAsync();
var snapshot = await jobs.GetAsync(handle);
Console.WriteLine($"final status: {snapshot!.Status}");

await host.StopAsync();

2Pass the token to the work, so the cancel can stop it

The handler hands its CancellationToken to everything it awaits; the cancel from outside ends the wait here.

operator-cancel.csexcerpt
public sealed class BigExportJob
{
    [Job("big-export")]
    public async Task Handle(BigExport input, CancellationToken ct)
    {
        Console.WriteLine($"[{input.Id}] export started");
        await Task.Delay(TimeSpan.FromSeconds(30), ct); // operator cancels mid-run, so ct trips here
        Console.WriteLine($"[{input.Id}] export finished"); // never reached
    }
}

3Run it and check the output

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

Terminal
dotnet run --project learn/300-failure-and-recovery/305-operator-cancel
Its output must contain
[export-1] export started
cancel result: Applied
final status: Cancelled

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/300-failure-and-recovery/305-operator-cancel, 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.

operator-cancel.cs56 lines
operator-cancel.cs
// How to cancel a running job from outside
// `CancelAsync` on a job's handle cancels it from outside its handler. Any process that holds an `IJobs` can do it,
// and a running handler's `CancellationToken` trips.
using Acta;
using Acta.Learn.OperatorCancel;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<OperatorCancelJobs>("operator-cancel");
});

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

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

var handle = await jobs.EnqueueAsync(new BigExport("export-1"));
await Task.Delay(500); // let it start running
Console.WriteLine($"status while running: {(await handle.GetStatusAsync())?.Status}");

// learn: Cancel the job from outside
// Operator cancel from outside the handler: any process holding an IJobs trips a running job's CancellationToken.
var result = await handle.CancelAsync("operator aborted the export");
Console.WriteLine($"cancel result: {result.Action}");

// learn: end

await handle.WaitAsync();
var snapshot = await jobs.GetAsync(handle);
Console.WriteLine($"final status: {snapshot!.Status}");

await host.StopAsync();

namespace Acta.Learn.OperatorCancel
{
    public sealed record BigExport(string Id);

    public sealed class BigExportJob
    {
        [Job("big-export")]
        public async Task Handle(BigExport input, CancellationToken ct)
        {
            Console.WriteLine($"[{input.Id}] export started");
            // learn: Pass the token to the work, so the cancel can stop it
            // The handler hands its CancellationToken to everything it awaits; the cancel from outside ends the wait here.
            await Task.Delay(TimeSpan.FromSeconds(30), ct); // operator cancels mid-run, so ct trips here
            // learn: end
            Console.WriteLine($"[{input.Id}] export finished"); // never reached
        }
    }
}

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.