Skip to main content

Immediate.Handlers by Stuart Turner

Nuget / site data​

Nuget GitHub last commit GitHub Repo stars

Details​

Info​

info

Name: Immediate.Handlers

TBD

Author: Stuart Turner

NuGet: https://www.nuget.org/packages/Immediate.Handlers/

You can find more details at https://github.com/immediateplatform/Immediate.Handlers

Source : https://github.com/immediateplatform/Immediate.Handlers

Original Readme​

note

Immediate.Handlers

NuGet GitHub release GitHub license GitHub issues GitHub issues-closed

GitHub Actions​

Immediate.Handlers is an implementation of the mediator pattern in .NET using source-generation. All pipeline behaviors are determined and the call-tree built at compile-time; meaning that all dependencies are enforced via compile-time safety checks. Behaviors and dependencies are obtained via DI at runtime based on compile-time determined dependencies.

Examples​

Installing Immediate.Handlers​

You can install Immediate.Handlers with NuGet:

Install-Package Immediate.Handlers

Or via the .NET Core command line interface:

dotnet add package Immediate.Handlers

Either commands, from Package Manager Console or .NET Core CLI, will download and install Immediate.Handlers.

Using Immediate.Handlers​

Creating Handlers​

Create a Handler by adding the following code:

[Handler]
public static partial class GetUsersQuery
{
    public record Query;

    private static ValueTask<IEnumerable<User>> HandleAsync(
        Query _,
        UsersService usersService,
        CancellationToken token
    )
    {
        return usersService.GetUsers();
    }
}

This will automatically create a new class, GetUsersQuery.Handler, which encapsulates the following:

  • attaching any behaviors defined for all queries in the assembly
  • using a class to receive any DI services, such as UsersService

Any consumer can now do the following:

public class Consumer(GetUsersQuery.Handler handler)
{
    public async Task Consumer(CancellationToken token)
    {
        var response = await handler.HandleAsync(new(), token);
        // do something with response
    }
}

For Command handlers, use a ValueTask, and Immediate.Handlers will insert a return type of ValueTuple to your handler automatically. 

[Handler]
public static partial class CreateUserCommand
{
    public record Command(string Email);

    private static async ValueTask HandleAsync( 
        Command command,
        UsersService usersService,
        CancellationToken token
    )
    {
        await usersService.CreateUser(command.Email);
    }
}

In case your project layout does not allow direct for references between consumer and handler, the handler will also be registered as an IHandler<TRequest, Response>.

public class Consumer(IHandler<Query, IEnumerable<User>> handler)
{
    public async Task Consumer(CancellationToken token)
    {
        var response = await handler.HandleAsync(new(), token);
        // do something with response
    }
}

Creating Behaviors​

Create a behavior by implementing the Immediate.Handlers.Shared.Behaviors<,> class, as so:

public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger)
    : Behavior<TRequest, TResponse>
{
    public override async ValueTask<TResponse> HandleAsync(TRequest request, CancellationToken cancellationToken)
    {
        logger.LogInformation("LoggingBehavior.Enter");
        var response = await Next(request, cancellationToken);
        logger.LogInformation("LoggingBehavior.Exit");
        return response;
    }
}

This can be registered assembly-wide using:

[assembly: Behaviors(
    typeof(LoggingBehavior<,>)
)]

or on an individual handler using:

[Handler]
[Behavior(
    typeof(LoggingBehavior<,>)
)]
public static class GetUsersQuery
{
    // ..
}

Once added to the pipeline, the behavior will be called as part of the pipeline to handle a request.

Note: adding a [Behavior] attribute to a handler will disregard all assembly-wide behaviors for that handler, so any global behaviors necessary must be independently added to the handler override behaviors list.

Behavior Constraints​

A constraint can be added to a behavior by using:

public sealed class LoggingBehavior<TRequest, TResponse>
    : Behavior<TRequest, TResponse>
    where TRequest : IRequestConstraint
    where TResponse : IResponseConstraint

When a pipeline is generated, all potential behaviors are evaluated against the request and response types, and if either type does not match a given constraint, the behavior is not added to the generated pipeline.

Registering with IServiceCollection​

Immediate.Handlers supports Microsoft.Extensions.DependencyInjection.Abstractions directly.

Registering Handlers​

services.AddHandlers();

This registers all classes in the assembly marked with [Handler].

Registering Behaviors​

services.AddBehaviors();

This registers all behaviors referenced in any [Behaviors] attribute.

Using with Swashbuckle​

For Swagger to work the JSON schema generated is required to have unique schemaId's. To achieve this, Swashbuckle uses class names as simple schemaId's. When using Immediate Handlers classes with a controller action inside, you might end up with Swashbuckle stating an error similar to this:

Swashbuckle.AspNetCore.SwaggerGen.SwaggerGeneratorException: Failed to generate schema for type - MyApp.Api.DeleteUser+Command. See inner exception
System.InvalidOperationException: Can't use schemaId "$Command" for type "$MyApp.Api.DeleteUser+Command". The same schemaId is already used for type "$MyApp.Api.CreateUserCommand+Command"

This error indicates Swashbuckle is trying to use two classes named Command from two (or more) different Handlers in different namespaces.

To fix this, you have to define the following options in your SwaggerGen configuration:

builder.Services.AddSwaggerGen( options =>
{
    options.CustomSchemaIds(x => x.FullName?.Replace("+", ".", StringComparison.Ordinal));
});

