1Name the schedule
A schedule is named by its namespace, its job, and its own name. The development start deploys the schedule before the worker starts, so its row exists once StartAsync returns.
using var host = builder.Build();
await host.StartAsync();
var schedules = host.Services.GetRequiredService<IActaOperations>().Schedules;
var queries = host.Services.GetRequiredService<IActaOperations>();
var lookup = new ScheduleLookup("schedule-control", "hourly-report", "every-hour");
Console.WriteLine("Pausing schedule indefinitely...");
var r1 = await schedules.PauseAsync(lookup, untilUtc: null, reasonMessage: "maintenance window");
Console.WriteLine($"After indefinite pause: status={r1.Status} next-run={r1.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");2Pause it until someone resumes it
An indefinite pause: the schedule does not fire until an operator explicitly resumes it.
var lookup = new ScheduleLookup("schedule-control", "hourly-report", "every-hour");
Console.WriteLine("Pausing schedule indefinitely...");
var r1 = await schedules.PauseAsync(lookup, untilUtc: null, reasonMessage: "maintenance window");
Console.WriteLine($"After indefinite pause: status={r1.Status} next-run={r1.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
var resumeAt = DateTime.UtcNow.AddHours(2);
Console.WriteLine($"Replacing with timed pause until {resumeAt:O}...");
var r2 = await schedules.PauseAsync(lookup, untilUtc: resumeAt, reasonMessage: "drain window");
Console.WriteLine($"After timed pause: status={r2.Status} paused-until={r2.PausedUntilUtc?.ToString("O") ?? "(none)"}");3Or pause it until an instant
A timed pause: the scheduler resumes the schedule by itself when the timestamp passes.
Console.WriteLine("Pausing schedule indefinitely...");
var r1 = await schedules.PauseAsync(lookup, untilUtc: null, reasonMessage: "maintenance window");
Console.WriteLine($"After indefinite pause: status={r1.Status} next-run={r1.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
var resumeAt = DateTime.UtcNow.AddHours(2);
Console.WriteLine($"Replacing with timed pause until {resumeAt:O}...");
var r2 = await schedules.PauseAsync(lookup, untilUtc: resumeAt, reasonMessage: "drain window");
Console.WriteLine($"After timed pause: status={r2.Status} paused-until={r2.PausedUntilUtc?.ToString("O") ?? "(none)"}");
Console.WriteLine("Resuming schedule...");
var r3 = await schedules.ResumeAsync(lookup, reasonMessage: "drain complete");
Console.WriteLine($"After resume: status={r3.Status} next-run={r3.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");4Resume it
A resume clears the pause and keeps the cursor; the next admission pass decides any missed occurrence.
Console.WriteLine("Resuming schedule...");
var r3 = await schedules.ResumeAsync(lookup, reasonMessage: "drain complete");
Console.WriteLine($"After resume: status={r3.Status} next-run={r3.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
// Confirm via the query surface that the schedule is active again and has a next-run time.
var page = await queries.Schedules.ListAsync(new ListSchedulesQuery(JobNamespace: "schedule-control"));
var item = page.Items.FirstOrDefault(i => i.ScheduleName == "every-hour");
Console.WriteLine($"Query confirms: status={item?.Status} next-run={item?.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");5The job it acts on
public sealed class HourlyReportJob
{
// 1h interval: will not fire during the short demo run, so only schedule-control is exercised.
[Job("hourly-report", EventRecording = EventRecordingCode.Failures)]
[Schedule("every-hour", "1h")]
public async Task Handle(GenerateHourlyReport input, CancellationToken ct)
{
await Task.Delay(100, ct);
Console.WriteLine("hourly report generated");
}
}6Run it and check the output
From a clone of the Acta repository, with the .NET 10 SDK:
dotnet run --project learn/100-scheduling/105-schedule-controlAfter indefinite pause: status=Paused
After timed pause: status=Paused paused-until=
After resume: status=Active
Query confirms: status=ActiveChecked 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/105-schedule-control, 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.
schedule-control.cs78 lines
// How to pause and resume a schedule
// `operations.Schedules` pauses a schedule from outside the handler, for good or until an instant, and resumes it.
using Acta;
using Acta.Learn.ScheduleControl;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.UseActa(j =>
{
j.UseLocalDatabase(builder.Configuration);
j.Run<ScheduleControlJobs>("schedule-control");
});
using var host = builder.Build();
await host.StartAsync();
var schedules = host.Services.GetRequiredService<IActaOperations>().Schedules;
var queries = host.Services.GetRequiredService<IActaOperations>();
// learn: 1. Name the schedule
// A schedule is named by its namespace, its job, and its own name.
// The development start deploys the schedule before the worker starts, so its row exists once StartAsync returns.
var lookup = new ScheduleLookup("schedule-control", "hourly-report", "every-hour");
// learn: end
Console.WriteLine("Pausing schedule indefinitely...");
// learn: 2. Pause it until someone resumes it
// An indefinite pause: the schedule does not fire until an operator explicitly resumes it.
var r1 = await schedules.PauseAsync(lookup, untilUtc: null, reasonMessage: "maintenance window");
// learn: end
Console.WriteLine($"After indefinite pause: status={r1.Status} next-run={r1.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
// learn: 3. Or pause it until an instant
// A timed pause: the scheduler resumes the schedule by itself when the timestamp passes.
var resumeAt = DateTime.UtcNow.AddHours(2);
Console.WriteLine($"Replacing with timed pause until {resumeAt:O}...");
var r2 = await schedules.PauseAsync(lookup, untilUtc: resumeAt, reasonMessage: "drain window");
// learn: end
Console.WriteLine($"After timed pause: status={r2.Status} paused-until={r2.PausedUntilUtc?.ToString("O") ?? "(none)"}");
Console.WriteLine("Resuming schedule...");
// learn: 4. Resume it
// A resume clears the pause and keeps the cursor; the next admission pass decides any missed occurrence.
var r3 = await schedules.ResumeAsync(lookup, reasonMessage: "drain complete");
// learn: end
Console.WriteLine($"After resume: status={r3.Status} next-run={r3.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
// Confirm via the query surface that the schedule is active again and has a next-run time.
var page = await queries.Schedules.ListAsync(new ListSchedulesQuery(JobNamespace: "schedule-control"));
var item = page.Items.FirstOrDefault(i => i.ScheduleName == "every-hour");
Console.WriteLine($"Query confirms: status={item?.Status} next-run={item?.NextOccurrenceAtUtc?.ToString("O") ?? "(none)"}");
await host.StopAsync();
namespace Acta.Learn.ScheduleControl
{
public readonly record struct GenerateHourlyReport;
public sealed class HourlyReportJob
{
// 1h interval: will not fire during the short demo run, so only schedule-control is exercised.
[Job("hourly-report", EventRecording = EventRecordingCode.Failures)]
[Schedule("every-hour", "1h")]
public async Task Handle(GenerateHourlyReport input, CancellationToken ct)
{
await Task.Delay(100, ct);
Console.WriteLine("hourly report generated");
}
}
}