MediateX 3.0.0

MediateX

The Modern Mediator Pattern for .NET 10+

MediateX is a bold reimagining of the mediator pattern, crafted exclusively for the modern .NET ecosystem. Born from the solid foundation of MediatR, MediateX takes a deliberate step forward, shedding the weight of backward compatibility to fully embrace the power and performance of .NET 10 and beyond.

Version 3.x marks a pivotal moment: upgraded to .NET 10, enhanced DI container compatibility, improved assembly scanning robustness, and critical bug fixes for notification handlers and nested generic behaviors.

Our philosophy is simple: always leverage the best of what the .NET platform offers. MediateX is built with the latest C# 14 features and targets .NET 10. This is not just another library; it's a commitment to staying on the cutting edge.

💖 Support the Project

MediateX is a passion project, driven by the desire to provide a truly modern tool for the .NET community. Maintaining this library requires significant effort: staying current with each .NET release, addressing issues promptly, implementing new features, keeping documentation up to date, and ensuring compatibility across different DI containers.

If MediateX has helped you build better applications or saved you development time, I would be incredibly grateful for your support. Your contribution—no matter the size—helps me dedicate time to respond to issues quickly, implement improvements, and keep the library evolving alongside the .NET platform.

I'm also looking for sponsors who believe in this project's mission. Sponsorship helps ensure MediateX remains actively maintained and continues to serve the .NET community for years to come.

Of course, there's absolutely no obligation. If you prefer, simply starring the repository or sharing MediateX with fellow developers is equally appreciated!

• ⭐ Star the repository on GitHub to raise its visibility

• 💬 Share MediateX with your team or community

• ☕ Support via Donations:

  • 
  • 

🎉 What's New in 3.0.0

Major .NET 10 Upgrade! MediateX 3.0.0 brings significant improvements:

• ⬆️ Target Framework: Upgraded from .NET 9 to .NET 10 with C# 14
• 🔧 DI Container Compatibility: Simplified mediator constructor works with all DI containers
• 🛡️ Assembly Scanning Robustness: Safe handling of assemblies with unloadable types (F# inref/outref, missing dependencies)
• 🐛 Notification Handler Fix: Fixed contravariance-based incorrect handler registration that caused duplicate invocations
• 🐛 Nested Generic Behaviors: Fixed AddOpenBehavior() for behaviors like IPipelineBehavior<TRequest, Result<T>>
• 📁 Project Structure: Reorganized to src/MediateX/ following .NET ecosystem conventions

See the full changelog for details.

🚀 Getting Started

Integrating MediateX into your .NET 10+ application is straightforward.

1. Install the NuGet Package:

dotnet add package MediateX

2. Register Services: In your Program.cs or service configuration, register MediateX and tell it which assembly to scan for handlers.

builder.Services.AddMediateX(cfg =>
{
    // Scans the assembly containing your handlers (e.g., Program)
    cfg.RegisterServicesFromAssemblyContaining<Program>();
});

3. Create and Send a Request: Define a request and its handler, then use the IMediator service to send it.

// Define a request and its expected response
public record GetProductQuery(int Id) : IRequest<Product>;

// Create a handler for the request
public class GetProductHandler : IRequestHandler<GetProductQuery, Product>
{
    public Task<Product> Handle(GetProductQuery request, CancellationToken cancellationToken)
    {
        // Your business logic here...
        var product = new Product { Id = request.Id, Name = "Awesome Gadget" };
        return Task.FromResult(product);
    }
}

// Inject IMediator and send the request from a controller or another service
var product = await mediator.Send(new GetProductQuery(42));

✨ Features

Core Capabilities

• Request/Response - Commands and queries with single handler (IRequest<TResponse>)
• Notifications & Events - Publish to multiple handlers (INotification)
• Streaming - Async stream responses with IAsyncEnumerable<T> (IStreamRequest<TResponse>)
• Separated Interfaces - Use ISender, IPublisher, or IMediator based on your needs

Pipeline Features

• Behaviors - Add cross-cutting concerns (logging, validation, caching, etc.)
• Pre/Post Processors - Execute logic before and after handlers
• Exception Handling - Sophisticated error handling with fallback responses
• Stream Behaviors - Wrap and transform async streams

Advanced Features

• Publishing Strategies - Sequential or parallel notification execution
• Generic Variance - Leverage C# covariance/contravariance
• Dynamic Dispatch - Runtime type resolution for flexibility
• Handler Prioritization - Automatic ordering based on assembly/namespace
• Open Generic Support - Register generic handlers with constraints

📅 Versioning & .NET Support Policy

MediateX follows a clear versioning strategy aligned with .NET's release cadence:

Version History

Future Support Policy

MediateX will always support the current LTS version plus the next standard release. When a new LTS version is released, support for older versions will be discontinued:

Why this policy?

• Focused development: By limiting supported versions, we can dedicate more effort to quality, performance, and new features
• Modern features: Each .NET version brings improvements that MediateX can fully leverage
• Clear upgrade path: Users know exactly when to plan their upgrades

Note: We recommend always using the latest LTS version of .NET for production applications.

📚 Documentation

Comprehensive guides to help you master MediateX:

Getting Started

• Getting Started - Installation, basic setup, and first request
• Requests & Handlers - Deep dive into requests, handlers, and best practices

Core Features

• Notifications & Events - Pub/sub pattern, publishing strategies, event handling
• Pipeline Behaviors - Cross-cutting concerns, behavior chaining, examples
• Configuration - Complete configuration reference and options

Advanced Topics

• Exception Handling - Exception handlers, actions, and strategies
• Streaming - Working with IAsyncEnumerable<T> and stream behaviors

Examples

Check out the samples folder for complete working examples with different DI containers and scenarios.

🙏 Acknowledgments

MediateX would not exist without the pioneering work of Jimmy Bogard and the many contributors to the original MediatR project. Their efforts created a robust and battle-tested foundation that has benefited countless .NET developers.

This library began as a fork of MediatR version 12.5.0. We are immensely grateful for their contribution to the .NET ecosystem, which provided the starting point for this new, forward-focused direction. While MediatR continues to serve a broad range of .NET versions, MediateX is our dedicated effort to serve developers who are ready to build exclusively on the future of the platform.

Original Project: MediatR on GitHub