Skip to content

MediatR extensions, behaviors and default configuration.

License

Notifications You must be signed in to change notification settings

gsoft-inc/wl-extensions-mediatr

Repository files navigation

Workleap.Extensions.MediatR

nuget build

This library ensures that MediatR is registered in the dependency injection container as a singleton and also adds several features:

Getting started

Use the AddMediator(params Assembly[] assemblies) extension method on your dependency injection services (IServiceCollection) to automatically register all the MediatR request handlers from a given assembly.

builder.Services.AddMediator(typeof(Program).Assembly /*, [more assemblies...] */);

If you use Application Insights and want to instrument your handlers, you can install the dedicated NuGet package:

builder.Services.AddMediator(typeof(Program).Assembly).AddApplicationInsights();

There are multiple method overloads of AddMediator. For instance, you can override MediatR configuration using this overload that accepts a Action<MediatRServiceConfiguration>:

builder.Services.AddMediator(
    cfg => cfg.NotificationPublisher = new TaskWhenAllPublisher(),
    typeof(Program).Assembly);

Example

// CQRS naming conventions are suggested by a Roslyn analyzer, but it can be disabled
public sealed record SayHelloCommand([property: Required] string To) : IRequest;

public sealed class SayHelloCommandHandler : IRequestHandler<SayHelloCommand>
{
    public Task Handle(SayHelloCommand command, CancellationToken cancellationToken)
    {
        Console.WriteLine($"Hello {command.To}!");
        return Task.CompletedTask;
    }
}

// [...] Retrieve an instance of IMediator or ISender
var mediator = serviceProvider.GetRequiredService<IMediator>();

// - We use the preferred Async-suffixed extension method to put emphasis on the asynchronous aspect of MediatR
// - A Roslyn analyzer suggests to specify a cancellation token, which is most of the time forgotten by developers
await mediator.SendAsync(new SayHelloCommand("world"), CancellationToken.None);

// This throws RequestValidationException because 'SayHelloCommand.To' is marked as required
await mediator.SendAsync(new SayHelloCommand(null!), CancellationToken.None);

Included Roslyn analyzers

Rule ID Category Severity Description
GMDTR01 Naming Warning Name should end with 'Command' or 'Query'
GMDTR02 Naming Warning Name should end with 'CommandHandler' or 'QueryHandler'
GMDTR03 Naming Warning Name should end with 'StreamQuery'
GMDTR04 Naming Warning Name should end with 'StreamQueryHandler'
GMDTR05 Naming Warning Name should end with 'Notification' or 'Event'
GMDTR06 Naming Warning Name should end with 'NotificationHandler' or 'EventHandler'
GMDTR07 Design Warning Use generic method instead
GMDTR08 Design Warning Provide a cancellation token
GMDTR09 Design Warning Handlers should not call other handlers
GMDTR10 Design Warning Handlers should not be public
GMDTR11 Design Warning Use 'AddMediator' extension method instead of 'AddMediatR'
GMDTR12 Design Warning Use method ending with 'Async' instead
GMDTR13 Naming Warning Name should end with 'Handler'

In order to change the severity of one of these diagnostic rules, use a .editorconfig file, for instance:

[*.cs]
dotnet_diagnostic.GMDTR01.severity = none

To learn more about how to configure or suppress code analysis warnings, read this documentation.

Building, releasing and versioning

The project can be built by running Build.ps1. It uses Microsoft.CodeAnalysis.PublicApiAnalyzers to help detect public API breaking changes. Use the built-in roslyn analyzer to ensure that public APIs are declared in PublicAPI.Shipped.txt, and obsolete public APIs in PublicAPI.Unshipped.txt.

A new preview NuGet package is automatically published on any new commit on the main branch. This means that by completing a pull request, you automatically get a new NuGet package.

When you are ready to officially release a stable NuGet package by following the SemVer guidelines, simply manually create a tag with the format x.y.z. This will automatically create and publish a NuGet package for this version.

License

Copyright © 2023, Workleap. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE.