DEV Community: A. Shafie

Migrating from MediatR to LiteBus

A. Shafie — Wed, 12 Nov 2025 00:11:57 +0000

This guide provides a step-by-step technical walkthrough for migrating a .NET application from MediatR to LiteBus. It maps MediatR's concepts directly to their LiteBus equivalents, focusing on code and configuration changes.

Since MediatR is shifting to a commercial model, LiteBus offers a powerful, free, and open-source alternative with a more ambitious feature set.

Core Philosophy: From Generic to Semantic

The primary difference between the two libraries is their approach to abstractions:

MediatR uses a generic IRequest<TResponse> for both commands and queries.
LiteBus provides distinct ICommand<TResult>, IQuery<TResult>, and IEvent interfaces.

This semantic distinction in LiteBus enforces Command Query Separation (CQS) at the compiler level, making your application's intent clearer.

Step 1: Update Project Dependencies

First, replace the MediatR packages with the LiteBus equivalents.

Remove MediatR:

dotnet remove MediatR

Add LiteBus:

# Core DI extension (pulls in Command, Query, Event modules)
dotnet add package LiteBus.Extensions.Microsoft.DependencyInjection

# Optional: For referencing only abstractions in domain/app layers
dotnet add package LiteBus.Commands.Abstractions
dotnet add package LiteBus.Queries.Abstractions
dotnet add package LiteBus.Events.Abstractions

Step 2: Update Dependency Injection (`Program.cs`)

The registration process is similar. LiteBus scans assemblies to discover handlers automatically.

Before (MediatR):

builder.Services.AddMediatR(cfg => 
{
    cfg.LicenseKey = "<License Key here>";
    cfg.RegisterServicesFromAssembly(typeof(Program).Assembly);
});

After (LiteBus):

builder.Services.AddLiteBus(liteBus =>
{
    var appAssembly = typeof(Program).Assembly;

    // Each module scans for its specific constructs (handlers, validators, etc.)
    liteBus.AddCommandModule(module => module.RegisterFromAssembly(appAssembly));
    liteBus.AddQueryModule(module => module.RegisterFromAssembly(appAssembly));
    liteBus.AddEventModule(module => module.RegisterFromAssembly(appAssembly));
});

Step 3: Convert Message Contracts

This is a direct mapping of interfaces.

Requests (Commands and Queries)

IRequest -> ICommand
IRequest<TResponse> -> ICommand<TResponse> (for state changes) or IQuery<TResponse> (for data retrieval).

Before (MediatR):

// Command
public class ShipOrderCommand : IRequest { ... }

// Query
public class GetProductQuery : IRequest<ProductDto> { ... }

After (LiteBus):

// Command
public class ShipOrderCommand : ICommand { ... }

// Query
public class GetProductQuery : IQuery<ProductDto> { ... }

Notifications (Events)

INotification -> IEvent or a Plain Old C# Object (POCO).

Before (MediatR):

public class OrderShippedEvent : INotification { ... }

After (LiteBus):

// Option 1: Using the interface
public class OrderShippedEvent : IEvent { ... }

// Option 2: Using a POCO (recommended for domain events)
public class OrderShippedEvent { ... }

Step 4: Convert Handlers

Handler interfaces also map directly.

Before (MediatR):

public class ShipOrderCommandHandler : IRequestHandler<ShipOrderCommand> { ... }
public class GetProductQueryHandler : IRequestHandler<GetProductQuery, ProductDto> { ... }
public class OrderShippedEventHandler : INotificationHandler<OrderShippedEvent> { ... }

After (LiteBus):

public class ShipOrderCommandHandler : ICommandHandler<ShipOrderCommand> { ... }
public class GetProductQueryHandler : IQueryHandler<GetProductQuery, ProductDto> { ... }
public class OrderShippedEventHandler : IEventHandler<OrderShippedEvent> { ... }

Step 5: Convert Pipeline Behaviors and Processors

MediatR uses IPipelineBehavior for cross-cutting concerns and has separate pre/post-processors. LiteBus unifies this into a structured pipeline of Pre-Handler, Post-Handler, and Error-Handler.

