MediatR
In-process mediator pattern implementation for .NET — decouples request senders from handlers via a central mediator, enabling CQRS and clean architecture. MediatR features: IRequest<T> for commands/queries, IRequestHandler<TRequest, TResponse> for handlers, INotification for domain events, INotificationHandler for event subscribers, IPipelineBehavior<TRequest, TResponse> for cross-cutting concerns (validation, logging, caching). Controller sends command: await _mediator.Send(new CreateAgentCommand(request)); handler processes in isolation. Notifications: await _mediator.Publish(new AgentCreatedEvent(agentId)) notifies all subscribers. Makes agent service handlers independently testable without controller infrastructure.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
MediatR pipeline behaviors are ideal for security cross-cutting concerns — implement AuthorizationBehavior<TRequest, TResponse> to check user permissions before every agent command handler executes. Pipeline ensures authorization runs consistently without relying on individual handler implementations. Authorization behavior should run before validation behavior.
⚡ Reliability
Best When
You're building a .NET agent service with CQRS, clean architecture, and multiple cross-cutting concerns (validation, logging, caching) — MediatR's pipeline behaviors apply concerns uniformly across all agent handlers.
Avoid When
Your agent service is simple CRUD without complex domain logic, you need cross-service messaging, or you want direct service injection without mediator indirection.
Use Cases
- • CQRS agent command handling — CreateAgentCommand { Name, Config } handled by CreateAgentCommandHandler implementing IRequestHandler<CreateAgentCommand, AgentDto>; controller sends command and returns result; decoupled from HTTP concerns
- • Agent query separation — GetAgentByIdQuery { AgentId } with GetAgentByIdQueryHandler using Dapper for optimized read path; separate from write-side EF Core commands; clean CQRS for agent service
- • Cross-cutting validation pipeline — ValidationBehavior<TRequest, TResponse> implements IPipelineBehavior running FluentValidation before agent command handlers; validation, logging, and caching added without modifying handlers
- • Domain event publishing for agent workflows — await mediator.Publish(new AgentActivatedEvent { AgentId = id }) notifies EmailNotificationHandler and AuditLogHandler independently; loose coupling of agent event consumers
- • Agent request logging pipeline — LoggingBehavior<TRequest, TResponse> IPipelineBehavior logs all agent commands/queries with timing; registered once applies to all agent handlers without handler modifications
Not For
- • Cross-service messaging — MediatR is in-process only; for agent events between microservices, use MassTransit or Azure Service Bus; MediatR INotification doesn't leave the process boundary
- • Simple CRUD APIs — MediatR adds abstraction layer; for a 5-endpoint agent CRUD API, direct service calls are simpler than commands/queries/handlers; adopt when complexity justifies the pattern
- • Workflow orchestration — MediatR handles request/response and publish/subscribe; for long-running agent workflows with compensation, use Temporal, MassTransit Sagas, or Dapr Workflow
Interface
Authentication
No auth — in-process messaging library. Authentication context passed via request objects or IHttpContextAccessor in pipeline behaviors for agent user context.
Pricing
MediatR is Apache 2.0 licensed, maintained by Jimmy Bogard. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Handler must be registered in DI container — services.AddMediatR(cfg => cfg.RegisterServicesFromAssembly(typeof(CreateAgentCommand).Assembly)); missing assembly registration causes InvalidOperationException 'No handler for type' at runtime; register all assemblies containing agent command handlers
- ⚠ IPipelineBehavior registration order is LIFO — behaviors execute in reverse registration order; services.AddTransient<IPipelineBehavior<,>, LoggingBehavior>(); services.AddTransient<IPipelineBehavior<,>, ValidationBehavior>() runs Validation first then Logging (LIFO); register agent pipeline behaviors in reverse intended execution order
- ⚠ INotification handlers run sequentially by default — Publish() calls handlers one by one; exception in first AgentCreatedEvent handler prevents subsequent handlers from running; use INotificationPublisher override for parallel or fire-and-forget agent notification handling
- ⚠ CancellationToken not propagated automatically — MediatR.Send(request, cancellationToken) passes token to handler; pipeline behaviors must explicitly pass cancellationToken to next(request, cancellationToken); forgetting token in agent behavior causes request cancellation to not propagate through pipeline
- ⚠ Generic constraints for typed pipeline behaviors — IPipelineBehavior<TRequest, TResponse> where TRequest : IAgentCommand applies behavior only to agent command types; without generic constraint, validation behavior runs on queries too; use marker interfaces (ICommand, IQuery) for targeted agent pipeline behavior application
- ⚠ MediatR 12.x changed registration API — MediatR 12 replaced AddMediatR(assemblies) with AddMediatR(cfg => cfg.RegisterServicesFromAssemblies(...)); upgrading from 11.x breaks registration; also removed ServiceFactory; agent projects upgrading must update all DI registration calls and remove ServiceFactory dependencies
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for MediatR.
Scores are editorial opinions as of 2026-03-06.