Add option to disable conventional handler discover

Author: ejsmith

AGENTS.md

@@ -299,6 +299,10 @@ Defined in `src/Foundatio.Mediator/Foundatio.Mediator.props`:
 
 <!-- Disable OpenTelemetry tracing (default: false) -->
 <MediatorDisableOpenTelemetry>true|false</MediatorDisableOpenTelemetry>
+
+<!-- Disable conventional handler discovery (default: false) -->
+<!-- When true, only handlers with IHandler interface or [Handler] attribute are discovered -->
+<MediatorDisableConventionalDiscovery>true|false</MediatorDisableConventionalDiscovery>
 ```
 
 Requirements for interceptors:

docs/guide/configuration.md

@@ -18,6 +18,9 @@ These properties control the source generator at compile time and affect code ge
 
     <!-- Disable OpenTelemetry integration (default: false) -->
     <MediatorDisableOpenTelemetry>true</MediatorDisableOpenTelemetry>
+
+    <!-- Disable conventional handler discovery (default: false) -->
+    <MediatorDisableConventionalDiscovery>true</MediatorDisableConventionalDiscovery>
 </PropertyGroup>
 ```
 
@@ -44,6 +47,13 @@ These properties control the source generator at compile time and affect code ge
 - **Effect:** When `true`, disables OpenTelemetry integration code generation
 - **Use Case:** Reduce generated code size when telemetry is not needed
 
+**`MediatorDisableConventionalDiscovery`**
+
+- **Values:** `true`, `false`
+- **Default:** `false`
+- **Effect:** When `true`, disables convention-based handler discovery (class names ending with `Handler` or `Consumer`). Only handlers that implement `IHandler` interface or have the `[Handler]` attribute will be discovered.
+- **Use Case:** Explicit control over which classes are treated as handlers, avoiding accidental handler discovery
+
 ### Example .csproj Configuration
 
 ```xml
@@ -56,6 +66,7 @@ These properties control the source generator at compile time and affect code ge
     <MediatorHandlerLifetime>Scoped</MediatorHandlerLifetime>
     <MediatorDisableInterceptors>false</MediatorDisableInterceptors>
     <MediatorDisableOpenTelemetry>true</MediatorDisableOpenTelemetry>
+    <MediatorDisableConventionalDiscovery>false</MediatorDisableConventionalDiscovery>
   </PropertyGroup>
 
   <PackageReference Include="Foundatio.Mediator" Version="1.0.0" />

docs/guide/handler-conventions.md

@@ -2,6 +2,8 @@
 
 Foundatio Mediator uses simple naming conventions to automatically discover handlers at compile time. This eliminates the need for interfaces, base classes, or manual registration while providing excellent compile-time validation.
 
+Alternatively, you can mark handlers explicitly using the `IHandler` marker interface or the `[Handler]` attribute. See [Explicit Handler Declaration](#explicit-handler-declaration) for details.
+
 ## Class Naming Conventions
 
 Handler classes must end with one of these suffixes:
@@ -462,6 +464,47 @@ public class OrderHandler
 }
 ```
 
+## Explicit Handler Declaration
+
+In addition to naming conventions, handlers can be explicitly declared using:
+
+1. **Interface** - Classes implementing the `IHandler` marker interface
+2. **Attribute** - Classes or methods decorated with `[Handler]`
+
+```csharp
+// Discovered via IHandler interface
+public class OrderProcessor : IHandler
+{
+    public Order Handle(CreateOrder command) { }
+}
+
+// Discovered via [Handler] attribute on class
+[Handler]
+public class EmailService
+{
+    public void Handle(SendEmail command) { }
+}
+
+// Discovered via [Handler] attribute on method
+public class NotificationService
+{
+    [Handler]
+    public void Process(SendNotification command) { }
+}
+```
+
+### Disabling Conventional Discovery
+
+If you prefer explicit handler declaration over naming conventions, you can disable conventional discovery entirely:
+
+```xml
+<PropertyGroup>
+    <MediatorDisableConventionalDiscovery>true</MediatorDisableConventionalDiscovery>
+</PropertyGroup>
+```
+
+When disabled, only handlers that implement `IHandler` or have the `[Handler]` attribute are discovered. Classes with names ending in `Handler` or `Consumer` will not be automatically discovered.
+
 ## Next Steps
 
 - [Result Types](./result-types) - Robust error handling patterns

src/Foundatio.Mediator/Foundatio.Mediator.props

@@ -4,5 +4,6 @@
     <CompilerVisibleProperty Include="MediatorDisableInterceptors" />
     <CompilerVisibleProperty Include="MediatorHandlerLifetime" />
     <CompilerVisibleProperty Include="MediatorDisableOpenTelemetry" />
+    <CompilerVisibleProperty Include="MediatorDisableConventionalDiscovery" />
   </ItemGroup>
 </Project>

src/Foundatio.Mediator/HandlerAnalyzer.cs

