Acta. Durable execution for .NET

learn actarun work on a schedule

How to run a job on a repeating schedule

[Schedule] with a cron makes one permanent job that fires on that cadence, with nothing to enqueue.

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

Checked every release learn/100-scheduling/101-recurring-job
Read as

1Put a schedule on the job

[Schedule] takes a name and a cron, here one of the Cron constants, read in UTC unless TimeZoneId says otherwise. One permanent job fires on the cadence, and the count each firing returns replaces the result the last one stored. EventRecording = Failures is optional: it keeps a frequent schedule from writing an event for every firing that succeeds. Nothing enqueues a scheduled job, so its input is an empty record.

recurring-job.csexcerpt
public sealed class PurgeStaleSessionsJob
{
    [Job("purge-stale-sessions", EventRecording = EventRecordingCode.Failures)]
    [Schedule("every-15-seconds", Cron.Every15Seconds)]
    public async Task<int> Handle(PurgeStaleSessions input, JobContext context, CancellationToken ct)
    {
        await Task.Delay(100, ct);
        var purged = Random.Shared.Next(0, 25);
        Console.WriteLine(
            $"{DateTime.UtcNow:HH:mm:ss} UTC [{string.Join(", ", context.TriggeringSchedules.Select(s => s.ScheduleName))}] purged {purged} stale sessions"
        );
        return purged;
    }
}

2Run it and check the output

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

Terminal
dotnet run --project learn/100-scheduling/101-recurring-job
Its output must contain
[every-15-seconds] purged

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

Remember

  • A schedule is written by a deploy: jobs migrate or jobs deploy in production, the development start on your own machine.
  • A permanent job keeps its step results from one firing to the next. Put the firing in a step's name, $"send.f{ctx.FiringId:N}", or the step that ran on the last firing answers this one from its record.
  • The handler does its bounded work and returns. Never loop inside it: the schedule brings the next firing.

The whole program

Every file of learn/100-scheduling/101-recurring-job, 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.

recurring-job.cs43 lines
recurring-job.cs
// How to run a job on a repeating schedule
// `[Schedule]` with a cron makes one permanent job that fires on that cadence, with nothing to enqueue.
using Acta;
using Acta.Learn.Recurring;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<RecurringJobs>("recurring-job");
});

// No enqueue: the deploy creates one permanent job for the [Schedule] below, and it fires on its cron cadence.
await builder.Build().RunAsync();

namespace Acta.Learn.Recurring
{
    public readonly record struct PurgeStaleSessions;

    public sealed class PurgeStaleSessionsJob
    {
        // learn: Put a schedule on the job
        // `[Schedule]` takes a name and a cron, here one of the `Cron` constants, read in UTC unless `TimeZoneId`
        // says otherwise. One permanent job fires on the cadence, and the count each firing returns replaces the
        // result the last one stored. `EventRecording = Failures` is optional: it keeps a frequent schedule from
        // writing an event for every firing that succeeds. Nothing enqueues a scheduled job, so its input is an
        // empty record.
        [Job("purge-stale-sessions", EventRecording = EventRecordingCode.Failures)]
        [Schedule("every-15-seconds", Cron.Every15Seconds)]
        // learn: end
        public async Task<int> Handle(PurgeStaleSessions input, JobContext context, CancellationToken ct)
        {
            await Task.Delay(100, ct);
            var purged = Random.Shared.Next(0, 25);
            Console.WriteLine(
                $"{DateTime.UtcNow:HH:mm:ss} UTC [{string.Join(", ", context.TriggeringSchedules.Select(s => s.ScheduleName))}] purged {purged} stale sessions"
            );
            return purged;
        }
    }
}

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.