Mediator Reference

⚠️ FSH uses the Mediator source-generator package (using Mediator;), NOT MediatR. Different interfaces — MediatR types won't compile. The CQRS interfaces below are the library's own (no FSH wrapper).

Interfaces

Purpose	✅ Mediator (use)	❌ MediatR (don't)
Command	`ICommand<TResponse>`	`IRequest<TResponse>`
Query	`IQuery<TResponse>`	`IRequest<TResponse>`
Command handler	`ICommandHandler<TCommand, TResponse>`	`IRequestHandler<…>`
Query handler	`IQueryHandler<TQuery, TResponse>`	`IRequestHandler<…>`
Notification / domain event	`INotification` (`IDomainEvent : INotification`)	`INotification`

Pattern

// Command/Query → the Contracts project (Modules.{X}.Contracts/v1/{Area}/)
public sealed record Create{Entity}Command(string Name) : ICommand<Guid>;

// Handler → the runtime project (Modules.{X}/Features/v1/{Area}/{Feature}/), public sealed
public sealed class Create{Entity}CommandHandler({X}DbContext db)
    : ICommandHandler<Create{Entity}Command, Guid>
{
    public async ValueTask<Guid> Handle(Create{Entity}Command command, CancellationToken cancellationToken)
    {
        // …
    }
}

Rules: handlers return ValueTask<T> (not Task<T>); parameter named command/query (not request); public sealed; .ConfigureAwait(false) on awaits. Send via mediator.Send(command, ct) (the IMediator interface name matches MediatR's — that part is fine).

Registration — the four places

The source generator only scans assemblies listed in o.Assemblies, and that list exists in two host files. A new module needs two markers (a Contracts type and the module type) added to the Mediator list plus an entry in the moduleAssemblies array — in both FSH.Starter.Api/Program.cs and FSH.Starter.DbMigrator/Program.cs:

builder.Services.AddMediator(o =>
{
    o.ServiceLifetime = ServiceLifetime.Scoped;
    o.Assemblies = [
        /* … */
        typeof(FSH.Modules.{X}.Contracts.{X}ContractsMarker),   // Contracts assembly
        typeof(FSH.Modules.{X}.{X}Module)];                     // runtime assembly
});

See add-module for the full procedure.

Common errors

Symptom	Cause → fix
`IRequest<T>` / `IRequestHandler<,>` not found	MediatR interface → use `ICommand`/`IQuery` + `ICommandHandler`/`IQueryHandler`
`Task<T>` vs `ValueTask<T>` mismatch	Handler must return `ValueTask<T>`
Handler not invoked at runtime	Assembly missing from `o.Assemblies` (in one or both Program.cs files)