Performance Overview
Excalibur.Dispatch is designed for low-latency messaging with explicit performance profiles for local and transport paths.
Before You Start
- .NET 8.0+ (latest baselines are .NET 10.0.3)
- Familiarity with pipeline profiles and middleware
Key Performance Metrics (Feb 19, 2026 Baseline)
Baseline source folder:
benchmarks/baselines/net10.0/dispatch-comparative-20260219/results/
| Metric | Value | Source |
|---|---|---|
| Dispatch single command (MediatR harness) | 118.79 ns | ...MediatRComparisonBenchmarks-report-github.md |
| Dispatch single command (Wolverine in-process harness) | 70.31 ns | ...WolverineInProcessComparisonBenchmarks-report-github.md |
| Dispatch single command (MassTransit mediator harness) | 67.20 ns | ...MassTransitMediatorComparisonBenchmarks-report-github.md |
| Dispatch queued command end-to-end (remote route parity harness) | 1.317 us | ...TransportQueueParityComparisonBenchmarks-report-github.md |
| Dispatch ultra-local API (single command) | 47.12 ns | ...MediatRComparisonBenchmarks-report-github.md |
| Pre-routed local command | 106.0 ns | ...RoutingFirstParityBenchmarks-report-github.md |
Comparison Snapshot
| Track | Status |
|---|---|
| MediatR in-process parity | MediatR faster in current baseline |
| Wolverine in-process parity | Dispatch faster |
| MassTransit mediator in-process parity | Dispatch faster |
| Queued/bus end-to-end parity | Dispatch faster in current baseline |
See Competitor Comparison for full tables and methodology notes.
Quick Wins
1. Use Ultra-Local for local hot paths
var result = await dispatcher.DispatchAsync(new CreateOrderAction(...), ct);
For explicit control, see Ultra-Local Dispatch.
2. Keep messages deterministic where possible
public record CreateOrderCommand(Guid OrderId, string CustomerId) : IDispatchAction;
public class CreateOrderHandler : IActionHandler<CreateOrderCommand> { }
3. Keep auto-freeze enabled
var host = builder.Build();
await host.RunAsync();
4. Prefer direct IMessageContext properties
context.ProcessingAttempts++;
Performance Guides
| Guide | Description |
|---|---|
| Ultra-Local Dispatch | Lowest-overhead local command/query path |
| Auto-Freeze | Automatic cache optimization |
| MessageContext Best Practices | Hot-path optimization patterns |
| Competitor Comparison | Two-track benchmarks vs MediatR/Wolverine/MassTransit |
Memory Allocation Strategy
Dispatch reduces allocations through:
- Object pooling for
MessageContext ArrayPool<T>on batch-style paths- Lazy initialization for optional context state
- ValueTask-based local fast paths
Running Benchmarks
# Full matrix refresh
pwsh ./eng/run-benchmark-matrix.ps1 -NoRestore -NoBuild
# In-process parity track
pwsh ./eng/run-benchmark-matrix.ps1 -NoRestore -NoBuild -Classes MediatRComparisonBenchmarks,WolverineInProcessComparisonBenchmarks,MassTransitMediatorComparisonBenchmarks
# Queued/bus end-to-end parity track
pwsh ./eng/run-benchmark-matrix.ps1 -NoRestore -NoBuild -Classes TransportQueueParityComparisonBenchmarks
Results default to BenchmarkDotNet.Artifacts/results/.