IRequestPreProcessor<TRequest> -> ICommandPreHandler<TCommand>
IRequestPostProcessor<TRequest, TResponse> -> ICommandPostHandler<TCommand, TResponse>
IPipelineBehavior logic can be split into pre and post handlers.

Let's convert a MediatR LoggingBehavior.

Before (MediatR):

public class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
    where TRequest : notnull
{
    public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken ct)
    {
        // Pre-logic
        _logger.LogInformation("Handling {RequestName}", typeof(TRequest).Name);
        var response = await next();
        // Post-logic
        _logger.LogInformation("Handled {RequestName}", typeof(TRequest).Name);
        return response;
    }
}

After (LiteBus):

The logic is split into two distinct, globally-scoped handlers.

// This runs BEFORE every command.
public class GlobalLoggingPreHandler : ICommandPreHandler
{
    public Task PreHandleAsync(ICommand command, CancellationToken cancellationToken)
    {
        _logger.LogInformation("Handling {CommandName}", command.GetType().Name);
        return Task.CompletedTask;
    }
}

// This runs AFTER every command.
public class GlobalLoggingPostHandler : ICommandPostHandler
{
    public Task PostHandleAsync(ICommand command, object? result, CancellationToken cancellationToken)
    {
        _logger.LogInformation("Handled {CommandName}", command.GetType().Name);
        return Task.CompletedTask;
    }
}

Step 6: Convert Exception Handling

MediatR uses IRequestExceptionHandler and IRequestExceptionAction. LiteBus uses a single, powerful IErrorHandler concept that can be scoped globally or to a specific message.

Before (MediatR):

public class MyExceptionHandler : IRequestExceptionHandler<MyRequest, MyResponse, MyException>
{
    public Task Handle(MyRequest request, MyException exception, RequestExceptionHandlerState<MyResponse> state, CancellationToken cancellationToken)
    {
        // Handle the exception, potentially setting a response
        state.SetHandled(new MyResponse());
        return Task.CompletedTask;
    }
}

After (LiteBus):

public class MyErrorHandler : ICommandErrorHandler<MyCommand>
{
    public Task HandleErrorAsync(MyCommand command, object? messageResult, Exception exception, CancellationToken cancellationToken)
    {
        if (exception is MyException myException)
        {
            // Access the execution context to set a result and stop the exception
            AmbientExecutionContext.Current.Abort(new MyCommandResult());
        }
        // If Abort() is not called, the original exception will be re-thrown
        return Task.CompletedTask;
    }
}

Step 7: Update Dispatching Code

Instead of a single IMediator, LiteBus provides specific interfaces.

Before (MediatR):

public class MyController
{
    private readonly IMediator _mediator;
    public async Task MyAction()
    {
        await _mediator.Send(new MyCommand());
        await _mediator.Publish(new MyEvent());
    }
}

After (LiteBus):

public class MyController
{
    private readonly ICommandMediator _commandMediator;
    private readonly IEventPublisher _eventPublisher;
    public async Task MyAction()
    {
        await _commandMediator.SendAsync(new MyCommand());
        await _eventPublisher.PublishAsync(new MyEvent());
    }
}

More Features of LiteBus

MediatR is, by its own definition, a "low-ambition" library. LiteBus is more ambitious and provides built-in solutions for complex, enterprise-level problems. Once migrated, you have access to:

Durable Command Inbox: Guarantee at-least-once execution of critical commands with the [StoreInInbox] attribute. This provides message-queue-like resilience for in-process operations without adding heavy infrastructure.
Advanced Event Concurrency: Configure event handlers to run sequentially or in parallel, both within priority groups and across them. This is essential for performance tuning complex event-driven workflows.
First-Class Streaming: Use IStreamQuery<T> and IAsyncEnumerable<T> to efficiently handle large datasets without high memory usage.
DI-Agnostic Core: Decoupled from any specific DI container, with official support for Microsoft DI and Autofac.
Advanced Handler Filtering: Use tags and dynamic predicates to select which handlers run in a given context, enabling patterns like feature flags or environment-specific logic.

