Sondor.Cqrs 0.3.0

Prefix Reserved
dotnet add package Sondor.Cqrs --version 0.3.0
                    
NuGet\Install-Package Sondor.Cqrs -Version 0.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sondor.Cqrs" Version="0.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sondor.Cqrs" Version="0.3.0" />
                    
Directory.Packages.props
<PackageReference Include="Sondor.Cqrs" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sondor.Cqrs --version 0.3.0
                    
#r "nuget: Sondor.Cqrs, 0.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sondor.Cqrs@0.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sondor.Cqrs&version=0.3.0
                    
Install as a Cake Addin
#tool nuget:?package=Sondor.Cqrs&version=0.3.0
                    
Install as a Cake Tool

Sondor.Cqrs

Commands, queries and notifications dispatched in process, with a pipeline of behaviours around them. MIT licensed, no licence key, and no third-party dependencies: the only packages it uses are Microsoft's dependency injection and logging abstractions.

dotnet add package Sondor.Cqrs

The basics

using Sondor.Cqrs;

// A query: it only reads. A command (ICommand<T>) changes something. IRequest<T> is neither.
public sealed record GetNode(Guid Id) : IQuery<Node?>;

public sealed class GetNodeHandler(INodeStore store) : IRequestHandler<GetNode, Node?>
{
    public ValueTask<Node?> Handle(GetNode request, CancellationToken cancellationToken) =>
        store.FindAsync(request.Id, cancellationToken);
}

Register it once, then send requests through ISender:

services.AddCqrs(cqrs => cqrs.AddHandlersFromAssemblyContaining<GetNodeHandler>());

public sealed class NodeEndpoint(ISender sender)
{
    public ValueTask<Node?> Get(Guid id, CancellationToken ct) => sender.Send(new GetNode(id), ct);
}

A request with nothing to return implements ICommand (or IRequest) and its handler returns Unit.Value.

Any response type works. Returning Result<T> from Sondor.Results is recommended, not required.

Notifications

A notification can have any number of handlers, including none.

public sealed record NodeProvisioned(Guid Id) : INotification;

public sealed class SendWelcome : INotificationHandler<NodeProvisioned>
{
    public ValueTask Handle(NodeProvisioned notification, CancellationToken cancellationToken) => ValueTask.CompletedTask;
}

await publisher.Publish(new NodeProvisioned(id), ct);     // IPublisher

Handlers run one after another and the first that throws stops the rest. For all at once, use cqrs.UseNotificationPublisher<ParallelNotificationPublisher>(), or write an INotificationPublisher.

The pipeline

A behaviour runs around every request it applies to. The first one added is the outermost.

public sealed class RetryBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    public async ValueTask<TResponse> Handle(TRequest request, RequestContinuation<TResponse> continuation, CancellationToken ct)
    {
        try { return await continuation.Invoke(); }
        catch (TimeoutException) { return await continuation.Invoke(); }     // may be called more than once, or not at all
    }
}

services.AddCqrs(cqrs =>
{
    cqrs.AddHandlersFromAssemblyContaining<GetNodeHandler>();
    cqrs.UseTracing();                       // built in, opt-in
    cqrs.UseMetrics();
    cqrs.UseLogging(slowRequestThreshold: TimeSpan.FromSeconds(1));
    cqrs.AddBehavior(typeof(RetryBehavior<,>));
});
Built in What it records
UseTracing() A span for each request, and for each notification and its handlers. Source Sondor.Cqrs; tags cqrs.request, cqrs.request.kind (command, query, request, notification), cqrs.handler, cqrs.outcome, sondor.error.code. Exceptions are recorded on the span.
UseMetrics() Meter Sondor.Cqrs: a counter cqrs.requests and a histogram cqrs.request.duration (seconds), tagged by request, kind and outcome (success, failure, error, cancelled).
UseLogging() One line per request: its kind and name, how long it took, how it ended. Never the request itself, which can hold a secret. A slow request is a warning.

Tracing, metrics and logging do nothing while nothing is listening. Add the names to your OpenTelemetry setup: .AddSource(CqrsTelemetry.SourceName) and .AddMeter(CqrsTelemetry.MeterName).

Failures that are returned, not thrown

When requests return a result type, a "failed" response is still a response. Register an IOutcomeReader<TResponse> and the built-ins report it as a failure, with its code:

services.AddSingleton<IOutcomeReader<MyResult>, MyResultOutcomeReader>();

Without one, every response that comes back counts as a success. An IFailureFactory<TResponse> lets a behaviour refuse a request by returning a failed response. Adapter packages register both for you.

Registration checks

AddCqrs fails at start-up, with the type names, when two handlers handle one request, or when a request type in a scanned assembly has no handler (turn the second off with cqrs.ValidateHandlers = false if a handler is registered elsewhere). Sending a request that has no handler throws an InvalidOperationException that says so.

Handlers are transient unless you set cqrs.HandlerLifetime. Handlers that are generic classes are not found by the scan; register those yourself.

Things that behave in a specific way

  • Send and Publish return ValueTask. Await each one once.
  • Publish uses the runtime type of the notification, so publishing through an INotification variable reaches the handlers of the type it really is.
  • ISender and IPublisher are transient and use the scope they are resolved from, so scoped handlers and behaviours work.
  • Nothing is on unless asked for, and nothing scans, reflects or builds a second service provider per request.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed.  net11.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Sondor.Cqrs:

Package Downloads
Sondor.Cqrs.Results

Sondor.Results support for Sondor.Cqrs: tracing, metrics and logging report a failed Result with its error code, and behaviours can refuse a request by returning one.

Sondor.Cqrs.FluentValidation

FluentValidation for Sondor.Cqrs: validates every request before its handler and refuses an invalid one, without a result type or an exception, as your response type allows.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.3.0 137 11/16/2026
0.2.1 153 11/14/2026
0.2.0 219 11/13/2026
0.1.0 126 11/12/2026
0.1.0-preview.1 54 11/12/2026