OpenParable
Skip to content
← Back to skills

Mediator Reference

Development
mediator-reference

Mediator 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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)
CommandICommand<TResponse>IRequest<TResponse>
QueryIQuery<TResponse>IRequest<TResponse>
Command handlerICommandHandler<TCommand, TResponse>IRequestHandler<…>
Query handlerIQueryHandler<TQuery, TResponse>IRequestHandler<…>
Notification / domain eventINotification (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

SymptomCause → fix
IRequest<T> / IRequestHandler<,> not foundMediatR interface → use ICommand/IQuery + ICommandHandler/IQueryHandler
Task<T> vs ValueTask<T> mismatchHandler must return ValueTask<T>
Handler not invoked at runtimeAssembly missing from o.Assemblies (in one or both Program.cs files)