DispatchR - GitLite

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #llm #golang #machine-learning #linux #java #windows #awesome #cli #vue

DispatchR

(★ 401)

Fast, zero-alloc alternative to MediatR for .NET – minimal, blazing fast, and DI-friendly.

파일 탐색기

최종 버전 다운로드 (.zip)

- - build-release.yml
- copilot-instructions.md
- FUNDING.yml
- - notification-stable.png
  - stream-with-pipeline-stable.png
  - stream-without-pipeline-stable.png
  - with-pipeline-stable.png
  - without-pipeline-stable.png
- - AspireModularExample.sln
  - README.md
- - appsettings.Development.json
  - appsettings.json
  - Benchmark.csproj
  - Program.cs
- - Constants.cs
  - DispatchR.csproj
  - Mediator.cs
  - TypeForwarders.cs
- - DispatchR.Abstractions.csproj
  - IMediator.cs
- - appsettings.Development.json
  - appsettings.json
  - BigFile.txt
  - Program.cs
  - Sample.csproj
  - Sample.http
- - DispatchR.IntegrationTest.csproj
  - NotificationTests.cs
  - RequestHandlerTests.cs
  - StreamRequestHandlerTests.cs
- - DispatchR.TestCommon.csproj
- - AddDispatchRConfigurationTests.cs
  - DispatchR.UnitTest.csproj
  - RequestHandlerTests.cs
  - StreamRequestHandlerTests.cs
.gitignore
CHANGELOG.md
Directory.Packages.props
DispatchR.slnx
icon-mini.png
icon.jpg
LICENSE
README.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/hasanxdev/DispatchR

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd DispatchR

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. .NET

보통 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
.NET SDK dotnet 명령어를 쓰기 위한 SDK입니다.

dotnet add package DispatchR.Mediator

이 명령어를 터미널에 그대로 입력해 실행하세요.

dotnet add package DispatchR.Mediator.Abstractions

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ dotnet run 실행 후 터미널에 나타나는 안내 메시지나 주소를 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# <img src="https://github.com/hasanxdev/DispatchR/raw/main/icon-mini.png" width="26">ispatchR 🚀

