Packages
Trax ships as 48 NuGet packages from one repository, TraxSharp/Trax. Most applications install four or five of them. This page lists every one: what it is for, the namespace you import to use it, the methods it adds, and what it needs beside it.
Every package releases at the same version, so install them all at one version. The site is published from the latest release, and the nuget.org link shows that release and its dependencies.
Requirements
Every library package targets net10.0, so every project that references one must target it too;
there is no net8.0 or net9.0 build. Trax.Core.Analyzers targets netstandard2.0, as Roslyn
analyzers do.
The packages depend on EF Core, Npgsql, HotChocolate and Microsoft.Extensions.*, and NuGet
resolves those. A project that also pins one of them directly has to pin at least the version Trax
was built against, or the restore fails with NU1605 (NU1109 under Central Package Management)
naming the package. The floors, from the repository's Directory.Packages.props at the release this
site was published from:
| Package | Minimum | Brought in by |
|---|---|---|
Microsoft.EntityFrameworkCore (and .Relational, .InMemory, .Sqlite) | 10.0.12 | Trax.Effect.Data and the data providers |
Npgsql | 10.0.3 | Trax.Effect.Data |
Npgsql.EntityFrameworkCore.PostgreSQL | 10.0.3 | Trax.Effect.Data.Postgres |
EFCore.NamingConventions | 10.0.1 | Trax.Effect.Data.Postgres |
Microsoft.Extensions.DependencyInjection, .Logging (and their .Abstractions) | 10.0.13 | Trax.Effect and up |
Other Microsoft.Extensions.* | 10.0.12 | Trax.Effect and up |
HotChocolate.* | 16.6.7 | Trax.Api.GraphQL |
Microsoft.AspNetCore.Authentication.JwtBearer, .OpenIdConnect | 10.0.9 | Trax.Api.Auth.Jwt, Trax.Api.Auth.Oidc |
A release can raise them; the dependency list on each package's nuget.org page is authoritative.
Which packages you need
Each layer depends on the one before it, and installing a package brings the layers below it with it. Pick the highest layer you need, then add one data provider.
| You want | Install |
|---|---|
| Typed pipelines only, no DI, no database | Trax.Core |
| Trains recorded in a database | Trax.Effect and one of Trax.Effect.Data.Postgres, Trax.Effect.Data.Sqlite, Trax.Effect.Data.InMemory |
| Dispatch by input type, startup chain checks | add Trax.Mediator |
| Cron and interval schedules, retries, dead letters | add Trax.Scheduler (needs a data provider; Postgres when several servers share the work) |
| A GraphQL API over your trains | add Trax.Api.GraphQL, plus an auth package such as Trax.Api.Auth.ApiKey or Trax.Api.Auth.Jwt |
| The operations console | add Trax.Api.Dashboard (a React app the host serves over its GraphQL API) |
A typical API host with a scheduler and the operations console:
dotnet add package Trax.Effect.Data.Postgres
dotnet add package Trax.Scheduler
dotnet add package Trax.Api.GraphQL
dotnet add package Trax.Api.Auth.ApiKey
dotnet add package Trax.Api.DashboardTrax.Effect.Data.Postgres brings Trax.Effect.Data, Trax.Effect and Trax.Core; Trax.Scheduler brings Trax.Mediator. The using lines each method needs are in the tables below.
Trax.Core
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.Core | Trains, junctions and chains: Train<TIn, TOut>, Junction<TIn, TOut>, Chain, ShortCircuit, Resolve, Memory. No DI container or database needed. See Core. | Trax.Core.Train, Trax.Core.Junction, and Trax.Core.Functional for Either and Unit | Nothing. Every other Trax package builds on it. |
| Trax.Core.Testing | Architecture-guard infrastructure and hygiene checkers: HygieneGuards, RepoConventionGuards, VocabularyGuards, GuardResult. See Architecture Guards. | Trax.Core.Testing, Trax.Core.Testing.Guards, Trax.Core.Testing.Fixtures | A test project. The other *.Testing guard packages build on it. |
| Trax.Core.Analyzers | Deprecated. The Roslyn analyzer for CHAIN001 and CHAIN002 no longer reports anything; the host checks every chain at startup instead. Do not install it. See Analyzer. |
Trax.Effect
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.Effect | ServiceTrain<TIn, TOut>, which records every run as a Metadata row; DI registration with AddTrax, AddEffects, AddScopedTraxRoute and the other lifetimes; AddLifecycleHook, UseBroadcaster, SetEffectLogLevel; the [TraxAuthorize] and [TraxAllowAnonymous] attributes. See Effect. | Trax.Effect.Extensions for the registration methods, Trax.Effect.Services.ServiceTrain for the base class, Trax.Effect.Attributes for the attributes | One data provider below, to persist the runs. |
| Trax.Effect.Data | The shared data layer behind the three providers: IDataContext over the Trax tables, AddDataContextLogging, and DomainDataContext with AddDomainDataContext for your own schemas. See Domain Data Contexts. | Trax.Effect.Data.Extensions (AddDataContextLogging), Trax.Effect.Data.Services.DomainContext (DomainDataContext, AddDomainDataContext, EnsureSchemaCreatedAsync) | Comes with each provider; install it directly only for a library that defines a DomainDataContext. |
| Trax.Effect.Data.Postgres | UsePostgres(connectionString) on the AddEffects builder, and SkipMigrations(). Persists runs to Postgres and applies the Trax schema migrations on startup. The production choice. See Data Persistence. | Trax.Effect.Data.Postgres.Extensions | Trax.Effect. Required by the scheduler when several servers share the work. |
| Trax.Effect.Data.Sqlite | UseSqlite(connectionString) on the AddEffects builder. For a single server or local development. See UseSqlite. | Trax.Effect.Data.Sqlite.Extensions | Trax.Effect. |
| Trax.Effect.Data.InMemory | UseInMemory() on the AddEffects builder. Runs are lost when the process exits. For tests and prototypes. See UseInMemory. | Trax.Effect.Data.InMemory.Extensions | Trax.Effect. |
| Trax.Effect.Data.Testing | Data-layer architecture guards: DataLayerGuards and DomainDataLayerGuardFixture (one schema per context, contexts derive DomainDataContext, owner-scope filters). See Architecture Guards. | Trax.Effect.Data.Testing | Trax.Core.Testing, in a test project. |
| Trax.Effect.Decisions.SystemOne | AddNimbleDecider(...): answers a train's decisions with Bespoke Labs' open-weights Nimble, on a Nimble server you run. AddSystemOneDecider(...) does the same for Jev or another server that accepts the System One format. See Decision Recording and Models. | Trax.Effect.Decisions.SystemOne.Extensions | Trax.Effect. |
| Trax.Effect.JunctionProvider.Logging | AddJunctionLogger(serializeJunctionData): logs each junction's start, finish and duration. See Junction Logger. | Trax.Effect.JunctionProvider.Logging.Extensions | Trax.Effect. Junctions must derive EffectJunction. |
| Trax.Effect.JunctionProvider.Progress | AddJunctionProgress(): writes the current junction to the Metadata row and checks for cancellation before each junction. See Junction Progress. | Trax.Effect.JunctionProvider.Progress.Extensions | Trax.Effect and a data provider, without which the host refuses to build. |
| Trax.Effect.Provider.Json | AddJson(): logs each tracked model's state as JSON while a train runs. For debugging. See JSON Effect. | Trax.Effect.Provider.Json.Extensions | Trax.Effect. |
| Trax.Effect.Provider.Parameter | SaveTrainParameters(): serializes each train's input and output into its Metadata row, masking members marked [TraxSensitive]. See Parameter Effect. | Trax.Effect.Provider.Parameter.Extensions | Trax.Effect and a data provider. |
| Trax.Effect.Broadcaster.RabbitMQ | UseRabbitMq(connectionString) on the UseBroadcaster builder, so lifecycle events raised in one process reach handlers in every other. See Broadcaster Sinks. | Trax.Effect.Broadcaster.RabbitMQ.Extensions | Trax.Effect. |
| Trax.Effect.Broadcaster.SignalR | UseSignalRHub() on the UseBroadcaster builder and MapTraxTrainEventHub() for the endpoint, so browser and Blazor clients see train events as they happen. See UseSignalRHub. | Trax.Effect.Broadcaster.SignalR.Extensions | Trax.Effect. |
Trax.StateMachine
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.StateMachine | The snapshot state-machine engine: state as language-neutral JSON that a C# backend and a TypeScript client agree on, authored through IMachineBuilder. Needs Trax.Effect; runs in process with no database. See State Machines. | Trax.StateMachine | Usually Trax.StateMachine.Persistence. |
| Trax.StateMachine.Persistence | Machine<TState, TTrigger>, the user-scoped snapshot store, the draft service, the run-once effect primitive, AddStateMachines and AddTraxStateMachineSelfCheck. See AddStateMachines. | Trax.StateMachine.Persistence | Trax.Effect and a data provider; AddStateMachines refuses to register without one. |
| Trax.StateMachine.Client | Drives a machine a host serves from .NET (Blazor, MAUI, Avalonia, WPF, another service): persisted ids from the client manifest, the change stream over a socket, each event predicted with the C# engine. See .NET client. | Trax.StateMachine.Client | Trax.StateMachine and Trax.Client, which it brings with it, and the host's client manifest. |
| Trax.Client | Sends a Trax host's GraphQL documents from .NET: queries and mutations over HTTP POST, subscriptions over one graphql-transport-ws socket, each by persisted id or as text. Every refusal or failure is a value. The typed documents trax client --operations --lang csharp generates are written against it. No dependencies. See .NET client. | Trax.Client | The documents trax client generates, or a TraxDocument of your own. |
| Trax.StateMachine.Testing | Replays the differential corpus produced by the TypeScript engine through the C# engine and returns the cases it fails to reproduce, proving the two engines agree. See Codegen Pipeline. | Trax.StateMachine.Testing | A test project, and the corpus trax machine generate writes. |
| Trax.StateMachine.Gherkin | Derives state machines from Gherkin features and their lexicon: each machine's IR, the host file that says who may use it, and the access report; runs the features on them in memory, lists what they leave out, and draws the event-storming board. trax machine from-gherkin is built on it. See Feature machines. | Trax.StateMachine.Gherkin | Usually nothing: the CLI writes the files and ServeFeatures serves them. |
| Trax.StateMachine.Gherkin.Reqnroll | Reqnroll bindings that run the same features against a host in the test process, each person a user of their own. See Feature bindings. | Trax.StateMachine.Gherkin.Reqnroll | A Reqnroll test project. |
Trax.Mediator
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.Mediator | AddMediator(...) on the AddTrax builder: discovers trains in the assemblies you name, dispatches by input type through ITrainBus, and refuses to start a host whose chains cannot run. See Mediator. | Trax.Mediator.Extensions for AddMediator, Trax.Mediator.Services.TrainBus for ITrainBus | Trax.Effect, and a data provider to record the runs. |
| Trax.Mediator.Testing | The EveryTrainHasInterface guard, through TrainGuards and TrainGuardFixture. See Architecture Guards. | Trax.Mediator.Testing | Trax.Core.Testing, in a test project. |
Trax.Scheduler
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.Scheduler | AddScheduler(...) on the AddTrax builder: cron and interval manifests, the work queue, retries, dead letters and dependent trains. Also ITraxScheduler for scheduling at run time, AddTraxWorker, AddTraxJobRunner with UseTraxRunEndpoint for remote runners, and AddTraxSchedulerLiveness. See Scheduling. | Trax.Scheduler.Extensions for the registration methods, Trax.Scheduler.Services.Scheduling for Every, Cron and Schedule, Trax.Scheduler.Services.TraxScheduler for ITraxScheduler | Trax.Mediator (brought with it) and a data provider. With Postgres or SQLite it runs jobs on local workers; with UseInMemory() it runs scheduled manifests inline and has no work-queue dispatcher, so a GraphQL mode: QUEUE request is refused with TRAX_QUEUE_UNAVAILABLE and nothing is written; use mode: RUN there. Use Postgres when several servers share the work. |
| Trax.Scheduler.Lambda | UseLambdaWorkers() and UseLambdaRun(): dispatch queued jobs and synchronous runs to an AWS Lambda function by direct invocation. See UseLambdaWorkers. | Trax.Scheduler.Lambda.Extensions | Trax.Scheduler in the scheduler host, and Trax.Runner.Lambda in the function. |
| Trax.Scheduler.Sqs | UseSqsWorkers(): dispatches queued jobs as SQS messages, plus the SQS-triggered Lambda consumer that runs them. See UseSqsWorkers. | Trax.Scheduler.Sqs.Extensions, Trax.Scheduler.Sqs.Lambda | Trax.Scheduler. |
| Trax.Runner.Lambda | TraxLambdaFunction, the base class for an AWS Lambda function that runs Trax trains. See TraxLambdaFunction. | Trax.Runner.Lambda | Trax.Scheduler.Lambda in the host that invokes it. |
Trax.Api
| Package | What it is for | Import | Pairs with |
|---|---|---|---|
| Trax.Api | The services behind the GraphQL API: AddTraxApi (which AddTraxGraphQL calls for you) and AddTraxHealthCheck. See API. | Trax.Api.Extensions | Comes with Trax.Api.GraphQL. |
| Trax.Api.GraphQL | AddTraxGraphQL(...) and UseTraxGraphQL(): a HotChocolate schema with queries, mutations and subscriptions generated from your trains. See API and AddTraxGraphQL. | Trax.Api.GraphQL.Extensions | A data provider and an auth package below. It brings Trax.Api, Trax.Mediator and Trax.Scheduler with it. |
| Trax.Api.Dashboard | UseTraxApiDashboard(...): serves the operations dashboard, a React app built into the package, at /trax/dashboard, behind the authorization posture you choose. It reads and changes everything through the Trax GraphQL endpoint. See API Dashboard. | Trax.Api.Dashboard.Extensions | Trax.Api.GraphQL, mapped with UseTraxGraphQL(). |
| Trax.Api.Console.Terminal | trax-console, a dotnet tool: the operations console in a terminal, and the same lists, actions and streams as JSON lines for scripts and agents. It sends only the console's documents. See trax-console. | (a tool) | A host that serves the console, or calls UseTraxOperatorConsoleDocuments(), and an API key or JWT its operations gate accepts. |
| Trax.Api.GraphQL.Audit | AddAudit<TSink>() on the GraphQL builder: an audit entry for each operation, written to your sink. See AddAudit. | Trax.Api.GraphQL.Audit | Trax.Api.GraphQL. |
| Trax.Api.GraphQL.PersistedOperations | UsePersistedOperations(...) on the GraphQL builder and AddPersistedOperationStore: an allow-list of operations that callers run by id. See Persisted Operations. | Trax.Api.GraphQL.PersistedOperations.Extensions | Trax.Api.GraphQL. |
| Trax.Api.GraphQL.Testing | Cross-schema GraphQL guards through CrossSchemaGuards and CrossSchemaGuardFixture. See Architecture Guards. | Trax.Api.GraphQL.Testing | Trax.Core.Testing, in a test project. |
| Trax.Api.GraphQL.Client | A typed client for a Trax GraphQL API: AddTraxGraphQLClient(uri), AddKeyedTraxGraphQLClient, and ValidateGraphQLClientAssembliesAsync to check your request types against the schema. See GraphQL Client. | Trax.Api.GraphQL.Client | Any .NET caller; it needs no other Trax package. |
| Trax.Api.GraphQL.Client.Typed | TypedRequest<TResponse>, which generates the query string from attributed request and result types. See GraphQL Client. | Trax.Api.GraphQL.Client.Typed | Trax.Api.GraphQL.Client. |
| Trax.Api.GraphQL.Client.Trax | UseAssemblySchema(...) and UseStartupValidation(...) on the client builder: validate against the server's schema built in-process. See GraphQL Client. | Trax.Api.GraphQL.Client.Trax | Trax.Api.GraphQL.Client, in a .NET process that can reference the server's schema configuration. |
| Trax.Api.Auth | The principal model the auth packages share: TraxPrincipal, ITraxPrincipalResolver, AddTraxPrincipalAccessor. See TraxPrincipal. | Trax.Api.Auth | Comes with each auth package below. |
| Trax.Api.Auth.ApiKey | AddTraxApiKeyAuth(...): API-key authentication. See AddTraxApiKeyAuth. | Trax.Api.Auth.ApiKey | Trax.Api.GraphQL. |
| Trax.Api.Auth.Jwt | AddTraxJwtAuth(...), the AddTraxCognitoJwtAuth, AddTraxEntraJwtAuth and AddTraxGoogleJwtAuth presets, and AddTraxJwtDispatcher for several issuers on one endpoint. See AddTraxJwtAuth. | Trax.Api.Auth.Jwt | Trax.Api.GraphQL. |
| Trax.Api.Auth.Jwt.Cognito | UseCognito(region, userPoolId, clientId) on the JWT builder, which also checks Cognito's token_use claim. See UseCognito. | Trax.Api.Auth.Jwt.Cognito | Trax.Api.Auth.Jwt. |
| Trax.Api.Auth.Oidc | AddTraxOidcAuth(...): the browser-facing OpenID Connect code flow, with a session cookie. See AddTraxOidcAuth. | Trax.Api.Auth.Oidc | A host that browsers sign in to. Token-based API clients use Trax.Api.Auth.Jwt instead. |
| Trax.Api.Auth.Jwt.Testing | TestJwksServer and TestTokenIssuer: a local JWKS endpoint and signed tokens for integration tests. See JWT Testing. | Trax.Api.Auth.Jwt.Testing | Trax.Api.Auth.Jwt, in a test project. |
| Trax.Api.Auth.Jwt.Cognito.Issuer | CreateCognitoIssuer() on TestJwksServer: tokens shaped like Cognito's, for testing UseCognito. See Cognito Issuer. | Trax.Api.Auth.Jwt.Cognito.Issuer | Trax.Api.Auth.Jwt.Testing and Trax.Api.Auth.Jwt.Cognito, in a test project. |
Tools and templates
| Package | What it is for | Install | Pairs with |
|---|---|---|---|
| Trax.Cli | The trax dotnet tool: trax generate scaffolds a project from a GraphQL SDL or OpenAPI schema, and trax machine scaffolds a state machine and generates its TypeScript twin. See CLI. | dotnet tool install --global Trax.Cli | Nothing; it is a tool, not a library. |
| Trax.Samples.Templates | dotnet new templates: trax-api, trax-scheduler and trax-hub, each a runnable host with a README and an NUnit test project. See Templates. | dotnet new install Trax.Samples.Templates | Nothing; the generated projects reference the packages they need. |
SDK Reference
AddTrax / AddEffects | UsePostgres | AddMediator | AddScheduler | AddTraxGraphQL | UseTraxApiDashboard