This guide covers the direct mapping of concepts for a smooth migration from MediatR. However, the true benefits of LiteBus are found in the features that go beyond basic mediation. To explore these capabilities in detail, the official Wiki provides in-depth guides on the Durable Command Inbox, advanced event concurrency, handler filtering, and other best practices.

LiteBus: A Free and Ambitious Alternative to MediatR for .NET Applications

A. Shafie — Sat, 19 Apr 2025 19:14:36 +0000

With MediatR recently announcing its transition to a commercial model, many .NET developers are evaluating alternatives for implementing the mediator pattern in their applications. If you're in this position, LiteBus might be worth considering—a lightweight, CQS-focused mediator library I developed five years ago that remains free and open-source.

The Background Story

Back in 2020, I was working as an engineer at a digital news media company, collaborating closely with our CTO on the initial architecture for new projects. We were building a content management system that needed to handle a high volume of media content, from articles to videos and live streams. Though not the technical lead, I was heavily involved in establishing the architectural approach for our growing team, which included both experienced developers and junior engineers.

I was fortunate to have input on our technical stack as we implemented Domain-Driven Design with Command Query Separation patterns. While evaluating mediator libraries to help with this implementation, MediatR was the obvious choice for most teams, but I identified some potential issues for our specific use case:

We wanted interfaces that directly reflected CQS concepts rather than generic requests
Our MongoDB-based architecture could benefit from streaming support for large datasets
With many junior developers joining the team, we needed the architecture to be as explicit as possible

I researched alternatives like Enexure.MicroBus, but found it used too much reflection and wasn't actively maintained. After discussing options with our CTO, I suggested we could build something tailored to our specific requirements. This led me to develop LiteBus — optimized for our performance needs and designed with clear architectural boundaries to help onboard new team members.

Core Architecture and Design Principles

LiteBus was built with several key design principles in mind:

Explicit over implicit: Clear interfaces representing CQS concepts
Performance focus: Minimal reflection usage
Modularity: Separated abstractions and implementations
DDD-friendly: Support for domain events without framework dependencies

One thing I focused on was reducing reflection by leveraging the .NET type system's covariance and contravariance. This means if you have a command hierarchy like BaseCommand and SpecificCommand, handlers can be registered for the base type and still process the specific types. This gives you inheritance-based handling without the performance cost of constantly using reflection.

Package Structure

LiteBus is modular by design, with abstractions and implementations separated into different packages:

LiteBus.Commands.Abstractions
LiteBus.Commands
LiteBus.Commands.Extensions.MicrosoftDependencyInjection

LiteBus.Queries.Abstractions
LiteBus.Queries
LiteBus.Queries.Extensions.MicrosoftDependencyInjection

LiteBus.Events.Abstractions
LiteBus.Events
LiteBus.Events.Extensions.MicrosoftDependencyInjection

With this separation you reference only the abstractions in your domain and application layers, keeping implementation details in your infrastructure layer which aligns well with clean architecture principles if you prioritize that.

The Message Handling Pipeline

LiteBus provides a comprehensive message handling pipeline with support for pre-processing, main handling, post-processing, and error handling. Here's an overview of the key interfaces available for each module:

Command Module

// Main interfaces
ICommand                                          // Base command interface (void result)
ICommand<TCommandResult>                          // Command returning a result

// Main handlers
ICommandHandler<TCommand>                         // For void commands
ICommandHandler<TCommand, TCommandResult>         // For commands returning results

// Pre-handlers
ICommandPreHandler                                // For all commands
ICommandPreHandler<TCommand>                      // For specific command types
ICommandValidator<TCommand>                       // Specialized validator

// Post-handlers
ICommandPostHandler                               // For all commands
ICommandPostHandler<TCommand>                     // For specific commands
ICommandPostHandler<TCommand, TCommandResult>     // For commands with results

// Error handlers
ICommandErrorHandler                              // For all commands
ICommandErrorHandler<TCommand>                    // For specific command types

Query Module

