Dotnet Mediator

Command Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Commands represent write intents — creating, updating, or deleting state. The command side of ArturRios.Mediator enforces a strict one-command-one-handler rule and isolates each execution in its own DI scope.

Core Types

Type	Purpose
`BaseCommand`	Abstract base class for all command data carriers
`CommandOutput`	Abstract base class for the result payload
`ICommandHandler<TCommand, TOutput>`	Synchronous handler contract
`ICommandHandlerAsync<TCommand, TOutput>`	Asynchronous handler contract
`CommandMediator`	Resolves and invokes the registered handler

BaseCommand

public abstract class BaseCommand;

Derive from BaseCommand to create a command. Expose the data the handler needs as plain properties. Commands are simple data carriers — no business logic belongs here.

CommandOutput

public abstract class CommandOutput;

Derive from CommandOutput to describe the result of a command (for example, the identifier of the newly created entity). The mediator wraps it in DataOutput<TOutput?> before returning it to the caller.

ICommandHandler

public interface ICommandHandler<in TCommand, TOutput>
 where TCommand : BaseCommand
 where TOutput : CommandOutput
{
 DataOutput<TOutput?> Handle(TCommand command);
}

Implement for synchronous execution. Register one implementation per <TCommand, TOutput> pair in the DI container.

ICommandHandlerAsync

public interface ICommandHandlerAsync<in TCommand, TOutput>
 where TCommand : BaseCommand
 where TOutput : CommandOutput
{
 Task<DataOutput<TOutput?>> HandleAsync(TCommand command);
}

Implement for asynchronous execution. Register one implementation per <TCommand, TOutput> pair in the DI container.

CommandMediator

public class CommandMediator(IServiceScopeFactory scopeFactory)
{
 public DataOutput<TOutput?> ExecuteCommand <TCommand, TOutput>(TCommand command) ...
 public Task<DataOutput<TOutput?>> ExecuteCommandAsync<TCommand, TOutput>(TCommand command) ...
}

For each call the mediator creates a new DI scope, resolves the matching handler, invokes it, and disposes the scope. This ensures scoped dependencies (e.g. DbContext) are isolated per command execution.

Class Diagram

classDiagram
direction TB
class BaseCommand {
<<abstract>>
}
class CommandOutput {
<<abstract>>
}
class ICommandHandler~TCommand TOutput~ {
<<interface>>
+Handle(command TCommand) DataOutput~TOutput?~
}
class ICommandHandlerAsync~TCommand TOutput~ {
<<interface>>
+HandleAsync(command TCommand) Task~DataOutput~TOutput?~~
}
class CommandMediator {
-IServiceScopeFactory _scopeFactory
+ExecuteCommand(command TCommand) DataOutput~TOutput?~
+ExecuteCommandAsync(command TCommand) Task~DataOutput~TOutput?~~
}
class CommandQueryMediator {
-CommandMediator _commandMediator
-QueryMediator _queryMediator
+ExecuteCommand(command TCommand) DataOutput~TOutput?~
+ExecuteCommandAsync(command TCommand) Task~DataOutput~TOutput?~~
}
ICommandHandler~TCommand TOutput~ ..> BaseCommand : constrains TCommand
ICommandHandler~TCommand TOutput~ ..> CommandOutput : constrains TOutput
ICommandHandlerAsync~TCommand TOutput~ ..> BaseCommand : constrains TCommand
ICommandHandlerAsync~TCommand TOutput~ ..> CommandOutput : constrains TOutput
CommandMediator --> ICommandHandler~TCommand TOutput~ : resolves & invokes
CommandMediator --> ICommandHandlerAsync~TCommand TOutput~ : resolves & invokes
CommandQueryMediator --> CommandMediator : delegates to

Sequence Diagrams

Synchronous Command Execution

sequenceDiagram
participant Caller
participant CommandMediator
participant DI as DI Container (scope)
participant Handler as ICommandHandler
Caller->>CommandMediator: ExecuteCommand<TCommand, TOutput>(command)
CommandMediator->>DI: CreateScope()
CommandMediator->>DI: GetRequiredService<ICommandHandler<TCommand, TOutput>>()
DI-->>CommandMediator: handler
CommandMediator->>Handler: Handle(command)
Handler-->>CommandMediator: DataOutput<TOutput?>
CommandMediator->>DI: Dispose scope
CommandMediator-->>Caller: DataOutput<TOutput?>

