AddTrax

Package Trax.EffectNamespaces Trax.Effect.Extensions, Trax.Effect.Configuration.TraxBuilderSource ServiceExtensions.cs, TraxBuilder.cs, TraxMarker.cs

Registers Trax on the service collection. The configure callback receives a TraxBuilder, on which the subsystems are added in a fixed order: AddEffects, then AddMediator, then AddScheduler. Every Trax host calls it once.

Signature

public static IServiceCollection AddTrax(
    this IServiceCollection services,
    Action<TraxBuilder> configure
)

Parameters

Parameter	Type	Description
`services`	`IServiceCollection`	The host's service collection
`configure`	`Action<TraxBuilder>`	Adds the subsystems and sets the host identity

Returns

IServiceCollection, the same collection, for chaining.

Behavior

configure runs first. Then AddTrax sets the process-wide host identity, TraxHostInfo.Current, from auto-detection and the host tracking methods called on the builder, and registers the services below. When configure does not call AddEffects, the effect configuration takes its defaults.

TraxBuilder

Member	Description
`AddEffects(...)`	The first step: configures effects and data providers. Returns `TraxBuilderWithEffects`. See AddEffects.
`SetHostEnvironment`, `SetHostInstanceId`, `AddHostLabel`, `AddHostLabels`	Override or extend the host identity. See Host Tracking.
`HasDataProvider`	True once `UsePostgres`, `UseSqlite` or `UseInMemory` ran. Set only by those methods.
`HasDatabaseProvider`	True once `UsePostgres` or `UseSqlite` ran; false for `UseInMemory`. Set only by those methods.
`ContributedMediatorAssemblies`	Assemblies a subsystem adds for `AddMediator` to scan, such as the state machine mutations' assembly `AddStateMachines` adds. `AddMediator` merges them into its scan.
`MediatorConfigured`	True once `AddMediator` has built the train registry.
`ServiceCollection`	The service collection being configured.

Order of the steps

Each step returns a builder type that has only the next steps on it, so an out-of-order chain does not compile.

Type	Returned by	Next step
`TraxBuilder`	the `AddTrax` callback	`AddEffects()`
`TraxBuilderWithEffects`	`AddEffects()`	`AddMediator()`
`TraxBuilderWithMediator`	`AddMediator()`, `AddScheduler()`	`AddScheduler()`

A call on the wrong step binds to an overload marked obsolete as an error, so the compiler reports the order (CS0619) instead of a missing method:

Call	Error
`AddMediator` before `AddEffects`	`Call AddEffects(...) before AddMediator(...).`
`AddMediator` a second time	`AddMediator(...) is already called. Call it once and configure everything in that call.`
`AddScheduler` before `AddMediator`	`Call AddMediator(...) before AddScheduler(...).`

Registered services

Service	Lifetime	Role
`TraxMarker`	Singleton	Records that `AddTrax` ran. `AddTraxGraphQL()` throws `InvalidOperationException` without it: `AddTraxGraphQL() requires AddTrax() to be called first.`
`IEffectRegistry`	Singleton	The `EffectRegistry` every effect, junction effect and lifecycle hook is registered in, and toggled through
`ITraxEffectConfiguration`	Singleton	The effect settings `AddEffects` built
`IEffectRunner`, `IJunctionEffectRunner`, `ILifecycleHookRunner`	Transient	Run a train's effects, junction effects and lifecycle hooks
`ILifecycleHookOutputPolicy`	Singleton	`DefaultLifecycleHookOutputPolicy`, unless `SaveTrainParameters` registered its own first
`ITraxChangeSignal`, `TraxChangeSignal`	Singleton	Collects the data-change signals behind `onDataChanged`. Its meter counts dropped signals as `TraxChangeSignal.DroppedCounterName` (`trax.change_signal.dropped`).
`ChangeSignalCoalescer`	Hosted service	Flushes the collected signals to every registered `IChangeSignalSink` (`FlushAsync`), one per changed domain per window
`ChangeSignalOptions`	Singleton, if none is registered	`CoalesceWindow` (250 ms) and `ChannelCapacity` (1024). Register a configured instance before `AddTrax` to change them.
`TimeProvider`	Singleton, if none is registered	`TimeProvider.System`
`CheckpointOptions`, `IRunResumes`, `ICheckpointStore`	Singleton, if none is registered	The checkpoint store and resume path

Example

services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)
        .AddJson()
        .SaveTrainParameters()
    )
    .AddMediator(typeof(IShipOrderTrain).Assembly)
    .AddScheduler()
);