Cayd.AspNetCore.Mediator 2.0.0

About

This is a mediator library that handles request-handler-response and request-stream flows for ASP.NET Core. It automatically matches requests with corresponding handlers and streams, and it supports interceptors for all requets and/or specific ones.

Quick Start

Request-Handler-Response

After installing the package, you can set up your own request-handler-response flow by using IAsyncRequest<> and IAsyncHandler<,> interfaces. After creating the classes, you need to register them for the dependency injection, so that you can use the SendAsync method of the IMediator interface.

• Creating Classes:

using Cayd.AspNetCore.Mediator.Abstractions;

public class MyRequest : IAsyncRequest<MyResponse>
{
    // ... properties of the request
}

public class MyHandler : IAsyncHandler<MyRequest, MyResponse>
{
    // Example dependency injection
    private readonly ILogger<MyHandler> _logger;

    // You can inject dependencies if needed
    public MyHandler(ILogger<MyHandler> logger)
    {
        _logger = logger;  // example
    }

    public async Task<MyResponse> HandleAsync(MyRequest request, CancellationToken cancellationToken)
    {
        // ... handle the request and return the corresponding response
    }
}

public class MyResponse
{
    // ... properties of the response
}

• Adding Mediator and Flows:

/**
 * Minimal API - Program.cs
 */
using Cayd.AspNetCore.Mediator.DependencyInjection;

builder.Services.AddMediator(config =>
{
    // Add flows from one assembly
    config.AddFlowsFromAssembly(Assembly.GetAssembly(typeof(MyRequest)!));

    // ... or from multiple assemblies
    config.AddFlowsFromAssemblies(Assembly.GetAssembly(typeof(MyRequest))!,
        Assembly.GetAssembly(typeof(MyClassInAnotherAssembly))!);
});


/**
 * .NET 5 - Startup.cs
 */
using Cayd.AspNetCore.Mediator.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMediator(config =>
        {
            // Add flows from one assembly
            config.AddFlowsFromAssembly(Assembly.GetAssembly(typeof(MyRequest)!));

            // ... or from multiple assemblies
            config.AddFlowsFromAssemblies(Assembly.GetAssembly(typeof(MyRequest))!,
                Assembly.GetAssembly(typeof(MyClassInAnotherAssembly))!);
        });
    }
}

• Sending Request:

using Cayd.AspNetCore.Mediator;

[ApiController]
public class MyController : ControllerBase
{
    private readonly IMediator _mediator;

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

    [HttpGet("example")]
    public async Task<IActionResult> Example()
    {
        var response = await _mediator.SendAsync(new MyRequest()
        {
            // ... properties of the request
        });

        // ... handle response
    }

    [HttpGet("example-with-cancellation")]
    public async Task<IActionResult> ExampleCancellation(CancellationToken cancellationToken)
    {
        var response = await _mediator.SendAsync(new MyRequest()
        {
            // ... properties of the request
        }, cancellationToken);

        // ... handle response
    }
}

Request-Stream

For request-stream flows, you need to use IAsyncStreamRequest<> and IAsyncStreamHandler<,> interfaces instead. After creating the required classes, you then need to register them for the dependency injection in the same way you do for request-handler-response flows. The usage is also the same as request-handler-response flows.

• Creating Classes:

using Cayd.AspNetCore.Mediator.Abstractions;

public class MyStreamRequest : IAsyncStreamRequest<MyStreamResponse>
{
    // ... properties of the request
}

public class MyStreamHandler : IAsyncStreamHandler<MyStreamRequest, MyStreamResponse>
{
    // Example dependency injection
    private readonly ILogger<MyStreamHandler> _logger;

    // You can inject dependencies if needed
    public MyStreamHandler(ILogger<MyStreamHandler> logger)
    {
        _logger = logger;  // example
    }

    public async IAsyncEnumerable<MyStreamResponse> HandleAsync(MyRequest request, [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        // ... handle the request and return the corresponding response
    }
}

public class MyStreamResponse
{
    // ... properties of the response
}

NOTE: Do not forget to add the EnumeratorCancellation attribute to the cancellation token in the handler.

• Adding Mediator and Flows:

/**
 * Minimal API - Program.cs
 */
using Cayd.AspNetCore.Mediator.DependencyInjection;

builder.Services.AddMediator(config =>
{
    // Add flows from one assembly
    config.AddFlowsFromAssembly(Assembly.GetAssembly(typeof(MyStreamRequest)!));

    // ... or from multiple assemblies
    config.AddFlowsFromAssemblies(Assembly.GetAssembly(typeof(MyStreamRequest))!,
        Assembly.GetAssembly(typeof(MyClassInAnotherAssembly))!);
});


/**
 * .NET 5 - Startup.cs
 */
using Cayd.AspNetCore.Mediator.DependencyInjection;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMediator(config =>
        {
            // Add flows from one assembly
            config.AddFlowsFromAssembly(Assembly.GetAssembly(typeof(MyStreamRequest)!));

            // ... or from multiple assemblies
            config.AddFlowsFromAssemblies(Assembly.GetAssembly(typeof(MyStreamRequest))!,
                Assembly.GetAssembly(typeof(MyClassInAnotherAssembly))!);
        });
    }
}

• Sending Request:

using Cayd.AspNetCore.Mediator;

[ApiController]
public class MyController : ControllerBase
{
    private readonly IMediator _mediator;

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

    [HttpGet("stream-example")]
    public async IAsyncEnumerable<MyStreamResponse> StreamExample()
    {
        var request = new MyStreamRequest()
        {
            // ... properties of the request
        };

        await foreach (var item in _mediator.SendAsync(request))
        {
            yield return item;
        }
    }

    [HttpGet("stream-example-with-cancellation")]
    public async IAsyncEnumerable<IActionResult> StreamExampleCancellation([EnumeratorCancellation] CancellationToken cancellationToken)
    {
        var request = new MyStreamRequest()
        {
            // ... properties of the request
        };

        await foreach (var item in _mediator.SendAsync(request, cancellationToken))
        {
            yield return item;
        }
    }
}

NOTE: Do not forget to add the EnumeratorCancellation attribute to the cancellation token in the controller.

Customizations & Implementations

You can customize the default request-handler-response or request-stream flow by adding interceptors. For more details, you can check out the GitHub Wiki to learn about the customizations, as well as the implementation of the library in detail.