Notifications¶
A notification is a message with any number of handlers, including none. Use it for events: something happened, and whoever is interested reacts.
Publish¶
using ForkForward.Mediator;
public record OrderPlaced(int OrderId) : INotification;
public class ReserveStock : INotificationHandler<OrderPlaced>
{
public Task Handle(OrderPlaced notification, CancellationToken cancellationToken) => Task.CompletedTask;
}
public class NotifyWarehouse : INotificationHandler<OrderPlaced>
{
public Task Handle(OrderPlaced notification, CancellationToken cancellationToken) => Task.CompletedTask;
}
AddMediator registers every handler it finds. A notification without handlers is published without an error.
Publish(object) does the same for an object whose type is known only at run time; an object that does not
implement INotification ends in an ArgumentException.
Synchronous handlers¶
A handler that does no asynchronous work can derive from NotificationHandler<TNotification> and override a
void method:
public class CountOrders(Statistics statistics) : NotificationHandler<OrderPlaced>
{
protected override void Handle(OrderPlaced notification) => statistics.OrdersPlaced++;
}
One handler for a family of notifications¶
A handler of a base type does not receive notifications of derived types when the container is
Microsoft.Extensions.DependencyInjection, because that container does not resolve variant generic types.
INotificationHandler<OrderEvent> is not called for an OrderShipped : OrderEvent.
Write the handler as an open generic type with a constraint instead. AddMediator registers open generic
notification handlers, and the container closes them for every matching notification:
public abstract record OrderEvent(int OrderId) : INotification;
public record OrderShipped(int OrderId) : OrderEvent(OrderId);
public class AuditOrderEvents<TEvent> : INotificationHandler<TEvent> where TEvent : OrderEvent
{
public Task Handle(TEvent notification, CancellationToken cancellationToken) => Task.CompletedTask;
}
How the handlers are called¶
A notification publisher decides how the handlers run. Two are included:
| Publisher | What it does | When a handler throws |
|---|---|---|
ForeachAwaitPublisher (default) |
Calls the handlers one after the other and awaits each before the next. | The exception ends Publish; the handlers after it do not run. |
TaskWhenAllPublisher |
Starts every handler and awaits them together with Task.WhenAll. |
The others still run to the end; Publish then throws the first exception. A handler that throws before it returns its task, from code that is not async, stops the handlers after it from starting. |
Choose one in the configuration:
using ForkForward.Mediator.NotificationPublishers;
services.AddMediator(cfg =>
{
cfg.RegisterServicesFromAssemblyContaining<Program>();
cfg.NotificationPublisher = new TaskWhenAllPublisher();
});
TaskWhenAllPublisher runs the handlers at the same time. Handlers that share a scoped service which is not
thread-safe, such as an Entity Framework DbContext, must not run in parallel.
A publisher of your own¶
Implement INotificationPublisher. It receives one NotificationHandlerExecutor per handler: the handler object,
and a callback that calls it.
public class LoggingPublisher(ILogger<LoggingPublisher> logger) : INotificationPublisher
{
public async Task Publish(IEnumerable<NotificationHandlerExecutor> handlerExecutors, INotification notification,
CancellationToken cancellationToken)
{
foreach (var executor in handlerExecutors)
{
logger.LogInformation("{Handler} handles {Notification}", executor.HandlerInstance.GetType().Name, notification);
await executor.HandlerCallback(notification, cancellationToken);
}
}
}
Set an instance with cfg.NotificationPublisher = ..., or set cfg.NotificationPublisherType = typeof(LoggingPublisher)
to have the container create it, with its dependencies, in the lifetime given by cfg.Lifetime.
The PublishStrategies sample shows further strategies: in parallel without waiting, in the background, and continuing past failures.