Reference

Registration Order

Trax's services.AddX() extensions are meant to be callable in any order, with one exception that is enforced loudly. Where order does matter, the host fails at startup with a message naming the call to move. Nothing about registration is allowed to fail silently.

What order does matter

RequirementWhat happens if you get it wrong
AddTrax() before AddTraxGraphQL()Throws immediately, naming the missing call.
AddEffects(...) before AddMediator(...), inside AddTraxDoes not compile: error CS0619, Call AddEffects(...) before AddMediator(...). See https://traxsharp.net/docs/cross-cutting/troubleshooting#call-addeffects-before-addmediator
AddStateMachines(...) before AddMediator(...), inside AddTraxDoes not compile: error CS0619, Call AddStateMachines(...) before AddMediator(...).
An authorization posture in the UseTraxApiDashboard(...) optionsUseTraxApiDashboard() throws, naming RequirePolicy, RequireRoles and AllowAnonymousShell.
Trains registered before AddTraxGraphQL()The host refuses to start, naming each [TraxQuery], [TraxMutation] or [TraxBroadcast] train registered afterwards. AddTraxGraphQL() checks each train's authorization posture and name and builds the schema roots from the trains registered before it.
Machines served from features (ServeFeatures(...) in AddStateMachines) before AddTraxGraphQL(), when they declare viewsThe host refuses to start: These views of machines served from features are registered, but AddTraxGraphQL() saw none of them, so the schema has no views root to serve them under: followed by the views, then Register the machines directory before AddTraxGraphQL().
Your own IDecisionObserver before AddTrax(), on a host that calls AddDecisionRecording()The host refuses to start, naming the observer, and every run that would record its decisions refuses too. One registered after AddTrax() would replace the composite that tells decision recording. See Other decision observers.
builder.Services.AddTrax(trax => trax.AddEffects(...).AddMediator(...));
builder.Services.AddTraxJwtAuth(...);
builder.Services.AddTraxGraphQL(graphql => graphql.AddDbContext<AppDbContext>());

Calls made more than once

CallWhat happens
A second AddMediator(...) in the same chainDoes not compile: error CS0619, AddMediator(...) is already called. Call it once and configure everything in that call.
A second AddStateMachines(...) in the same chainThrows at registration: AddStateMachines() was called more than once. Call it once, passing every assembly that holds your machines and configuring every option in that call: AddStateMachines(o => ..., typeof(A).Assembly, typeof(B).Assembly).

Missing registrations and what they raise

These are not about order: the call is missing. Each one fails at startup, with the message shown.

MissingMessage
A data provider (UseInMemory(), UseSqlite(), UsePostgres()) in AddEffects on a host that calls AddScheduler()AddScheduler() requires a data provider (UsePostgres(), UseSqlite(), or UseInMemory()).
The train's assembly in AddMediator(...), for a train named in Schedule<T>No train implements IServiceTrain<TInput, TOut>. Add the train's assembly to AddMediator(m => m.ScanAssemblies(typeof(MyTrain).Assembly)).
[TraxAuthorize] or [TraxAllowAnonymous] on a [TraxQuery] or [TraxMutation] trainTrax GraphQL exposure authorization check failed: followed by one line per train
AddTraxGraphQL() on a host that calls UseTraxApiDashboard()UseTraxApiDashboard() requires AddTraxGraphQL(): the dashboard reads and changes everything through the Trax GraphQL endpoint.
ExposeOperationQueries() on a host that calls UseTraxApiDashboard()UseTraxApiDashboard() requires the GraphQL operations namespace, which every page of the dashboard reads, and AddTraxGraphQL() does not expose it.
AddTraxGraphQL() on a host that calls UseTraxGraphQL()UseTraxGraphQL() requires AddTraxGraphQL() to be called first.
AddAuthentication() on a host that calls UseAuthentication() with no auth package registered (a template outside Development, where the demo key is not registered)Unable to resolve service for type 'Microsoft.AspNetCore.Authentication.IAuthenticationSchemeProvider'
A registered demo key outside Development: AddTraxApiKeyAuth with a key containing do-not-use-in-productionAddTraxApiKeyAuth() registered a key containing 'do-not-use-in-production', which marks a published demo key, and the environment is 'Production'.
A demo signing key outside Development: AddTraxJwtAuth with a symmetric key containing do-not-use-in-productionAddTraxJwtAuth() registered a signing key containing 'do-not-use-in-production', which marks a published demo key, and the environment is 'Production'.
An authentication scheme on a host whose dashboard uses RequirePolicy(...) or RequireRoles(...)The dashboard requires authorization, but the host has no authentication scheme to challenge a caller with
The type an [ExtendObjectType("...")] class extends, such as Subscription where Trax's root is LifecycleSubscriptionsType extension '...' extends 'Subscription', which is not a type in this schema

Without an authentication scheme, a dashboard policy would have nobody to challenge, and every request it refused would be a 500 rather than a 401 or 403. That is why the dashboard refuses to start instead. Register the scheme your users sign in with before choosing a policy.

A complete host that registers all of these in a working order is the trax-hub template: its Program.cs comments each call with the message its removal raises.

What order does not matter

Everything else, and deliberately so:

  • @authorize from [TraxAuthorize] is attached to the schema, so query and mutation gating behaves identically whichever way round the host is composed.
  • Services the GraphQL components depend on are resolved on first use, not when AddTraxGraphQL() runs, so AddAuthentication() and AddAuthorization() may come after it.
  • Repeated AddTraxJwtAuth(...) calls accumulate into one registry regardless of order.
  • Auth schemes (AddTraxJwtAuth, AddTraxApiKeyAuth, AddTraxJwtDispatcher) may come before or after AddTraxGraphQL(). The subscription interceptor reads them from the finished container on the first connection.
  • app.UseTraxGraphQL() before or after app.UseAuthentication() and app.UseAuthorization(). It maps an endpoint, and a WebApplication runs endpoints after all of its middleware, so the caller is authenticated either way. Calling the two Use methods first is still the conventional order, and the one the templates use.

The rule that keeps it this way, for anyone writing a registration extension, is in API conventions.

SDK Reference

AddTraxGraphQL | Subscriptions | Architecture guards