Add findings document explaining EventPipe dispatch fix

Co-authored-by: brianrob <6210322+brianrob@users.noreply.github.com>

Author: Copilot

EventPipeDispatchFix.md

@@ -0,0 +1,79 @@
+# EventPipe EventSource Dispatch Issue - Investigation Results
+
+## Issue Summary
+The original issue reported that EventSource events from EventPipe files were not being dispatched properly when using `TraceEventDispatcher.GetDispatcherFromFileName()` directly, while they worked correctly when using `TraceLog.Events.GetSource()`.
+
+## Investigation Findings
+
+### Root Cause
+The issue was caused by the lack of a specialized parser to handle EventPipe-specific event templates. When EventPipe files were read using `TraceEventDispatcher.GetDispatcherFromFileName()`, the created `EventPipeEventSource` would:
+
+1. Parse metadata from the EventPipe file and create `DynamicTraceEventData` templates
+2. Store these templates in an internal `_metadataTemplates` dictionary
+3. But these templates were not being registered with the TraceEventSource's template lookup table
+
+When events were dispatched:
+- The `Lookup` method couldn't find the template in the table
+- It would call unhandled event handlers
+- But there was no handler that knew how to retrieve templates from EventPipeEventSource's metadata cache
+
+### The Fix
+The fix was implemented through the introduction of `EventPipeTraceEventParser` (commit 338bf0507753a9e7b261469fde800b681b0ac9ac):
+
+1. **EventPipeTraceEventParser** - A new parser class was created that:
+   - Extends `ExternalTraceEventParser` to automatically register as an unhandled event handler
+   - Implements `TryLookup` to retrieve templates from `EventPipeEventSource._metadataTemplates`
+   - Integrates with the DynamicTraceEventParser's event definition system
+
+2. **DynamicTraceEventParser Integration** - The DynamicTraceEventParser was updated to:
+   - Create an `EventPipeTraceEventParser` instance (line 53)
+   - Hook up the parser's `NewEventDefinition` callback to its own `OnNewEventDefintion` method (line 54)
+   - This ensures that when EventPipe templates are discovered, they're properly registered
+
+### How It Works
+When an unknown EventSource event is encountered in an EventPipe file:
+
+1. `EventPipeEventSource.DispatchEvent` is called
+2. `Lookup` doesn't find the event in the template table, returns unhandled
+3. The unhandled event handlers are called in order:
+   - `RegisteredTraceEventParser.TryLookup` - checks if it's a registered system event
+   - `EventPipeTraceEventParser.TryLookup` - retrieves the template from EventPipeEventSource's metadata cache
+4. The template is registered via `OnNewEventDefintion`
+5. Subsequent events of the same type are dispatched directly
+
+## Test Results
+
+### Test Created
+A comprehensive test was added to `EventPipeParsing.cs` called `EventSourceEventsDispatchedUsingGetDispatcherFromFileName` that:
+- Creates a synthetic EventPipe file with EventSource-like events
+- Tests both `TraceEventDispatcher.GetDispatcherFromFileName()` and `TraceLog.Events.GetSource()`
+- Verifies both methods see the same events
+
+### Test Output
+```
+Events from Dispatcher: 4
+Event names: AppStarted, ProcessingItem, ProcessingItem, AppStopped
+Events from TraceLog: 4
+Event names: AppStarted, ProcessingItem, ProcessingItem, AppStopped
+```
+
+**Result: PASSED** ✅
+
+Both methods now correctly dispatch all EventSource events from EventPipe files.
+
+## Conclusion
+
+The issue has been **FIXED** by the addition of `EventPipeTraceEventParser` and its integration with `DynamicTraceEventParser`. The test confirms that EventSource events are now properly dispatched when using `TraceEventDispatcher.GetDispatcherFromFileName()` on EventPipe files.
+
+## Code Locations
+
+- **Fix Implementation**: `src/TraceEvent/EventPipe/EventPipeTraceEventParser.cs`
+- **Integration Point**: `src/TraceEvent/DynamicTraceEventParser.cs` (lines 52-54)
+- **Metadata Storage**: `src/TraceEvent/EventPipe/EventPipeEventSource.cs` (CacheMetadata, TryGetTemplateFromMetadata)
+- **Test Validation**: `src/TraceEvent/TraceEvent.Tests/Parsing/EventPipeParsing.cs` (EventSourceEventsDispatchedUsingGetDispatcherFromFileName)
+
+## References
+
+- Original Issue: EventSource Events from EventPipe Aren't Dispatched Properly using EventPipeEventSource Directly
+- Fix Commit: 338bf0507753a9e7b261469fde800b681b0ac9ac - "Implement A Thread Time View for Universal Traces (#2320)"
+- Related CoreCLR PR: https://github.com/dotnet/coreclr/pull/16645