Simplify.Bus.Impl 0.1.3

Simplify.Bus Documentation

A lightweight, async-first message bus implementing the mediator pattern. It supports three messaging styles:

• Commands — a fire-and-forget request handled by a single handler.
• Queries — a request handled by a single handler that returns a response.
• Events — a notification published to multiple handlers.

In addition, a behavior pipeline allows middleware-style interceptors (validation, logging, etc.) to wrap request handling.

All operations are Task-based.

Abstractions are available at NuGet as binary package. The implementation and Simplify.DI integration are in Simplify.Bus.Impl.

Core types

All abstractions live in the Simplify.Bus namespace; the implementations and DI registration extensions live in Simplify.Bus.Impl.

Handler method signatures:

// IRequestHandler<TRequest>
Task Handle(TRequest request);

// IRequestHandler<TRequest, TResponse>
Task<TResponse> Handle(TRequest request);

// IEventHandler<TEvent>
Task Handle(TEvent busEvent);

Commands (fire-and-forget)

Define a request and its handler:

using Simplify.Bus;

public class CreateUserCommand(IUser user)
{
    public IUser User { get; } = user;
}

public class CreateUserCommandHandler : IRequestHandler<CreateUserCommand>
{
    public Task Handle(CreateUserCommand command)
    {
        // ... create the user
        return Task.CompletedTask;
    }
}

Register and dispatch:

using Simplify.DI;
using Simplify.Bus;
using Simplify.Bus.Impl;

DIContainer.Current
    .Register<IRequestHandler<CreateUserCommand>, CreateUserCommandHandler>()
    .RegisterBus<CreateUserCommand>();

using var scope = DIContainer.Current.BeginLifetimeScope();

var bus = scope.Resolver.Resolve<IBusAsync<CreateUserCommand>>();
await bus.Send(new CreateUserCommand(user));

Queries (request with response)

using Simplify.Bus;

public class GetUserQuery(int userId)
{
    public int UserId { get; } = userId;
}

public class GetUserResponse(IUser? user)
{
    public IUser? User { get; } = user;
}

public class GetUserQueryHandler(IUsersRepository repository)
    : IRequestHandler<GetUserQuery, GetUserResponse>
{
    public async Task<GetUserResponse> Handle(GetUserQuery request) =>
        new GetUserResponse(await repository.GetAsync(request.UserId));
}

DIContainer.Current
    .Register<IRequestHandler<GetUserQuery, GetUserResponse>, GetUserQueryHandler>()
    .RegisterBus<GetUserQuery, GetUserResponse>();

using var scope = DIContainer.Current.BeginLifetimeScope();

var bus = scope.Resolver.Resolve<IBusAsync<GetUserQuery, GetUserResponse>>();
var response = await bus.Send(new GetUserQuery(1));

Events (publish to multiple handlers)

An event can have any number of handlers:

using Simplify.Bus;

public class UserCreatedEvent(IUser user)
{
    public IUser User { get; } = user;
}

public class SendWelcomeEmailHandler : IEventHandler<UserCreatedEvent>
{
    public Task Handle(UserCreatedEvent busEvent) { /* ... */ return Task.CompletedTask; }
}

public class AuditUserCreationHandler : IEventHandler<UserCreatedEvent>
{
    public Task Handle(UserCreatedEvent busEvent) { /* ... */ return Task.CompletedTask; }
}

DIContainer.Current
    .Register<SendWelcomeEmailHandler>()
    .Register<AuditUserCreationHandler>()
    .RegisterEventBus<UserCreatedEvent>(
        typeof(SendWelcomeEmailHandler),
        typeof(AuditUserCreationHandler));

using var scope = DIContainer.Current.BeginLifetimeScope();

var bus = scope.Resolver.Resolve<IEventBusAsync<UserCreatedEvent>>();
await bus.Publish(new UserCreatedEvent(user));

Publish strategy

The order/error handling of event handlers is controlled by the PublishStrategy enum:

• SyncStopOnException (default) — handlers run sequentially and publishing stops on the first exception.
• ParallelWhenAll — all handlers run in parallel and exceptions are aggregated.

Pass the strategy as the first argument when registering the event bus:

DIContainer.Current
    .Register<SendWelcomeEmailHandler>()
    .Register<AuditUserCreationHandler>()
    .RegisterEventBus<UserCreatedEvent>(
        PublishStrategy.ParallelWhenAll,
        typeof(SendWelcomeEmailHandler),
        typeof(AuditUserCreationHandler));

Behaviors (middleware pipeline)

Behaviors wrap request handling, receiving the request and a next delegate that invokes the next behavior (or finally the handler).

using Simplify.Bus;

// For commands (no response)
public class LoggingBehavior<TRequest> : IBehavior<TRequest>
{
    public Task Handle(TRequest request, RequestHandler next)
    {
        // pre-processing
        return next();
        // post-processing could await next() then continue
    }
}

// For queries (with response)
public class ValidationBehavior : IBehavior<GetUserQuery, GetUserResponse>
{
    public Task<GetUserResponse> Handle(GetUserQuery request, RequestHandler<GetUserResponse> next)
    {
        // validate request...
        return next();
    }
}

The next parameters are the delegates public delegate Task RequestHandler(); and public delegate Task<TResponse> RequestHandler<TResponse>();.

Behaviors are passed to RegisterBus and execute in the order listed (behavior1 → behavior2 → handler):

DIContainer.Current
    .Register<IRequestHandler<CreateUserCommand>, CreateUserCommandHandler>()
    .Register<LoggingBehavior<CreateUserCommand>>()
    .Register<CreateUserCommandValidationBehavior>()
    .RegisterBus<CreateUserCommand>(
        typeof(LoggingBehavior<CreateUserCommand>),
        typeof(CreateUserCommandValidationBehavior));

DI registration reference

The Simplify.Bus.Impl namespace provides these IDIRegistrator extension methods:

// Commands
IDIRegistrator RegisterBus<TRequest>(this IDIRegistrator registrator, params Type[] behaviors);

// Queries
IDIRegistrator RegisterBus<TRequest, TResponse>(this IDIRegistrator registrator, params Type[] behaviors);

// Events
IDIRegistrator RegisterEventBus<TEvent>(this IDIRegistrator registrator, params Type[] eventHandlers);
IDIRegistrator RegisterEventBus<TEvent>(this IDIRegistrator registrator, PublishStrategy publishStrategy, params Type[] eventHandlers);

These register the corresponding IBusAsync<...> / IEventBusAsync<...> implementation. You must register the request handlers, event handlers, and behaviors themselves separately (as shown in the examples above).