MinimalCqrs.Core 1.1.0

MinimalCQRS

A lightweight, dependency-free CQRS library for .NET
designed for Web APIs and Vertical Slice architecture.

MinimalCQRS provides pure CQRS without pipelines, behaviors, or framework lock-in.

• Targets: .NET 8 / 9 / 10
• Zero third-party dependencies
• Strongly-typed dispatcher (no dynamic)
• Built Web API–first

Author: livedcode
License: MIT
Current Version: 1.1.0

✨ Why MinimalCQRS?

MinimalCQRS is for developers who want:

• ✔ Explicit Commands and Queries
• ✔ Optional Command<TResult> return values
• ✔ A clear validation pipeline
• ✔ Strong typing throughout
• ✔ Vertical Slice–friendly design
• ✔ First-class ASP.NET Web API support
• ✔ Deterministic behavior (no hidden pipelines)
• ✔ Full unit & integration testability
• ✔ No MediatR, no magic

📦 Core Concepts

✔ Commands

public sealed class CreateLogCommand : ICommand;
public sealed class CreateUserCommand : ICommand<int>;

Commands mutate state.

✔ Queries

public sealed class GetUserQuery : IQuery<UserDto>;

Queries never mutate state and never run validation.

✔ Dispatcher (v1.1.0)

Task SendAsync(ICommand command);
Task<TResult> SendAsync<TResult>(ICommand<TResult> command);
Task<TResult> QueryAsync<TResult>(IQuery<TResult> query);

Guarantees:

• Validation always runs before handlers
• Handlers are NOT invoked if validation fails
• All validators are executed and errors are aggregated
• Queries bypass validation entirely
• Each dispatch executes in its own DI scope
• No dynamic usage (strong typing only)

✔ Validation Pipeline (Commands only)

public interface ICommandValidator<TCommand>
{
    IEnumerable<string> Validate(TCommand command);
}

• Multiple validators per command are supported
• All validation errors are returned in a single response
• Validators never throw – they return errors
• Dispatcher throws a single CommandValidationException

🚀 Getting Started (Web API)

Register MinimalCQRS

Always register CQRS using a feature assembly marker:

public sealed class ApiFeatureAssemblyMarker { }

builder.Services.AddMinimalCqrs(
    typeof(ApiFeatureAssemblyMarker).Assembly
);

🧯 Error Handling

MinimalCQRS does not handle HTTP concerns.

Recommended pattern:

catch (CommandValidationException ex)
{
    context.Response.StatusCode = 400;
    await context.Response.WriteAsJsonAsync(new
    {
        errors = ex.Errors
    });
}

🧪 Testing Strategy (v1.1.0)

MinimalCQRS is fully testable without mocks.

• Dispatcher execution flow
• Validation aggregation
• Handler invocation guarantees
• Missing handler failures
• Query execution without validation
• End-to-end API integration tests

🧠 Design Principles

• MinimalCQRS is infrastructure-only
• No dependency on ASP.NET
• No dependency on application/domain code
• Validation belongs to the application layer
• Commands mutate state, queries do not
• Fail fast, fail clearly, fail consistently

📜 License

MIT License — see LICENSE.

⭐ Summary

MinimalCQRS is:

• ✔ Explicit
• ✔ Predictable
• ✔ Strongly typed
• ✔ Web-API ready
• ✔ Fully testable
• ✔ Free of hidden abstractions

A clean alternative to MediatR
for teams that want full control over CQRS.