Acta. Durable execution for .NET

learn actasplit work across child jobs

How to start a child job in another namespace

A parent starts a child in another worker's namespace and waits across the boundary.

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

Checked every release learn/700-topology-and-deployment/704-cross-namespace-child
Read as

1Run a worker for each namespace

A child can target any registered namespace: the parent's wait is released when the child finishes, whichever namespace ran it.

cross-namespace-child.csexcerpt
var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    j.Run<CrossNamespaceChildJobs>("storefront");
    j.Run<CrossNamespaceChildJobs>("billing");
});

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

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

2Name the child's namespace and job

The raw EnqueueChildAsync overload names an explicit (namespace, job) route. The first argument is the child's name: on a re-entry the same name finds the child already enqueued, so it is sent once.

cross-namespace-child.csexcerpt
var charge = await context.EnqueueChildAsync(
    "charge",
    "billing",
    "charge-payment",
    JobPayload.Json(new ChargePayment(order.OrderId, order.Amount)),
    ct: ct
);

var outcome = await context.WaitChildAsync(charge, ct);
if (!outcome.Succeeded)
{
    await context.FailAsync($"billing declined ({outcome.Status}); see the child's job events for the reason", ct);
}

3Wait for the child and read its result

cross-namespace-child.csexcerpt
var outcome = await context.WaitChildAsync(charge, ct);
if (!outcome.Succeeded)
{
    await context.FailAsync($"billing declined ({outcome.Status}); see the child's job events for the reason", ct);
}
 
var receipt = await context.GetChildResultAsync<PaymentReceipt>(charge.JobId, ct);
return new OrderConfirmation(order.OrderId, receipt.TransactionId);

4Run it and check the output

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

Terminal
dotnet run --project learn/700-topology-and-deployment/704-cross-namespace-child
Its output must contain
EUR for order-7
order finished: OrderConfirmation { OrderId = order-7, TransactionId = tx-order-7 }

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/700-topology-and-deployment/704-cross-namespace-child, 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.

cross-namespace-child.cs93 lines
cross-namespace-child.cs
// How to start a child job in another namespace
// A parent starts a child in another worker's namespace and waits across the boundary.
using Acta;
using Acta.Learn.CrossNamespaceChild;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);

    // learn: 1. Run a worker for each namespace
    // A child can target any registered namespace: the parent's wait is released when the child finishes,
    // whichever namespace ran it.
    j.Run<CrossNamespaceChildJobs>("storefront");
    j.Run<CrossNamespaceChildJobs>("billing");
    // learn: end
});

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

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

var order = await jobs.EnqueueAsync(
    new EnqueueJobRequest("storefront", "place-order", JobPayload.Json(new PlaceOrder("order-7", 99.90m))),
    CancellationToken.None
);

while (true)
{
    var status = (await jobs.GetStatusAsync(order))?.Status;
    if (status is { } s && s.IsFinished)
    {
        break;
    }
    await Task.Delay(100);
}

Console.WriteLine($"order finished: {await jobs.GetResultAsync<OrderConfirmation>(order)}");

await host.StopAsync();

namespace Acta.Learn.CrossNamespaceChild
{
    public sealed record PlaceOrder(string OrderId, decimal Amount);

    public sealed record ChargePayment(string OrderId, decimal Amount);

    public sealed record PaymentReceipt(string TransactionId);

    public sealed record OrderConfirmation(string OrderId, string TransactionId);

    public sealed class OrderJobs
    {
        [Job("place-order")]
        public async Task<OrderConfirmation> Handle(PlaceOrder order, JobContext context, CancellationToken ct)
        {
            // learn: 2. Name the child's namespace and job
            // The raw EnqueueChildAsync overload names an explicit (namespace, job) route. The first argument is
            // the child's name: on a re-entry the same name finds the child already enqueued, so it is sent once.
            var charge = await context.EnqueueChildAsync(
                "charge",
                "billing",
                "charge-payment",
                JobPayload.Json(new ChargePayment(order.OrderId, order.Amount)),
                ct: ct
            );
            // learn: end

            // learn: 3. Wait for the child and read its result
            var outcome = await context.WaitChildAsync(charge, ct);
            if (!outcome.Succeeded)
            {
                await context.FailAsync($"billing declined ({outcome.Status}); see the child's job events for the reason", ct);
            }
 
            var receipt = await context.GetChildResultAsync<PaymentReceipt>(charge.JobId, ct);
            // learn: end
            return new OrderConfirmation(order.OrderId, receipt.TransactionId);
        }

        [Job("charge-payment")]
        public async Task<PaymentReceipt> Charge(ChargePayment charge, CancellationToken ct)
        {
            await Task.Delay(200, ct);
            Console.WriteLine($"[billing] charged {charge.Amount:0.00} EUR for {charge.OrderId}");
            return new PaymentReceipt($"tx-{charge.OrderId}");
        }
    }
}

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.