Asynchronous Command Execution

sequenceDiagram
participant Caller
participant CommandMediator
participant DI as DI Container (scope)
participant Handler as ICommandHandlerAsync
Caller->>CommandMediator: ExecuteCommandAsync<TCommand, TOutput>(command)
CommandMediator->>DI: CreateScope()
CommandMediator->>DI: GetRequiredService<ICommandHandlerAsync<TCommand, TOutput>>()
DI-->>CommandMediator: handler
CommandMediator->>Handler: HandleAsync(command)
Handler-->>CommandMediator: Task<DataOutput<TOutput?>>
CommandMediator->>DI: Dispose scope
CommandMediator-->>Caller: DataOutput<TOutput?>

Usage Example

Define the command and output

public class CreateProductCommand : BaseCommand
{
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
}

public class CreateProductOutput : CommandOutput
{
 public Guid Id { get; set; }
}

Implement the handler

public class CreateProductHandler : ICommandHandlerAsync<CreateProductCommand, CreateProductOutput>
{
 private readonly IProductRepository _repository;

 public CreateProductHandler(IProductRepository repository) => _repository = repository;

 public async Task<DataOutput<CreateProductOutput?>> HandleAsync(CreateProductCommand command)
 {
 var id = await _repository.InsertAsync(command.Name, command.Price);
 return DataOutput<CreateProductOutput?>.Success(new CreateProductOutput { Id = id });
 }
}

Register in DI

builder.Services.AddSingleton<CommandMediator>();
builder.Services.AddScoped<ICommandHandlerAsync<CreateProductCommand, CreateProductOutput>, CreateProductHandler>();

Dispatch

var result = await mediator.ExecuteCommandAsync<CreateProductCommand, CreateProductOutput>(
 new CreateProductCommand { Name = "Widget", Price = 9.99m });

if (result.IsSuccess)
 Console.WriteLine($"Created: {result.Data!.Id}");

Query Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Queries represent read-only requests for data. The query side of ArturRios.Mediator supports two result shapes: a single DataOutput<T> for item lookups and a PaginatedOutput<T> for collection queries that need page metadata.

Core Types

Type	Purpose
`BaseQuery`	Abstract base class for all query data carriers
`QueryOutput`	Abstract base class for the result payload
`IQueryHandler<TQuery, TOutput>`	Synchronous single-result handler contract
`IQueryHandlerAsync<TQuery, TOutput>`	Asynchronous single-result handler contract
`IPaginatedQueryHandler<TQuery, TOutput>`	Synchronous paginated handler contract
`IPaginatedQueryHandlerAsync<TQuery, TOutput>`	Asynchronous paginated handler contract
`QueryMediator`	Resolves and invokes the registered handler

BaseQuery

public abstract class BaseQuery
{
 public int PageNumber { get; set; } = 1; // 1-based
 public int PageSize { get; set; } = 100;
}

Derive from BaseQuery to create a query. Expose filter criteria as plain properties. The PageNumber and PageSize properties are consumed by paginated handlers and ignored by single-result ones.

QueryOutput

public abstract class QueryOutput;

Derive from QueryOutput to describe the shape of the data returned by a query.

IQueryHandler / IQueryHandlerAsync

public interface IQueryHandler<in TQuery, TOutput>
 where TQuery : BaseQuery
 where TOutput : QueryOutput
{
 DataOutput<TOutput?> Handle(TQuery query);
}

public interface IQueryHandlerAsync<in TQuery, TOutput>
 where TQuery : BaseQuery
 where TOutput : QueryOutput
{
 Task<DataOutput<TOutput?>> HandleAsync(TQuery query);
}

Use for queries that return a single result. Register one implementation per <TQuery, TOutput> pair.

IPaginatedQueryHandler / IPaginatedQueryHandlerAsync

public interface IPaginatedQueryHandler<in TQuery, TOutput>
 where TQuery : BaseQuery
 where TOutput : QueryOutput
{
 PaginatedOutput<TOutput> Handle(TQuery query);
}

public interface IPaginatedQueryHandlerAsync<in TQuery, TOutput>
 where TQuery : BaseQuery
 where TOutput : QueryOutput
{
 Task<PaginatedOutput<TOutput>> HandleAsync(TQuery query);
}

