AddScheduler

Adds the Trax.Core scheduler subsystem. Registers ITraxScheduler, the background polling service, and all scheduler infrastructure. Provides a SchedulerConfigurationBuilder lambda for configuring global options, execution backends, and startup schedules.

Signature

// With configuration
public static TraxBuilderWithMediator AddScheduler(
    this TraxBuilderWithMediator builder,
    Func<SchedulerConfigurationBuilder, SchedulerConfigurationBuilder> configure
)
 
// Parameterless defaults
public static TraxBuilderWithMediator AddScheduler(
    this TraxBuilderWithMediator builder
)

AddScheduler is called on TraxBuilderWithMediator (the return type of AddMediator()), which enforces at compile time that effects and the mediator are configured before the scheduler.

The parameterless overload registers the scheduler with default settings, equivalent to AddScheduler(scheduler => scheduler).

Parameters

Returns

TraxBuilderWithMediator, for continued fluent chaining (adding another AddScheduler() call is not typical, but the type allows further configuration).

Example

services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
    )
    .AddMediator(typeof(Program).Assembly)
    .AddScheduler(scheduler => scheduler
        .ManifestManagerPollingInterval(TimeSpan.FromSeconds(5))
        .JobDispatcherPollingInterval(TimeSpan.FromSeconds(5))
        .MaxActiveJobs(50)
        .DefaultMaxRetries(5)
        .DefaultRetryDelay(TimeSpan.FromMinutes(2))
        .RetryBackoffMultiplier(2.0)
        .MaxRetryDelay(TimeSpan.FromHours(1))
        .DefaultJobTimeout(TimeSpan.FromMinutes(20))
        .DefaultMisfirePolicy(MisfirePolicy.FireOnceNow)
        .DefaultMisfireThreshold(TimeSpan.FromSeconds(60))
        .RecoverStuckJobsOnStartup()
        .DependentPriorityBoost(16)
        .AddMetadataCleanup()
        .Schedule<MyTrain>(
            "my-job",
            new MyInput(),
            Every.Minutes(5),
            options => options
                .Priority(10)
                .Group("my-group"))
    )
);

SchedulerConfigurationBuilder Options

These methods are available on the SchedulerConfigurationBuilder passed to the configure lambda:

Execution Backend

Global Options

Value Ranges

AddScheduler checks every duration and count it is given when the scheduler is built, against the same ranges a runtime change through the dashboard or updateScheduler is held to. A value outside its range fails the build with an InvalidOperationException that lists every problem at once, each named by the method (or options property) that set it.

FailureCountWindow is checked earlier, at the call: it throws ArgumentOutOfRangeException unless the window is between one second and ten years.

The polling services never wait less than one second between cycles, whatever interval reaches them. At startup the scheduler also logs a warning when the retry backoff for DefaultMaxRetries retries adds up to FailureCountWindow or more: the oldest failure would leave the window before the last retry, so a manifest that always fails would retry for ever without being dead-lettered. Lengthen the window, or lower DefaultMaxRetries, DefaultRetryDelay or MaxRetryDelay.

Startup Schedules

Remarks

• The settings the dashboard's Server Settings page and the updateScheduler mutation edit (the enable switches, polling intervals, MaxActiveJobs, retry, timeout, failure-count window and dead-letter settings, the local worker count and the metadata cleanup interval and retention) are stored in trax.scheduler_config. A save stores only the settings it names (a scheduler host leaves out a field equal to the value it runs with; a host that does not run the scheduler stores every field it sends; the dashboard sends only the fields the operator changed), and any host can make one, the first included, including an API-only one. Every running scheduler applies the stored values over these builder values at startup and re-reads the row every few seconds, so a saved change reaches all of them without a restart; the local worker count is the exception and applies when the worker pool next starts. A setting no save has named is not stored, so each host keeps its builder value for it. A stored value takes precedence over the builder value until it is changed or the row is deleted, and the scheduler logs a warning when one replaces a different builder value; AutoPurgeDeadLetters and DeadLetterRetentionPeriod fail closed instead (see their rows). A scheduler that cannot read the row at startup runs with the builder values and applies the row at its first successful read. See scheduler ADR 0010.
• AddScheduler requires AddEffects() and AddMediator() to be called first. This is enforced at compile time -- AddScheduler is only available on TraxBuilderWithMediator, which is the return type of AddMediator().
• AddScheduler requires a data provider (UsePostgres() or UseInMemory()). If no data provider is configured, AddScheduler throws InvalidOperationException at build time with a helpful error message showing the required configuration.
• Internal scheduler trains (ManifestManager, InMemoryManifestManager, JobDispatcher, JobRunner, MetadataCleanup, DeadLetterCleanup) are automatically excluded from MaxActiveJobs.
• With UseInMemory(), JobDispatcherPollingService and MetadataCleanupPollingService are not registered. The ManifestManagerPollingService runs an InMemoryManifestManagerTrain that dispatches jobs inline through the in-memory job submitter.
• The host refuses to start, with an InvalidOperationException naming the trains whose chains ask a decider, when it does not register AddDecisionRecording(). Such a host could not replay a requeue's recorded decisions, so a requeue that landed on it would fail, Permanent; Trax refuses at startup rather than leave that to be found by the first requeue. The check runs before any worker claims work. See A host that does not record.
• Manifests declared via Schedule/ScheduleMany are not created immediately. They are seeded on application startup by the SchedulerStartupService.
• Manifests declared via Schedule/ThenInclude/Include get a ManifestGroup based on their groupId parameter (defaults to externalId). Per-group dispatch controls (MaxActiveJobs, Priority, IsEnabled) are configured from the dashboard.
• At build time, the scheduler validates that ManifestGroup dependencies form a DAG (no circular dependencies). If a cycle is detected, AddScheduler throws InvalidOperationException with the groups involved. See Dependent Trains: Cycle Detection.