Skip to main content
Version: 3.x

Commands and Queries

In Synapse every operation that expects a response is modelled as a request. Commands and queries are both requests — the difference is a matter of intent and convention, not a technical distinction enforced by the framework. To make that intent visible in your types you can optionally use the marker interfaces ICommand, ICommand<TResponse> and IQuery<TResponse> (in UnambitiousFx.Synapse.Abstractions). They are pure markers: the library treats them like any other request.

ConceptIntentMarker interface
CommandMutates state, may return an ID or acknowledgementICommand or ICommand<TResponse> (still an IRequest underneath)
QueryReads state, always returns dataIQuery<TResponse>

For strict command/query separation at runtime, see Pipeline Behaviors — CQRS enforcement. That behavior does not use the markers: it still blocks any request dispatched inside a handler.

Marker interfaces and handler aliases​

public record CreateTaskCommand(string Title) : ICommand<Guid>;
public record GetTaskQuery(Guid TaskId) : IQuery<TaskDto>;

[RequestHandler<CreateTaskCommand, Guid>]
public class CreateTaskCommandHandler : ICommandHandler<CreateTaskCommand, Guid> { ... }

ICommandHandler<TCommand>, ICommandHandler<TCommand, TResponse> and IQueryHandler<TQuery, TResponse> are naming aliases of IRequestHandler: they add nothing at runtime. Registration still uses [RequestHandler<...>], no marker is required, and existing IRequest code keeps working unchanged. The markers matter mainly for scoping behaviors, see Applying a behavior to commands or queries only.

The markers are optional. Because they live in UnambitiousFx.Synapse.Abstractions, a file that imports that namespace and also your own ICommand or IQuery<T> from another namespace gets an ambiguous-reference error (CS0104) after upgrading. Either keep your own markers and disambiguate with an alias such as using ICommand = MyApp.Messaging.ICommand;, or migrate to the built-in ones.

Requests with a response — IRequest<TResponse>​

Use IRequest<TResponse> when the operation produces a typed result:

public record GetTaskQuery(Guid TaskId) : IRequest<TaskDto>;
public record CreateTaskCommand(string Title) : IRequest<Guid>;

The handler interface is IRequestHandler<TRequest, TResponse>:

public class GetTaskQueryHandler : IRequestHandler<GetTaskQuery, TaskDto>
{
private readonly ITaskRepository _repository;

public GetTaskQueryHandler(ITaskRepository repository) => _repository = repository;

public async ValueTask<Result<TaskDto>> HandleAsync(
GetTaskQuery query,
CancellationToken ct = default)
{
var task = await _repository.FindAsync(query.TaskId, ct);

return task is null
? Result.Failure<TaskDto>($"Task {query.TaskId} not found.")
: Result.Success(TaskDto.From(task));
}
}

Fire-and-forget commands — IRequest​

Use IRequest (without type parameter) when the command produces no value — only success or failure:

public record DeleteTaskCommand(Guid TaskId) : IRequest;

public class DeleteTaskCommandHandler : IRequestHandler<DeleteTaskCommand>
{
private readonly ITaskRepository _repository;

public DeleteTaskCommandHandler(ITaskRepository repository) => _repository = repository;

public async ValueTask<Result> HandleAsync(
DeleteTaskCommand command,
CancellationToken ct = default)
{
var deleted = await _repository.DeleteAsync(command.TaskId, ct);

return deleted
? Result.Success()
: Result.Failure($"Task {command.TaskId} not found.");
}
}

Optional base class​

Both handler interfaces have an optional base class that adapts a synchronous Handle method to the async interface. Use it only when your handler has no async work:

public class EchoQueryHandler : RequestHandler<EchoQuery, string>
{
protected override Result<string> Handle(EchoQuery query)
=> Result.Success(query.Message);
}

Invoking requests​

Inject IInvoker and call InvokeAsync. The response type is inferred from the IRequest<TResponse> type argument — no need to specify it explicitly:

// Typed response — TResponse inferred as TaskDto
Result<TaskDto> result = await invoker.InvokeAsync(new GetTaskQuery(id), ct);

// Typed response — TResponse inferred as Guid
Result<Guid> created = await invoker.InvokeAsync(new CreateTaskCommand("Buy milk"), ct);

// No response
Result deleted = await invoker.InvokeAsync(new DeleteTaskCommand(id), ct);

Registration​

Register each handler in AddSynapse:

services.AddSynapse(cfg =>
{
// With response
cfg.RegisterRequestHandler<GetTaskQueryHandler, GetTaskQuery, TaskDto>();
cfg.RegisterRequestHandler<CreateTaskHandler, CreateTaskCommand, Guid>();

// Without response
cfg.RegisterRequestHandler<DeleteTaskHandler, DeleteTaskCommand>();

// Conditional — only registered when the predicate returns true
cfg.RegisterRequestHandlerWhen<FeatureFlagHandler, MyCommand, bool>(() => featureEnabled);
});

Each handler type is stored in an O(1) dispatch dictionary keyed on the request type, looked up once per InvokeAsync call.

Modular registration with IRegisterGroup​

For larger projects, group related registrations into a class that implements IRegisterGroup:

public class TasksRegisterGroup : IRegisterGroup
{
public void Register(IDependencyInjectionBuilder builder)
{
builder.RegisterRequestHandler<GetTaskQueryHandler, GetTaskQuery, TaskDto>();
builder.RegisterRequestHandler<CreateTaskHandler, CreateTaskCommand, Guid>();
builder.RegisterRequestHandler<DeleteTaskHandler, DeleteTaskCommand>();
}
}

// In Program.cs
services.AddSynapse(cfg => cfg.AddRegisterGroup(new TasksRegisterGroup()));

The Source Generator can generate this class automatically from handler attributes — either as the default RegisterGroup in your root namespace, or into a partial class of your own choosing via the [RegisterGroup] attribute.

See also​

  • Validation — run validators before the handler is invoked.
  • Pipeline Behaviors — add cross-cutting concerns to all or specific request types.
  • Error Handling — work with Result and Result<T> in call sites.