https://github.com/hbartosch/routya
Routya is a fast, lightweight message dispatching library built for .NET applications that use the CQRS pattern. It provides a flexible way to route requests/responses and notifications to their respective handlers with minimal overhead and high performance.
https://github.com/hbartosch/routya
c-sharp csharp dispatch dispatcher dotnet10 dotnet80 dotnet90 dotnetstandard dotnetstandard20 dotnetstandard21 notification notifications parrallel-dispatcher request requests routing sequential-dispatcher source-generation source-generator
Last synced: 16 days ago
JSON representation
Routya is a fast, lightweight message dispatching library built for .NET applications that use the CQRS pattern. It provides a flexible way to route requests/responses and notifications to their respective handlers with minimal overhead and high performance.
- Host: GitHub
- URL: https://github.com/hbartosch/routya
- Owner: HBartosch
- License: mit
- Created: 2025-04-16T08:43:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-07T10:45:19.000Z (2 months ago)
- Last Synced: 2026-04-07T11:08:50.194Z (2 months ago)
- Topics: c-sharp, csharp, dispatch, dispatcher, dotnet10, dotnet80, dotnet90, dotnetstandard, dotnetstandard20, dotnetstandard21, notification, notifications, parrallel-dispatcher, request, requests, routing, sequential-dispatcher, source-generation, source-generator
- Language: C#
- Homepage:
- Size: 435 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Routya
[](https://www.nuget.org/packages/Routya.Core)
[](https://www.nuget.org/packages/Routya.Core)
**Routya** is a fast, lightweight message dispatching library built for .NET applications that use the CQRS pattern.
It provides a flexible way to route requests/responses and notifications to their respective handlers with minimal overhead and high performance.
---
## ⚡ **NEW: v3.0 Source Generator - 46% Faster!**
Get **compile-time code generation** for zero-overhead dispatching:
```bash
dotnet add package Routya.SourceGenerators --version 3.0.0
```
```csharp
using Routya.Generated;
builder.Services.AddGeneratedRoutya(); // Auto-registers all handlers!
public class MyController : ControllerBase
{
private readonly IGeneratedRoutya _routya;
public MyController(IGeneratedRoutya routya) => _routya = routya;
public async Task GetUser(int id)
{
return await _routya.SendAsync(new GetUserRequest { UserId = id });
}
}
```
**Performance:**
- ⚡ **46% faster** than MediatR on notifications
- 🔥 **Zero reflection** - all dispatch code generated at compile-time
- 📦 **Zero dictionary lookups** - direct method calls
- 🎯 **Full IntelliSense** - type-specific interface with your exact methods
📖 **[Getting Started Guide →](./GETTING_STARTED_V3.md)** | 📦 **[Release Notes →](./RELEASE_NOTES_V3.md)** | 📚 **[Full Docs →](./Routya.SourceGenerators/README.md)**
---
## ✨ Features
- ✅ Clean interface-based abstraction for Requests/Responses and Notifications
- 🚀 **High-performance dispatching** - Competitive with MediatR while offering more flexibility
- **⚡ NEW: Source generation** - Compile-time code generation for maximum speed
- **🌊 NEW: Streaming support** - `IAsyncEnumerable` for large datasets
- ⚙️ **Configurable handler lifetimes** - Choose Singleton, Scoped, or Transient per handler
- 🧩 Pipeline behavior support for cross-cutting concerns
- 🔄 Supports both **sequential** and **parallel** notification dispatching
- 🎯 **Multi-framework support** - netstandard2.0, netstandard2.1, .NET 8, .NET 9, .NET 10
- 💾 **Memory efficient** - Zero memory leaks with proper scope management
- ♻️ Simple to extend and integrate with your existing architecture
---
## 📦 NuGet Packages
### v3.0 - Source Generator (Recommended for new projects)
```bash
dotnet add package Routya.SourceGenerators --version 3.0.0
```
Includes `Routya.Core` automatically.
### v2.x - Runtime Dispatcher
```bash
dotnet add package Routya.Core --version 2.0.0
```
Use for existing projects or when runtime flexibility is needed.
### ⚠️ Breaking Changes in v2.0.0
**1. Pipeline Behavior Delegate Signature Change**
The `RequestHandlerDelegate` now requires a `CancellationToken` parameter:
```csharp
// ❌ Old (v1.x)
public delegate Task RequestHandlerDelegate();
// ✅ New (v2.0)
public delegate Task RequestHandlerDelegate(CancellationToken cancellationToken);
```
**Migration Guide:**
Update your pipeline behaviors to pass the `CancellationToken` to the `next()` delegate:
```csharp
// ❌ Old code (v1.x)
public async Task Handle(
TRequest request,
RequestHandlerDelegate next,
CancellationToken cancellationToken)
{
// Your logic before
var result = await next(); // ❌ No parameter
// Your logic after
return result;
}
// ✅ New code (v2.0)
public async Task Handle(
TRequest request,
RequestHandlerDelegate next,
CancellationToken cancellationToken)
{
// Your logic before
var result = await next(cancellationToken); // ✅ Pass cancellationToken
// Your logic after
return result;
}
```
**2. Performance Improvements**
- Registry-based optimization with smart fallback
- Auto-caching of discovered handlers for improved performance
- 9-10% faster request dispatching with Singleton/Transient handlers
- 30% faster notification dispatching with Singleton sequential handlers
## 🚀 Quick Start
# Dependency injection
On startup you can define if **Routya** should create a new instance of the service provider each time it is called or work on the root service provider.
Note!!! By default scope is enabled
# Scoped
Creates a new DI scope for each dispatch
- Safely supports handlers registered as Scoped
- ✅ Use this if your handlers depend on:
- EF Core DbContext
- IHttpContextAccessor
- IMemoryCache, etc.
```C#
builder.Services.AddRoutya(cfg => cfg.Scope = RoutyaDispatchScope.Scoped, Assembly.GetExecutingAssembly());
```
# Root
Fastest option
- avoids creating a service scope per dispatch
- Resolves handlers directly from the root IServiceProvider
- ✅ Ideal for stateless handlers that are registered as Transient or Singleton
- ⚠️ Will fail if your handler is registered as Scoped (e.g., it uses DbContext or IHttpContextAccessor)
```C#
builder.Services.AddRoutya(cfg => cfg.Scope = RoutyaDispatchScope.Root, Assembly.GetExecutingAssembly());
```
You can add an auto registration of IRequestHandler, IAsyncRequestHandler and INotificationHandler by adding the executing assembly. This however registers all your request handlers with the default lifetime (Scoped).
Note!!! By default you would have to manually register your Requests/Notifications and Handlers
```C#
builder.Services.AddRoutya(cfg => cfg.Scope = RoutyaDispatchScope.Scoped, Assembly.GetExecutingAssembly());
```
# Handler Lifetimes (New in v1.0.5)
Configure handler lifetimes for optimal performance based on your use case:
### Option 1: Assembly Scanning with Uniform Lifetime
```C#
// Register all handlers as Singleton (fastest, stateless handlers only)
builder.Services.AddRoutya(cfg => cfg.HandlerLifetime = ServiceLifetime.Singleton, Assembly.GetExecutingAssembly());
// Register all handlers as Scoped (default, works with DbContext)
builder.Services.AddRoutya(cfg => cfg.HandlerLifetime = ServiceLifetime.Scoped, Assembly.GetExecutingAssembly());
// Register all handlers as Transient (new instance every time)
builder.Services.AddRoutya(cfg => cfg.HandlerLifetime = ServiceLifetime.Transient, Assembly.GetExecutingAssembly());
```
### Option 2: Optimized Manual Registration (Recommended for Performance)
Use Routya's specialized registration methods for optimal performance:
```C#
// Register Routya core services
builder.Services.AddRoutya();
// Use AddRoutyaAsyncRequestHandler for request handlers
builder.Services.AddRoutyaAsyncRequestHandler(ServiceLifetime.Singleton);
builder.Services.AddRoutyaRequestHandler(ServiceLifetime.Scoped);
// Use AddRoutyaNotificationHandler for notifications
builder.Services.AddRoutyaNotificationHandler(ServiceLifetime.Singleton);
builder.Services.AddRoutyaNotificationHandler(ServiceLifetime.Scoped);
```
**Why use these methods?**
- ✅ **Automatic registry population** - Handlers added to high-performance registry
- ✅ **30% faster** for notifications (110ns vs 158ns with Singleton)
- ✅ **Type-safe** - Compile-time verification of handler signatures
- ✅ **Flexible lifetimes** - Choose Singleton/Scoped/Transient per handler
### Option 3: Traditional DI Registration (Still Supported)
You can also use standard DI registration - works with auto-caching fallback:
```C#
// Register Routya core services (no assembly scanning)
builder.Services.AddRoutya();
// Traditional DI registration (automatically cached to registry on first use)
builder.Services.AddSingleton, CreateProductHandler>();
builder.Services.AddScoped, GetProductHandler>();
builder.Services.AddTransient>, GetAllProductsHandler>();
// Notification handlers (automatically cached on first publish)
builder.Services.AddSingleton, SendEmailHandler>();
```
**Trade-off**: First call uses standard DI resolution (~5-10% slower), subsequent calls automatically use optimized registry.
**Performance Comparison:**
- **Singleton**: ~380 ns (2% slower than MediatR, 50% less memory, best for stateless handlers)
- **Transient**: ~384 ns (3% slower than MediatR, matches memory, maximum isolation)
- **Scoped**: ~440 ns (18% overhead, safe for DbContext and scoped dependencies)
Routya lets YOU choose the right lifetime per handler:
- 🚀 **Singleton** for stateless handlers = fastest, least memory
- 🔄 **Scoped** for handlers with DbContext = safe with proper scope management
- 🔒 **Transient** when you need maximum isolation = new instance every time
### Backward Compatibility & Auto-Registry
Routya maintains full backward compatibility with traditional DI registration:
```C#
// Traditional registration (still works!)
builder.Services.AddScoped, MyHandler>();
builder.Services.AddScoped, MyNotificationHandler>();
```
**Smart Fallback with Auto-Caching:**
When handlers aren't found in the registry, Routya automatically:
1. Falls back to `GetService/GetServices` resolution (first call)
2. **Adds discovered handlers to the registry** (automatic optimization!)
3. Uses fast registry-based dispatch for all subsequent calls
This ensures:
- ✅ **First call**: Fallback resolution (~same speed as traditional)
- ✅ **Second+ calls**: Registry-optimized dispatch (~28% faster for notifications!)
- ✅ Smooth migration path from older versions
- ✅ Works with existing code without changes
- ✅ Automatic performance improvement after first use
# Requests
### 📊 Benchmark Results (.NET 8 - November 2025)
Benchmarks comparing Routya against MediatR 13.1.0 with simple request handlers (BenchmarkDotNet v0.14.0)
**Test Environment:**
- CPU: 11th Gen Intel Core i7-11800H @ 2.30GHz (8 cores, 16 logical processors)
- RAM: System with AVX-512F support
- OS: Windows 11 (10.0.22623)
- .NET: 8.0.17 (8.0.1725.26602), X64 RyuJIT
- GC: Concurrent Server
#### Request Dispatching Performance
| Method | Mean | Ratio | Gen0 | Allocated | Notes |
|--------------------------- |---------:|------:|-------:|----------:|-------|
| MediatR_SendAsync | 369.3 ns | 1.00 | 0.0038 | 1016 B | Baseline |
| **Routya_Singleton_Send** | **333.9 ns** | **0.90** | 0.0038 | 1008 B | ⚡ **10% faster!** |
| **Routya_Transient_Send** | **336.0 ns** | **0.91** | 0.0038 | 1032 B | ⚡ **9% faster!** |
| Routya_Singleton_SendAsync | 397.7 ns | 1.08 | 0.0048 | 1168 B | 8% overhead for async |
| Routya_Scoped_Send | 395.5 ns | 1.07 | 0.0048 | 1216 B | Scoped DI overhead |
| Routya_Transient_SendAsync | 418.0 ns | 1.13 | 0.0048 | 1192 B | 13% overhead for async |
| Routya_Scoped_SendAsync | 476.4 ns | 1.29 | 0.0048 | 1376 B | Scoped + async overhead |
**Key Highlights:**
- ✅ **Singleton/Transient Send handlers are 9-10% faster than MediatR!** 🚀
- ✅ **Registry-based dispatch** with auto-caching fallback
- ✅ **Zero memory leaks** with proper scope disposal
- ✅ **Fast-path optimization** when no behaviors configured
- 🎯 **Configurable handler lifetimes** (Singleton/Scoped/Transient)
Define a request
```C#
public class HelloRequest(string name) : IRequest
{
public string Name { get; } = name;
}
```
Implement the Sync handler ...
```C#
public class HelloSyncHandler : IRequestHandler
{
public string Handle(HelloRequest request)
{
return $"Hello, {request.Name}!";
}
}
```
or Implement the async handler
```C#
public class HelloAsyncHandler : IAsyncRequestHandler
{
public async Task HandleAsync(HelloRequest request, CancellationToken cancellationToken)
{
return await Task.FromResult($"[Async] Hello, {request.Name}!");
}
}
```
Inject the **IRoutya** interface and dispatch your requests in sync...
```C#
public class Example : ControllerBase
{
private readonly IRoutya _dispatcher;
public Example(IRoutya dispatcher)
{
_dispatcher = dispatcher;
}
}
```
```C#
_dispatcher.Send(new HelloRequest("Sync World"));
```
or async
```C#
await _dispatcher.SendAsync(new HelloRequest("Async World"));
```
# Pipeline Behaviors
You can add pipeline behaviors to execute around your requests. These behaviors need to be registered manually and execute in the order they are registered.
```C#
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(LoggingBehavior<,>));
services.AddScoped(typeof(IPipelineBehavior<,>), typeof(ValidationBehavior<,>));
```
In the following example the LoggingBehavior will write to console before your request, wait for the request(in the example above first execute the ValidationBehavior and then in the ValidationBehavior it will execute the request) to execute and then write to the console afterward executing the request.
```C#
public class LoggingBehavior : IPipelineBehavior
{
public async Task Handle(
TRequest request,
Routya.Core.Abstractions.RequestHandlerDelegate next,
CancellationToken cancellationToken)
{
Console.WriteLine($"[Logging] → {typeof(TRequest).Name}");
var result = await next(cancellationToken); // Pass cancellationToken to next
Console.WriteLine($"[Logging] ✓ {typeof(TRequest).Name}");
return result;
}
}
```
# Notifications
### 📊 Notification Dispatching Performance
Benchmarks comparing Routya against MediatR 13.1.0 for notification patterns (BenchmarkDotNet v0.14.0)
| Method | Mean | Ratio | Gen0 | Allocated | Notes |
|---------------------------- |---------:|------:|-------:|----------:|-------|
| MediatR_Publish | 157.6 ns | 1.00 | 0.0017 | 440 B | Baseline |
| **Routya_Singleton_Sequential** | **110.5 ns** | **0.70** | 0.0007 | 192 B | ⚡ **30% faster, 56% less memory!** 🚀 |
| **Routya_Singleton_Parallel** | **143.6 ns** | **0.91** | 0.0012 | 312 B | ⚡ **9% faster, 29% less memory** |
| **Routya_Transient_Sequential** | **146.0 ns** | **0.93** | 0.0010 | 240 B | ⚡ **7% faster, 45% less memory** |
| Routya_Transient_Parallel | 170.6 ns | 1.08 | 0.0014 | 360 B | 8% slower (parallel overhead) |
| Routya_Scoped_Sequential | 238.1 ns | 1.51 | 0.0014 | 424 B | Scoped DI overhead |
| Routya_Scoped_Parallel | 265.8 ns | 1.69 | 0.0019 | 544 B | Scoped + parallel overhead |
**Key Highlights:**
- ✅ **Singleton sequential: 30% faster than MediatR with 56% less memory** (192B vs 440B) 🚀
- ✅ **Transient sequential: 7% faster with 45% less memory** (240B vs 440B)
- ✅ **Registry-based dispatch with auto-caching** - Zero GetServices calls after first use
- ✅ **Parallel dispatching** available with minimal overhead
- ✅ **Flexible lifetime management** for different use cases
Define your notification
```C#
public class UserRegisteredNotification(string email) : INotification
{
public string Email { get; } = email;
}
```
Define your handlers
```C#
public class LogAnalyticsHandler : INotificationHandler
{
public async Task Handle(UserRegisteredNotification notification, CancellationToken cancellationToken = default)
{
await Task.Delay(100, cancellationToken);
Console.WriteLine($"📊 Analytics event logged for {notification.Email}");
}
}
```
```C#
public class SendWelcomeEmailHandler : INotificationHandler
{
public async Task Handle(UserRegisteredNotification notification, CancellationToken cancellationToken = default)
{
await Task.Delay(200, cancellationToken);
Console.WriteLine($"📧 Welcome email sent to {notification.Email}");
}
}
```
Inject the **IRoutya** interface and dispatch your notifications sequentially...
```C#
public class Example : ControllerBase
{
private readonly IRoutya _dispatcher;
public Example(IRoutya dispatcher)
{
_dispatcher = dispatcher
}
}
```
```C#
await dispatcher.PublishAsync(new UserRegisteredNotification("john.doe@example.com"));
```
or in parallel
```C#
await dispatcher.PublishParallelAsync(new UserRegisteredNotification("john.doe@example.com"));
```
---
## 🌐 Web API Demos
### Source Generator demo — [`Routya.WebApi.SourceGen.Demo`](./Routya.WebApi.SourceGen.Demo)
The recommended starting point if you're using `IGeneratedRoutya`. Demonstrates:
- ✅ **Compile-time dispatch** via `AddGeneratedRoutya()` — no reflection, no assembly scanning
- ✅ **Open-generic pipeline behavior** (`LoggingBehavior`)
- ✅ **Notification fan-out** — two handlers dispatched in parallel from a single `PublishAsync`
- ✅ **`IAsyncEnumerable` streaming** — products streamed one by one to the HTTP response
```powershell
cd Routya.WebApi.SourceGen.Demo
dotnet run
# http://localhost:5080
```
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/products` | List all products |
| GET | `/products/{id}` | Get a single product |
| POST | `/products` | Create a product |
| GET | `/products/stream` | Stream products via `IAsyncEnumerable` |
| POST | `/orders/{id}/shipped` | Publish a notification to two handlers |
---
### Runtime dispatch demo — [`Routya.WebApi.Demo`](./Routya.WebApi.Demo)
Demonstrates `IRoutya` (runtime reflection-based dispatch) with Entity Framework Core:
- ✅ **All three handler lifetimes** (Singleton, Scoped, Transient)
- ✅ **Entity Framework Core** with SQL Server
- ✅ **Full CRUD operations** via RESTful API
```powershell
cd Routya.WebApi.Demo
dotnet run
# http://localhost:5079
```