@@ -83,6 +83,9 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
         bool implementsMarker = classSymbol.AllInterfaces.Any(i => i.ToDisplayString() == "Foundatio.Mediator.IHandler");
         bool hasClassHandlerAttribute = classSymbol.GetAttributes().Any(attr => attr.AttributeClass?.ToDisplayString() == WellKnownTypes.HandlerAttribute);
 
+        // Explicit discovery: IHandler interface or [Handler] attribute on class
+        bool isExplicitlyDeclared = implementsMarker || hasClassHandlerAttribute;
+
         bool treatAsHandlerClass = nameMatches || implementsMarker || hasClassHandlerAttribute;
 
         var handlerMethods = GetMethods(classSymbol)
@@ -158,6 +161,10 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
                 }
             }
 
+            // Check if this specific method has [Handler] attribute (also counts as explicit declaration)
+            bool hasMethodHandlerAttribute = handlerMethod.GetAttributes().Any(attr => attr.AttributeClass?.ToDisplayString() == WellKnownTypes.HandlerAttribute);
+            bool methodIsExplicitlyDeclared = isExplicitlyDeclared || hasMethodHandlerAttribute;
+
             handlers.Add(new HandlerInfo
             {
                 Identifier = classSymbol.Name.ToIdentifier(),
@@ -177,6 +184,7 @@ public static List<HandlerInfo> GetHandlers(GeneratorSyntaxContext context)
                 Parameters = new(parameterInfos.ToArray()),
                 CallSites = [],
                 Middleware = [],
+                IsExplicitlyDeclared = methodIsExplicitlyDeclared,
             });
         }
 

src/Foundatio.Mediator/MediatorGenerator.cs

@@ -32,7 +32,11 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
                     && openTelemetrySwitch.Equals("true", StringComparison.OrdinalIgnoreCase);
                 var openTelemetryEnabled = !openTelemetryDisabled;
 
-                return new GeneratorConfiguration(interceptorsEnabled, handlerLifetime, openTelemetryEnabled);
+                // Read conventional discovery disabled property. Default: false (conventional discovery enabled by default)
+                var conventionalDiscoveryDisabled = options.GlobalOptions.TryGetValue($"build_property.{Constants.DisableConventionalDiscoveryPropertyName}", out string? conventionalDiscoverySwitch)
+                    && conventionalDiscoverySwitch.Equals("true", StringComparison.OrdinalIgnoreCase);
+
+                return new GeneratorConfiguration(interceptorsEnabled, handlerLifetime, openTelemetryEnabled, conventionalDiscoveryDisabled);
             })
             .WithTrackingName(TrackingNames.Settings);
 
