Adding open generic handler support

Author: ejsmith

docs/guide/handler-conventions.md

@@ -173,6 +173,52 @@ public class UserHandler
 
 **Note:** Handlers are singleton by default. Constructor dependencies are resolved once and shared across all invocations.
 
+### Open Generic Handlers
+
+Handlers can be declared as open generic classes and will be automatically closed for the concrete message type at runtime. This lets you build reusable handler logic that applies to many message types.
+
+```csharp
+// Generic command definitions
+public record UpdateEntity<T>(T Entity);
+public record UpdateRelation<TLeft, TRight>(TLeft Left, TRight Right);
+
+// Open generic handler (single generic parameter)
+public class EntityHandler<T>
+{
+    public Task HandleAsync(UpdateEntity<T> command, CancellationToken ct)
+    {
+        // process update for entity of type T
+        return Task.CompletedTask;
+    }
+}
+
+// Open generic handler (two generic parameters)
+public class RelationHandler<TLeft, TRight>
+{
+    public Task HandleAsync(UpdateRelation<TLeft, TRight> command, CancellationToken ct)
+    {
+        return Task.CompletedTask;
+    }
+}
+
+// Usage
+await mediator.InvokeAsync(new UpdateEntity<Order>(order));
+await mediator.InvokeAsync(new UpdateRelation<User, Role>(user, role));
+```
+
+Guidelines:
+
+- The handler class, not the method, must be generic (generic handler methods are not currently supported).
+- The message type must use the handler's generic parameters (e.g., `UpdateEntity<T>` in `EntityHandler<T>`).
+- Open generic handlers participate in normal invocation rules: exactly one match required for `Invoke / InvokeAsync`; multiple open generics for the same message generic definition will cause an error when invoking (publish supports multiple).
+
+Performance Notes:
+
+- First invocation of a new closed generic combination incurs a small reflection cost; subsequent calls are cached.
+- Static middleware resolution still applies and middleware can itself be generic.
+
+If you need a custom behavior per entity type later, you can still add a concrete handler; the more specific (closed) handler will coexist.
+
 ## Multiple Handlers in One Class
 
 A single class can handle multiple message types:

src/Foundatio.Mediator.Abstractions/Mediator.cs

@@ -194,7 +194,32 @@ private PublishAsyncDelegate[] GetAllApplicableHandlers(object message)
     [DebuggerStepThrough]
     private IEnumerable<HandlerRegistration> GetHandlersForType(Type type)
     {
-        return _serviceProvider.GetKeyedServices<HandlerRegistration>(MessageTypeKey.Get(type)).ToArray();
+        var list = _serviceProvider.GetKeyedServices<HandlerRegistration>(MessageTypeKey.Get(type)).ToList();
+        if (list.Count > 0)
+            return list;
+
+        // attempt open generic resolution
+        if (type.IsGenericType)
+        {
+            var genericDefinition = type.GetGenericTypeDefinition();
+            var registration = _openGenericClosedCache.GetOrAdd(type, t =>
+            {
+                var descriptors = _serviceProvider.GetServices<OpenGenericHandlerDescriptor>();
+                foreach (var descriptor in descriptors)
+                {
+                    if (descriptor.MessageTypeGenericDefinition == genericDefinition)
+                    {
+                        return ConstructClosedRegistration(t, descriptor);
+                    }
+                }
+                return null;
+            });
+
+            if (registration != null)
+                return new[] { registration };
+        }
+
+        return list;
     }
 
     private static readonly ConcurrentDictionary<Type, object> _middlewareCache = new();
@@ -229,5 +254,43 @@ public static T GetOrCreateMiddleware<T>(IServiceProvider serviceProvider) where
     private static readonly ConcurrentDictionary<(Type MessageType, Type ResponseType), InvokeResponseDelegate> _invokeWithResponseCache = new();
 
     private static readonly ConcurrentDictionary<Type, PublishAsyncDelegate[]> _publishCache = new();
