NPv.CQS.Infrastructure 3.0.6

NPv.CQS.Infrastructure

Infrastructure for declarative execution of commands and queries in CQS-based applications.
Includes default implementations, Unit of Work executor, and Microsoft.Extensions.DependencyInjection integration.

📌 Breaking changes

v3.0.0

• Target framework updated to net10.0 (dropped net9.0 support).

This is a personal library that focuses on the latest .NET runtime to keep maintenance simple and enjoyable.

✨ Overview

NPv.CQS.Infrastructure provides essential building blocks for executing commands and queries defined using NPv.CQS.Abstractions.

It includes:

• ICommandBuilder and IQueryFor<TResult> for resolving and executing handlers,
• UnitOfWorkCommandExecutor for command execution with commit on success,
• Service collection extensions for automatic handler registration with fail-fast duplicate detection.

This package is intended for the application or composition root layers, where behaviors are wired and executed.

🚨 Breaking Changes in v2.0.0

Starting with v2.1.0, all commands now return a Result (from NPv.ResultPattern) instead of being void tasks.

• Before (v1.x):

  public class CreateOrderCommand : ICommand<CreateOrderCommandContext>
  {
      public Task ExecuteAsync(CreateOrderCommandContext context)
      {
          // Domain logic
          return Task.CompletedTask;
      }
  }
  

• After (v2.x):

  public class CreateOrderCommand : ICommand<CreateOrderCommandContext>
  {
      public Task<Result> ExecuteAsync(CreateOrderCommandContext context, CancellationToken ct = default)
      {
          if (context.Amount <= 0)
              return Task.FromResult(Result.Failure(new Error("Validation.Invalid", "Amount")));
  
          // Domain logic
          return Task.FromResult(Result.Success());
      }
  }
  

ICommandBuilder and ICommandExecutor have been updated to propagate the Result.
UnitOfWorkCommandExecutor now commits the Unit of Work only if the result was successful.

🚨 Breaking Changes in v2.4.0

As of v2.4.0, Autofac support has been completely removed.
The package now relies solely on Microsoft.Extensions.DependencyInjection (MS.DI).

• CQSModule (Autofac integration) has been removed.
• Registration is now done through IServiceCollection extensions.
• Handler registration includes fail-fast duplicate detection by full generic service contract.

🔧 Key Features

• 📦 Built-in ICommandBuilder and IQueryFor<TResult> implementations
• 📡 Centralized command and query execution
• 💼 UnitOfWorkCommandExecutor for wrapping commands in a Unit of Work with automatic commit on success
• 🔍 Fail-fast duplicate detection for handler registration
• 💡 Compatible with all abstractions from NPv.CQS.Abstractions

📦 Installation

dotnet add package NPv.CQS.Infrastructure

🧪 Usage Example

1. Register Infrastructure (in Program.cs)

using NPv.CQS.Infrastructure;

builder.Services.AddCqsInfrastructure(new[]
{
    typeof(CreateOrderCommand).Assembly,
    typeof(FindByIdQuery).Assembly
});

2. Execute a Command Declaratively

var result = await _commandExecutor.ExecuteAsync(new CreateOrderCommandContext(orderId, amount));
if (result.IsFailure)
{
    return BadRequest(result.Errors);
}
return Ok();

3. Execute a Query Declaratively

var order = await _queryFor<Order>()
    .With(new FindById(orderId));

Execution and validation boundary

These semantics apply to the implementations registered by AddCqsInfrastructure:

• ICommandExecutor (UnitOfWorkCommandExecutor) creates and disposes a separate async DI scope for every root execution, resolving ICommandBuilder and IUnitOfWork there. It commits that UoW only when the handler returns a successful Result or Result<TResult>; failure skips commit.
• ICommandBuilder dispatches the handler in its current DI scope and does not commit. Nested builder calls share the current scope/UoW; the root executor owns commit based on the root result. Propagate nested failures when they must prevent that commit.
• A nested executor call creates a separate scope/UoW and execution/commit boundary. Its commit is independent of the outer result; nested executor calls do not form one atomic operation.
• CQS does not run DataAnnotations validation. A command callable outside HTTP must enforce required application-level validation and invariants itself (in the handler or application/domain logic it invokes); HTTP validation alone is insufficient.
• The execution scope does not automatically put handler reads or external side effects before commit inside a database transaction. See UoW transaction limits.

Use the executor to own a root command's scope and commit; use the builder to compose commands within an existing scope/UoW. Outside an executor, the caller owns commit.

Handler registration

AddCqsInfrastructure scans the supplied assemblies. Handler identity is the full closed generic service contract: ICommand<TContext>, ICommand<TContext, TResult>, or IQuery<TCriterion, TResult>, including every generic argument. Registering one does not satisfy another contract with a different result type or generic arity.

For each dispatch, check that the handler's assembly is included and its implemented interface matches the exact context/criterion and result types used by that call. Duplicate detection rejects an already registered service contract during scanning; it does not prove that all required handlers are registered. A missing registration fails at dispatch.

🧩 Components Included

📚 Related Packages

• NPv.CQS.Abstractions – core interfaces and contracts
• NPv.ResultPattern – lightweight Result pattern implementation
• NPv.Uow.Abstractions – unit of work contract for transactional execution

Author's Note

This library grew out of my long-standing personal interest in structuring and publishing open source packages. Over time, I’ve revisited and refined earlier internal utilities and ideas, giving them a more consistent shape and preparing them for wider reuse. Along the way, I’ve also taken the opportunity to explore how open source distribution and licensing work in the .NET ecosystem.

It’s a small step toward something I’ve always wanted to try — sharing practical, minimal tools that reflect years of learning, experimentation, and refinement.

Hopefully, someone finds it useful.

Nikolai 😛

⚖️ License

MIT — you are free to use this in commercial and open-source software.