Concordia: The Open-Source .NET Mediator You’ve Been Waiting For

lucafabbri — Thu, 31 Jul 2025 21:57:21 +0000

A Lightweight, Performant, and Compile-Time Optimized Alternative to MediatR

In the world of .NET application development, the Mediator pattern has become an indispensable tool for achieving clean architecture, separation of concerns, and maintainable codebases. Libraries like MediatR have long been the go-to choice for implementing this pattern, facilitating Command Query Responsibility Segregation (CQRS) and Publish/Subscribe mechanisms.

However, with recent shifts towards commercial licensing for some popular open-source projects, the community has begun seeking robust, freely accessible alternatives. This is where Concordia steps in.

Concordia is a new .NET library designed from the ground up to be a lightweight, performant, and easily integrated solution for the Mediator pattern. Its key differentiator? The strategic leverage of C# Source Generators for automatic handler registration at compile-time, a feature that brings significant advantages over traditional reflection-based approaches.

Why Concordia? Embracing the Open-Source Ethos

Concordia was born out of a commitment to the open-source community. We believe that fundamental architectural patterns, crucial for building scalable and maintainable applications, should remain freely accessible to all developers. Concordia offers a powerful alternative for those looking for a modern, efficient Mediator implementation without licensing constraints.

Key Advantages:

An Open-Source Alternative: Built with community collaboration in mind.
Lightweight and Minimal: Focuses on core Mediator functionalities, avoiding unnecessary overhead.
Optimized Performance: Achieves faster application startup and zero runtime reflection thanks to Source Generators.
Easy DI Integration: Seamlessly integrates with Microsoft.Extensions.DependencyInjection.
Same MediatR Interfaces: Designed with identical interface signatures to MediatR, making migration incredibly straightforward.
CQRS and Pub/Sub Patterns: Naturally supports these patterns for enhanced code organization.

The Power of Source Generators: Performance Meets Compile-Time Safety

The most compelling feature of Concordia is its innovative use of C# Source Generators for handler discovery and registration. But what exactly are Source Generators, and why are they a game-changer for a Mediator library?

What are C# Source Generators?
Source Generators are a feature introduced in .NET 5 that allow C# developers to inspect user code and generate new C# source files that are added to the compilation. This happens during compilation, meaning the generated code is treated exactly like hand-written code by the compiler.

How Concordia Leverages Them:
Traditionally, Mediator libraries use runtime reflection to scan assemblies and discover handlers. While effective, reflection can impact application startup time, especially in larger applications with many handlers.

Concordia’s Source Generator eliminates this runtime overhead. During compilation, the generator:

Scans your project: It identifies all classes implementing Concordia’s IRequestHandler, INotificationHandler, IPipelineBehavior, IRequestPreProcessor, and IRequestPostProcessor interfaces.
Generates registration code: It writes a new C# file containing explicit services.AddTransient<Interface, Implementation>() calls for every discovered handler.
Compiles the generated code: This new file is then compiled directly into your application’s assembly.

The Benefits are Clear:

Blazing Fast Startup: No runtime scanning means your application starts up significantly faster.
Zero Reflection Overhead: Eliminates performance penalties associated with reflection.
Compile-Time Validation: If you accidentally delete or rename a handler, the compilation will fail, immediately notifying you of the issue. This provides a level of safety that runtime reflection cannot.
Smaller Deployment Footprint: No need to ship reflection-related metadata or code that performs runtime scanning.

Familiarity and Ease of Migration: MediatR-like Interfaces

For developers familiar with MediatR, migrating to Concordia is designed to be a breeze. Concordia uses interfaces with identical signatures to MediatR, meaning your existing requests, commands, notifications, and handlers will likely require only namespace changes.

This “drop-in” compatibility significantly reduces the friction of switching, allowing you to leverage Concordia’s performance benefits with minimal code refactoring.

Key Features of Concordia

Concordia provides all the essential functionalities you expect from a robust Mediator library:

Requests with Responses (IRequest<TResponse>, IRequestHandler<TRequest, TResponse>): For queries and commands that return a specific result.
Fire-and-Forget Requests (IRequest, IRequestHandler<TRequest>): For commands that execute an action without returning a value.
Notifications (INotification, INotificationHandler<TNotification>): For publishing events to multiple subscribers (handlers).
IMediator: The central interface for sending requests and publishing notifications.
ISender: A focused interface for sending requests, useful when you only need dispatching capabilities.
Pipeline Behaviors (IPipelineBehavior<TRequest, TResponse>): Intercept requests before and after their handlers, perfect for cross-cutting concerns like logging, validation, or error handling.
Request Pre-Processors (IRequestPreProcessor<TRequest>): Execute logic before a request handler.
Request Post-Processors (IRequestPostProcessor<TRequest, TResponse>): Execute logic after a request handler has produced a response.
Custom Notification Publishers (INotificationPublisher): Define how notifications are dispatched (e.g., sequentially, in parallel). Concordia provides a default ForeachAwaitPublisher.

Getting Started with Concordia: A Practical Guide

Let’s walk through a simple example of how to integrate Concordia into your ASP.NET Core application.

1. Installation

You’ll need Concordia.Core and either Concordia.Generator (recommended) or Concordia.MediatR.

Option A: Using the Source Generator (Recommended)

dotnet add package Concordia.Core --version 1.0.0
dotnet add package Concordia.Generator --version 1.0.0

Option B: Using the MediatR Compatibility Layer

dotnet add package Concordia.Core --version 1.0.0
dotnet add package Concordia.MediatR --version 1.0.0

2. Define Your Contracts (Requests, Notifications)

Your messages will implement interfaces from Concordia.Contracts.

// Request with response (e.g., a Query)
using Concordia.Contracts;

namespace MyProject.Requests
{
    public class GetProductByIdQuery : IRequest<ProductDto>
    {
        public int ProductId { get; set; }
    }
    public class ProductDto
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public decimal Price { get; set; }
    }
}

// Fire-and-forget command
using Concordia.Contracts;

namespace MyProject.Commands
{
    public class CreateProductCommand : IRequest
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
    }
}

// Notification (event)
using Concordia.Contracts;

namespace MyProject.Notifications
{
    public class ProductCreatedNotification : INotification
    {
        public int ProductId { get; set; }
        public string ProductName { get; set; }
    }
}

3. Implement Your Handlers

Create handlers for your requests and notifications.

// Handler for GetProductByIdQuery
using Concordia.Contracts;
using MyProject.Requests;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Handlers
{
    public class GetProductByIdQueryHandler : IRequestHandler<GetProductByIdQuery, ProductDto>
    {
        public Task<ProductDto> Handle(GetProductByIdQuery request, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Handling GetProductByIdQuery for ProductId: {request.ProductId}");
            var product = new ProductDto { Id = request.ProductId, Name = $"Product {request.ProductId}", Price = 10.50m };
            return Task.FromResult(product);
        }
    }
}

// Handler for CreateProductCommand
using Concordia.Contracts;
using MyProject.Commands;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Handlers
{
    public class CreateProductCommandHandler : IRequestHandler<CreateProductCommand>
    {
        public Task Handle(CreateProductCommand request, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Creating product: {request.ProductName} with ID: {request.ProductId}");
            return Task.CompletedTask;
        }
    }
}

// Multiple handlers for ProductCreatedNotification
using Concordia.Contracts;
using MyProject.Notifications;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Handlers
{
    public class SendEmailOnProductCreated : INotificationHandler<ProductCreatedNotification>
    {
        public Task Handle(ProductCreatedNotification notification, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Sending email for new product: {notification.ProductName} (Id: {notification.ProductId})");
            return Task.CompletedTask;
        }
    }

    public class LogProductCreation : INotificationHandler<ProductCreatedNotification>
    {
        public Task Handle(ProductCreatedNotification notification, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Logging product creation: {notification.ProductName} (Id: {notification.ProductId}) created at {DateTime.Now}");
            return Task.CompletedTask;
        }
    }
}

4. Register Services in `Program.cs`

This is where you choose your registration strategy.

Option A: Using the Source Generator (Recommended)