@@ -79,6 +83,11 @@ public void Initialize(IncrementalGeneratorInitializationContext context)
 
     private static void Execute(ImmutableArray<HandlerInfo> handlers, ImmutableArray<MiddlewareInfo> middleware, ImmutableArray<CallSiteInfo> callSites, GeneratorConfiguration configuration, Compilation compilation, SourceProductionContext context)
     {
+        // Filter out conventionally-discovered handlers when conventional discovery is disabled
+        var filteredHandlers = configuration.ConventionalDiscoveryDisabled
+            ? handlers.Where(h => h.IsExplicitlyDeclared).ToImmutableArray()
+            : handlers;
+
         // Scan referenced assemblies for cross-assembly middleware
         var metadataMiddleware = MetadataMiddlewareScanner.ScanReferencedAssemblies(compilation);
 
@@ -99,7 +108,7 @@ private static void Execute(ImmutableArray<HandlerInfo> handlers, ImmutableArray
         var crossAssemblyHandlerMessageTypes = new HashSet<string>(crossAssemblyHandlers.Select(h => h.MessageType.FullName));
 
         var handlersWithInfo = new List<HandlerInfo>();
-        foreach (var handler in handlers)
+        foreach (var handler in filteredHandlers)
         {
             callSitesByMessage.TryGetValue(handler.MessageType, out var handlerCallSites);
             var applicableMiddleware = GetApplicableMiddlewares(allMiddleware.ToImmutableArray(), handler, compilation);
@@ -113,7 +122,7 @@ private static void Execute(ImmutableArray<HandlerInfo> handlers, ImmutableArray
                 continue;
 
             // Check if this message type has a handler in a referenced assembly but NOT in the current assembly
-            bool hasLocalHandler = handlers.Any(h => h.MessageType.FullName == callSite.MessageType.FullName);
+            bool hasLocalHandler = filteredHandlers.Any(h => h.MessageType.FullName == callSite.MessageType.FullName);
             bool hasCrossAssemblyHandler = crossAssemblyHandlerMessageTypes.Contains(callSite.MessageType.FullName);
 
             if (!hasLocalHandler && hasCrossAssemblyHandler)

src/Foundatio.Mediator/Models/GeneratorConfiguration.cs

@@ -3,4 +3,5 @@ namespace Foundatio.Mediator.Models;
 internal record GeneratorConfiguration(
     bool InterceptorsEnabled,
     string HandlerLifetime,
-    bool OpenTelemetryEnabled);
+    bool OpenTelemetryEnabled,
+    bool ConventionalDiscoveryDisabled);

src/Foundatio.Mediator/Models/HandlerInfo.cs

@@ -23,6 +23,11 @@ internal readonly record struct HandlerInfo
     public string? MessageGenericTypeDefinitionFullName { get; init; }
     public int MessageGenericArity { get; init; }
     public EquatableArray<string> GenericConstraints { get; init; }
+    /// <summary>
+    /// Whether this handler was discovered via explicit means (IHandler interface or [Handler] attribute)
+    /// rather than conventional discovery (class name ending with Handler/Consumer).
+    /// </summary>
+    public bool IsExplicitlyDeclared { get; init; }
 }
 
 internal readonly record struct ParameterInfo

src/Foundatio.Mediator/Utility/Constants.cs

@@ -5,4 +5,5 @@ internal static class Constants
     public const string DisableInterceptorsPropertyName = "MediatorDisableInterceptors";
     public const string HandlerLifetimePropertyName = "MediatorHandlerLifetime";
     public const string DisableOpenTelemetryPropertyName = "MediatorDisableOpenTelemetry";
+    public const string DisableConventionalDiscoveryPropertyName = "MediatorDisableConventionalDiscovery";
 }

tests/Foundatio.Mediator.Tests/ConventionalDiscoveryToggleTests.cs

@@ -0,0 +1,193 @@
+namespace Foundatio.Mediator.Tests;
+
+public class ConventionalDiscoveryToggleTests : GeneratorTestBase
+{
+    [Fact]
+    public void ConventionalDiscovery_Enabled_DiscoversHandlerByNamingConvention()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Discovered by naming convention (ends with Handler)
+            public class MyMessageHandler
+            {
+                public void Handle(MyMessage m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "false"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Handler should be discovered and a wrapper generated
+        Assert.Contains(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_DoesNotDiscoverHandlerByNamingConvention()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Should NOT be discovered when conventional discovery is disabled
+            public class MyMessageHandler
+            {
+                public void Handle(MyMessage m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "true"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Handler should NOT be discovered
+        Assert.DoesNotContain(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_DiscoversHandlerWithIHandlerInterface()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Discovered via IHandler interface
+            public class MessageProcessor : IHandler
+            {
+                public void Handle(MyMessage m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "true"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Handler should be discovered via IHandler interface
+        Assert.Contains(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_DiscoversHandlerWithClassAttribute()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Discovered via [Handler] attribute on class
+            [Handler]
+            public class MessageProcessor
+            {
+                public void Handle(MyMessage m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "true"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Handler should be discovered via [Handler] attribute
+        Assert.Contains(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_DiscoversHandlerWithMethodAttribute()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Discovered via [Handler] attribute on method
+            public class MessageProcessor
+            {
+                [Handler]
+                public void Process(MyMessage m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "true"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Handler should be discovered via [Handler] attribute on method
+        Assert.Contains(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_DefaultsToEnabledWhenPropertyNotSet()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record MyMessage;
+
+            // Discovered by naming convention when property not set (default behavior)
+            public class MyMessageHandler
+            {
+                public void Handle(MyMessage m) { }
+            }
+            """;
+
+        // No options set - defaults to conventional discovery enabled
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], optionsProvider: null);
+
+        // Handler should be discovered
+        Assert.Contains(trees, t => t.HintName.Contains("MyMessage_Handler.g.cs"));
+    }
+
+    [Fact]
+    public void ConventionalDiscovery_Disabled_MixedHandlers_OnlyExplicitHandlersGenerated()
+    {
+        var src = """
+            using System.Threading;
+            using System.Threading.Tasks;
+            using Foundatio.Mediator;
+
+            public record Message1;
+            public record Message2;
+            public record Message3;
+
+            // Should NOT be discovered (naming convention only)
+            public class Message1Handler
+            {
+                public void Handle(Message1 m) { }
+            }
+
+            // SHOULD be discovered (IHandler interface)
+            public class Processor2 : IHandler
+            {
+                public void Handle(Message2 m) { }
+            }
+
+            // SHOULD be discovered ([Handler] attribute)
+            [Handler]
+            public class Processor3
+            {
+                public void Handle(Message3 m) { }
+            }
+            """;
+
+        var opts = CreateOptions(("build_property.MediatorDisableConventionalDiscovery", "true"));
+        var (_, _, trees) = RunGenerator(src, [new MediatorGenerator()], opts);
+
+        // Message1Handler should NOT be discovered (conventional only)
+        Assert.DoesNotContain(trees, t => t.HintName.Contains("Message1_Handler.g.cs"));
+
+        // Processor2 and Processor3 SHOULD be discovered (explicit)
+        Assert.Contains(trees, t => t.HintName.Contains("Message2_Handler.g.cs"));
+        Assert.Contains(trees, t => t.HintName.Contains("Message3_Handler.g.cs"));
+    }
+}