![CI](https://github.com/hasanxdev/DispatchR/workflows/Release/badge.svg)
[![codecov](https://codecov.io/github/hasanxdev/dispatchr/graph/badge.svg?token=1FUG5DPUOE)](https://codecov.io/github/hasanxdev/dispatchr)
[![NuGet](https://img.shields.io/nuget/dt/DispatchR.Mediator.svg)](https://www.nuget.org/packages/DispatchR.Mediator)
[![NuGet](https://img.shields.io/nuget/vpre/DispatchR.Mediator.svg)](https://www.nuget.org/packages/DispatchR.Mediator)

### A High-Performance Mediator Implementation for .NET :trollface:
** *Minimal memory footprint. Blazing-fast execution.* **

> [!NOTE]
> If you're curious to see the power of this library, [check out the benchmark](https://github.com/hasanxdev/DispatchR?tab=readme-ov-file#-bechmark-result) comparing MediatR vs Mediator Source Generator vs DispatchR.

## ⚡ Key Features
- Built entirely on top of Dependency Injection
- Zero runtime reflection after registration
- Choose your handler return type: `Task`, `ValueTask`, or `Synchronous Method`
- Allocates nothing on the heap — ideal for high-throughput scenarios
- Outperforms existing solutions in most real-world benchmarks
- Seamlessly compatible with MediatR — migrate with minimal effort
- Include or exclude a set of handlers from an assembly — ideal for use with Aspire
- Currently supports
    1. Simple Request:
        1. `IRequest<TRquest, TResponse>`
        2. `IRequestHandler<TRequest, TResponse>`
        3. `IPipelineBehavior<TRequest, TResponse>`
    2. Stream Request:
        1. `IStreamRequest<TRquest, TResponse>`
        2. `IStreamRequestHandler<TRequest, TResponse>`
        3. `IStreamPipelineBehavior<TRequest, TResponse>`
    3. Notifications:
        1. `INotification`
        2. `INotificationHandler<TRequestEvent>`
        3. Open-generic `INotificationHandler<TNotification> where TNotification : INotification`
> :bulb: **Tip:** *If you're looking for a mediator with the raw performance of hand-written code, DispatchR is built for you.*

## ✨ How to install?
```
dotnet add package DispatchR.Mediator
```
You can also separately add only the abstractions, which include the interfaces, in another layer:
```
dotnet add package DispatchR.Mediator.Abstractions
```

# Syntax Comparison: DispatchR vs MediatR

###### In the following, you will see the key differences and implementation details between MediatR and DispatchR.

## Request Definition

### MediatR
```csharp
public sealed class PingMediatR : IRequest<int> { }
```

### DispatchR
1. Sending `TRequest` to `IRequest`
2. Precise selection of output for both `async` and `sync` handlers
    1. Ability to choose between `Task` and `ValueTask`

```csharp
public sealed class PingDispatchR : IRequest<PingDispatchR, ValueTask<int>> { } 
```

> [!IMPORTANT]
> Always use a **generic** return type such as `Task<TResult>` or `ValueTask<TResult>`. Using a bare `Task` or `ValueTask` (without a type argument) may prevent the handler from being triggered when pipeline behaviors or validators are present.

## Handler Definition

### MediatR
```csharp
public sealed class PingHandlerMediatR : IRequestHandler<PingMediatR, int>
{
    public Task<int> Handle(PingMediatR request, CancellationToken cancellationToken)
    {
        return Task.FromResult(0);
    }
}
```

### DispatchR (Don't change)

```csharp
public sealed class PingHandlerDispatchR : IRequestHandler<PingDispatchR, ValueTask<int>>
{
    public ValueTask<int> Handle(PingDispatchR request, CancellationToken cancellationToken)
    {
        return ValueTask.FromResult(0);
    }
}
```

## Pipeline Behavior

### MediatR
```csharp
public sealed class LoggingBehaviorMediat : IPipelineBehavior<PingMediatR, int>
{
    public Task<int> Handle(PingMediatR request, RequestHandlerDelegate<int> next, CancellationToken cancellationToken)
    {
        return next(cancellationToken);
    }
}
```

### DispatchR
1. Use ___Chain of Responsibility___ pattern

```csharp
public sealed class LoggingBehaviorDispatchR : IPipelineBehavior<PingDispatchR, ValueTask<int>>
{
    public required IRequestHandler<PingDispatchR, ValueTask<int>> NextPipeline { get; set; }

public ValueTask<int> Handle(PingDispatchR request, CancellationToken cancellationToken)
    {
        return NextPipeline.Handle(request, cancellationToken);
    }
}
```

#### Generic pipeline behavior DispatchR
1. For every kind of return type — `Task`, `ValueTask`, or synchronous methods — you need to write a generic pipeline behavior. However, you don't need a separate pipeline for each request. As shown in the code below, this is a GenericPipeline for requests that return a `ValueTask`.
```csharp
public class GenericPipelineBehavior<TRequest, TResponse>() : IPipelineBehavior<TRequest, ValueTask<TResponse>>
    where TRequest : class, IRequest<TRequest, ValueTask<TResponse>>
{
    public required IRequestHandler<TRequest, ValueTask<TResponse>> NextPipeline { get; set; }
    
    public ValueTask<TResponse> Handle(TRequest request, CancellationToken cancellationToken)
    {
        // You can add custom logic here, like logging or validation
        // This pipeline behavior can be used for any request type
        return NextPipeline.Handle(request, cancellationToken);
    }
}
```

## Summary

- **DispatchR** lets the request itself define the return type.
- **No runtime reflection** in DispatchR — it's optimized for performance.
- **No static behavior chains** — pipelines are chained via DI and handler wiring.
- **Supports `void`, `Task`, or `ValueTask`** as return types.

Ideal for high-performance .NET applications.

## Stream Request Definition

### MediatR Stream
```csharp
public sealed class CounterStreamRequestMediatR : IStreamRequest<int> { }
```

### DispatchR
1. Sending `TRequest` to `IStreamRequest`

```csharp
public sealed class CounterStreamRequestDispatchR : IStreamRequest<CounterStreamRequestDispatchR, int> { } 
```

## Stream Handler Definition

### Stream Handler MediatR
```csharp
public sealed class CounterStreamHandlerMediatR : IStreamRequestHandler<CounterStreamRequestMediatR, int>
{
    public async IAsyncEnumerable<int> Handle(CounterStreamRequestMediatR request, CancellationToken cancellationToken)
    {
        yield return 1;
    }
}
```

### Stream Handler DispatchR (Don't change)

```csharp
public sealed class CounterStreamHandlerDispatchR : IStreamRequestHandler<CounterStreamRequestDispatchR, int>
{
    public async IAsyncEnumerable<int> Handle(CounterStreamRequestDispatchR request, CancellationToken cancellationToken)
    {
        yield return 1;
    }
}
```

## Stream Pipeline Behavior

### Stream Pipeline MediatR
```csharp
public sealed class CounterPipelineStreamHandler : IStreamPipelineBehavior<CounterStreamRequestMediatR, string>
{
    public async IAsyncEnumerable<string> Handle(CounterStreamRequestMediatR request, StreamHandlerDelegate<string> next, [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var response in next().WithCancellation(cancellationToken).ConfigureAwait(false))
        {
            yield return response;
        }
    }
}
```

### Stream Pipeline DispatchR
1. Use ___Chain of Responsibility___ pattern

```csharp
public sealed class CounterPipelineStreamHandler : IStreamPipelineBehavior<CounterStreamRequestDispatchR, string>
{
    public required IStreamRequestHandler<CounterStreamRequestDispatchR, string> NextPipeline { get; set; }
    
    public async IAsyncEnumerable<string> Handle(CounterStreamRequestDispatchR request, [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var response in NextPipeline.Handle(request, cancellationToken).ConfigureAwait(false))
        {
            yield return response;
        }
    }
}
```

#### Generic stream pipeline behavior DispatchR
```csharp
public class GenericStreamPipelineBehavior<TRequest, TResponse>() : IStreamPipelineBehavior<TRequest, TResponse>
    where TRequest : class, IStreamRequest<TRequest, TResponse>
{
    public IStreamRequestHandler<TRequest, TResponse> NextPipeline { get; set; }
    
    public async IAsyncEnumerable<TResponse> Handle(TRequest request, CancellationToken cancellationToken)
    {
        await foreach (var response in NextPipeline.Handle(request, cancellationToken).ConfigureAwait(false))
        {
            yield return response;
        }
    }
}
```

------------
## Notification

### Notification MediatR
```csharp
public sealed record Event(Guid Id) : INotification;

public sealed class EventHandler(ILogger<Event> logger) : INotificationHandler<Event>
{
    public Task Handle(Event notification, CancellationToken cancellationToken)
    {
        logger.LogInformation("Received notification");
        return Task.CompletedTask;
    }
}
```

### Notification DispatchR
1. Use ___ValueTask___

```csharp
public sealed record Event(Guid Id) : INotification;

public sealed class EventHandler(ILogger<Event> logger) : INotificationHandler<Event>
{
    public ValueTask Handle(Event notification, CancellationToken cancellationToken)
    {
        logger.LogInformation("Received notification");
        return ValueTask.CompletedTask;
    }
}
```

#### Generic notification handler DispatchR
1. A single open-generic handler receives **every** notification type — ideal for cross-cutting concerns such as logging, auditing, or telemetry.

```csharp
public sealed class AllNotificationsLogger<TNotification>(ILogger<AllNotificationsLogger<TNotification>> logger)
    : INotificationHandler<TNotification>
    where TNotification : INotification
{
    public ValueTask Handle(TNotification notification, CancellationToken cancellationToken)
    {
        logger.LogInformation("[Generic] Received notification of type {NotificationType}: {@Notification}",
            typeof(TNotification).Name, notification);
        return ValueTask.CompletedTask;
    }
}
```

# ⚡ How DispatchR Achieves High Performance

###### DispatchR is designed with one goal in mind: **maximize performance with minimal memory usage**. Here's how it accomplishes that:

## What Happens Inside the `Send` Method?

```csharp
public TResponse Send<TRequest, TResponse>(IRequest<TRequest, TResponse> request,
    CancellationToken cancellationToken) where TRequest : class, IRequest
{
    return serviceProvider
        .GetRequiredService<IRequestHandler<TRequest, TResponse>>()
        .Handle(Unsafe.As<TRequest>(request), cancellationToken);
}
```

## What Happens Inside the `CreateStream` Method?

```csharp
public IAsyncEnumerable<TResponse> CreateStream<TRequest, TResponse>(IStreamRequest<TRequest, TResponse> request, 
        CancellationToken cancellationToken) where TRequest : class, IStreamRequest
{
    return serviceProvider.GetRequiredService<IStreamRequestHandler<TRequest, TResponse>>()
        .Handle(Unsafe.As<TRequest>(request), cancellationToken);
}
```
**Only the handler is resolved and directly invoked!**

## What Happens Inside the `Publish` Method?

```csharp
public async ValueTask Publish<TNotification>(TNotification request, CancellationToken cancellationToken) where TNotification : INotification
{
    var notificationsInDi = serviceProvider.GetRequiredService<IEnumerable<INotificationHandler<TNotification>>>();
    
    var notifications = Unsafe.As<INotificationHandler<TNotification>[]>(notificationsInDi);
    foreach (var notification in notifications)
    {
        var valueTask = notification.Handle(request, cancellationToken);
        if (valueTask.IsCompletedSuccessfully is false) // <-- Handle sync notifications
        {
            await valueTask;
        }
    }
}
```

But the real magic happens behind the scenes when DI resolves the handler dependency:
> 💡 __Tips:__
> 1. *We cache the handler using DI, so in scoped scenarios, the object is constructed only once and reused afterward.*
>
> 2. *In terms of Dependency Injection (DI), everything in Requests is an IRequestHandler, it's just the keys that differ.
     When you request a specific key, a set of 1+N objects is returned: the first one is the actual handler, and the rest are the pipeline behaviors.*

```csharp
services.AddScoped(handlerInterface, sp =>
{
    var pipelinesWithHandler = Unsafe
        .As<IRequestHandler[]>(sp.GetKeyedServices<IRequestHandler>(key));
    
    IRequestHandler lastPipeline = pipelinesWithHandler[0];
    for (int i = 1; i < pipelinesWithHandler.Length; i++)
    {
        var pipeline = pipelinesWithHandler[i];
        pipeline.SetNext(lastPipeline);
        lastPipeline = pipeline;
    }

return lastPipeline;
});
```

This elegant design chains pipeline behaviors at resolution time — no static lists, no reflection, no magic.

## 🪴 How to use?
It's simple! Just use the following code:
```csharp
builder.Services.AddDispatchR(typeof(MyCommand).Assembly, withPipelines: true, withNotifications: true);
```
This code will automatically register all pipelines by default.
If you need to register them in a specific order, you can pass the order via ConfigurationOptions, as shown in the example below.
<br>
Additionally, you can include or exclude specific handlers from an assembly — which is especially useful when working with Aspire.
You can also check the Samples section to see the Aspire-specific example.
```csharp
builder.Services.AddDispatchR(options =>
{
    options.Assemblies.Add(typeof(DispatchRSample.Ping).Assembly);
    options.RegisterPipelines = true;
    options.RegisterNotifications = true;
    options.PipelineOrder =
    [
        typeof(DispatchRSample.FirstPipelineBehavior),
        typeof(DispatchRSample.SecondPipelineBehavior),
        typeof(DispatchRSample.GenericPipelineBehavior<,>)
    ];
    options.IncludeHandlers = null;
    options.ExcludeHandlers = null;
});
```

If you need additional customization, you can either add them manually or write your own reflection logic:
```csharp
builder.Services.AddDispatchR(typeof(MyCommand).Assembly, withPipelines: false, withNotifications: false);
builder.Services.AddScoped<IPipelineBehavior<MyCommand, int>, PipelineBehavior>();
builder.Services.AddScoped<IPipelineBehavior<MyCommand, int>, ValidationBehavior>();
builder.Services.AddScoped<IStreamPipelineBehavior<MyStreamCommand, int>, ValidationBehavior>();
builder.Services.AddScoped<INotificationHandler<Event>, EventHandler>();
```
### 💡 Key Notes:
1. Automatic pipeline and notification registration is enabled by default
2. Manual registration allows for custom pipeline or notification ordering
3. You can implement custom reflection if needed

# 🧪 Bechmark Result:
> [!IMPORTANT]
> This benchmark was conducted using MediatR version 12.5.0 and the stable release of Mediator Source Generator, version 2.1.7.
Version 3 of Mediator Source Generator was excluded due to significantly lower performance.

### Send Request
#### 1. MediatR vs Mediator Source Generator vs DispatchR With Pipeline
![Benchmark Result](https://github.com/hasanxdev/DispatchR/raw/main/benchmark/results/with-pipeline-stable.png)
#### 2. MediatR vs Mediator Source Generator vs DispatchR Without Pipeline
![Benchmark Result](https://github.com/hasanxdev/DispatchR/raw/main/benchmark/results/without-pipeline-stable.png)

### Stream Request
#### 1. MediatR vs Mediator Source Generator vs DispatchR With Pipeline
![Benchmark Result](https://github.com/hasanxdev/DispatchR/raw/main/benchmark/results/stream-with-pipeline-stable.png)
#### 2. MediatR vs Mediator Source Generator vs DispatchR Without Pipeline
![Benchmark Result](https://github.com/hasanxdev/DispatchR/raw/main/benchmark/results/stream-without-pipeline-stable.png)

### Notification
#### 1. MediatR vs Mediator Source Generator vs DispatchR
![Benchmark Result](https://github.com/hasanxdev/DispatchR/raw/main/benchmark/results/notification-stable.png)

## ✨ Contribute & Help Grow This Package! ✨
We welcome contributions to make this package even better! ❤️
- Found a bug? → Open an issue
- Have an idea? → Suggest a feature
- Want to code? → Submit a PR

## Star History
<a href="https://star-history.dera.page/#hasanxdev/DispatchR&Timeline">
  <img src="https://star-history.dera.page/svg?repos=hasanxdev/DispatchR&type=Timeline" width="400"/>
</a>

Let's build something amazing together! 🚀