Acta. Durable execution for .NET

learn actamake work survive a crash

How to check, delete, and default a job's variables

Beyond GetOrSetVariableAsync, shown across a retry in 203, a handler can check for a variable, delete it, read it with a default, and store a raw JobPayload.

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

Checked every release learn/200-durable-execution/216-variable-lifecycle
Read as

1Compute a value once

GetOrSet: factory runs on the first call; the second call returns the stored value without invoking the factory.

variable-lifecycle.csexcerpt
var factoryCalls = 0;
var v1 = await context.GetOrSetVariableAsync(
    "counter",
    () =>
    {
        factoryCalls++;
        return 42;
    },
    ct
);
var v2 = await context.GetOrSetVariableAsync(
    "counter",
    () =>
    {
        factoryCalls++;
        return 99;
    },
    ct
);
Console.WriteLine($"get-or-set: v1={v1} v2={v2} factory-calls={factoryCalls}");

// ExistsVariableAsync: the variable is present right after get-or-set.
var existsBefore = await context.ExistsVariableAsync("counter", ct);
Console.WriteLine($"exists before delete: {existsBefore}");

2Delete a variable, and check whether one is there

DeleteVariableAsync removes the variable; Exists is false immediately after.

variable-lifecycle.csexcerpt
// ExistsVariableAsync: the variable is present right after get-or-set.
var existsBefore = await context.ExistsVariableAsync("counter", ct);
Console.WriteLine($"exists before delete: {existsBefore}");

await context.DeleteVariableAsync("counter", ct);
var existsAfter = await context.ExistsVariableAsync("counter", ct);
Console.WriteLine($"exists after delete: {existsAfter}");

var fallback = await context.GetVariableOrDefaultAsync("counter", "missing", ct);
Console.WriteLine($"default fallback: {fallback}");

3Read a variable that may not be there

GetVariableOrDefaultAsync with a default value: absent variable returns the supplied default.

variable-lifecycle.csexcerpt
await context.DeleteVariableAsync("counter", ct);
var existsAfter = await context.ExistsVariableAsync("counter", ct);
Console.WriteLine($"exists after delete: {existsAfter}");

var fallback = await context.GetVariableOrDefaultAsync("counter", "missing", ct);
Console.WriteLine($"default fallback: {fallback}");

4Run it and check the output

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

Terminal
dotnet run --project learn/200-durable-execution/216-variable-lifecycle
Its output must contain
get-or-set: v1=42 v2=42 factory-calls=1
exists before delete: True
exists after delete: False
default fallback: missing
raw payload round-trip: raw-value

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

Remember

  • A variable write is durable by itself and needs no step around it. Read it from outside the job with jobs.GetVariableOrDefaultAsync<T>(jobRef, name, ct).

The whole program

Every file of learn/200-durable-execution/216-variable-lifecycle, 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.

variable-lifecycle.cs83 lines
variable-lifecycle.cs
// How to check, delete, and default a job's variables
// Beyond `GetOrSetVariableAsync`, shown across a retry in 203, a handler can check for a variable, delete it, read it
// with a default, and store a raw `JobPayload`.
using Acta;
using Acta.Learn.VariableLifecycle;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<VariableLifecycleJobs>("variable-lifecycle");
});

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

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

await jobs.CallAsync(new InspectVariables());

await host.StopAsync();

namespace Acta.Learn.VariableLifecycle
{
    public readonly record struct InspectVariables;

    public sealed class InspectVariablesJob
    {
        [Job("inspect-variables")]
        public async Task Handle(InspectVariables input, JobContext context, CancellationToken ct)
        {
            var factoryCalls = 0;
            // learn: 1. Compute a value once
            // GetOrSet: factory runs on the first call; the second call returns the stored value without invoking the factory.
            var v1 = await context.GetOrSetVariableAsync(
                "counter",
                () =>
                {
                    factoryCalls++;
                    return 42;
                },
                ct
            );
            var v2 = await context.GetOrSetVariableAsync(
                "counter",
                () =>
                {
                    factoryCalls++;
                    return 99;
                },
                ct
            );
            // learn: end
            Console.WriteLine($"get-or-set: v1={v1} v2={v2} factory-calls={factoryCalls}");

            // ExistsVariableAsync: the variable is present right after get-or-set.
            var existsBefore = await context.ExistsVariableAsync("counter", ct);
            Console.WriteLine($"exists before delete: {existsBefore}");

            // learn: 2. Delete a variable, and check whether one is there
            // DeleteVariableAsync removes the variable; Exists is false immediately after.
            await context.DeleteVariableAsync("counter", ct);
            var existsAfter = await context.ExistsVariableAsync("counter", ct);
            // learn: end
            Console.WriteLine($"exists after delete: {existsAfter}");

            // learn: 3. Read a variable that may not be there
            // GetVariableOrDefaultAsync with a default value: absent variable returns the supplied default.
            var fallback = await context.GetVariableOrDefaultAsync("counter", "missing", ct);
            // learn: end
            Console.WriteLine($"default fallback: {fallback}");

            // Raw JobPayload variable: store a pre-serialized payload; the format travels with the value.
            var raw = JobPayload.Json("raw-value");
            await context.SetVariableAsync("raw-var", raw, ct);
            var rawBack = await context.GetVariableOrDefaultAsync<string>("raw-var", ct);
            Console.WriteLine($"raw payload round-trip: {rawBack}");
        }
    }
}

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.