Coordix 0.2.0

Coordix

A lightweight and straightforward mediator implementation for .NET applications with minimal setup.

Key Features

• Built for maximum compatibility - Built with .NET Standard 2.1 for maximum compatibility across .NET platforms
• Zero external dependencies - Completely standalone with no third-party dependencies (except Microsoft.Extensions.DependencyInjection)
• High-performance design - Optimized for performance with cached delegates and minimal reflection overhead
• DDD-friendly design - Support for plain domain events without library dependencies, keeping your domain model clean
• Dependency Injection Native - Built from scratch to work seamlessly with Microsoft Dependency Injection
• Comprehensive messaging types:
  • IRequest<TResponse> - For queries and commands that return a value
  • IRequest - For commands that don't return a value
  • INotification - For events and notifications
• Automatic handler discovery - Automatically registers all handlers in your assemblies
• Thread-safe - All operations are thread-safe and optimized for concurrent access

Performance Optimizations

Coordix is designed with performance in mind, implementing several optimization strategies:

Cached MethodInfo

• MethodInfo caching: The Handle method's MethodInfo is cached per handler type using a ConcurrentDictionary
• One-time reflection: GetMethod("Handle") is called only once per handler type, eliminating repeated reflection overhead
• Thread-safe: All caches use ConcurrentDictionary for safe concurrent access

Compiled Delegates

• Strongly-typed delegates: Instead of using MethodInfo.Invoke, Coordix uses compiled Expression Trees to create strongly-typed delegates
• Direct invocation: Handlers are invoked through pre-compiled delegates, avoiding reflection overhead on every call
• Type-specific caching: Separate delegate caches for:
  • Request handlers without return value
  • Request handlers with return value
  • Notification handlers

Performance Benefits

• First invocation: Creates and caches the delegate (one-time overhead ~1-5ms)
• Subsequent invocations: Direct delegate calls with near-native performance (<0.01ms)
• Scalability: Performance improvements become more significant as handler invocation frequency increases

Getting Started

Installation

You can install the Coordix package via NuGet Package Manager or the .NET CLI:

dotnet add package Coordix

Quick Start

1. Register Coordix

using Coordix.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register Coordix and automatically discover all handlers
builder.Services.AddCoordix();

2. Define a Request

using Coordix.Interfaces;

public class GetUserQuery : IRequest<UserDto>
{
    public int UserId { get; set; }
}

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

3. Implement a Handler

using Coordix.Interfaces;

public class GetUserQueryHandler : IRequestHandler<GetUserQuery, UserDto>
{
    private readonly IUserRepository _repository;

    public GetUserQueryHandler(IUserRepository repository)
    {
        _repository = repository;
    }

    public async Task<UserDto> Handle(GetUserQuery request, CancellationToken cancellationToken)
    {
        var user = await _repository.GetByIdAsync(request.UserId, cancellationToken);
        return new UserDto { Id = user.Id, Name = user.Name };
    }
}

4. Use the Mediator

public class UsersController : ControllerBase
{
    private readonly IMediator _mediator;

    public UsersController(IMediator mediator)
    {
        _mediator = mediator;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<UserDto>> GetUser(int id)
    {
        var user = await _mediator.Send(new GetUserQuery { UserId = id });
        return Ok(user);
    }
}

Examples

Simple Request/Response

// Request
public class GetUserQuery : IRequest<UserDto>
{
    public int UserId { get; set; }
}

// Handler
public class GetUserQueryHandler : IRequestHandler<GetUserQuery, UserDto>
{
    public async Task<UserDto> Handle(GetUserQuery request, CancellationToken cancellationToken)
    {
        // Your logic here
        return new UserDto { Id = request.UserId, Name = "John" };
    }
}

// Usage
var user = await _mediator.Send(new GetUserQuery { UserId = 123 });

Command (No Response)

// Command
public class CreateUserCommand : IRequest
{
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
}

// Handler
public class CreateUserCommandHandler : IRequestHandler<CreateUserCommand>
{
    public async Task Handle(CreateUserCommand request, CancellationToken cancellationToken)
    {
        // Your logic here
        await SaveUserAsync(request);
    }
}

// Usage
await _mediator.Send(new CreateUserCommand { Name = "John", Email = "john@example.com" });

Notifications (Events)

// Notification
public class UserCreatedEvent : INotification
{
    public int UserId { get; }
    public string Email { get; }

    public UserCreatedEvent(int userId, string email)
    {
        UserId = userId;
        Email = email;
    }
}

// Handler
public class SendWelcomeEmailHandler : INotificationHandler<UserCreatedEvent>
{
    public async Task Handle(UserCreatedEvent notification, CancellationToken cancellationToken)
    {
        // Send welcome email
        await SendEmailAsync(notification.Email, "Welcome!");
    }
}

// Usage
await _mediator.Publish(new UserCreatedEvent(userId, email));

Registration Options

Automatic Registration (Recommended)

// Scan all assemblies in the current AppDomain
services.AddCoordix();

// Scan specific assemblies
services.AddCoordix(typeof(MyHandler).Assembly);

// Scan by namespace prefix
services.AddCoordix("MyApp");

Manual Registration

services.AddSingleton<IMediator, Mediator>();
services.AddScoped<IRequestHandler<GetUserQuery, UserDto>, GetUserQueryHandler>();
services.AddTransient<INotificationHandler<UserCreatedEvent>, SendWelcomeEmailHandler>();

Compatibility Alias

If you're migrating from MediatR, you can use the AddMediator alias:

services.AddMediator(); // Same as AddCoordix()

Extension Packages

Coordix has extension packages that add additional functionality:

Coordix.Background

Background job processing for fire-and-forget in-process jobs:

dotnet add package Coordix.Background

// AddCoordixBackground automatically includes core services
services.AddCoordixBackground();

Note: You do not need to call AddCoordix() when using AddCoordixBackground(). The Background extension registers all core services automatically.

See the Background Jobs Guide for more information.

Documentation

For comprehensive documentation, visit the GitHub repository:

Core Documentation

• 📖 Installation Guide
• 🚀 Getting Started Guide
• 📚 Usage Guide
• ⚡ Performance Guide
• 🔧 API Reference
• 🎯 Best Practices
• 🔄 Migration Guide
• ❓ FAQ

Extension Packages

• 🔄 Background Jobs Guide - Coordix.Background package

Examples

Check out the samples folder for complete, runnable examples:

• ✅ Simple Sample - Basic usage with Send and Publish
• ✅ Advanced Sample - Complete application with multiple handlers, events, and patterns

Requirements

• .NET Standard 2.1 or higher
• .NET Core 2.1+ / .NET 5+ / .NET 6+ / .NET 7+ / .NET 8+
• Microsoft.Extensions.DependencyInjection (included with ASP.NET Core)

License

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

About

Coordix was developed by Gabriel Santana under the MIT license.

Give a Star! ⭐

If this project made your life easier, a star would mean a lot to us!

Made with ❤️ by the Coordix community