+    private static readonly ConcurrentDictionary<Type, HandlerRegistration?> _openGenericClosedCache = new();
+
+    private HandlerRegistration? ConstructClosedRegistration(Type closedMessageType, OpenGenericHandlerDescriptor descriptor)
+    {
+        try
+        {
+            var typeArgs = closedMessageType.GetGenericArguments();
+            var wrapperClosed = descriptor.WrapperGenericTypeDefinition.MakeGenericType(typeArgs);
+            var asyncMethod = wrapperClosed.GetMethod("UntypedHandleAsync", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
+            if (asyncMethod == null)
+                return null;
+
+            HandleAsyncDelegate asyncDelegate = (IMediator mediator, object message, CancellationToken ct, Type? returnType) =>
+            {
+                var taskObj = asyncMethod.Invoke(null, new object?[] { mediator, message, ct, returnType });
+                return taskObj is ValueTask<object?> vt ? vt : (ValueTask<object?>)taskObj!;
+            };
+
+            HandleDelegate? syncDelegate = null;
+            if (!descriptor.IsAsync)
+            {
+                var syncMethod = wrapperClosed.GetMethod("UntypedHandle", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
+                if (syncMethod != null)
+                {
+                    syncDelegate = (IMediator mediator, object message, CancellationToken ct, Type? returnType) =>
+                    {
+                        return syncMethod.Invoke(null, new object?[] { mediator, message, ct, returnType });
+                    };
+                }
+            }
+
+            return new HandlerRegistration(MessageTypeKey.Get(closedMessageType), wrapperClosed.FullName ?? wrapperClosed.Name, asyncDelegate, syncDelegate, descriptor.IsAsync);
+        }
+        catch
+        {
+            return null;
+        }
+    }
 
 }

src/Foundatio.Mediator.Abstractions/MediatorExtensions.cs

@@ -63,6 +63,16 @@ private static bool IsAssemblyMarkedWithFoundatioHandlerModule(Assembly assembly
     }
 }
 
+public static class MediatorServiceCollectionExtensions
+{
+    public static IServiceCollection AddHandler(this IServiceCollection services, HandlerRegistration registration)
+    {
+        services.AddKeyedSingleton(registration.MessageTypeName, registration);
+        services.AddSingleton(registration);
+        return services;
+    }
+}
+
 public class MediatorConfigurationBuilder
 {
     private readonly MediatorConfiguration _configuration = new MediatorConfiguration();

src/Foundatio.Mediator.Abstractions/OpenGenericHandlerDescriptor.cs

@@ -0,0 +1,30 @@
+namespace Foundatio.Mediator;
+
+/// <summary>
+/// Descriptor for an open generic handler method. Used to construct concrete <see cref="HandlerRegistration"/> instances at runtime
+/// when a closed generic message type is invoked or published.
+/// </summary>
+public sealed class OpenGenericHandlerDescriptor
+{
+    public OpenGenericHandlerDescriptor(Type messageTypeGenericDefinition, Type wrapperGenericTypeDefinition, bool isAsync)
+    {
+        MessageTypeGenericDefinition = messageTypeGenericDefinition ?? throw new ArgumentNullException(nameof(messageTypeGenericDefinition));
+        WrapperGenericTypeDefinition = wrapperGenericTypeDefinition ?? throw new ArgumentNullException(nameof(wrapperGenericTypeDefinition));
+        IsAsync = isAsync;
+    }
+
+    /// <summary>
+    /// The open generic (generic type definition) of the message type (e.g. typeof(UpdateEntity&lt;&gt;)).
+    /// </summary>
+    public Type MessageTypeGenericDefinition { get; }
+
+    /// <summary>
+    /// The open generic (generic type definition) of the generated handler wrapper static class.
+    /// </summary>
+    public Type WrapperGenericTypeDefinition { get; }
+
+    /// <summary>
+    /// Indicates if the handler method should be treated as async.
+    /// </summary>
+    public bool IsAsync { get; }
+}

src/Foundatio.Mediator/DIRegistrationGenerator.cs

@@ -58,39 +58,50 @@ public static void Execute(SourceProductionContext context, List<HandlerInfo> ha
                     source.AppendLine($"services.{lifetimeMethod}<{handler.FullName}>();");
             }
 
-            source.AppendLine($"AddMediatorHandler(services, new HandlerRegistration(");
-            source.AppendLine($"        MessageTypeKey.Get(typeof({handler.MessageType.FullName})),");
-            source.AppendLine($"        \"{handlerClassName}\",");
-
-            if (handler.IsAsync)
+            if (handler.IsGenericHandlerClass)
             {
-                source.AppendLine($"        {handlerClassName}.UntypedHandleAsync,");
-                source.AppendLine($"        null,");
+                // open generic registration
+                if (handler.MessageGenericTypeDefinitionFullName != null && handler.GenericArity > 0)
+                {
+                    // Build unbound generic typeof expressions
+                    var wrapperTypeOf = handler.GenericArity switch
+                    {
+                        1 => $"typeof({handlerClassName}<>)",
+                        2 => $"typeof({handlerClassName}<,>)",
+                        3 => $"typeof({handlerClassName}<,,>)",
+                        4 => $"typeof({handlerClassName}<,,,>)",
+                        _ => $"typeof({handlerClassName}<>)" // fallback
+                    };
+                    var msgTypeOf = $"typeof({handler.MessageGenericTypeDefinitionFullName})";
+                    source.AppendLine($"// Open generic handler registration for {handler.MessageGenericTypeDefinitionFullName}");
+                    source.AppendLine($"services.AddSingleton(new OpenGenericHandlerDescriptor({msgTypeOf}, {wrapperTypeOf}, {handler.IsAsync.ToString().ToLower()}));");
+                }
             }
             else
             {
-                source.AppendLine($"        (mediator, message, cancellationToken, responseType) => new ValueTask<object?>({handlerClassName}.UntypedHandle(mediator, message, cancellationToken, responseType)),");
-                source.AppendLine($"        {handlerClassName}.UntypedHandle,");
+                source.AppendLine($"services.AddHandler(new HandlerRegistration(");
+                source.AppendLine($"        MessageTypeKey.Get(typeof({handler.MessageType.FullName})),");
+                source.AppendLine($"        \"{handlerClassName}\",");
+
+                if (handler.IsAsync)
+                {
+                    source.AppendLine($"        {handlerClassName}.UntypedHandleAsync,");
+                    source.AppendLine($"        null,");
+                }
+                else
+                {
+                    source.AppendLine($"        (mediator, message, cancellationToken, responseType) => new ValueTask<object?>({handlerClassName}.UntypedHandle(mediator, message, cancellationToken, responseType)),");
+                    source.AppendLine($"        {handlerClassName}.UntypedHandle,");
+                }
+
+                source.AppendLine($"        {handler.IsAsync.ToString().ToLower()}));");
+                source.AppendLine();
             }
-
-            source.AppendLine($"        {handler.IsAsync.ToString().ToLower()}));");
-
-            source.AppendLine();
         }
 
         source.DecrementIndent();
         source.AppendLine("}");
 
-        source.AppendLine()
-            .AppendLines($$"""
-                           [DebuggerStepThrough]
-                           private static void AddMediatorHandler(IServiceCollection services, HandlerRegistration registration)
-                           {
-                               services.AddKeyedSingleton(registration.MessageTypeName, registration);
-                               services.AddSingleton(registration);
-                           }
-                           """);
-
         source.DecrementIndent();
         source.AppendLine("}");
 

src/Foundatio.Mediator/HandlerAnalyzer.cs

@@ -69,8 +69,7 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
         var semanticModel = context.SemanticModel;
 
         if (semanticModel.GetDeclaredSymbol(classDeclaration) is not { } classSymbol
-            || classSymbol.HasIgnoreAttribute(context.SemanticModel.Compilation)
-            || classSymbol.IsGenericType)
+            || classSymbol.HasIgnoreAttribute(context.SemanticModel.Compilation))
             return [];
 
         // Exclude generated handler classes in Foundatio.Mediator namespace with names ending in "_Handler"
@@ -101,7 +100,7 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
                 continue;
 
             if (handlerMethod.IsGenericMethod)
-                continue;
+                continue; // do not support generic handler methods, only generic classes
 
             var messageParameter = handlerMethod.Parameters[0];
             var messageType = messageParameter.Type;
@@ -120,6 +119,18 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
                 });
             }
 