// Main interfaces
IQuery<TQueryResult>                              // Regular query interface
IStreamQuery<TQueryResult>                        // Streaming query interface

// Main handlers
IQueryHandler<TQuery, TQueryResult>               // For regular queries
IStreamQueryHandler<TQuery, TQueryResult>         // For streaming queries

// Pre-handlers
IQueryPreHandler                                  // For all queries
IQueryPreHandler<TQuery>                          // For specific query types

// Post-handlers
IQueryPostHandler                                 // For all queries
IQueryPostHandler<TQuery>                         // For specific queries
IQueryPostHandler<TQuery, TQueryResult>           // For specific queries with results

// Error handlers
IQueryErrorHandler                                // For all queries
IQueryErrorHandler<TQuery>                        // For specific query types

Event Module

// Main interface
IEvent                                            // Base event interface (optional for POCO events)

// Main handlers
IEventHandler<TEvent>                             // For handling specific events

// Pre-handlers
IEventPreHandler                                  // For all events
IEventPreHandler<TEvent>                          // For specific event types

// Post-handlers
IEventPostHandler                                 // For all events
IEventPostHandler<TEvent>                         // For specific event types

// Error handlers
IEventErrorHandler                                // For all events
IEventErrorHandler<TEvent>                        // For specific event types

The pipeline components work together to process messages:

1. Pre-Handlers

Pre-handlers execute before the main handler, useful for cross-cutting concerns such as validation, logging, or security checks:

public class ValidationPreHandler : ICommandPreHandler<CreateArticleCommand>
{
    public Task PreHandleAsync(CreateArticleCommand command, CancellationToken cancellationToken)
    {
        // Validation logic
        if (string.IsNullOrEmpty(command.Title))
            throw new ValidationException("Title is required");

        return Task.CompletedTask;
    }
}

These pre-handlers can work with inheritance too. A pre-handler for a base command can automatically handle derived commands, so you don't need to duplicate validation logic across similar command types.

2. Main Handlers

Main handlers contain the core business logic for processing commands and queries:

public class CreateArticleCommandHandler : ICommandHandler<CreateArticleCommand, ArticleDto>
{
    private readonly IArticleRepository _repository;

    public async Task<ArticleDto> HandleAsync(CreateArticleCommand command, CancellationToken cancellationToken)
    {
        var article = new Article
        {
            Id = Guid.NewGuid(),
            Title = command.Title,
            Content = command.Content
        };

        await _repository.SaveAsync(article, cancellationToken);

        return new ArticleDto
        {
            Id = article.Id,
            Title = article.Title
        };
    }
}

In query handlers, the same inheritance principles apply. A handler can return a more specific type than what the interface requires, giving you flexibility without extra code.

3. Post-Handlers

Post-handlers run after the main handler, useful for operations like caching, notifications, or logging:

public class NotificationPostHandler : ICommandPostHandler<CreateArticleCommand, ArticleDto>
{
    private readonly IEventPublisher _eventPublisher;

    public async Task PostHandleAsync(
        CreateArticleCommand command, 
        ArticleDto result,
        CancellationToken cancellationToken)
    {
        await _eventPublisher.PublishAsync(new ArticleCreatedEvent
        {
            ArticleId = result.Id,
            Title = result.Title
        }, cancellationToken);
    }
}

Post-handlers follow the same pattern - a post-handler for a base command works with all derived commands.

4. Error Handlers

Error handlers provide centralized exception handling:

public class LoggingErrorHandler : ICommandErrorHandler<CreateArticleCommand>
{
    private readonly ILogger<LoggingErrorHandler> _logger;

    public Task HandleErrorAsync(
        CreateArticleCommand command, 
        object? result,
        Exception exception, 
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "Error creating article: {Title}", command.Title);
        return Task.CompletedTask;
    }
}

DDD-Friendly Event Handling

A particularly useful feature of LiteBus is its support for domain events without requiring domain objects to implement framework interfaces. This aligns with DDD principles, where the domain model should be independent of infrastructure concerns.

You can publish plain objects as events:

// Domain event with no dependencies on LiteBus
public class ArticlePublished
{
    public Guid ArticleId { get; }
    public string Title { get; }
    public DateTime PublishedAt { get; }

    public ArticlePublished(Guid articleId, string title)
    {
        ArticleId = articleId;
        Title = title;
        PublishedAt = DateTime.UtcNow;
    }
}

// In your application service
public async Task PublishArticle(Guid articleId)
{
    var article = await _repository.GetByIdAsync(articleId);
    article.MarkAsPublished();

    await _repository.SaveAsync(article);

    // Publish domain event without requiring it to implement IEvent
    await _eventPublisher.PublishAsync(new ArticlePublished(article.Id, article.Title));
}

Handlers for these events are still type-safe:

public class NotifySubscribersHandler : IEventHandler<ArticlePublished>
{
    public async Task HandleAsync(ArticlePublished @event, CancellationToken cancellationToken)
    {
        // Send notification to subscribers
    }
}

Specialized Features

Beyond the core functionality, LiteBus offers several specialized features that emerged from real-world requirements.

Streaming Support

LiteBus provides first-class support for streaming data through IStreamQuery<T> and IAsyncEnumerable<T>:

public class StreamRecentArticlesQuery : IStreamQuery<ArticleDto>
{
    public int BatchSize { get; init; } = 100;
}

public class StreamRecentArticlesQueryHandler 
    : IStreamQueryHandler<StreamRecentArticlesQuery, ArticleDto>
{
    private readonly IArticleRepository _repository;

    public async IAsyncEnumerable<ArticleDto> StreamAsync(
        StreamRecentArticlesQuery query,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var article in _repository.GetRecentArticlesAsync(
            query.BatchSize, cancellationToken))
        {
            yield return new ArticleDto
            {
                Id = article.Id,
                Title = article.Title
            };
        }
    }
}

This streaming capability was crucial for our media platform, allowing us to efficiently process large sets of articles, videos, and other content without consuming excessive memory.

Contextual Command Handling

LiteBus supports tag-based filtering for handlers to enable different processing based on the execution context:

[HandlerTag("Frontend")]
public class FrontendValidator : ICommandPreHandler<PublishArticleCommand>
{
    // Validation logic specific to frontend requests
}

[HandlerTag("InternalService")]
public class InternalValidator : ICommandPreHandler<PublishArticleCommand>
{
    // Validation logic specific to internal service requests
}

This feature emerged from our need to handle commands differently based on their source. Our system had to process commands coming both from user-facing frontend applications and internal backend services. The validation requirements, security considerations, and other aspects varied significantly depending on the source.

With tag-based handlers, we could implement appropriate validation and processing for each context:

// From frontend
await _commandMediator.SendAsync(command, "Frontend");

// From internal service
await _commandMediator.SendAsync(command, "InternalService");

Generic Commands

Generic commands provide flexibility for cross-cutting concerns like logging:

public class LogActivityCommand<TPayload> : ICommand
{
    public required string UserId { get; init; }
    public required string Action { get; init; }
    public required TPayload Payload { get; init; }
}

public class LogActivityCommandHandler<TPayload> 
    : ICommandHandler<LogActivityCommand<TPayload>>
{
    public Task HandleAsync(LogActivityCommand<TPayload> command, 
        CancellationToken cancellationToken)
    {
        // Generic logging logic that works with any payload type
        return Task.CompletedTask;
    }
}

We used this pattern extensively for our activity logging system, allowing us to maintain a consistent logging structure while accommodating diverse payload types for different user actions.

Integration with ASP.NET Core

Integrating LiteBus into an ASP.NET Core application is straightforward:

services.AddLiteBus(liteBus =>
{
    liteBus.AddCommandModule(module =>
    {
        module.RegisterFromAssembly(typeof(Program).Assembly);
    });

    liteBus.AddQueryModule(module =>
    {
        module.RegisterFromAssembly(typeof(Program).Assembly);
    });

    liteBus.AddEventModule(module =>
    {
        module.RegisterFromAssembly(typeof(Program).Assembly);
    });
});

