Allow Custom Registration of INotificationHandler without Duplicate Registrations

[gentledepp]

Allow Custom Registration of INotificationHandler without Duplicate Registrations

Problem Description

Currently, when using Mediator, developers cannot register their INotificationHandler<T> implementations manually without causing duplicate service registrations. If you register a handler yourself and then call services.AddMediator(...), the handler gets registered twice in the DI container.

Additionally, calling services.AddMediator() first and then attempting to manually register handlers doesn't work either, because Mediator uses factory functions (GetRequiredService<T>()) rather than direct type registrations for notification handlers.

Current Behavior

// Scenario 1: Manual registration first (causes duplicates)
services.AddScoped<INotificationHandler<MyNotification>, MyNotificationHandler>();
services.AddMediator(); // Results in duplicate registration

// Scenario 2: AddMediator first (doesn't work due to factory pattern)
services.AddMediator(); 
services.AddScoped<INotificationHandler<MyNotification>, MyNotificationHandler>(); // Again duplicate registration

// Scenario 3: Attempt to override after AddMediator (impossible due to factory registration)
services.AddMediator();
// Try to find and remove auto-registration to replace with custom lifetime
var existingHandler = services.FirstOrDefault(s => 
    s.ServiceType == typeof(INotificationHandler<MyNotification>) && 
    s.ImplementationType == typeof(MyNotificationHandler)); // This returns null!
// existingHandler is null because ImplementationType is null for factory registrations
// The actual registration uses: sp => sp.GetRequiredService<MyNotificationHandler>()

Proposed Solutions

I see two potential approaches to resolve this issue:

Option 1: Roslyn Analyzer (Less Preferred)

Create a Roslyn analyzer that emits compilation errors when developers attempt to manually register INotificationHandler<T> implementations.

Option 2: Smart Registration Check (Preferred)

Modify the Mediator registration logic to check for existing handler registrations before adding new ones.

Preferred Implementation

My preferred solution would implement the following behavior:

1. Allow manual handler registration with any desired lifetime (Transient, Scoped, Singleton)
2. Smart duplicate detection in services.AddMediator(...):
   • Check if a service for the given handler type and implementation type is already registered
   • If already registered → ignore it
   • If not registered → register with default lifetime

Code Examples

Desired Usage Pattern

public class MyNotificationHandler : INotificationHandler<OrderCreated>
{
    public Task Handle(OrderCreated notification, CancellationToken cancellationToken)
    {
        // Handle the notification
        return Task.CompletedTask;
    }
}

// In Program.cs or Startup.cs
services.AddSingleton<INotificationHandler<OrderCreated>, MyNotificationHandler>(); // Custom lifetime
services.AddScoped<INotificationHandler<CustomerUpdated>, CustomerUpdatedHandler>(); // Custom lifetime

// This should not duplicate the manually registered handlers
services.AddMediator(options => 
{
    options.DefaultHandlerLifetime = ServiceLifetime.Transient; // Default for auto-registered handlers
});

Implementation Logic (Based on Generated Code Analysis)

Looking at the actual generated code, the current registration pattern for notification handlers is:

// 1. Register the concrete handler implementation
services.TryAdd(new ServiceDescriptor(typeof(MyNotificationHandler), typeof(MyNotificationHandler), ServiceLifetime.Singleton));

// 2. Register the interface using a factory that resolves the concrete type
services.Add(new ServiceDescriptor(typeof(INotificationHandler<MyNotification>), 
    sp => sp.GetRequiredService<MyNotificationHandler>(), ServiceLifetime.Singleton));

The proposed smart registration logic would need to:

/// <summary>
/// Enhanced registration method that respects existing handler registrations
/// while maintaining factory pattern compatibility
/// </summary>
public static IServiceCollection AddMediator(this IServiceCollection services, Action<MediatorOptions> configure = null)
{
    var options = new MediatorOptions();
    configure?.Invoke(options);

    // Register core Mediator services first...
    RegisterMediatorCore(services);

    // Build cache of existing registrations for efficient lookup
    var existingRegistrations = BuildRegistrationCache(services);

    foreach (var handlerInfo in discoveredHandlers)
    {
        var registrationKey = new ServiceRegistrationKey(handlerInfo.ConcreteType, handlerInfo.ConcreteType);
        
        if (!existingRegistrations.TryGetValue(registrationKey, out var existingDescriptor))
        {
            // Register concrete handler with default lifetime if not already present
            services.TryAdd(new ServiceDescriptor(
                handlerInfo.ConcreteType, 
                handlerInfo.ConcreteType, 
                options.DefaultHandlerLifetime));
            existingDescriptor = new ServiceDescriptor(handlerInfo.ConcreteType, handlerInfo.ConcreteType, options.DefaultHandlerLifetime);
        }
        // If already registered, respect the existing registration and its lifetime

        // Always register the interface mapping using factory pattern
        // This overwrites any direct interface registrations (which wouldn't work anyway)
        services.Add(new ServiceDescriptor(
            handlerInfo.InterfaceType,
            sp => sp.GetRequiredService(handlerInfo.ConcreteType),
            existingDescriptor.Lifetime));
    }

    return services;
}

