Acta. Durable execution for .NET

learn actatake the first steps

How to read a job's result

TryGetResultAsync<T> finds nothing before Succeeded; GetResultAsync<T> returns the result you expect.

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/013-read-result
Read as

1Ask whether a result exists yet

Both reads are point-in-time and never wait. TryGetResultAsync says whether a result exists yet.

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

var handle = await jobs.EnqueueAsync(new AddNumbers(20, 22));

var early = await handle.TryGetResultAsync<AddNumbersResult>();
Console.WriteLine($"right away:        {(early.Found ? early.Value!.Sum.ToString() : "no result yet")}");

await handle.WaitAsync();

var done = await handle.GetResultAsync<AddNumbersResult>();
Console.WriteLine($"after it finishes: {done.Sum}");

2Read the result you expect

GetResultAsync returns the result, and throws when there is none.

read-result.csexcerpt
var early = await handle.TryGetResultAsync<AddNumbersResult>();
Console.WriteLine($"right away:        {(early.Found ? early.Value!.Sum.ToString() : "no result yet")}");

await handle.WaitAsync();

var done = await handle.GetResultAsync<AddNumbersResult>();
Console.WriteLine($"after it finishes: {done.Sum}");

await host.StopAsync();

3The job it acts on

read-result.csexcerpt
public static class AddNumbersJob
{
    [Job("add-numbers")]
    public static async Task<AddNumbersResult> Handle(AddNumbers input, CancellationToken ct)
    {
        await Task.Delay(300, ct);
        return new AddNumbersResult(input.Left + input.Right);
    }
}

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/013-read-result
Its output must contain
right away:        no result yet
after it finishes: 42

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

Remember

  • GetResultAsync<T> throws when there is no result; TryGetResultAsync<T> answers (Found, Value). Neither read waits for the job.

The whole program

Every file of learn/000-fundamentals/013-read-result, 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-result.cs56 lines
read-result.cs
// How to read a job's result
// `TryGetResultAsync<T>` finds nothing before Succeeded; `GetResultAsync<T>` returns the result you expect.
using Acta;
using Acta.Learn.ReadResult;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<ReadResultJobs>("read-result");
});

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

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

var handle = await jobs.EnqueueAsync(new AddNumbers(20, 22));

// learn: 1. Ask whether a result exists yet
// Both reads are point-in-time and never wait. `TryGetResultAsync` says whether a result exists yet.
var early = await handle.TryGetResultAsync<AddNumbersResult>();
Console.WriteLine($"right away:        {(early.Found ? early.Value!.Sum.ToString() : "no result yet")}");

// learn: end

await handle.WaitAsync();

// learn: 2. Read the result you expect
// `GetResultAsync` returns the result, and throws when there is none.
var done = await handle.GetResultAsync<AddNumbersResult>();
Console.WriteLine($"after it finishes: {done.Sum}");

// learn: end

await host.StopAsync();

namespace Acta.Learn.ReadResult
{
    public sealed record AddNumbers(int Left, int Right);

    public sealed record AddNumbersResult(int Sum);

    public static class AddNumbersJob
    {
        [Job("add-numbers")]
        public static async Task<AddNumbersResult> Handle(AddNumbers input, CancellationToken ct)
        {
            await Task.Delay(300, ct);
            return new AddNumbersResult(input.Left + input.Right);
        }
    }
}

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.