Add exclusion logging

ejsmith · ejsmith · commit c247dbb8b391 · 2026-03-10T12:34:00.000-05:00
diff --git a/src/Foundatio.Mediator/EndpointGenerator.cs b/src/Foundatio.Mediator/EndpointGenerator.cs
@@ -137,6 +137,11 @@ public static void Execute(
         // Filter handlers that should generate endpoints based on discovery mode
         var endpointHandlers = GetEndpointHandlers(handlers, endpointDefaults);
 
+        // Collect handlers that were skipped from endpoint generation (with reasons)
+        var skippedHandlers = handlers
+            .Where(h => h.Endpoint is { GenerateEndpoint: false, ExcludeReason: not null } && !h.MessageType.IsInterface && !h.IsGenericHandlerClass)
+            .ToList();
+
         if (endpointHandlers.Count == 0 && !compilationInfo.IsApplication)
             return;
 
@@ -146,7 +151,7 @@ public static void Execute(
             ValidateEndpoints(context, endpointHandlers, endpointDefaults);
 
             // Generate the per-module endpoint registration code
-            var source = GenerateEndpointCode(endpointHandlers, endpointDefaults, configuration, compilationInfo);
+            var source = GenerateEndpointCode(endpointHandlers, skippedHandlers, endpointDefaults, configuration, compilationInfo);
             context.AddSource("_MediatorEndpoints.g.cs", source);
         }
 
@@ -247,7 +252,7 @@ private static void ValidateEndpoints(SourceProductionContext context, List<Hand
     /// <summary>
     /// Generates the complete endpoint registration source code.
     /// </summary>
-    private static string GenerateEndpointCode(List<HandlerInfo> handlers, EndpointDefaultsInfo endpointDefaults, GeneratorConfiguration configuration, CompilationInfo compilationInfo)
+    private static string GenerateEndpointCode(List<HandlerInfo> handlers, List<HandlerInfo> skippedHandlers, EndpointDefaultsInfo endpointDefaults, GeneratorConfiguration configuration, CompilationInfo compilationInfo)
     {
         var source = new IndentedStringBuilder();
 
@@ -297,7 +302,7 @@ private static string GenerateEndpointCode(List<HandlerInfo> handlers, EndpointD
 
         // Generate the core implementation as a static partial void method
         // that fills in the stub declared in _MediatorEndpoints.Api.g.cs
-        GenerateMapMediatorEndpointsCoreMethod(source, handlers, endpointDefaults, configuration, hasAsParametersAttribute, hasFromBodyAttribute, hasWithOpenApi, assemblySuffix, compilationInfo.HasLoggerFactory);
+        GenerateMapMediatorEndpointsCoreMethod(source, handlers, skippedHandlers, endpointDefaults, configuration, hasAsParametersAttribute, hasFromBodyAttribute, hasWithOpenApi, assemblySuffix, compilationInfo.HasLoggerFactory);
 
         source.DecrementIndent();
         source.AppendLine("}");
@@ -316,6 +321,7 @@ private static string GenerateEndpointCode(List<HandlerInfo> handlers, EndpointD
     private static void GenerateMapMediatorEndpointsCoreMethod(
         IndentedStringBuilder source,
         List<HandlerInfo> handlers,
+        List<HandlerInfo> skippedHandlers,
         EndpointDefaultsInfo endpointDefaults,
         GeneratorConfiguration configuration,
         bool hasAsParametersAttribute,
@@ -409,7 +415,7 @@ private static void GenerateMapMediatorEndpointsCoreMethod(
             .ToList();
 
         // Collect endpoint info for startup logging
-        var endpointLogEntries = new List<(string HttpMethod, string FullRoute, string HandlerInfo)>();
+        var endpointLogEntries = new List<(string HttpMethod, string FullRoute, string HandlerInfo, bool IsExplicitRoute)>();
 
         foreach (var categoryGroup in handlersByCategory)
         {
@@ -493,12 +499,22 @@ private static void GenerateMapMediatorEndpointsCoreMethod(
                 endpointLogEntries.Add((
                     handler.Endpoint!.Value.HttpMethod,
                     fullRoute,
-                    $"{handler.Identifier}.{handler.MethodName}({handler.MessageType.Identifier})"));
+                    $"{handler.Identifier}.{handler.MethodName}({handler.MessageType.Identifier})",
+                    handler.Endpoint!.Value.HasExplicitRoute));
             }
         }
 
+        // Collect skipped handler info for logging
+        var skippedLogEntries = new List<(string HandlerInfo, string Reason)>();
+        foreach (var handler in skippedHandlers)
+        {
+            skippedLogEntries.Add((
+                $"{handler.Identifier}.{handler.MethodName}({handler.MessageType.Identifier})",
+                handler.Endpoint!.Value.ExcludeReason!));
+        }
+
         // Emit endpoint logging block
-        EmitEndpointLogging(source, endpointLogEntries, hasLoggerFactory);
+        EmitEndpointLogging(source, endpointLogEntries, skippedLogEntries, hasLoggerFactory);
 
         source.DecrementIndent();
         source.AppendLine("}");
@@ -509,14 +525,15 @@ private static void GenerateMapMediatorEndpointsCoreMethod(
     /// </summary>
     private static void EmitEndpointLogging(
         IndentedStringBuilder source,
-        List<(string HttpMethod, string FullRoute, string HandlerInfo)> entries,
+        List<(string HttpMethod, string FullRoute, string HandlerInfo, bool IsExplicitRoute)> entries,
+        List<(string HandlerInfo, string Reason)> skippedEntries,
         bool hasLoggerFactory)
     {
-        if (entries.Count == 0)
+        if (entries.Count == 0 && skippedEntries.Count == 0)
             return;
 
-        var maxMethodLen = entries.Max(e => e.HttpMethod.Length);
-        var maxRouteLen = entries.Max(e => e.FullRoute.Length);
+        var maxMethodLen = entries.Count > 0 ? entries.Max(e => e.HttpMethod.Length) : 0;
+        var maxRouteLen = entries.Count > 0 ? entries.Max(e => e.FullRoute.Length) : 0;
 
         source.AppendLine();
         source.AppendLine("// Log mapped endpoints when requested");
@@ -540,11 +557,21 @@ private static void EmitEndpointLogging(
 
         source.AppendLine($"writeLog(\"Foundatio.Mediator mapped {entries.Count} endpoint(s):\");");
 
-        foreach (var (httpMethod, fullRoute, handlerInfo) in entries)
+        foreach (var (httpMethod, fullRoute, handlerInfo, isExplicitRoute) in entries)
         {
             var paddedMethod = httpMethod.PadRight(maxMethodLen);
             var paddedRoute = fullRoute.PadRight(maxRouteLen);
-            source.AppendLine($"writeLog(\"  {paddedMethod}  {paddedRoute}  \u2192 {handlerInfo}\");");
+            var routeSource = isExplicitRoute ? "explicit" : "convention";
+            source.AppendLine($"writeLog(\"  {paddedMethod}  {paddedRoute}  \u2192 {handlerInfo} ({routeSource})\");");
+        }
+
+        if (skippedEntries.Count > 0)
+        {
+            source.AppendLine($"writeLog(\"Foundatio.Mediator skipped {skippedEntries.Count} handler(s) from endpoint generation:\");");
+            foreach (var (handlerInfo, reason) in skippedEntries)
+            {
+                source.AppendLine($"writeLog(\"  SKIP  {handlerInfo} ({reason})\");");
+            }
         }
 
         source.DecrementIndent();
diff --git a/src/Foundatio.Mediator/HandlerAnalyzer.cs b/src/Foundatio.Mediator/HandlerAnalyzer.cs
@@ -403,13 +403,14 @@ private static string[] ExtractTypeArrayArgument(AttributeData? attr, string arg
 
         if (isExcluded)
         {
-            return new EndpointInfo { GenerateEndpoint = false };
+            return new EndpointInfo { GenerateEndpoint = false, ExcludeReason = "excluded by attribute" };
         }
 
         // Auto-exclude events/notifications from endpoint generation
-        if (ShouldExcludeAsEvent(classSymbol, messageType))
+        var eventExcludeReason = GetEventExcludeReason(classSymbol, messageType);
+        if (eventExcludeReason != null)
         {
-            return new EndpointInfo { GenerateEndpoint = false };
+            return new EndpointInfo { GenerateEndpoint = false, ExcludeReason = eventExcludeReason };
         }
 
         // Extract category info
@@ -934,30 +935,42 @@ private static string RemoveVerbPrefix(string name)
     /// Determines if a handler/message should be excluded from endpoint generation because it's an event.
     /// </summary>
     private static bool ShouldExcludeAsEvent(INamedTypeSymbol classSymbol, INamedTypeSymbol messageType)
+        => GetEventExcludeReason(classSymbol, messageType) != null;
+
+    /// <summary>
+    /// Returns a human-readable reason string if the handler/message should be excluded from endpoint generation
+    /// because it's an event, or null if it should not be excluded.
+    /// </summary>
+    private static string? GetEventExcludeReason(INamedTypeSymbol classSymbol, INamedTypeSymbol messageType)
     {
         // 1. Check if message implements INotification (MediatR-style)
-        if (messageType.AllInterfaces.Any(i =>
+        var notificationInterface = messageType.AllInterfaces.FirstOrDefault(i =>
             i.Name == "INotification" ||
             i.ToDisplayString() == "Foundatio.Mediator.INotification" ||
-            i.ToDisplayString() == "MediatR.INotification"))
+            i.ToDisplayString() == "MediatR.INotification");
+        if (notificationInterface != null)
         {
-            return true;
+            return $"implements {notificationInterface.Name}";
         }
 
         // 2. Check if message implements common event marker interfaces
-        if (messageType.AllInterfaces.Any(i =>
+        var eventInterface = messageType.AllInterfaces.FirstOrDefault(i =>
             i.Name == "IEvent" ||
             i.Name == "IDomainEvent" ||
-            i.Name == "IIntegrationEvent"))
+            i.Name == "IIntegrationEvent");
+        if (eventInterface != null)
         {
-            return true;
+            return $"implements {eventInterface.Name}";
         }
 
         // 3. Check if handler class name ends with "EventHandler" or "NotificationHandler"
-        if (classSymbol.Name.EndsWith("EventHandler") ||
-            classSymbol.Name.EndsWith("NotificationHandler"))
+        if (classSymbol.Name.EndsWith("EventHandler"))
         {
-            return true;
+            return "handler name ends with 'EventHandler'";
+        }
+        if (classSymbol.Name.EndsWith("NotificationHandler"))
+        {
+            return "handler name ends with 'NotificationHandler'";
         }
 
         // 4. Check if message type name has common event suffixes
@@ -966,11 +979,11 @@ private static bool ShouldExcludeAsEvent(INamedTypeSymbol classSymbol, INamedTyp
         {
             if (messageName.EndsWith(suffix, StringComparison.Ordinal))
             {
-                return true;
+                return $"message name ends with '{suffix}'";
             }
         }
 
-        return false;
+        return null;
     }
 
     #endregion
diff --git a/src/Foundatio.Mediator/Models/EndpointInfo.cs b/src/Foundatio.Mediator/Models/EndpointInfo.cs
@@ -84,6 +84,12 @@ internal readonly record struct EndpointInfo
     /// </summary>
     public bool GenerateEndpoint { get; init; }
 
+    /// <summary>
+    /// Reason this handler was excluded from endpoint generation, if applicable.
+    /// Null when the handler is not excluded.
+    /// </summary>
+    public string? ExcludeReason { get; init; }
+
     /// <summary>
     /// Whether this handler has an explicit [HandlerEndpoint] attribute on the method or class.
     /// Used by "Explicit" discovery mode to distinguish explicitly marked handlers.
diff --git a/tests/Foundatio.Mediator.Tests/BasicHandlerGenerationTests.EndpointGeneration.verified.txt b/tests/Foundatio.Mediator.Tests/BasicHandlerGenerationTests.EndpointGeneration.verified.txt
@@ -184,7 +184,7 @@ public static partial class Tests_MediatorEndpoints
         {
             System.Action<string> writeLog = System.Console.WriteLine;
             writeLog("Foundatio.Mediator mapped 1 endpoint(s):");
-            writeLog("  GET  /api/widget/{id}  → WidgetHandler.Handle(GetWidget)");
+            writeLog("  GET  /api/widget/{id}  → WidgetHandler.Handle(GetWidget) (convention)");
         }
         else
         {

Original file line number	Diff line number	Diff line change
`@@ -403,13 +403,14 @@ private static string[] ExtractTypeArrayArgument(AttributeData? attr, string arg`
`403`	`403`
`404`	`404`	`if (isExcluded)`
`405`	`405`	`{`
`406`		`- return new EndpointInfo { GenerateEndpoint = false };`
	`406`	`+ return new EndpointInfo { GenerateEndpoint = false, ExcludeReason = "excluded by attribute" };`
`407`	`407`	`}`
`408`	`408`
`409`	`409`	`// Auto-exclude events/notifications from endpoint generation`
`410`		`- if (ShouldExcludeAsEvent(classSymbol, messageType))`
	`410`	`+ var eventExcludeReason = GetEventExcludeReason(classSymbol, messageType);`
	`411`	`+ if (eventExcludeReason != null)`
`411`	`412`	`{`
`412`		`- return new EndpointInfo { GenerateEndpoint = false };`
	`413`	`+ return new EndpointInfo { GenerateEndpoint = false, ExcludeReason = eventExcludeReason };`
`413`	`414`	`}`
`414`	`415`
`415`	`416`	`// Extract category info`
`@@ -934,30 +935,42 @@ private static string RemoveVerbPrefix(string name)`
`934`	`935`	`/// Determines if a handler/message should be excluded from endpoint generation because it's an event.`
`935`	`936`	`/// </summary>`
`936`	`937`	`private static bool ShouldExcludeAsEvent(INamedTypeSymbol classSymbol, INamedTypeSymbol messageType)`
	`938`	`+ => GetEventExcludeReason(classSymbol, messageType) != null;`
	`939`	`+`
	`940`	`+ /// <summary>`
	`941`	`+ /// Returns a human-readable reason string if the handler/message should be excluded from endpoint generation`
	`942`	`+ /// because it's an event, or null if it should not be excluded.`
	`943`	`+ /// </summary>`
	`944`	`+ private static string? GetEventExcludeReason(INamedTypeSymbol classSymbol, INamedTypeSymbol messageType)`
`937`	`945`	`{`
`938`	`946`	`// 1. Check if message implements INotification (MediatR-style)`
`939`		`- if (messageType.AllInterfaces.Any(i =>`
	`947`	`+ var notificationInterface = messageType.AllInterfaces.FirstOrDefault(i =>`
`940`	`948`	`i.Name == "INotification" \|\|`
`941`	`949`	`i.ToDisplayString() == "Foundatio.Mediator.INotification" \|\|`
`942`		`- i.ToDisplayString() == "MediatR.INotification"))`
	`950`	`+ i.ToDisplayString() == "MediatR.INotification");`
	`951`	`+ if (notificationInterface != null)`
`943`	`952`	`{`
`944`		`- return true;`
	`953`	`+ return $"implements {notificationInterface.Name}";`
`945`	`954`	`}`
`946`	`955`
`947`	`956`	`// 2. Check if message implements common event marker interfaces`
`948`		`- if (messageType.AllInterfaces.Any(i =>`
	`957`	`+ var eventInterface = messageType.AllInterfaces.FirstOrDefault(i =>`
`949`	`958`	`i.Name == "IEvent" \|\|`
`950`	`959`	`i.Name == "IDomainEvent" \|\|`
`951`		`- i.Name == "IIntegrationEvent"))`
	`960`	`+ i.Name == "IIntegrationEvent");`
	`961`	`+ if (eventInterface != null)`
`952`	`962`	`{`
`953`		`- return true;`
	`963`	`+ return $"implements {eventInterface.Name}";`
`954`	`964`	`}`
`955`	`965`
`956`	`966`	`// 3. Check if handler class name ends with "EventHandler" or "NotificationHandler"`
`957`		`- if (classSymbol.Name.EndsWith("EventHandler") \|\|`
`958`		`- classSymbol.Name.EndsWith("NotificationHandler"))`
	`967`	`+ if (classSymbol.Name.EndsWith("EventHandler"))`
`959`	`968`	`{`
`960`		`- return true;`
	`969`	`+ return "handler name ends with 'EventHandler'";`
	`970`	`+ }`
	`971`	`+ if (classSymbol.Name.EndsWith("NotificationHandler"))`
	`972`	`+ {`
	`973`	`+ return "handler name ends with 'NotificationHandler'";`
`961`	`974`	`}`
`962`	`975`
`963`	`976`	`// 4. Check if message type name has common event suffixes`
`@@ -966,11 +979,11 @@ private static bool ShouldExcludeAsEvent(INamedTypeSymbol classSymbol, INamedTyp`
`966`	`979`	`{`
`967`	`980`	`if (messageName.EndsWith(suffix, StringComparison.Ordinal))`
`968`	`981`	`{`
`969`		`- return true;`
	`982`	`+ return $"message name ends with '{suffix}'";`
`970`	`983`	`}`
`971`	`984`	`}`
`972`	`985`
`973`		`- return false;`
	`986`	`+ return null;`
`974`	`987`	`}`
`975`	`988`
`976`	`989`	`#endregion`
Original file line number	Diff line number	Diff line change
`@@ -184,7 +184,7 @@ public static partial class Tests_MediatorEndpoints`
`184`	`184`	`{`
`185`	`185`	`System.Action<string> writeLog = System.Console.WriteLine;`
`186`	`186`	`writeLog("Foundatio.Mediator mapped 1 endpoint(s):");`
`187`		`- writeLog(" GET /api/widget/{id} → WidgetHandler.Handle(GetWidget)");`
	`187`	`+ writeLog(" GET /api/widget/{id} → WidgetHandler.Handle(GetWidget) (convention)");`
`188`	`188`	`}`
`189`	`189`	`else`
`190`	`190`	`{`