Brighter (Paramore.Brighter)

Overview

Paramore Brighter is a command dispatcher and processor library for .NET implementing the Command pattern with a pipeline of handlers. It supports synchronous dispatch, asynchronous task queues (via Paramore Darker for queries), attribute-based policies (retry, circuit breaker, timeout), and integration with external message brokers for decoupled messaging. Brighter separates command dispatch from handling and enables cross-cutting concerns through a decorator pipeline.

NuGet Packages

•Paramore.Brighter -- core command processor and handler infrastructure
•Paramore.Brighter.Extensions.DependencyInjection -- Microsoft DI integration
•Paramore.Brighter.Extensions.Hosting -- hosted service for message pump
•Paramore.Brighter.MessagingGateway.RMQ -- RabbitMQ transport
•Paramore.Brighter.MessagingGateway.AzureServiceBus -- Azure Service Bus transport
•Paramore.Darker -- query processor (read side of CQRS)
•Paramore.Darker.AspNetCore -- ASP.NET Core integration for queries

Commands and Events

csharp

using Paramore.Brighter;

// Command: intent to perform an action (one handler)
public class CreateOrder : Command
{
    public string CustomerId { get; init; }
    public decimal Total { get; init; }

    public CreateOrder(string customerId, decimal total)
        : base(Guid.NewGuid())
    {
        CustomerId = customerId;
        Total = total;
    }
}

// Event: notification of something that happened (multiple handlers)
public class OrderCreated : Event
{
    public Guid OrderId { get; init; }
    public string CustomerId { get; init; }

    public OrderCreated(Guid orderId, string customerId)
        : base(Guid.NewGuid())
    {
        OrderId = orderId;
        CustomerId = customerId;
    }
}

Request Handlers

csharp

using Paramore.Brighter;
using Paramore.Brighter.Policies.Attributes;

public class CreateOrderHandler : RequestHandlerAsync<CreateOrder>
{
    private readonly IOrderRepository _repository;
    private readonly IAmACommandProcessor _processor;

    public CreateOrderHandler(IOrderRepository repository, IAmACommandProcessor processor)
    {
        _repository = repository;
        _processor = processor;
    }

    [RequestLogging(step: 1, timing: HandlerTiming.Before)]
    [UsePolicy(CommandProcessor.RETRYPOLICYASYNC, step: 2)]
    public override async Task<CreateOrder> HandleAsync(
        CreateOrder command,
        CancellationToken ct = default)
    {
        var order = new Order(command.CustomerId, command.Total);
        await _repository.AddAsync(order, ct);

        await _processor.PostAsync(
            new OrderCreated(order.Id, order.CustomerId), cancellationToken: ct);

        return await base.HandleAsync(command, ct);
    }
}

// Event handler (subscriber)
public class OrderCreatedNotificationHandler : RequestHandlerAsync<OrderCreated>
{
    private readonly INotificationService _notifications;

    public OrderCreatedNotificationHandler(INotificationService notifications)
        => _notifications = notifications;

    public override async Task<OrderCreated> HandleAsync(
        OrderCreated @event,
        CancellationToken ct = default)
    {
        await _notifications.SendAsync(
            @event.CustomerId, $"Order {@event.OrderId} confirmed.", ct);

        return await base.HandleAsync(@event, ct);
    }
}

Registration and Configuration

csharp

using Paramore.Brighter.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBrighter(options =>
    {
        options.PolicyRegistry = GetPolicies();
    })
    .AutoFromAssemblies();

builder.Services.AddScoped<IOrderRepository, OrderRepository>();

var app = builder.Build();

app.MapPost("/orders", async (CreateOrder cmd, IAmACommandProcessor processor) =>
{
    await processor.SendAsync(cmd);
    return Results.Accepted();
});

app.Run();

