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, so 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

Each group setting is written only when stated: an existing group keeps any setting its members leave unstated, including a change made from the dashboard. Members of one group that state different values for a setting fail AddScheduler at startup. See What a Restart Rewrites.

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
    .AddEffects(effects => effects.UsePostgres(connectionString))
    .AddMediator(typeof(Program).Assembly)
    .AddScheduler(scheduler => scheduler
        .Schedule<ISyncTrain>(
            "sync-daily",
            new SyncInput { Source = "production" },
            Cron.Daily(hour: 3),
            options => options
                .MaxRetries(5)
                .Priority(20)
                .Group("daily-syncs"))
    )
);

AddScheduler extends the builder AddMediator returns, so it comes after AddEffects and AddMediator; called earlier, it does not compile. 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 every5Minutes = Every.Minutes(5).WithVariance(TimeSpan.FromMinutes(2));
 
// Cron with 30-minute jitter
var dailyAt3 = 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 and needs no Schedule object. See Delayed / One-Off Jobs for details.