Fluens.Cqrs 0.6.6

Fluens.Cqrs

CQRS pattern implementation with command/query dispatchers, handler interfaces, and logging/tracing decorators.

Installation

dotnet add package Fluens.Cqrs

Usage

Registration

fluensBuilder
    .AddCqrs()
    .AddCqrsHandlers<Program>()
    .AddCqrsLoggingDecorator()
    .AddCqrsTracingDecorator();

Commands

// Command without return value
public record CreateOrder(string Number) : ICommand;

public class CreateOrderHandler : ICommandHandler<CreateOrder>
{
    public async Task<Result> HandleAsync(CreateOrder command, CancellationToken cancellationToken)
    {
        // ...
        return Result.Success();
    }
}

// Command with return value
public record GetOrder(int Id) : ICommand<OrderDto>;

public class GetOrderHandler : ICommandHandler<GetOrder, OrderDto>
{
    public async Task<Result<OrderDto>> HandleAsync(GetOrder command, CancellationToken cancellationToken)
    {
        // ...
        return Result.Success(new OrderDto());
    }
}

Paginated Queries

public record SearchOrders(string? Term) : PagedQuery<PagedResult<OrderDto>>;

PagedQuery<TResult> provides default pagination properties with [JsonPropertyName] short codes to minimize JSON payload:

Subclasses automatically inherit the short names in any JsonSerializerContext — no extra configuration required. Pagination constants are available via Constants.Cqrs.Query (DefaultPageIndex, DefaultPageSize, MinPageSize, MaxPageSize).

Queries

public record SearchOrders(string? Term) : IQuery<IReadOnlyList<OrderDto>>;

public class SearchOrdersHandler : IQueryHandler<SearchOrders, IReadOnlyList<OrderDto>>
{
    public async Task<IReadOnlyList<OrderDto>> HandleAsync(SearchOrders query, CancellationToken cancellationToken)
    {
        // Queries return the result directly (no Result wrapper)
        return [];
    }
}

Module-Level Registration

// In IModuleSetup.RegisterServices:
module.AddHandlers(); // scans module assembly, validates assembly boundaries

AddHandlers() scans the module assembly for handler implementations, registers them with scoped lifetime, and enforces module boundary rules: handlers can only handle commands/queries defined in the same module assembly, and cross-module dispatch at runtime throws InvalidOperationException.

Dispatching

// Inject ICommandDispatcher / IQueryDispatcher
Result result = await commandDispatcher.SendAsync(new CreateOrder("ORD-001"), ct);
IReadOnlyList<OrderDto> orders = await queryDispatcher.SendAsync(new SearchOrders("test"), ct);

Built-in decorators: LoggingCommandHandlerDecorator (logs execution), TracingCommandHandlerDecorator (OpenTelemetry activity).

License

This project is licensed under the MIT License.