Use for queries that return a page of results together with pagination metadata (TotalCount, TotalPages, etc. provided by PaginatedOutput<T>).

QueryMediator

public class QueryMediator(IServiceScopeFactory scopeFactory)
{
 public DataOutput<TOutput?> ExecuteQuery <TQuery, TOutput>(TQuery query) ...
 public Task<DataOutput<TOutput?>> ExecuteQueryAsync <TQuery, TOutput>(TQuery query) ...
 public PaginatedOutput<TOutput> ExecutePaginatedQuery <TQuery, TOutput>(TQuery query) ...
 public Task<PaginatedOutput<TOutput>> ExecutePaginatedQueryAsync<TQuery, TOutput>(TQuery query) ...
}

For each call the mediator creates a new DI scope, resolves the matching handler, invokes it, and disposes the scope.

Class Diagram

classDiagram
direction TB
class BaseQuery {
<<abstract>>
+PageNumber int
+PageSize int
}
class QueryOutput {
<<abstract>>
}
class IQueryHandler~TQuery TOutput~ {
<<interface>>
+Handle(query TQuery) DataOutput~TOutput?~
}
class IQueryHandlerAsync~TQuery TOutput~ {
<<interface>>
+HandleAsync(query TQuery) Task~DataOutput~TOutput?~~
}
class IPaginatedQueryHandler~TQuery TOutput~ {
<<interface>>
+Handle(query TQuery) PaginatedOutput~TOutput~
}
class IPaginatedQueryHandlerAsync~TQuery TOutput~ {
<<interface>>
+HandleAsync(query TQuery) Task~PaginatedOutput~TOutput~~
}
class QueryMediator {
-IServiceScopeFactory _scopeFactory
+ExecuteQuery(query TQuery) DataOutput~TOutput?~
+ExecuteQueryAsync(query TQuery) Task~DataOutput~TOutput?~~
+ExecutePaginatedQuery(query TQuery) PaginatedOutput~TOutput~
+ExecutePaginatedQueryAsync(query TQuery) Task~PaginatedOutput~TOutput~~
}
class CommandQueryMediator {
-CommandMediator _commandMediator
-QueryMediator _queryMediator
+ExecuteQuery(query TQuery) DataOutput~TOutput?~
+ExecuteQueryAsync(query TQuery) Task~DataOutput~TOutput?~~
+ExecutePaginatedQuery(query TQuery) PaginatedOutput~TOutput~
+ExecutePaginatedQueryAsync(query TQuery) Task~PaginatedOutput~TOutput~~
}
IQueryHandler~TQuery TOutput~ ..> BaseQuery : constrains TQuery
IQueryHandler~TQuery TOutput~ ..> QueryOutput : constrains TOutput
IQueryHandlerAsync~TQuery TOutput~ ..> BaseQuery : constrains TQuery
IQueryHandlerAsync~TQuery TOutput~ ..> QueryOutput : constrains TOutput
IPaginatedQueryHandler~TQuery TOutput~ ..> BaseQuery : constrains TQuery
IPaginatedQueryHandler~TQuery TOutput~ ..> QueryOutput : constrains TOutput
IPaginatedQueryHandlerAsync~TQuery TOutput~ ..> BaseQuery : constrains TQuery
IPaginatedQueryHandlerAsync~TQuery TOutput~ ..> QueryOutput : constrains TOutput
QueryMediator --> IQueryHandler~TQuery TOutput~ : resolves & invokes
QueryMediator --> IQueryHandlerAsync~TQuery TOutput~ : resolves & invokes
QueryMediator --> IPaginatedQueryHandler~TQuery TOutput~ : resolves & invokes
QueryMediator --> IPaginatedQueryHandlerAsync~TQuery TOutput~ : resolves & invokes
CommandQueryMediator --> QueryMediator : delegates to

Sequence Diagrams

Single-Result Query (Asynchronous)

sequenceDiagram
participant Caller
participant QueryMediator
participant DI as DI Container (scope)
participant Handler as IQueryHandlerAsync
Caller->>QueryMediator: ExecuteQueryAsync<TQuery, TOutput>(query)
QueryMediator->>DI: CreateScope()
QueryMediator->>DI: GetRequiredService<IQueryHandlerAsync<TQuery, TOutput>>()
DI-->>QueryMediator: handler
QueryMediator->>Handler: HandleAsync(query)
Handler-->>QueryMediator: Task<DataOutput<TOutput?>>
QueryMediator->>DI: Dispose scope
QueryMediator-->>Caller: DataOutput<TOutput?>