First, ensure your application’s .csproj correctly references Concordia.Generator as an analyzer. You can also customize the generated method name:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <!-- Optional: Customize the generated extension method name -->
    <ConcordiaGeneratedMethodName>AddMyConcordiaHandlers</ConcordiaGeneratedMethodName>
    <!-- Optional: Customize the namespace for the generated class (defaults to project's RootNamespace) -->
    <!-- <ConcordiaGeneratedNamespace>MyProject.Generated</ConcordiaGeneratedNamespace> -->
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="PathToYour\Concordia.Core\Concordia.Core.csproj" />
    <ProjectReference Include="PathToYour\Concordia.Generator\Concordia.Generator.csproj"
                      OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>

  <!-- Ensure your Request, Handler, Processor, and Behavior files are included in the project -->
  <ItemGroup>
    <Compile Include="Requests\GetProductByIdQuery.cs" />
    <Compile Include="Commands\CreateProductCommand.cs" />
    <Compile Include="Notifications\ProductCreatedNotification.cs" />
    <Compile Include="Handlers\GetProductByIdQueryHandler.cs" />
    <Compile Include="Handlers\CreateProductCommandHandler.cs" />
    <Compile Include="Handlers\SendEmailOnProductCreated.cs" />
    <Compile Include="Handlers\LogProductCreation.cs" />
    <!-- ... other handlers, processors, behaviors ... -->
  </ItemGroup>
</Project>

Then, in your Program.cs:

using Concordia; // For IMediator, ISender
using Concordia.DependencyInjection; // For AddConcordiaCoreServices
using MyProject.Web; // Example: Namespace where ConcordiaGeneratedRegistrations is generated

var builder = WebApplication.CreateBuilder(args);

// 1. Register Concordia's core services.
builder.Services.AddConcordiaCoreServices();

// 2. Register your specific handlers and pipeline behaviors discovered by the generator.
// The method name will depend on your .csproj configuration (e.g., AddMyConcordiaHandlers).
builder.Services.AddMyConcordiaHandlers(); // Use the name configured in .csproj

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

Option B: Using the MediatR Compatibility Layer

If you prefer runtime reflection or are migrating from MediatR, use Concordia.MediatR.

using Concordia; // For IMediator, ISender
using Concordia.MediatR; // NEW: Namespace for the AddMediator extension method
using System.Reflection; // Required for Assembly.GetExecutingAssembly()
using Microsoft.Extensions.DependencyInjection; // Required for ServiceLifetime

var builder = WebApplication.CreateBuilder(args);

// Register Concordia and all handlers using the reflection-based AddMediator method.
builder.Services.AddMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
    // Optional: Configure the default service lifetime for scanned services (default is Transient)
    cfg.Lifetime = ServiceLifetime.Scoped;
    // Optional: Register a custom notification publisher type
    // cfg.NotificationPublisherType = typeof(MyCustomNotificationPublisher);
    // Optional: Explicitly add an open generic pipeline behavior
    // cfg.AddOpenBehavior(typeof(MyLoggingBehavior<,>));
});

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

5. Use the Mediator

Inject IMediator or ISender into your controllers or services.

using Microsoft.AspNetCore.Mvc;
using Concordia; // For IMediator, ISender
using MyProject.Requests;
using MyProject.Commands;
using MyProject.Notifications;
using System.Threading.Tasks;

namespace MyProject.Web.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class ProductsController : ControllerBase
    {
        private readonly IMediator _mediator;
        private readonly ISender _sender;

        public ProductsController(IMediator mediator, ISender sender)
        {
            _mediator = mediator;
            _sender = sender;
        }

        [HttpGet("{id}")]
        public async Task<IActionResult> Get(int id)
        {
            var query = new GetProductByIdQuery { ProductId = id };
            var product = await _sender.Send(query);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }

        [HttpPost]
        public async Task<IActionResult> CreateProduct([FromBody] CreateProductCommand command)
        {
            await _sender.Send(command);
            var notification = new ProductCreatedNotification
            {
                ProductId = command.ProductId,
                ProductName = command.ProductName
            };
            await _mediator.Publish(notification);
            return CreatedAtAction(nameof(Get), new { id = command.ProductId }, null);
        }
    }
}

Diving Deeper: Pipeline Behaviors, Pre- and Post-Processors

Concordia supports a rich pipeline for requests, allowing you to inject cross-cutting concerns.

Pipeline Behaviors (`IPipelineBehavior`)

These wrap the entire request handling process.

using Concordia.Contracts;
using System;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Behaviors
{
    public class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
        where TRequest : IRequest<TResponse>
    {
        public async Task<TResponse> Handle(TRequest request, RequestHandlerDelegate<TResponse> next, CancellationToken cancellationToken)
        {
            Console.WriteLine($"--- Before Handling Request: {typeof(TRequest).Name} ---");
            var response = await next(); // Calls the next behavior in the pipeline or the final handler
            Console.WriteLine($"--- After Handling Request: {typeof(TRequest).Name} - Response Type: {typeof(TResponse).Name} ---");
            return response;
        }
    }
}

Request Pre-Processors (`IRequestPreProcessor`)

Execute logic before the handler.

using Concordia.Contracts;
using MyProject.Requests;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Processors
{
    public class MyRequestLoggerPreProcessor : IRequestPreProcessor<GetProductByIdQuery>
    {
        public Task Process(GetProductByIdQuery request, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Pre-processing GetProductByIdQuery for ProductId: {request.ProductId}");
            return Task.CompletedTask;
        }
    }
}

Request Post-Processors (`IRequestPostProcessor`)

Execute logic after the handler has produced a response.

using Concordia.Contracts;
using MyProject.Requests;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject.Processors
{
    public class MyResponseLoggerPostProcessor : IRequestPostProcessor<GetProductByIdQuery, ProductDto>
    {
        public Task Process(GetProductByIdQuery request, ProductDto response, CancellationToken cancellationToken)
        {
            Console.WriteLine($"Post-processing GetProductByIdQuery. Response: {response.Name}");
            return Task.CompletedTask;
        }
    }
}

Migration Guide from MediatR

Migrating from MediatR to Concordia is designed to be straightforward due to the identical interfaces.

1. Update NuGet Packages

Remove MediatR and install Concordia packages:

dotnet remove package MediatR
dotnet remove package MediatR.Extensions.Microsoft.DependencyInjection # If present
dotnet add package Concordia.Core --version 1.0.0
dotnet add package Concordia.MediatR --version 1.0.0 # Or Concordia.Generator

2. Update Namespaces

Change MediatR namespaces to Concordia and Concordia.Contracts where applicable.

MediatR.IRequest<TResponse> becomes Concordia.Contracts.IRequest<TResponse>
MediatR.IMediator becomes Concordia.IMediator
…and so on for all interfaces and main types.

3. Update Service Registration in `Program.cs`

Replace AddMediatR with Concordia's AddMediator (if using reflection) or the generated method (if using Source Generators).

Before (MediatR):

using MediatR;
using MediatR.Extensions.Microsoft.DependencyInjection;
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMediatR(cfg =>
{
    cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
    // Other MediatR configs
});

After (Concordia.MediatR — Reflection):

using Concordia.MediatR;
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddMediator(cfg =>
{
    cfg.RegisterServicesFromAssembly(Assembly.GetExecutingAssembly());
    // Similar configuration options
});

After (Concordia.Generator — Compile-Time):

using Concordia.DependencyInjection; // For AddConcordiaCoreServices
using MyProject.Web; // Namespace of your generated method

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddConcordiaCoreServices();
builder.Services.AddMyConcordiaHandlers(); // Your custom generated method name

4. Verify and Test

Rebuild and run your tests. Due to interface parity, minimal code changes beyond namespaces and DI registration should be required.

Conclusion

Concordia offers a compelling open-source alternative for the Mediator pattern in .NET. By embracing C# Source Generators, it provides superior performance and compile-time safety, without sacrificing the familiarity and ease of use that developers expect. Whether you’re starting a new project or looking to migrate from existing solutions, Concordia is designed to streamline your development process and enhance your application’s architecture.

We invite you to explore Concordia, contribute to its growth, and discover how it can empower your .NET projects.

Get the Source Code:
Find the complete source code and contribute to Concordia on GitHub:
https://github.com/lucafabbri/Concordia

DEV Community: lucafabbri