Mediant.Behaviors 1.2.0

Mediant

Enterprise-Grade CQRS Mediator for .NET

A production-ready CQRS mediator library for .NET with Result pattern, pipeline behaviors, DDD support, and attribute-based HTTP endpoint mapping.

Why Mediant?

• Result Pattern built-in — No more throwing exceptions for control flow
• Explicit CQRS — ICommand<T>, IQuery<T> instead of just IRequest
• 10 built-in behaviors — Audit, logging, validation, auth, transactions, retry, caching, performance, idempotency, cache invalidation
• Attribute-based HTTP endpoints — [HttpEndpoint] eliminates controller boilerplate
• DDD native — IDomainEvent, aggregate root patterns
• Publish performance — Up to ~65% faster notification dispatch with 4.7x less memory (benchmarks)
• 300 tests — Unit, integration, load, E2E

Performance

Benchmarked against MediatR v12 using BenchmarkDotNet (Apple M5, .NET 10). These measure framework dispatch overhead with no-op handlers — real handlers doing I/O narrow the relative gap. Full results and method: docs/BENCHMARKS.md

Publish (Notification Dispatch) — Mediant wins

Send (Pipeline) — Equal speed, Mediant uses less memory

Quick Start

1. Install

dotnet add package Mediant

2. Register

builder.Services.AddMediant(cfg =>
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly));

3. Define a Command

public record CreateOrderCommand(string UserId, List<OrderItem> Items)
    : ICommand<Result<Guid>>;

4. Handle it

public class CreateOrderHandler : ICommandHandler<CreateOrderCommand, Result<Guid>>
{
    public ValueTask<Result<Guid>> Handle(CreateOrderCommand request, CancellationToken ct)
    {
        var orderId = Guid.NewGuid();
        // ... create order
        return new ValueTask<Result<Guid>>(Result<Guid>.Success(orderId));
    }
}

5. Send

var result = await mediator.Send(new CreateOrderCommand("user-1", items));
result.Match(
    id => Console.WriteLine($"Order created: {id}"),
    error => Console.WriteLine($"Failed: {error}")
);

Features

CQRS Separation

// Commands — change state
public record CreateOrder(string UserId) : ICommand<Result<Guid>>;
public record CancelOrder(Guid Id) : ICommand<Result>;

// Queries — read state, no side effects
public record GetOrderById(Guid Id) : IQuery<Result<Order>>;

// Streaming
public record SearchOrders(string? Status) : IStreamRequest<Order>;

Result Pattern

// Success
return Result<Guid>.Success(orderId);

// Failure with typed errors
return Error.NotFound("Order.NotFound", "Order not found");

// Functional operations
var name = result.Map(order => order.Name)
                 .Bind(name => ValidateName(name))
                 .Match(
                     name => $"Hello, {name}",
                     error => $"Error: {error.Description}");

Domain Events

public record OrderCreatedEvent(Guid OrderId, string UserId) : IDomainEvent
{
    public DateTimeOffset OccurredOn { get; } = DateTimeOffset.UtcNow;
}

// Multiple handlers per event
public class SendEmail : INotificationHandler<OrderCreatedEvent> { ... }
public class UpdateInventory : INotificationHandler<OrderCreatedEvent> { ... }

await publisher.Publish(new OrderCreatedEvent(orderId, userId));

HTTP Endpoint Mapping

[HttpEndpoint("POST", "/api/orders", Tags = new[] { "Orders" })]
[Transactional]
[Auditable]
public record CreateOrderCommand : ICommand<Result<Guid>> { ... }

// In Program.cs
app.MapMediantEndpoints(typeof(Program).Assembly);
// Result auto-mapped: Success->200/201, Validation->400, NotFound->404, etc.

Pipeline Behaviors

All behaviors are attribute-driven, configurable, and automatically ordered via IBehaviorOrder.

Full Configuration

builder.Services.AddMediant(cfg =>
{
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
    cfg.NotificationPublishStrategy = NotificationPublishStrategy.Parallel;
    cfg.EnablePolymorphicNotifications = true;
    cfg.ValidateOnStartup = true;

    // Open-generic behavior that wraps every request (runs in IBehaviorOrder order).
    cfg.AddOpenBehavior(typeof(MyLoggingBehavior<,>));
});

builder.Services.AddMediantValidation(typeof(Program).Assembly);

builder.Services.AddMediantAllBehaviors(opts =>
{
    opts.ConfigureLogging = log =>
    {
        log.MaskProperties.Add("CardNumber");
        log.MaxSerializedLength = 4096;
    };
    opts.ConfigurePerformance = perf =>
    {
        perf.WarningThresholdMs = 500;
        perf.CriticalThresholdMs = 5000;
    };
});

Reliable Events (Transactional Outbox)

For at-least-once delivery that survives crashes, enqueue notifications into the outbox inside your business transaction; a background processor publishes them after commit and retries failures:

builder.Services.AddMediantOutbox();   // InMemoryOutboxStore + processor (provide a durable store for prod)

// in a handler, within the transaction:
await _outbox.EnqueueAsync(new OrderCreatedEvent(orderId), ct);

Provide a durable IOutboxStore (EF Core, SQL, …) in production; the in-memory store is for development and tests.

Native AOT & Trimming

Add the Mediant.SourceGenerator package and register via the generated method — handlers are discovered and dispatch is precomputed at compile time, with no assembly scanning and no runtime code generation:

// Generated: registers every handler + precomputes Send/Publish/Stream dispatch
builder.Services.AddMediantGenerated();

The core Mediant assembly is marked IsAotCompatible and its dispatch path is verified trim/AOT-clean by the analyzers. The reflection-based AddMediant(...) scanning path still works for JIT scenarios; under trimming/AOT use AddMediantGenerated().

Features that serialize JSON (caching, idempotency store, outbox) accept an explicit SerializerOptions — set it to options backed by a JsonSerializerContext (System.Text.Json source generation) for AOT, e.g. opts.SerializerOptions = MyJsonContext.Default.Options;.

Observability (OpenTelemetry)

The mediator emits OpenTelemetry-compatible traces and metrics using the built-in System.Diagnostics primitives — no dependency on the OpenTelemetry SDK. Wire them into your collector:

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(MediatorDiagnostics.ActivitySourceName))   // "Mediant"
    .WithMetrics(m => m.AddMeter(MediatorDiagnostics.MeterName));            // "Mediant"

• Spans: mediator.send <Request> and mediator.publish <Notification>, tagged with the request/notification type and an Ok/Error status (failures record error.type).
• Metrics: mediant.send.count / .duration, mediant.publish.count / .duration.

When nothing is listening (the default), instrumentation is effectively free — the hot path only performs a cheap HasListeners()/Enabled check and skips all activity and measurement work.

MediatR vs Mediant

Test Coverage

Packages

Sample Project

See tests/Mediant.Sample.ECommerce/ for a complete e-commerce example with:

• Order aggregate root with domain events
• Commands with transactions, audit, authorization, idempotency, and retry
• Queries with caching and streaming
• FluentValidation validators
• Attribute-based HTTP endpoint mapping
• Full behavior pipeline configuration

Migration from MediatR

See docs/MIGRATION_GUIDE.md for a step-by-step migration guide.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

MIT License