Paginated Query (Asynchronous)

sequenceDiagram
participant Caller
participant QueryMediator
participant DI as DI Container (scope)
participant Handler as IPaginatedQueryHandlerAsync
Caller->>QueryMediator: ExecutePaginatedQueryAsync<TQuery, TOutput>(query)
note over Caller,QueryMediator: query.PageNumber and query.PageSize are set
QueryMediator->>DI: CreateScope()
QueryMediator->>DI: GetRequiredService<IPaginatedQueryHandlerAsync<TQuery, TOutput>>()
DI-->>QueryMediator: handler
QueryMediator->>Handler: HandleAsync(query)
Handler-->>QueryMediator: Task<PaginatedOutput<TOutput>>
QueryMediator->>DI: Dispose scope
QueryMediator-->>Caller: PaginatedOutput<TOutput>

Single-Result Query (Synchronous)

sequenceDiagram
participant Caller
participant QueryMediator
participant DI as DI Container (scope)
participant Handler as IQueryHandler
Caller->>QueryMediator: ExecuteQuery<TQuery, TOutput>(query)
QueryMediator->>DI: CreateScope()
QueryMediator->>DI: GetRequiredService<IQueryHandler<TQuery, TOutput>>()
DI-->>QueryMediator: handler
QueryMediator->>Handler: Handle(query)
Handler-->>QueryMediator: DataOutput<TOutput?>
QueryMediator->>DI: Dispose scope
QueryMediator-->>Caller: DataOutput<TOutput?>

Usage Examples

Single-Result Query

// Query + output
public class GetProductQuery : BaseQuery
{
 public Guid Id { get; set; }
}

public class GetProductOutput : QueryOutput
{
 public Guid Id { get; set; }
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
}

// Handler
public class GetProductHandler : IQueryHandlerAsync<GetProductQuery, GetProductOutput>
{
 private readonly IProductRepository _repository;

 public GetProductHandler(IProductRepository repository) => _repository = repository;

 public async Task<DataOutput<GetProductOutput?>> HandleAsync(GetProductQuery query)
 {
 var product = await _repository.FindByIdAsync(query.Id);
 return product is null
 ? DataOutput<GetProductOutput?>.Failure("Product not found.")
 : DataOutput<GetProductOutput?>.Success(new GetProductOutput
 {
 Id = product.Id,
 Name = product.Name,
 Price = product.Price
 });
 }
}

// Register
builder.Services.AddSingleton<QueryMediator>();
builder.Services.AddScoped<IQueryHandlerAsync<GetProductQuery, GetProductOutput>, GetProductHandler>();

// Dispatch
var result = await mediator.ExecuteQueryAsync<GetProductQuery, GetProductOutput>(
 new GetProductQuery { Id = productId });

Paginated Query

// Query + output
public class ListProductsQuery : BaseQuery // PageNumber and PageSize inherited
{
 public string? NameFilter { get; set; }
}

public class ProductListItem : QueryOutput
{
 public Guid Id { get; set; }
 public string Name { get; set; } = string.Empty;
 public decimal Price { get; set; }
}

// Handler
public class ListProductsHandler : IPaginatedQueryHandlerAsync<ListProductsQuery, ProductListItem>
{
 private readonly IProductRepository _repository;

 public ListProductsHandler(IProductRepository repository) => _repository = repository;

 public async Task<PaginatedOutput<ProductListItem>> HandleAsync(ListProductsQuery query)
 {
 var (items, total) = await _repository.ListAsync(
 query.NameFilter, query.PageNumber, query.PageSize);

 return PaginatedOutput<ProductListItem>.Success(
 items.Select(p => new ProductListItem { Id = p.Id, Name = p.Name, Price = p.Price }),
 total, query.PageNumber, query.PageSize);
 }
}

// Register
builder.Services.AddScoped<
 IPaginatedQueryHandlerAsync<ListProductsQuery, ProductListItem>,
 ListProductsHandler>();

// Dispatch
var page = await mediator.ExecutePaginatedQueryAsync<ListProductsQuery, ProductListItem>(
 new ListProductsQuery { NameFilter = "Widget", PageNumber = 2, PageSize = 20 });