static PolicyRegistry GetPolicies()
{
    var registry = new PolicyRegistry
    {
        {
            CommandProcessor.RETRYPOLICYASYNC,
            Policy.Handle<Exception>()
                  .WaitAndRetryAsync(3, retry => TimeSpan.FromMilliseconds(100 * Math.Pow(2, retry)))
        },
        {
            CommandProcessor.CIRCUITBREAKERASYNC,
            Policy.Handle<Exception>()
                  .CircuitBreakerAsync(5, TimeSpan.FromSeconds(30))
        }
    };
    return registry;
}

Query Side with Darker

csharp

using Paramore.Darker;

// Query and result
public class GetOrderById : IQuery<OrderResult>
{
    public Guid OrderId { get; init; }
}

public class OrderResult
{
    public Guid Id { get; init; }
    public string CustomerId { get; init; } = default!;
    public decimal Total { get; init; }
    public string Status { get; init; } = default!;
}

// Query handler
public class GetOrderByIdHandler : QueryHandlerAsync<GetOrderById, OrderResult>
{
    private readonly IOrderRepository _repository;

    public GetOrderByIdHandler(IOrderRepository repository)
        => _repository = repository;

    public override async Task<OrderResult> ExecuteAsync(
        GetOrderById query,
        CancellationToken ct = default)
    {
        var order = await _repository.GetByIdAsync(query.OrderId, ct);
        return new OrderResult
        {
            Id = order.Id,
            CustomerId = order.CustomerId,
            Total = order.Total,
            Status = order.Status
        };
    }
}

// Registration
builder.Services.AddDarker()
    .AddHandlersFromAssemblies(typeof(GetOrderByIdHandler).Assembly);

Async Messaging with RabbitMQ

csharp

using Paramore.Brighter.MessagingGateway.RMQ;

builder.Services.AddBrighter(options =>
    {
        options.PolicyRegistry = GetPolicies();
    })
    .UseExternalBus(new RmqProducerRegistryFactory(
        new RmqMessagingGatewayConnection
        {
            AmpqUri = new AmqpUriSpecification(new Uri("amqp://guest:guest@localhost:5672")),
            Exchange = new Exchange("orders.exchange")
        },
        new[]
        {
            new RmqPublication
            {
                Topic = new RoutingKey("order.created"),
                RequestType = typeof(OrderCreated),
                WaitForConfirmsTimeOutInMilliseconds = 1000
            }
        }).Create())
    .AutoFromAssemblies();

Brighter vs MediatR vs MassTransit

Feature	Brighter	MediatR	MassTransit
Command dispatch	Yes (Send)	Yes (Send)	Yes (via consumers)
Event publish	Yes (Post/Publish)	Yes (Publish)	Yes (Publish)
Policy pipeline	Attribute-based (retry, CB)	Pipeline behaviors	Middleware filters
External messaging	RabbitMQ, Azure SB, Kafka	None (in-process)	RabbitMQ, Azure SB, SQS
Query support	Via Darker	Yes (IRequest<T>)	No built-in query
Outbox pattern	Built-in	Not built-in	Built-in

Best Practices

•Use Command for operations handled by exactly one handler and Event for notifications that may have zero or more subscribers.
•Apply [UsePolicy] attributes to handlers for retry and circuit-breaker logic rather than wrapping handler code in try/catch with manual retry loops.
•Call SendAsync for commands (single handler expected) and PublishAsync for events (fan-out to multiple handlers).
•Register handlers using AutoFromAssemblies() for automatic discovery rather than manually wiring each handler to its command type.
•Keep handlers single-purpose; extract shared logic into services injected via the constructor instead of duplicating code across handlers.
•Use the Outbox pattern (DepositPostAsync + ClearOutboxAsync) when publishing events after a database write to ensure at-least-once delivery without dual-write issues.
•Pair Brighter (command side) with Darker (query side) in CQRS architectures to maintain a clean separation of reads and writes.
•Define policy registries centrally (retry, circuit breaker, timeout) and reference them by name in handler attributes for consistency across the application.
•Use PostAsync (internal dispatch) for in-process event fans and PublishAsync (external) when events must cross service boundaries via a message broker.
•Test handlers in isolation by mocking IAmACommandProcessor and repository dependencies, verifying that commands produce the expected downstream events.