Mediator Reference
Developmentmediator-referenceMediator Reference is an Agent Skill for development published in the fullstackhero/dotnet-starter-kit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
CQRS interface reference for FSH. This project uses the Mediator source generator, NOT MediatR. Reference when implementing commands, queries, and handlers.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/fullstackhero/dotnet-starter-kit/blob/HEAD/.agents/skills/mediator-reference/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mediator-reference, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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) |