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
| Requirement | What happens if you get it wrong |
|---|---|
AddTrax() before AddTraxGraphQL() | Throws immediately, naming the missing call. |
AddEffects(...) before AddMediator(...), inside AddTrax | Does not compile: error CS0619, Call AddEffects(...) before AddMediator(...). See https://traxsharp.net/docs/cross-cutting/troubleshooting#call-addeffects-before-addmediator |
AddStateMachines(...) before AddMediator(...), inside AddTrax | Does not compile: error CS0619, Call AddStateMachines(...) before AddMediator(...). |
An authorization posture in the UseTraxApiDashboard(...) options | UseTraxApiDashboard() 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 views | The 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
| Call | What happens |
|---|---|
A second AddMediator(...) in the same chain | Does not compile: error CS0619, AddMediator(...) is already called. Call it once and configure everything in that call. |
A second AddStateMachines(...) in the same chain | Throws 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.
| Missing | Message |
|---|---|
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] train | Trax 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-production | AddTraxApiKeyAuth() 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-production | AddTraxJwtAuth() 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 LifecycleSubscriptions | Type 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:
@authorizefrom[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, soAddAuthentication()andAddAuthorization()may come after it. - Repeated
AddTraxJwtAuth(...)calls accumulate into one registry regardless of order. - Auth schemes (
AddTraxJwtAuth,AddTraxApiKeyAuth,AddTraxJwtDispatcher) may come before or afterAddTraxGraphQL(). The subscription interceptor reads them from the finished container on the first connection. app.UseTraxGraphQL()before or afterapp.UseAuthentication()andapp.UseAuthorization(). It maps an endpoint, and aWebApplicationruns endpoints after all of its middleware, so the caller is authenticated either way. Calling the twoUsemethods 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.