How-to guide

Schedule a train

Run a train on a schedule stored in Postgres: one job every 30 seconds and one every night, then read what the scheduler recorded, trigger a job on demand and quiet the scheduler's own logs. The steps use a small report train in a new project; in an existing host, skip to step 3.

Every C# block on this page is compiled in CI. You need the .NET 10 SDK and Docker.

1. Create a project and start Postgres

dotnet new web -n Reports
cd Reports

Replace Reports.csproj with this:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
 
  <ItemGroup>
    <PackageReference Include="Trax.Effect" Version="1.70.0" />
    <PackageReference Include="Trax.Effect.Data.Postgres" Version="1.70.0" />
    <PackageReference Include="Trax.Mediator" Version="1.70.0" />
    <PackageReference Include="Trax.Scheduler" Version="1.70.0" />
  </ItemGroup>
</Project>

Start a database and point the application at it:

docker run -d --name reports-db -p 5432:5432 \
  -e POSTGRES_USER=trax -e POSTGRES_PASSWORD=trax123 -e POSTGRES_DB=trax postgres:17

appsettings.json:

{
  "ConnectionStrings": {
    "TraxDatabase": "Host=localhost;Port=5432;Database=trax;Username=trax;Password=trax123"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

docker ps lists reports-db as running.

2. Define the train

The scheduler stores each job's input in the database, so the input implements IManifestProperties. A train whose input does not implement it cannot be passed to the scheduling methods.

Report.cs:

using Trax.Core.Functional;
using Trax.Effect.Models.Manifest;
using Trax.Effect.Services.EffectJunction;
using Trax.Effect.Services.ServiceTrain;
 
namespace Reports;
 
public record ReportInput : IManifestProperties
{
    public string Region { get; init; } = "";
}
 
public class BuildReportJunction(ILogger<BuildReportJunction> logger)
    : EffectJunction<ReportInput, Unit>
{
    public override Task<Unit> Run(ReportInput input)
    {
        logger.LogInformation("Building the {Region} report", input.Region);
        return Task.FromResult(Unit.Default);
    }
}
 
public interface IReportTrain : IServiceTrain<ReportInput, Unit>;
 
public class ReportTrain : ServiceTrain<ReportInput, Unit>, IReportTrain
{
    protected override Task<Either<Exception, Unit>> Junctions() =>
        Chain<BuildReportJunction>().Resolve();
}

dotnet build succeeds. Nothing runs the train yet.

3. Run it every 30 seconds

Program.cs:

using Reports;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
using Trax.Scheduler.Services.Scheduling;
 
var builder = WebApplication.CreateBuilder(args);
 
var connectionString =
    builder.Configuration.GetConnectionString("TraxDatabase")
    ?? throw new InvalidOperationException("Set ConnectionStrings:TraxDatabase.");
 
builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UsePostgres(connectionString))
        .AddMediator(typeof(Program).Assembly)
        .AddScheduler(scheduler =>
            scheduler.Schedule<IReportTrain>(
                "report-eu",
                new ReportInput { Region = "eu" },
                Every.Seconds(30)
            )
        )
);
 
var app = builder.Build();
app.Run();
dotnet run

Within a few seconds the log shows Building the eu report, and again every 30 seconds after that. UsePostgres created the trax schema on start, Schedule stored the job as a manifest named report-eu, and the scheduler ran it on worker threads in this process.

4. Read what the scheduler recorded

In a second terminal:

docker exec reports-db psql -U trax -d trax -c \
  "select external_id, schedule_type, interval_seconds, last_successful_run from trax.manifest"
 
docker exec reports-db psql -U trax -d trax -c \
  "select name, train_state, start_time from trax.metadata
   where manifest_id is not null order by id desc limit 5"

The first query shows one manifest, report-eu, with a 30-second interval and the time of its last successful run. The second shows one row per run of it, each named Reports.IReportTrain and Completed. A run that fails is recorded too, with the junction that failed and its exception, and the scheduler retries it.

