Skip to main content

Introduction to NetMediate

Welcome to NetMediate, a lightweight and efficient .NET implementation of the Mediator pattern for in-process messaging and communication between components.

What is NetMediate?​

NetMediate is a mediator pattern library for .NET that enables decoupled communication between components in your application. It provides a simple and flexible way to send commands, publish notifications, make requests, and handle streaming responses while maintaining clean architecture principles.

Key Features​

🚀 Commands​

Send one-way messages to all registered handlers sequentially. Perfect for triggering side-effects across multiple consumers.

📨 Notifications​

Publish messages to multiple handlers — all handlers started in parallel (Task.WhenAll); handler results and exceptions are discarded (fire-and-forget). Batch notifications are also dispatched in parallel. Behaviors run fully and their exceptions propagate. Ideal for event-driven architectures.

🔄 Requests​

Send a message to a single handler and receive a typed response. Great for queries and request-response patterns.

📡 Streaming​

Handle requests that return multiple responses over time via IAsyncEnumerable. Perfect for real-time data feeds.

🔌 Pipeline Behaviors​

Interceptors with pre/post flow for every message kind. Implement cross-cutting concerns like logging, validation, and caching.

🛡️ Optional Resilience Package​

Retry, timeout, and circuit-breaker behaviors in NetMediate.Resilience to make your applications more robust.

📊 OpenTelemetry-Ready Diagnostics​

Built-in ActivitySource/Meter for Send/Request/Notify/Stream operations with full distributed tracing support.

🐕 Optional DataDog Integrations​

OpenTelemetry, Serilog, and ILogger support packages for comprehensive observability.

🔑 Keyed Handler Routing​

Register handlers under named keys and dispatch to specific subsets at runtime.

🌊 Streaming Fan-Out​

Multiple IStreamHandler registrations supported — their items are merged sequentially.

⏹️ Cancellation Support​

Full cancellation token support across all operations.

🌐 Broad Runtime Compatibility​

Multi-targeted for net10.0, netstandard2.0, and netstandard2.1.

Why Use the Mediator Pattern?​

The Mediator pattern helps you:

  • Decouple Components: Reduce direct dependencies between classes
  • Single Responsibility: Each handler focuses on one specific task
  • Testability: Handlers can be easily unit tested in isolation
  • Maintainability: Changes to one handler don't affect others
  • Flexibility: Easy to add or remove handlers without affecting the rest of your code

Architecture Overview​

┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ├─── Send Command ────►┌──────────────┐      ┌─────────────────┐
       │                      │              │      │  Command        │
       ├─── Notify ──────────►│   IMediator  ├─────►│  Notification   │
       │                      │              │      │  Request        │
       ├─── Request ─────────►│              │      │  Stream         │
       │                      └──────────────┘      │  Handlers       │
       └─── RequestStream ───►                      └─────────────────┘
                                     │
                                     ▼
                              ┌─────────────────┐
                              │  Pipeline       │
                              │  Behaviors      │
                              └─────────────────┘

Message Types​

NetMediate supports four types of messages, each with a specific purpose:

Message KindHandler InterfaceDispatch Semantics
CommandICommandHandler<TMessage>All registered handlers, sequential in registration order
RequestIRequestHandler<TMessage, TResponse>First registered handler only; returns TResponse
NotificationINotificationHandler<TMessage>All handlers started in parallel (fire-and-forget via Task.WhenAll); handler exceptions unobserved
StreamIStreamHandler<TMessage, TResponse>All registered handlers, items merged sequentially

No Marker Interfaces Required​

Unlike some mediator implementations, NetMediate does not require marker interfaces on your message types. Any plain class or record can be a message:

public record CreateUserCommand(string Email, string Name);  // ✅ Works!
public record UserCreatedNotification(string UserId);        // ✅ Works!
public record GetUserQuery(string UserId);                   // ✅ Works!

Getting Started​

Ready to dive in? Head over to the Installation Guide to get NetMediate set up in your project, or jump straight to the Quick Start for a working example.

Package Ecosystem​

NetMediate consists of several packages:

  • NetMediate - Core mediator implementation; includes the NetMediate.SourceGeneration analyzer (activated by PrivateAssets="all")
  • NetMediate.Resilience - Retry, timeout, and circuit breaker behaviors
  • NetMediate.Diagnostics - OpenTelemetry integration
  • NetMediate.Quartz - Persistent notifications with Quartz.NET
  • NetMediate.Moq - Testing utilities for Moq
  • NetMediate.DataDog.OpenTelemetry - DataDog OTLP exporter integration
  • NetMediate.DataDog.Serilog - DataDog Serilog sink integration
  • NetMediate.DataDog.ILogger - DataDog ILogger integration

Community and Support​

License​

NetMediate is licensed under the MIT License. See the LICENSE file for details.