Acta. Durable execution for .NET

learn actarun work on a schedule

How to skip public holidays on a daily schedule

A cron cannot name the days a country takes off. An occurrence calendar can: local times on the weekdays you list, minus the dates you exclude. The list is data an operator publishes, so next year's holidays need no deploy.

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/114-holiday-calendar
Read as

1List the holidays in a calendar definition

A daily-local-time definition fires at each of times on each of days, and skips every date in excludedDates. Paste the whole list of holidays: one that falls on a weekend is skipped twice over.

holiday-calendar.csexcerpt
public static class Definitions
{
    public const string WorkingDays = """
        {
          "kind": "daily-local-time",
          "times": ["08:00"],
          "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
          "excludedDates": ["2027-11-01", "2027-12-25", "2027-12-26", "2028-01-01", "2028-01-02", "2028-02-08"]
        }
        """;
}

2Preview the draft, then publish it

The preview answers the draft's next occurrences from any instant, in the zone you name. This one starts on the Friday before a Monday holiday. When the list changes, save the new definition and publish it again: every schedule that names the calendar follows the new version.

holiday-calendar.csexcerpt
var calendars = seedHost.Services.GetRequiredService<IActaOperations>().Calendars;

var draft = await calendars.SaveDraftAsync(workingDays, CalendarRoleCode.Occurrence, Definitions.WorkingDays);
var friday = new DateTimeOffset(2027, 10, 29, 0, 0, 0, TimeSpan.Zero);
var preview = (await calendars.PreviewAsync(workingDays, draft.Version!.Value, friday, count: 3, timeZoneId: "Europe/Ljubljana"))!;
foreach (var occurrence in preview.OccurrencesUtc)
{
    Console.WriteLine($"reports {Local(occurrence)}");
}
 
await calendars.PublishAsync(workingDays, draft.Version.Value, reasonMessage: "Holidays through February 2028");
current = draft.Version.Value;

await seedHost.StopAsync();

3Name the calendar on the schedule

Calendar takes the place of a cron or an interval, and TimeZoneId is the zone the calendar's local times are read in.

holiday-calendar.csexcerpt
public sealed class DailyReportJob
{
    [Job("daily-report")]
    [Schedule("working-days-at-eight", Calendar = "working-days", TimeZoneId = "Europe/Ljubljana")]
    public Task Handle(DailyReport input, CancellationToken ct)
    {
        Console.WriteLine($"{DateTime.UtcNow:yyyy-MM-dd} sent the daily report");
        return Task.CompletedTask;
    }
}

4Run it and check the output

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

Terminal
dotnet run --project learn/100-scheduling/114-holiday-calendar
Its output must contain
reports Fri 2027-10-29 08:00
reports Tue 2027-11-02 08:00
reports Wed 2027-11-03 08:00
the calendar's next instant: True

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/100-scheduling/114-holiday-calendar, 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.

holiday-calendar.cs107 lines
holiday-calendar.cs
// How to skip public holidays on a daily schedule
// A cron cannot name the days a country takes off. An occurrence calendar can: local times on the weekdays you list,
// minus the dates you exclude. The list is data an operator publishes, so next year's holidays need no deploy.
using System.Globalization;
using Acta;
using Acta.Learn.HolidayCalendar;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

// A family in sys is shared: every namespace binds it by its plain name.
var workingDays = new CalendarLookup("sys", "working-days");
var zone = TimeZoneInfo.FindSystemTimeZoneById("Europe/Ljubljana");
string Local(DateTime utc) =>
    TimeZoneInfo
        .ConvertTimeFromUtc(DateTime.SpecifyKind(utc, DateTimeKind.Utc), zone)
        .ToString("ddd yyyy-MM-dd HH:mm", CultureInfo.InvariantCulture);

// Phase 1: a deploy step publishes the calendar before the jobs that name it start. An enqueue-only host (no Run<>)
// still bootstraps the schema, and the operations need no worker.
long current;
{
    var seed = Host.CreateApplicationBuilder(args);
    seed.Services.UseActa(j => j.UseLocalDatabase(seed.Configuration));
    using var seedHost = seed.Build();
    await seedHost.StartAsync();

    var calendars = seedHost.Services.GetRequiredService<IActaOperations>().Calendars;

    // learn: 2. Preview the draft, then publish it
    // The preview answers the draft's next occurrences from any instant, in the zone you name. This one starts on the
    // Friday before a Monday holiday. When the list changes, save the new definition and publish it again: every
    // schedule that names the calendar follows the new version.
    var draft = await calendars.SaveDraftAsync(workingDays, CalendarRoleCode.Occurrence, Definitions.WorkingDays);
    var friday = new DateTimeOffset(2027, 10, 29, 0, 0, 0, TimeSpan.Zero);
    var preview = (await calendars.PreviewAsync(workingDays, draft.Version!.Value, friday, count: 3, timeZoneId: "Europe/Ljubljana"))!;
    foreach (var occurrence in preview.OccurrencesUtc)
    {
        Console.WriteLine($"reports {Local(occurrence)}");
    }
 
    await calendars.PublishAsync(workingDays, draft.Version.Value, reasonMessage: "Holidays through February 2028");
    // learn: end
    current = draft.Version.Value;

    await seedHost.StopAsync();
}

// Phase 2: the start deploys daily-report, whose schedule names working-days. The deploy checks that the family has
// a published version.
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
    j.UseLocalDatabase(builder.Configuration);
    j.Run<HolidayCalendarJobs>("reports");
});

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

// The schedule has no expression of its own: its next occurrence is the calendar's next instant. The namespace also
// lists the system jobs' schedules (alerts, retention), so the read names the job.
var operations = host.Services.GetRequiredService<IActaOperations>();
var schedule = (
    await operations.Schedules.ListAsync(new ListSchedulesQuery(JobNamespace: "reports", JobName: "daily-report"))
).Items.Single();
var next = (await operations.Calendars.PreviewAsync(workingDays, current, count: 1, timeZoneId: "Europe/Ljubljana"))!.OccurrencesUtc[0];
Console.WriteLine(
    $"Next report {Local(schedule.NextOccurrenceAtUtc!.Value)}; the calendar's next instant: {schedule.NextOccurrenceAtUtc == next}"
);

await host.StopAsync();

namespace Acta.Learn.HolidayCalendar
{
    public readonly record struct DailyReport;

    public static class Definitions
    {
        // learn: 1. List the holidays in a calendar definition
        // A `daily-local-time` definition fires at each of `times` on each of `days`, and skips every date in
        // `excludedDates`. Paste the whole list of holidays: one that falls on a weekend is skipped twice over.
        public const string WorkingDays = """
            {
              "kind": "daily-local-time",
              "times": ["08:00"],
              "days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
              "excludedDates": ["2027-11-01", "2027-12-25", "2027-12-26", "2028-01-01", "2028-01-02", "2028-02-08"]
            }
            """;
        // learn: end
    }

    public sealed class DailyReportJob
    {
        [Job("daily-report")]
        // learn: 3. Name the calendar on the schedule
        // `Calendar` takes the place of a cron or an interval, and `TimeZoneId` is the zone the calendar's local times
        // are read in.
        [Schedule("working-days-at-eight", Calendar = "working-days", TimeZoneId = "Europe/Ljubljana")]
        // learn: end
        public Task Handle(DailyReport input, CancellationToken ct)
        {
            Console.WriteLine($"{DateTime.UtcNow:yyyy-MM-dd} sent the daily report");
            return Task.CompletedTask;
        }
    }
}

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.