MediatorLite.Abstractions 1.0.13

MediatorLite

A lightweight, high-performance mediator library for .NET 10+. Built from the ground up with source generators for zero-reflection dispatch and minimal allocations.

Documentation: behl1anmol.github.io/MediatorLite

Features

• High Performance - Source generators eliminate runtime reflection for handler dispatch
• Zero-Reflection Dispatch - Compile-time handler discovery and typed dispatch via source generation
• Lightweight - Minimal dependencies, focused core
• Extensible - Pipeline behaviors for cross-cutting concerns
• Request/Response - Type-safe command and query handling with ValueTask
• Notifications - Pub-sub pattern with sequential, parallel, and stop-on-first strategies
• Observable - Built-in logging and OpenTelemetry tracing support
• DI Native - First-class Microsoft.Extensions.DependencyInjection integration

Installation

dotnet add package MediatorLite

Optional (contracts-only scenarios such as shared request assemblies):

dotnet add package MediatorLite.Abstractions

Package and Versioning Guide

Which package should I install?

Will Abstractions be installed automatically?

• If you install MediatorLite, yes. MediatorLite.Abstractions is pulled transitively.
• If you install only MediatorLite.SourceGeneration, no. Source generation package does not pull runtime contracts by itself.
• If you install both MediatorLite and MediatorLite.SourceGeneration, yes (via MediatorLite).

Compatibility Matrix

Use this matrix as the default rule for safe upgrades.

Versioning Policy

• MediatorLite.Abstractions follows strict SemVer:
  • Patch: docs/internal fixes, no API break
  • Minor: additive API only, backward compatible
  • Major: breaking contract changes
• MediatorLite declares a dependency on MediatorLite.Abstractions.
• For predictable restores, keep all three packages on the same major and minor version.
• For pre-release builds, use matching pre-release versions across packages (for example, all 1.2.0-preview.3).

Upgrade Checklist

1. Upgrade MediatorLite first.
2. Upgrade MediatorLite.SourceGeneration to the same major/minor.
3. If you directly reference MediatorLite.Abstractions, align it to the same major/minor.
4. Run dotnet restore and dotnet build to force source regeneration and verify compatibility.

Quick Start

1. Define a Request and Handler

public record GetUserQuery(int Id) : IRequest<User>;

public class GetUserQueryHandler : IRequestHandler<GetUserQuery, User>
{
    public ValueTask<User> HandleAsync(GetUserQuery request, CancellationToken cancellationToken = default)
    {
        return ValueTask.FromResult(new User(request.Id, "John Doe"));
    }
}

2. Register Services

The source generator automatically discovers all handlers at compile time. Use AddGeneratedHandlers() to register them with the DI container:

using MediatorLite.Generated;

services
    .AddGeneratedHandlers()   // Source-generated: registers all handlers, notifications, behaviors
    .AddMediatorLite();       // Registers the mediator and options

AddGeneratedHandlers() registers:

• All IRequestHandler<,> implementations
• All INotificationHandler<> implementations
• All IPipelineBehavior<,> implementations
• The ISourceGeneratedMediator for zero-reflection dispatch

To configure options:

services
    .AddGeneratedHandlers()
    .AddMediatorLite(options =>
    {
        options.EnableBuiltInLogging = true;
        options.EnableTracing = true;
        options.NotificationExecutionStrategy = NotificationExecutionStrategy.Parallel;
    });

Granular Registration

If you only need to register specific handler categories:

services
    .AddGeneratedRequestHandlers()        // Only request handlers
    .AddGeneratedNotificationHandlers()   // Only notification handlers
    .AddGeneratedBehaviors()              // Only pipeline behaviors
    .AddMediatorLite();

Manual DI Registration (Without Source Generation)

You can register handlers manually with standard DI if preferred:

services.AddTransient<IRequestHandler<GetUserQuery, User>, GetUserQueryHandler>();
services.AddTransient<INotificationHandler<UserCreatedNotification>, SendWelcomeEmailHandler>();
services.AddTransient(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
services.AddMediatorLite();

Excluding Types from Source Generation

Use [MediatorGeneration(Skip = true)] to exclude specific handlers from source-generated discovery:

[MediatorGeneration(Skip = true)]
public class TestOnlyHandler : IRequestHandler<TestQuery, string>
{
    // This handler will NOT be registered by AddGeneratedHandlers()
}

3. Send Requests

public class MyService(IMediator mediator)
{
    public async Task<User> GetUserAsync(int id, CancellationToken ct)
    {
        return await mediator.SendAsync(new GetUserQuery(id), ct);
    }
}

4. Publish Notifications

public record UserCreatedNotification(int UserId, string Email) : INotification;

// Multiple handlers can subscribe
public class SendWelcomeEmailHandler : INotificationHandler<UserCreatedNotification>
{
    public async ValueTask HandleAsync(UserCreatedNotification notification, CancellationToken ct = default)
    {
        await _emailService.SendWelcomeAsync(notification.Email);
    }
}

// Publish
await mediator.PublishAsync(new UserCreatedNotification(user.Id, user.Email));

Documentation

Full documentation is available at behl1anmol.github.io/MediatorLite.

• Quick Start Guide
• Pipeline Behaviors
• Validation
• Notifications
• Migration from MediatR

Notification Execution Strategies

MediatorLite provides flexible notification execution with three strategies:

*Parallel mode always aggregates exceptions because concurrent tasks cannot be cancelled mid-execution.

services.AddMediatorLite(options =>
{
    options.NotificationExecutionStrategy = NotificationExecutionStrategy.Parallel;
    options.NotificationErrorStrategy = NotificationErrorStrategy.ContinueAndAggregate;
});

See Notifications documentation for detailed strategy behavior and error handling patterns.

Why MediatorLite?

License

This project is licensed under the MIT License - see the LICENSE file for details.