LiteBus.Commands.Extensions.Microsoft.DependencyInjection 7.1.0

LiteBus

Commands, queries, and events for .NET, with a full handler pipeline and an optional inbox, outbox, and sagas. LiteBus is MIT licensed, free for commercial use, and will stay free.

Full documentation: litebus.io/docs

Table of Contents

• Features
• Installation
• Usage
• Examples
• Packages
• Documentation
• Contributing
• Support
• Security
• License

Features

Installation

LiteBus targets .NET 10. For commands, queries, and events on Microsoft dependency injection, install one package:

dotnet add package LiteBus.Extensions.Microsoft.DependencyInjection

To install only the modules you use, or to use Autofac, reference the per-module packages instead:

dotnet add package LiteBus.Commands.Extensions.Microsoft.DependencyInjection
dotnet add package LiteBus.Queries.Extensions.Autofac

Durable messaging, storage, and broker support are separate packages. See Packages.

Usage

Register LiteBus and discover the handlers in your assembly:

builder.Services.AddLiteBus(liteBus =>
{
    liteBus.AddMessaging(_ => { });
    liteBus.AddCommands(c => c.RegisterFromAssembly(typeof(Program).Assembly));
    liteBus.AddQueries(q => q.RegisterFromAssembly(typeof(Program).Assembly));
    liteBus.AddEvents(e => e.RegisterFromAssembly(typeof(Program).Assembly));
});

Define a command and its handler:

public sealed record CreateProductCommand(string Name, decimal Price) : ICommand<Guid>;

public sealed class CreateProductCommandHandler : ICommandHandler<CreateProductCommand, Guid>
{
    public Task<Guid> HandleAsync(CreateProductCommand command, CancellationToken cancellationToken = default)
        => Task.FromResult(Guid.NewGuid());
}

Inject ICommandMediator and send it:

var id = await commandMediator.SendAsync(new CreateProductCommand("Widget", 9.99m), cancellationToken);

Getting Started walks through queries, events, and handler discovery.

Examples

Queries and Streaming Queries

public sealed record GetProductQuery(Guid Id) : IQuery<ProductDto>;
public sealed record SearchProductsQuery(string Term) : IStreamQuery<ProductDto>;

public sealed class SearchProductsQueryHandler : IStreamQueryHandler<SearchProductsQuery, ProductDto>
{
    public async IAsyncEnumerable<ProductDto> StreamAsync(
        SearchProductsQuery query,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        await foreach (var product in _repository.SearchAsync(query.Term, cancellationToken))
            yield return new ProductDto(product.Id, product.Name);
    }
}

var product = await queryMediator.QueryAsync(new GetProductQuery(id), cancellationToken);

await foreach (var item in queryMediator.StreamAsync(new SearchProductsQuery("chair"), cancellationToken))
    Console.WriteLine(item.Name);

See Queries.

Events With Ordered Handlers

Events can be plain classes with no LiteBus dependency. Every handler runs, and HandlerPriority sets the order.

public sealed record OrderShipped(Guid OrderId, string TrackingNumber);

[HandlerPriority(1)]
public sealed class UpdateReadModel : IEventHandler<OrderShipped> { /* ... */ }

[HandlerPriority(2)]
public sealed class SendShippingEmail : IEventHandler<OrderShipped> { /* ... */ }

await eventMediator.PublishAsync(new OrderShipped(orderId, trackingNumber), cancellationToken);

See Events and Handler Priority.

Validators, Pre-Handlers, and Post-Handlers

public sealed class CreateProductValidator : ICommandValidator<CreateProductCommand>
{
    public Task<Validity> ValidateAsync(CreateProductCommand command, CancellationToken cancellationToken = default)
        => Task.FromResult(command.Price > 0
            ? Validity.Valid
            : Validity.Invalid("the price must be positive", nameof(command.Price)));
}

public sealed class LogCommand : ICommandPreHandler<CreateProductCommand>
{
    public Task PreHandleAsync(CreateProductCommand command, CancellationToken cancellationToken = default) { /* ... */ }
}

public sealed class PublishProductCreated : ICommandPostHandler<CreateProductCommand, Guid>
{
    public Task PostHandleAsync(CreateProductCommand command, Guid productId, CancellationToken cancellationToken = default) { /* ... */ }
}

A failed validation reaches the caller as LiteBusMessageInvalidException carrying every failure. See The Handler Pipeline and Validation.

Guards

A guard decides whether the work happens at all, for example an authorization check that needs the loaded entity.

public sealed class CancelOrderGuard : ICommandGuard<CancelOrderCommand>
{
    public async Task<Verdict> DecideAsync(CancelOrderCommand command, CancellationToken cancellationToken = default)
    {
        var order = await _orders.LoadAsync(command.OrderId, cancellationToken);

        return order is null ? Verdict.Deny("the order does not exist") : Verdict.Allow;
    }
}