/// <summary>
/// Builds a dictionary cache of existing service registrations for efficient lookup
/// </summary>
/// <param name="services">The service collection to cache</param>
/// <returns>Dictionary with ServiceRegistrationKey as key and ServiceDescriptor as value</returns>
private static Dictionary<ServiceRegistrationKey, ServiceDescriptor> BuildRegistrationCache(IServiceCollection services)
{
    var cache = new Dictionary<ServiceRegistrationKey, ServiceDescriptor>();
    
    foreach (var service in services)
    {
        if (service.ImplementationType != null)
        {
            var key = new ServiceRegistrationKey(service.ServiceType, service.ImplementationType);
            cache[key] = service;
        }
    }
    
    return cache;
}

/// <summary>
/// Composite key for service registration lookup combining ServiceType and ImplementationType
/// </summary>
private readonly struct ServiceRegistrationKey : IEquatable<ServiceRegistrationKey>
{
    public Type ServiceType { get; }
    public Type ImplementationType { get; }

    public ServiceRegistrationKey(Type serviceType, Type implementationType)
    {
        ServiceType = serviceType;
        ImplementationType = implementationType;
    }

    public bool Equals(ServiceRegistrationKey other) =>
        ServiceType == other.ServiceType && ImplementationType == other.ImplementationType;

    public override bool Equals(object obj) =>
        obj is ServiceRegistrationKey other && Equals(other);

    public override int GetHashCode() =>
        HashCode.Combine(ServiceType, ImplementationType);
}

Benefits

1. Resolves Issue [Suggestion] Option to control handler lifetime #60: Provides flexibility for custom handler lifetimes while maintaining default behavior
2. Developer Control: Allows explicit lifetime management for specific handlers
3. Backward Compatibility: Existing code continues to work unchanged
4. Clean Registration: No duplicate services in the DI container
5. Performance Optimized: Uses dictionary caching for efficient registration lookups

Disadvantages

1. Performance: since we need to create a dictionary and loop through all handlers, the startup performance would be worse of course. But maybe this feature could be configured using a new "AddMediator" option. (i.e. bool AllowExplicitHandlerRegistrations If that would be false, the roslyn analyzer that provides a build error if you'd register handlers yourself would again come in handy ;-)

Questions

1. Is this approach technically feasible with the current architecture?
2. Would you prefer a different detection mechanism for existing registrations?
3. Should there be any configuration options to control this behavior?

---

This enhancement would significantly improve the developer experience when working with custom handler lifetimes and DI container management.

[martinothamar]

Hi, thanks for looking at this and going into such detail. Reading the code I sort of realized there's a dealbreaker here

• Any assumption about the servicelifetime is no longer safe (i.e. places we use ServiceLifetimeIsTransient/ServiceLifetimeIsScoped/ServiceLifetimeIsSingleton etc in code gen the template)
• Moving those checks to runtime would complicate the implementation significantly and/or worsen the performance

I think the feature of having different handler lifetimes does not justify the cost here.

Reading up a bit on the history here, I think if people have heterogeneous handler lifetimes across a whole application I consider 2 migration paths acceptable

• Migrate everything in 1 go
• Gradual migration by keeping 2 solutions active (like we traditionally do in large scale architecture rework, this is messy but sometimes what we have to do)

Of course there is the option to not migrate at all 😄

TLDR: I don't think the benefits of the outcome here justifies the means (worse perf, significantly more complicated internals)

[gentledepp]

hmmm... sounds bad.
Well, it was worth a try ;-)

And what about the ISingletonNotificationHandler interface approach?
Would that work, or do you also see major issues there?

People use mediators for very different applications.
We for example use it for our client apps, which run on Android and iOS.
So, while memory usage/perf is very important to us, sometimes we need stateful services (scoped/transient)
So there is definitely a need for this.

Sure, we could create only singleton handlers, then manually create a service scope and create the services with that, but that would be additional manual work and we developers are lazy by nature ;-)

Thanks for looking into it!

[martinothamar]

Well, it was worth a try ;-)

Indeed, thanks for that 🙏

And what about the ISingletonNotificationHandler interface approach?

Unfortunately same thing really, the codegen would have to consider on a handler-by-handler basis instead of just evaluating the MediatorOptions configuration. It would be a ton of branching in the codegen and I personally find it hard enough to maintain/develop as it is.

So, while memory usage/perf is very important to us, sometimes we need stateful services (scoped/transient)

I don't disagree with this. We all (probably) need state somewhere, but IMO there are better solutions than relying on DI scope to manage the lifecycle/scoping of that state. In other words, I believe we have two separate concerns here

• Structuring application logic (behavior, code) - this is where the mediator pattern is relevant
• Controlling state scoping and lifecycle - this is application/domain specific

If we ask the mediator pattern implementation to solve both concerns I believe we are complecting things.

To illustrate through an example, here is a PR where we imagine there is some state kept for each HTTP request: #227

It's a very artificial example, but I think the general approach can be adapted to practically anything

• Per HTTP request (multiple message could refer to the same context, would need thread synchronization in that case)
• Per user interaction
• Per message

In that specific example, if we added the state to some Scoped service (which would force the handler and behavior to also be Scoped), the runtime would have to allocate memory for all these object every single request. The impact of the Scoped approach becomes even worse when you consider large applications where perhaps many handlers and behaviors don't even any scoped state in the first place. In the sample as currently implemented, the memory cost of the state keeping is dependent only on the size of the state itself (no one else pays the price).

It's of course also possible to do ambient state like the AsyncLocal<> based approach which is what IHttpContextAccessor, but I try to avoid that generally as well