Shuttle.Mediator 21.0.1

Shuttle.Core.Mediator

The Shuttle.Core.Mediator package provides a mediator pattern implementation.

Installation

dotnet add package Shuttle.Core.Mediator

Configuration

Register the IMediator dependency along with all the relevant IParticipant dependencies.

You can register the mediator using IServiceCollection:

services.AddMediator(options =>
{
    options.Sending += async (sender, args) => await Task.CompletedTask;
}).AddParticipantsFrom(assembly);

The AddMediator method returns a MediatorBuilder that can be used to further configure the mediator:

services.AddMediator()
    .AddParticipantsFrom(assembly)
    .AddParticipantsFrom(new[] { assembly1, assembly2 })
    .AddParticipant<Participant>()
    .AddParticipant(participantType)
    
    // The default service lifetime, Scoped, can be explicitly overidden:
    .AddParticipant(participantType, _ => ServiceLifetime.Transient)
    
    // Instance registration
    .AddParticipant(participant)
    
    // Delegate registration
    .AddParticipant(async (UserCreated message, CancellationToken cancellationToken) =>
    {
        await Task.CompletedTask;
    })

    // Delegate registration with dependency injection
    .AddParticipant(async (UserCreated message, IService service, CancellationToken cancellationToken) =>
    {
        await service.DoSomethingAsync(message);
    });

Usage

// Define a message
public class UserCreated
{
    public string UserName { get; set; }
}

// Create participants
public class EmailNotificationParticipant : IParticipant<UserCreated>
{
    public Task HandleAsync(UserCreated message, CancellationToken cancellationToken = default)
    {
        Console.WriteLine($"Sending welcome email to {message.UserName}");
        return Task.CompletedTask;
    }
}

public class AuditLogParticipant : IParticipant<UserCreated>
{
    public Task HandleAsync(UserCreated message, CancellationToken cancellationToken = default)
    {
        Console.WriteLine($"Auditing user creation: {message.UserName}");
        return Task.CompletedTask;
    }
}

// Send the message
await mediator.SendAsync(new UserCreated { UserName = "john.doe" });

IMediator

The core interface is the IMediator interface and the default implementation provided is the Mediator class.

Participants types are instantiated from the IServiceProvider instance. This means that it depends on how you register the type as to the behavior.

Task SendAsync(object message, CancellationToken cancellationToken = default);

The SendAsync method will find all participants that implement the IParticipant<T> with the type T of the message type that you are sending.

IParticipant implementations

public interface IParticipant<in T>
{
    Task HandleAsync(T message, CancellationToken cancellationToken = default);
}

A participant would handle the message that is sent using the mediator. There may be any number of participants that process the message, but there must be at least one participant or delegate registered for the message type.

Design philosophy

There are no request/response semantics and the design philosophy here is that the message encapsulates the state that is passed along in a pipes & filters approach.

MediatorOptions

The MediatorOptions class provides the following events:

• Sending: An AsyncEvent<SendEventArgs> that is raised before a message is sent to participants.
• Sent: An AsyncEvent<SendEventArgs> that is raised after a message has been sent to all participants.

Considerations

If you have a rather predictable sequential workflow and you require something with faster execution then you may wish to consider the Shuttle.Core.Pipelines package.

Performing a benchmark for your use-case would be able to indicate the more suitable option.