See Deciding Whether the Work Happens.

One Handler for Many Messages

A handler for a base type or interface runs for every message that implements it. An open generic handler runs for every message of its kind.

public sealed class AuditPreHandler : ICommandPreHandler<IAuditableCommand> { /* ... */ }

public sealed class LoggingPreHandler<TCommand> : ICommandPreHandler<TCommand>
    where TCommand : ICommand { /* ... */ }

See Polymorphic Dispatch and Open Generic Handlers.

Handlers Selected by Tag

Untagged handlers run for every call. Tagged handlers run only when the caller names their tag.

[HandlerTag("PublicAPI")]
public sealed class StrictValidationPreHandler : ICommandPreHandler<CreateUserCommand> { /* ... */ }

await commandMediator.SendAsync(command, "PublicAPI", cancellationToken);

See Handler Filtering.

Idempotent Commands

A repeated PaymentId is answered from the store instead of running the handler again.

public sealed class ApplyPaymentDefinition : IIdempotencyDefinition<ApplyPaymentCommand>
{
    public IdempotencyDeclaration Idempotency =>
        IdempotencyDeclaration.KeyedBy<ApplyPaymentCommand>(command => command.PaymentId.ToString());
}

liteBus.AddCommands(commands =>
{
    commands.RegisterFromAssembly(typeof(Program).Assembly);
    commands.EnableIdempotency();
    commands.UsePostgreSqlIdempotencyStore(postgres => postgres.UseDataSource(dataSource));
});

See Idempotency.

Transactional Outbox

Store an event beside your data and publish it to the broker after the commit.

dotnet add package LiteBus.Outbox.Storage.PostgreSql
dotnet add package LiteBus.Outbox.Dispatch.Amqp

liteBus.AddAmqpTransport(new AmqpConnectionOptions { Uri = new Uri(amqpConnectionString) });

liteBus.AddOutbox(outbox =>
{
    outbox.Contracts.Register<OrderSubmitted>("orders.order-submitted", 1);
    outbox.UsePostgreSqlStorage(postgres => postgres.UseDataSource(dataSource));
    outbox.UseAmqpDispatch(amqp => amqp.DefaultDestination = "orders.order-submitted");
    outbox.EnableOutboxProcessor();
});

await outbox.EnqueueAsync(new OrderSubmitted { OrderId = orderId }, cancellationToken);

See Outbox, Inbox, Saga, and Transactional Writes.

Packages

LiteBus ships as 87 packages, one per concern, so a service installs only what it runs. A Kafka service never references the RabbitMQ client, and an in-memory test host never references Npgsql.

Mediation

Storage

Packages follow the pattern LiteBus.Inbox.Storage.PostgreSql, LiteBus.Outbox.Storage.EntityFrameworkCore, LiteBus.Outbox.Storage.Marten, LiteBus.Saga.Storage.PostgreSql, LiteBus.Commands.Storage.PostgreSql, LiteBus.Commands.Storage.Marten, and LiteBus.Commands.Recurring.Storage.PostgreSql.

Brokers

Packages follow the pattern LiteBus.Transport.Kafka, LiteBus.Outbox.Dispatch.Kafka, LiteBus.Inbox.Dispatch.Kafka, and LiteBus.Inbox.Ingress.Kafka. Outbox dispatch publishes stored events to the broker, inbox dispatch runs stored commands through it, and inbox ingress accepts commands consumed from it.

Durable Messaging Core

LiteBus.Inbox, LiteBus.Outbox, LiteBus.Saga, LiteBus.Saga.InboxIntegration, LiteBus.Inbox.Dispatch, LiteBus.Outbox.Dispatch, LiteBus.Inbox.Ingress, LiteBus.Transport, LiteBus.Storage.PostgreSql, LiteBus.Storage.EntityFrameworkCore

Containers and Hosting

Observability

LiteBus.Messaging.Extensions.OpenTelemetry, LiteBus.Inbox.Extensions.OpenTelemetry, LiteBus.Outbox.Extensions.OpenTelemetry, LiteBus.Transport.Extensions.OpenTelemetry, and LiteBus.Transport.Amqp.Extensions.OpenTelemetry register traces and metrics for mediation, processors, and brokers.

Tooling

Each module also has an *.Abstractions package for libraries that only reference contracts. The Feature and Package Index maps every feature to its package, and the Dependency Graph lists what each one references.

Documentation

• Getting Started and the Cookbook
• The Handler Pipeline
• Reliable Messaging
• Operations and Testing
• Differences from MediatR and the Migration Guide v7
• Changelog

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the workflow and build steps, and the AI Use Policy if you use generative AI tools.

Support

Ask questions in GitHub Discussions and report bugs in GitHub Issues. See SUPPORT.md for what to include.

Security

Report vulnerabilities privately as described in SECURITY.md, not in a public issue.

License

LiteBus is licensed under the MIT License.