+            string? messageGenericDefinition = null;
+            int messageGenericArity = 0;
+            if (messageType is INamedTypeSymbol namedMsg && namedMsg.IsGenericType)
+            {
+                messageGenericDefinition = namedMsg.ConstructUnboundGenericType().ToDisplayString();
+                messageGenericArity = namedMsg.TypeArguments.Length;
+            }
+
+            var genericParamNames = classSymbol.IsGenericType
+                ? classSymbol.TypeParameters.Select(tp => tp.Name).ToArray()
+                : Array.Empty<string>();
+
             handlers.Add(new HandlerInfo
             {
                 Identifier = classSymbol.Name.ToIdentifier(),
@@ -128,6 +139,11 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
                 MessageType = TypeSymbolInfo.From(messageType, context.SemanticModel.Compilation),
                 ReturnType = TypeSymbolInfo.From(handlerMethod.ReturnType, context.SemanticModel.Compilation),
                 IsStatic = handlerMethod.IsStatic,
+                IsGenericHandlerClass = classSymbol.IsGenericType,
+                GenericArity = classSymbol.IsGenericType ? classSymbol.TypeParameters.Length : 0,
+                GenericTypeParameters = new(genericParamNames),
+                MessageGenericTypeDefinitionFullName = messageGenericDefinition,
+                MessageGenericArity = messageGenericArity,
                 Parameters = new(parameterInfos.ToArray()),
                 CallSites = [],
                 Middleware = [],

src/Foundatio.Mediator/HandlerGenerator.cs

@@ -65,7 +65,15 @@ namespace Foundatio.Mediator;
         source.AppendLine();
         source.AddGeneratedCodeAttribute();
         source.AppendLine("[ExcludeFromCodeCoverage]");
-        source.AppendLine($"internal static class {wrapperClassName}");
+        if (handler.IsGenericHandlerClass && handler.GenericArity > 0 && handler.GenericTypeParameters.Length == handler.GenericArity)
+        {
+            var genericParams = string.Join(", ", handler.GenericTypeParameters);
+            source.AppendLine($"internal static class {wrapperClassName}<{genericParams}>");
+        }
+        else
+        {
+            source.AppendLine($"internal static class {wrapperClassName}");
+        }
         source.AppendLine("{");
 
         source.IncrementIndent();

src/Foundatio.Mediator/Models/HandlerInfo.cs

@@ -15,6 +15,11 @@ internal readonly record struct HandlerInfo
     public EquatableArray<ParameterInfo> Parameters { get; init; }
     public EquatableArray<CallSiteInfo> CallSites { get; init; }
     public EquatableArray<MiddlewareInfo> Middleware { get; init; }
+    public bool IsGenericHandlerClass { get; init; }
+    public int GenericArity { get; init; }
+    public EquatableArray<string> GenericTypeParameters { get; init; }
+    public string? MessageGenericTypeDefinitionFullName { get; init; }
+    public int MessageGenericArity { get; init; }
 }
 
 internal readonly record struct ParameterInfo

tests/Foundatio.Mediator.Tests/OpenGeneric/OpenGenericHandlerTests.cs

@@ -0,0 +1,53 @@
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.DependencyInjection;
+using Xunit;
+
+namespace Foundatio.Mediator.Tests.OpenGeneric;
+
+public record UpdateEntity<T>(T Entity) : ICommand;
+public record UpdateEntityPair<T1, T2>(T1 First, T2 Second) : ICommand;
+
+public class EntityHandler<T>
+{
+    public Task HandleAsync(UpdateEntity<T> command, CancellationToken cancellationToken)
+    {
+        // no-op
+        return Task.CompletedTask;
+    }
+}
+
+public class EntityPairHandler<T1, T2>
+{
+    public Task HandleAsync(UpdateEntityPair<T1, T2> command, CancellationToken cancellationToken)
+    {
+        return Task.CompletedTask;
+    }
+}
+
+public class OpenGenericHandlerTests
+{
+    [Fact]
+    public async Task CanInvokeSingleGenericParameterHandler()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddMediator();
+        var provider = services.BuildServiceProvider();
+        var mediator = provider.GetRequiredService<IMediator>();
+
+        await mediator.InvokeAsync(new UpdateEntity<int>(5));
+    }
+
+    [Fact]
+    public async Task CanInvokeTwoGenericParameterHandler()
+    {
+        var services = new ServiceCollection();
+        services.AddLogging();
+        services.AddMediator();
+        var provider = services.BuildServiceProvider();
+        var mediator = provider.GetRequiredService<IMediator>();
+
+        await mediator.InvokeAsync(new UpdateEntityPair<int, string>(5, "test"));
+    }
+}