How-to guide

Choose effect providers

Effect providers do the side effects of a run: database writes, logging, serialization. Each one is independent, so adding or removing one does not change train code. Why they work this way is on Effect.

Pick the providers

ProviderCallPackagePick it to
Data persistenceUsePostgres, UseSqlite, UseInMemoryTrax.Effect.Data.Postgres, .Sqlite, .InMemoryKeep a queryable row for every run. Postgres or Sqlite in production, InMemory in tests.
JSON effectAddJsonTrax.Effect.Provider.JsonLog each run's state changes as JSON, with no database
Parameter effectSaveTrainParametersTrax.Effect.Provider.ParameterStore each run's input and output as JSON on its row
Junction loggerAddJunctionLoggerTrax.Effect.JunctionProvider.LoggingLog a structured entry for every junction of a run
Junction progressAddJunctionProgressTrax.Effect.JunctionProvider.ProgressShow the running junction on the dashboard, and stop a run between junctions when it is cancelled
Lifecycle hooksAddLifecycleHook<T>Trax.EffectRun code of your own when a run starts, completes, fails or is cancelled

The junction logger and junction progress run around EffectJunction<TIn, TOut> only, not a plain Junction<TIn, TOut> (EffectJunction vs Junction). A lifecycle hook that throws is caught and logged; it never fails the run.

Other calls on the same builder record or carry more than the run row: junction events (AddJunctionEvents), decision records (AddDecisionRecording) and broadcasters (UseBroadcaster). Host tracking is on by default.

Combine them

Providers compose on one AddEffects call. A production host:

using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Effect.JunctionProvider.Logging.Extensions;
using Trax.Effect.JunctionProvider.Progress.Extensions;
using Trax.Effect.Provider.Parameter.Extensions;
using Trax.Mediator.Extensions;
 
services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UsePostgres(connectionString)                     // Persist run rows
        .SaveTrainParameters()                             // Input and output on the row
        .AddJunctionLogger(serializeJunctionData: true)    // Log each junction
        .AddJunctionProgress()                             // Junction progress and cancellation check
    )
    .AddMediator(assemblies)
);

A development host, with no database:

using Trax.Effect.Data.InMemory.Extensions;
using Trax.Effect.Extensions;
using Trax.Effect.JunctionProvider.Logging.Extensions;
using Trax.Effect.Provider.Json.Extensions;
using Trax.Mediator.Extensions;
 
services.AddTrax(trax => trax
    .AddEffects(effects => effects
        .UseInMemory()
        .AddJson()                                         // Log state changes
        .AddJunctionLogger()
    )
    .AddMediator(assemblies)
);

The AddEffects lambda returns the builder from its last call. A data provider returns TraxEffectBuilderWithData, which is what the data-dependent calls (AddDataContextLogging, AddDecisionRecording, AddJunctionEvents) need, so they come after it. AddTrax and AddEffects has the builder types.

SDK Reference

UsePostgres | UseSqlite | UseInMemory | AddJson | SaveTrainParameters | AddJunctionLogger | AddJunctionProgress | AddLifecycleHook | AddMediator