Schedule / ScheduleAsync

Schedules a single train to run on a recurring basis. Schedule is used at startup configuration time; ScheduleAsync is used at runtime via ITraxScheduler.

Both use upsert semantics — if a manifest with the given externalId already exists, it is updated; otherwise a new one is created.

Signatures

Startup (SchedulerConfigurationBuilder) — Recommended

The input type TInput is inferred from the TTrain interface at configuration time — only a single type parameter is needed:

public SchedulerConfigurationBuilder Schedule<TTrain>(
    string externalId,
    IManifestProperties input,
    Schedule schedule,
    Action<ScheduleOptions>? options = null
)
    where TTrain : class

The method resolves TInput by reflecting on TTrain's IServiceTrain<TInput, TOutput> interface. If the provided input doesn't match the expected type, an InvalidOperationException is thrown at configuration time. The output type is not constrained — scheduled trains can return any output type, and the output is discarded for background jobs.

Startup (SchedulerConfigurationBuilder) — Explicit Type Parameters

The legacy three-type-parameter form is still available for backward compatibility:

public SchedulerConfigurationBuilder Schedule<TTrain, TInput, TOutput>(
    string externalId,
    TInput input,
    Schedule schedule,
    Action<ScheduleOptions>? options = null
)
    where TTrain : IServiceTrain<TInput, TOutput>
    where TInput : IManifestProperties

Runtime (ITraxScheduler)

Task<Manifest> ScheduleAsync<TTrain, TInput, TOutput>(
    string externalId,
    TInput input,
    Schedule schedule,
    Action<ScheduleOptions>? options = null,
    CancellationToken ct = default
)
    where TTrain : IServiceTrain<TInput, TOutput>
    where TInput : IManifestProperties

Type Parameters

Parameters

ScheduleOptions

The ScheduleOptions fluent builder consolidates all optional scheduling parameters:

Manifest-level methods

Group-level methods

ManifestGroupOptions

Returns

• Startup: SchedulerConfigurationBuilder — for continued fluent chaining.
• Runtime: Task<Manifest> — the created or updated manifest record.

Examples

Startup Configuration (Recommended — Inferred Input Type)

services.AddTrax(trax => trax
    .AddScheduler(scheduler => scheduler
        .Schedule<ISyncTrain>(
            "sync-daily",
            new SyncInput { Source = "production" },
            Cron.Daily(hour: 3),
            options => options
                .MaxRetries(5)
                .Priority(20)
                .Group("daily-syncs"))
    )
);

Only the train interface type is specified. The input type (SyncInput) is inferred from ISyncTrain : IServiceTrain<SyncInput, TOutput> and validated at configuration time. The output type is not constrained — it can be Unit or any other type, and the output is discarded for background jobs.

Runtime Scheduling

public class MyService(ITraxScheduler scheduler)
{
    public async Task SetupSchedule()
    {
        var manifest = await scheduler.ScheduleAsync<ISyncTrain, SyncInput, Unit>(
            "sync-on-demand",
            new SyncInput { Source = "staging" },
            Every.Hours(1),
            options => options.Priority(15));
    }
}

Schedule Record

The Schedule record defines the timing for a scheduled manifest. Create instances via Every.*, Cron.*, or Schedule.FromInterval() / Schedule.FromCron().

Properties

Methods

// Interval with 2-minute jitter
var schedule = Every.Minutes(5).WithVariance(TimeSpan.FromMinutes(2));
 
// Cron with 30-minute jitter
var schedule = Cron.Daily(3).WithVariance(TimeSpan.FromMinutes(30));

Remarks

• At startup, manifests are not created immediately — they are captured and seeded when the application starts via SchedulerStartupService.
• At runtime, ScheduleAsync creates/updates the manifest in the database immediately.
• The externalId is the primary key for upsert logic. Changing it creates a new manifest rather than updating the existing one.
• If the train type is not registered in the TrainRegistry (via AddMediator), an InvalidOperationException is thrown.
• The group is determined by .Group(...) on ScheduleOptions. When not specified, it defaults to the externalId. Groups are auto-created (upserted by name) during scheduling. Orphaned groups are cleaned up on startup.
• For one-off jobs that should run once and auto-disable, use ScheduleOnceAsync instead of ScheduleAsync. It creates a manifest with ScheduleType.Once — no Schedule object needed. See Delayed / One-Off Jobs for details.