Feature Comparison with MediatR

For a factual comparison, here's how LiteBus measures up against MediatR:

Feature	MediatR	LiteBus
Base Abstraction	`IRequest<TResponse>`	`ICommand`, `IQuery<T>`, `IEvent`
Streaming Support	Added in later versions	First-class with `IStreamQuery<T>`
Pipeline	Behaviors	Pre-handlers, post-handlers, error handlers
Contextual Processing	Limited	Tag-based handler filtering
Reflection Usage	Standard	Minimized with type system features
POCO Event Support	Limited	Full support without requiring interfaces
Package Structure	Consolidated	Separated abstractions and implementations
Current Licensing	Going Commercial	Free and open-source

LiteBus has many more features not covered in this overview. For the complete picture, check out the GitHub repository and Wiki documentation, which include detailed examples, best practices, and guides for advanced scenarios.

Implement Chain of Responsibility/Commands in C# Using ChainRunner

A. Shafie — Wed, 16 Jun 2021 20:24:33 +0000

I have been working on an ASP.NET Core Web API application which is responsible for users' comments. The application receives new comments and based on multiple business criteria decides to whether reject or censor them. In nutshell, each new comment must go through the following steps:

Censor curse words
Modify incorrect words
Reject if it has improper tone

The steps are not that complex and must be executed sequentially. To implement these steps, I decided to go for chain of responsibility pattern. However, I could not find a simple and proper library to implement this pattern so I created a library called ChainRunner to make all this work.

The picture depicts how ChainRunner works

Implementation

Below you can seee how I used ChainRunner to implement the steps. For each step I created a responsibility handler:

public class CensorCurseWordsHandler : IResponsibilityHandler<Comment>
{
    public Task HandleAsync(Comment request, CancellationToken cancellationToken = default)
    {
        // process comment ...
    }
}

public class ModifyIncorrectWordsHandler : IResponsibilityHandler<Comment>
{
    public Task HandleAsync(Comment request, CancellationToken cancellationToken = default)
    {
        // process comment ...
    }
}

public class ImproperToneHandler : IResponsibilityHandler<Comment>
{
    public Task HandleAsync(Comment request, CancellationToken cancellationToken = default)
    {
        // process comment ...
    }
}

Then, I configured the chain in Startup.cs (ASP.NET Core):

services.AddChain<Comment>()
        .WithHandler<CensorCurseWordsHandler>()
        .WithHandler<ModifyIncorrectWordsHandler>()
        .WithHandler<ImproperToneHandler>();

Finally, I injected the chain into my class and ran the chain like so:


[ApiController]
[Route("[controller]")]
public class CommentController
{
    private readonly IChain<Comment> _chain;

    public CommentController(IChain<Comment> chain)
    {
        _chain = chain;
    }

    [HttpPost]
    public async Task<IActionResult> Post(Comment comment)
    {
        await _chain.RunAsync(comment);

        return Ok();
    }
}

DEV Community: A. Shafie

Migrating from MediatR to LiteBus

Core Philosophy: From Generic to Semantic

Step 1: Update Project Dependencies

Step 2: Update Dependency Injection (Program.cs)

Step 3: Convert Message Contracts

Requests (Commands and Queries)

Notifications (Events)

Step 4: Convert Handlers

Step 5: Convert Pipeline Behaviors and Processors

Step 6: Convert Exception Handling

Step 7: Update Dispatching Code

More Features of LiteBus

LiteBus: A Free and Ambitious Alternative to MediatR for .NET Applications

The Background Story

Core Architecture and Design Principles

Package Structure

The Message Handling Pipeline

Command Module

Query Module

Event Module

1. Pre-Handlers

2. Main Handlers

3. Post-Handlers

4. Error Handlers

DDD-Friendly Event Handling

Specialized Features

Streaming Support

Contextual Command Handling

Generic Commands

Integration with ASP.NET Core

Feature Comparison with MediatR

Implement Chain of Responsibility/Commands in C# Using ChainRunner

Implementation

Links

Step 2: Update Dependency Injection (`Program.cs`)