5. Add a nightly job with retries

Add a second manifest for the same train, on a cron schedule, with up to five retries.

Program.cs:

using Reports;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
using Trax.Scheduler.Services.Scheduling;
 
var builder = WebApplication.CreateBuilder(args);
 
var connectionString =
    builder.Configuration.GetConnectionString("TraxDatabase")
    ?? throw new InvalidOperationException("Set ConnectionStrings:TraxDatabase.");
 
builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UsePostgres(connectionString))
        .AddMediator(typeof(Program).Assembly)
        .AddScheduler(scheduler =>
            scheduler
                .Schedule<IReportTrain>(
                    "report-eu",
                    new ReportInput { Region = "eu" },
                    Every.Seconds(30)
                )
                .Schedule<IReportTrain>(
                    "report-us-nightly",
                    new ReportInput { Region = "us" },
                    Cron.Daily(hour: 3),
                    options => options.MaxRetries(5)
                )
        )
);
 
var app = builder.Build();
app.Run();

Stop the host, run it again, and repeat the first query. There are two manifests now: report-us-nightly has a cron expression and a next_scheduled_run of the next 03:00 UTC. A cron job never runs at startup, so the log still shows only the eu report. Restarting did not duplicate report-eu: each start writes the manifests by external id, updating the ones that exist.

6. Run the nightly job now

A host can trigger any manifest through ITraxScheduler. Map an endpoint that does it, in Development only, since anyone who can reach it can run the job.

Program.cs:

using Reports;
using Trax.Effect.Data.Postgres.Extensions;
using Trax.Effect.Extensions;
using Trax.Mediator.Extensions;
using Trax.Scheduler.Extensions;
using Trax.Scheduler.Services.Scheduling;
using Trax.Scheduler.Services.TraxScheduler;
 
var builder = WebApplication.CreateBuilder(args);
 
var connectionString =
    builder.Configuration.GetConnectionString("TraxDatabase")
    ?? throw new InvalidOperationException("Set ConnectionStrings:TraxDatabase.");
 
builder.Services.AddTrax(trax =>
    trax.AddEffects(effects => effects.UsePostgres(connectionString))
        .AddMediator(typeof(Program).Assembly)
        .AddScheduler(scheduler =>
            scheduler
                .Schedule<IReportTrain>(
                    "report-eu",
                    new ReportInput { Region = "eu" },
                    Every.Seconds(30)
                )
                .Schedule<IReportTrain>(
                    "report-us-nightly",
                    new ReportInput { Region = "us" },
                    Cron.Daily(hour: 3),
                    options => options.MaxRetries(5)
                )
        )
);
 
var app = builder.Build();
 
if (app.Environment.IsDevelopment())
    app.MapPost(
        "/reports/{externalId}/run",
        async (string externalId, ITraxScheduler scheduler) =>
        {
            await scheduler.TriggerAsync(externalId);
            return Results.Accepted();
        }
    );
 
app.Run();
dotnet run
curl -X POST http://localhost:5000/reports/report-us-nightly/run

Use the port dotnet run prints. The request answers 202, and within a couple of seconds the log shows Building the us report. The trigger queued one run of the manifest and left its schedule alone, so it still runs at 03:00.

7. Quiet the scheduler's own logs

The log also has a few lines from the scheduler every cycle. Raise their category in appsettings.json:

{
  "ConnectionStrings": {
    "TraxDatabase": "Host=localhost;Port=5432;Database=trax;Username=trax;Password=trax123"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Trax.Scheduler.Trains": "Warning"
    }
  }
}

Run the host again. The log now shows the reports and little else. Failures still come through: a failed job is logged at Error, and a job that runs out of retries at Warning.

Where next

SDK Reference

AddScheduler | Schedule | Every / Cron | TriggerAsync | ITraxScheduler