1Save the calendar as a draft and publish it
A calendar is a JSON definition saved as a draft, then published. officeHours names the family office-hours in sys, which every namespace binds by its plain name, and Definitions.OpenAllDay is a definition open all day, every day. A deploy step names no versions, so it runs again as it is: a definition the latest version already holds saves nothing and answers AlreadyInState with that version, and publishing the current version again changes nothing.
// Phase 1: the calendar is published before the job that binds it deploys, as an operator would do it from
// the dashboard. An enqueue-only host (no Run<>) still bootstraps the schema, and the operations need no worker.
{
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;
var draft = await calendars.SaveDraftAsync(officeHours, CalendarRoleCode.Availability, Definitions.OpenAllDay);
Console.WriteLine($"Draft saved: {draft.Action}, version {draft.Version}");
var published = await calendars.PublishAsync(officeHours, draft.Version!.Value, reasonMessage: "Go live");
Console.WriteLine($"Published: {published.Action}, version {published.Version} is current");
await seedHost.StopAsync();
}2Bind the schedule to the calendar by name
Availability names the calendar. The schedule fires only inside the windows its current version opens.
public sealed class TickJob
{
[Job("tick")]
[Schedule("every-10s-in-hours", "PT10S", Availability = "office-hours")]
public Task Handle(Tick input, CancellationToken ct)
{
Console.WriteLine($"{DateTime.UtcNow:HH:mm:ss} UTC tick");
return Task.CompletedTask;
}
}3Publish a change and let it retime the schedule
The publication moves the cursor of every schedule bound to the calendar, in the same transaction. closed is the draft saved just above, whose definition has no window today.
var result = await operations.Calendars.PublishAsync(officeHours, closed.Version.Value, reasonMessage: $"Closed on {today}");
Console.WriteLine($"Published: {result.Action}; retimed [{string.Join(", ", result.RetimedSchedules)}]");
// The namespace also lists the system jobs' schedules (alerts, retention), so the read names the job.
var schedule = (
await operations.Schedules.ListAsync(new ListSchedulesQuery(JobNamespace: "calendar-catalog", JobName: "tick"))
).Items.Single();
Console.WriteLine($"Next occurrence {schedule.NextOccurrenceAtUtc:O}.");4Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/100-scheduling/108-calendar-catalogPublished: Applied, version 1 is current
UTC tick
Published: Applied; retimed [calendar-catalog/tick/every-10s-in-hours]
Watching 15s for a tick that must not come...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/108-calendar-catalog, 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.
calendar-catalog.cs122 lines
// How to drive a schedule from a published calendar
// A calendar is data that an operator publishes through `operations.Calendars`. A schedule binds it by name, and a
// later publication retimes every schedule bound to it in one transaction while workers run.
using System.Globalization;
using Acta;
using Acta.Learn.CalendarCatalog;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
// A family in sys is shared: every namespace binds it by its plain name.
var officeHours = new CalendarLookup("sys", "office-hours");
// Phase 1: the calendar is published before the job that binds it deploys, as an operator would do it from
// the dashboard. An enqueue-only host (no Run<>) still bootstraps the schema, and the operations need no worker.
{
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: 1. Save the calendar as a draft and publish it
// A calendar is a JSON definition saved as a draft, then published. `officeHours` names the family
// `office-hours` in `sys`, which every namespace binds by its plain name, and `Definitions.OpenAllDay` is a
// definition open all day, every day.
// A deploy step names no versions, so it runs again as it is: a definition the latest version already holds saves
// nothing and answers AlreadyInState with that version, and publishing the current version again changes nothing.
var draft = await calendars.SaveDraftAsync(officeHours, CalendarRoleCode.Availability, Definitions.OpenAllDay);
Console.WriteLine($"Draft saved: {draft.Action}, version {draft.Version}");
var published = await calendars.PublishAsync(officeHours, draft.Version!.Value, reasonMessage: "Go live");
// learn: end
Console.WriteLine($"Published: {published.Action}, version {published.Version} is current");
await seedHost.StopAsync();
}
// Phase 2: the development start deploys tick, whose schedule names office-hours. The deploy checks that the family
// has a published version, and the name resolves to the shared family's current version afresh at every evaluation.
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<CalendarCatalogJobs>("calendar-catalog");
});
using var host = builder.Build();
await host.StartAsync();
var operations = host.Services.GetRequiredService<IActaOperations>();
Console.WriteLine("Ticking every 10s inside the open window...");
await Task.Delay(TimeSpan.FromSeconds(25));
// The operator closes today, editing the version they read: naming it as the expected latest version turns another
// operator's save in between into a VersionConflict rather than a draft built on a stale read. The draft is previewed
// beside the current version, then published: the bound schedule's cursor moves to the first instant inside the next window.
var today = DateTime.UtcNow.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
var read = (await operations.Calendars.GetAsync(officeHours))!;
var closed = await operations.Calendars.SaveDraftAsync(
officeHours,
CalendarRoleCode.Availability,
Definitions.ClosedOn(today),
expectedLatestVersion: read.LatestVersion,
reasonMessage: $"Closed on {today}"
);
var preview = (await operations.Calendars.PreviewAsync(officeHours, closed.Version!.Value, count: 3))!;
Console.WriteLine(
$"Preview of version {closed.Version}: the next window opens {preview.Windows[0].StartUtc:O}; "
+ $"{preview.SchedulesTotal} bound schedule(s), {preview.OverdueTotal} overdue"
);
// learn: 3. Publish a change and let it retime the schedule
// The publication moves the cursor of every schedule bound to the calendar, in the same transaction. `closed` is the
// draft saved just above, whose definition has no window today.
var result = await operations.Calendars.PublishAsync(officeHours, closed.Version.Value, reasonMessage: $"Closed on {today}");
Console.WriteLine($"Published: {result.Action}; retimed [{string.Join(", ", result.RetimedSchedules)}]");
// learn: end
// The namespace also lists the system jobs' schedules (alerts, retention), so the read names the job.
var schedule = (
await operations.Schedules.ListAsync(new ListSchedulesQuery(JobNamespace: "calendar-catalog", JobName: "tick"))
).Items.Single();
Console.WriteLine($"Next occurrence {schedule.NextOccurrenceAtUtc:O}.");
Console.WriteLine("Watching 15s for a tick that must not come...");
await Task.Delay(TimeSpan.FromSeconds(15));
await host.StopAsync();
namespace Acta.Learn.CalendarCatalog
{
public readonly record struct Tick;
public static class Definitions
{
public const string OpenAllDay = """
{"kind":"weekly-availability","timeZone":"UTC",
"weekly":[{"days":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"windows":[["00:00","23:59:59"]]}]}
""";
// A date override replaces the weekday's windows for that date; none closes it.
public static string ClosedOn(string date) =>
$$$"""
{"kind":"weekly-availability","timeZone":"UTC",
"weekly":[{"days":["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"],"windows":[["00:00","23:59:59"]]}],
"dateOverrides":{"{{{date}}}":[]}}
""";
}
public sealed class TickJob
{
[Job("tick")]
// learn: 2. Bind the schedule to the calendar by name
// `Availability` names the calendar. The schedule fires only inside the windows its current version opens.
[Schedule("every-10s-in-hours", "PT10S", Availability = "office-hours")]
// learn: end
public Task Handle(Tick input, CancellationToken ct)
{
Console.WriteLine($"{DateTime.UtcNow:HH:mm:ss} UTC tick");
return Task.CompletedTask;
}
}
}