Performance Comparisons​

All performance benchmarks reported use the following environment:

// * Summary *

BenchmarkDotNet v0.13.12, Windows 11 (10.0.22621.3007/22H2/2022Update/SunValley2)
12th Gen Intel Core i7-12700H, 1 CPU, 20 logical and 14 physical cores
.NET SDK 8.0.101
  [Host]     : .NET 8.0.1 (8.0.123.58001), X64 RyuJIT AVX2
  DefaultJob : .NET 8.0.1 (8.0.123.58001), X64 RyuJIT AVX2

Benchmarks.Simple​

This benchmark tests the various mediator implementations with a single request/response handler.

MethodMeanErrorRatioRankAllocated
SendRequest_Baseline0.7701 ns0.0180 ns1.001-
SendRequest_IHandler15.6780 ns0.0476 ns20.362-
SendRequest_ImmediateHandler16.6023 ns0.0561 ns21.563-
SendRequest_Mediator27.2993 ns0.4269 ns35.494-
SendRequest_IMediator31.3420 ns0.1006 ns40.645-
SendRequest_MediatR68.3384 ns0.3453 ns88.736240 B

Benchmarks.Large​

This benchmark tests the various mediator implementations in the face of 999 request/response handlers.

MethodMeanErrorRatioRankAllocated
SendRequest_Baseline0.5656 ns0.0252 ns1.001-
SendRequest_ImmediateHandler15.4346 ns0.0516 ns27.342-
SendRequest_IHandler16.0959 ns0.0552 ns28.503-
SendRequest_Mediator27.4104 ns0.0449 ns48.544-
SendRequest_MediatR80.0953 ns0.4749 ns141.835240 B
SendRequest_IMediator435.3890 ns1.6399 ns771.016-

Benchmarks.Behaviors​

This benchmark tests a more realistic scenario of using 1 behavior and 1 service.

MethodMeanErrorRatioRankAllocated
SendRequest_Baseline56.71 ns0.174 ns1.00140 B
SendRequest_IHandler78.90 ns0.304 ns1.39240 B
SendRequest_ImmediateHandler80.02 ns0.288 ns1.41340 B
SendRequest_Mediator101.23 ns0.263 ns1.78440 B
SendRequest_IMediator104.92 ns0.297 ns1.85540 B
SendRequest_MediatR201.27 ns1.023 ns3.556560 B

About​

note

Generating mediator like handlers

How to use​

Example ( source csproj, source files )​

This is the CSharp Project that references Immediate.Handlers

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
    <PropertyGroup>
        <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
        <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GX</CompilerGeneratedFilesOutputPath>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Immediate.Handlers" Version="1.6.1" />
        <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="7.0.0" />
        <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.1" />        
    </ItemGroup>

</Project>

Generated Files​

Those are taken from $(BaseIntermediateOutputPath)\GX

using Microsoft.Extensions.DependencyInjection;

#pragma warning disable CS1591

partial class PingHandler
{
    public sealed partial class Handler : global::Immediate.Handlers.Shared.IHandler<global::Ping, global::Pong>
    {
        private readonly global::PingHandler.HandleBehavior _handleBehavior;
        private readonly global::LoggingBehavior<global::Ping, global::Pong> _loggingBehavior;

        public Handler(
            global::PingHandler.HandleBehavior handleBehavior,
            global::LoggingBehavior<global::Ping, global::Pong> loggingBehavior
        )
        {
            var handlerType = typeof(PingHandler);

            _handleBehavior = handleBehavior;

            _loggingBehavior = loggingBehavior;
            _loggingBehavior.HandlerType = handlerType;

            _loggingBehavior.SetInnerHandler(_handleBehavior);
        }

        public async global::System.Threading.Tasks.ValueTask<global::Pong> HandleAsync(
            global::Ping request,
            global::System.Threading.CancellationToken cancellationToken = default
        )
        {
            return await _loggingBehavior
                .HandleAsync(request, cancellationToken)
                .ConfigureAwait(false);
        }
    }

    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
    public sealed class HandleBehavior : global::Immediate.Handlers.Shared.Behavior<global::Ping, global::Pong>
    {

        public HandleBehavior(
        )
        {
        }

        public override async global::System.Threading.Tasks.ValueTask<global::Pong> HandleAsync(
            global::Ping request,
            global::System.Threading.CancellationToken cancellationToken
        )
        {
            return await global::PingHandler
                .HandleAsync(
                    request
                    , cancellationToken
                )
                .ConfigureAwait(false);
        }
    }

    [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
    public static IServiceCollection AddHandlers(
        IServiceCollection services,
        ServiceLifetime lifetime = ServiceLifetime.Scoped
    )
    {
        services.Add(new(typeof(global::PingHandler.Handler), typeof(global::PingHandler.Handler), lifetime));
        services.Add(new(typeof(global::Immediate.Handlers.Shared.IHandler<global::Ping, global::Pong>), typeof(global::PingHandler.Handler), lifetime));
        services.Add(new(typeof(global::PingHandler.HandleBehavior), typeof(global::PingHandler.HandleBehavior), lifetime));
        return services;
    }
}

Usefull​

Download Example (.NET C# )​

tip

Download Example project Immediate.Handlers

Share Immediate.Handlers​

https://ignatandrei.github.io/RSCG_Examples/v2/docs/Immediate.Handlers

In the same category (Mediator) - 2 other generators​

DeeDee​

Mediator​