Workleap.Extensions.MediatR

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

• Activity-based OpenTelemetry instrumentation
• High-performance logging with Debug log level
• Data annotations support for request validation, similar to ASP.NET Core model validation
• Application Insights instrumentation (in a separate NuGet package)
• CQRS conventions and MediatR best practices with Roslyn analyzers

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);

MediatR License Configuration

This library automatically handles MediatR license configuration. The license key can be provided through:

1. Environment variable: Set the MEDIATR_LICENSE_KEY environment variable
2. Application configuration: Add the MEDIATR_LICENSE_KEY key to your configuration (e.g., appsettings.json, user secrets, etc.)

Using environment variable

# Set environment variable
export MEDIATR_LICENSE_KEY="your-license-key-here"

Using appsettings.json

{
  "MEDIATR_LICENSE_KEY": "your-license-key-here"
}

Manual configuration

You can also set the license key manually using the configuration overload:

builder.Services.AddMediator(
    cfg => cfg.LicenseKey = "your-license-key-here",
    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/workleap/gsoft-license/blob/master/LICENSE.