Add and use TimeWarp.Mediator 15.0 - in-process request/response and notifications for .NET with one source-generated dispatcher. Use when adding TimeWarp.Mediator to a project, writing requests, handlers, notifications or pipeline behaviors, calling AddGeneratedMediator, setting up named pipelines (ISender<TScope>), reading MediatorManifest, naming a handler another generator emits, or fixing TWM001-TWM004, TWM007, TWM008, TWM010, TWM011, and TWM012.

Maintained in timewarp-mediator · Canonical file: SKILL.md

Install

With TimeWarp.Skills:

dnx TimeWarp.Skills -- add tw-mediator https://timewarp.software/

Add a harness target and skills sync (see the TimeWarp.Skills page). Or copy the SKILL.md into your agent's skills directory.


TimeWarp.Mediator

In-process messaging for .NET. ISender.Send reaches one handler. IPublisher.Publish reaches many handlers, sequentially. The dispatcher is source-generated. A host calls AddGeneratedMediator(). Handlers and behaviors return ValueTask.

Packages: TimeWarp.Mediator (contracts, GeneratedHandlerAttribute, and TWM001–TWM004 plus TWM012) and TimeWarp.Mediator.Generators. Repository: https://github.com/TimeWarpEngineering/timewarp-mediator Docs this skill links instead of repeating: architecture.md, diagnostics.md, m2-named-pipelines.md, migration.md.

1. Dispatcher

15.0
Packages TimeWarp.Mediator + TimeWarp.Mediator.Generators
Registration services.AddGeneratedMediator() / AddGeneratedMediator<TScope>() from the generated namespace. The dispatcher is transient
Handler discovery compile time, member assemblies only
Missing / duplicate handler build error (TWM001 / TWM002)
Handler emitted by another generator A GeneratedHandlerAttribute-derived attribute on the request. HandlerTypeName is relative to the containing type. An attribute in another assembly passes it as a constructor parameter named handlerTypeName (a default value is enough). A bad or missing name is TWM012
Behaviors [assembly: MediatorBehavior(typeof(B<,>))], always woven. The host supplies IServiceProvider
Named pipelines (ISender<TScope>) yes
Streams, pre/post processors, exception handlers removed with the reflection runtime
Trimming / NativeAOT safe, including woven behaviors

There is one emission. TimeWarpMediatorProfile is removed.

2. Minimal host

Keep both packages on the same version. Generators does not bring TimeWarp.Mediator with it.

<!-- Directory.Packages.props -->
<ItemGroup>
  <PackageVersion Include="TimeWarp.Mediator" Version="15.0.0-beta.5" />
  <PackageVersion Include="TimeWarp.Mediator.Generators" Version="15.0.0-beta.5" />
  <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.12" />
</ItemGroup>
<!-- host .csproj (net10.0 or net11.0) -->
<ItemGroup>
  <PackageReference Include="TimeWarp.Mediator" />
  <PackageReference Include="TimeWarp.Mediator.Generators" PrivateAssets="all" />
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
</ItemGroup>

Use the version this repo is packing, currently 15.0.0-beta.5. 14.0.0 on nuget.org is the previous surface: the id TimeWarp.Mediator was the reflection runtime (AddMediator), contracts were TimeWarp.Mediator.Contracts, analyzers were a separate package, and handlers returned Task.

Membership

A project that references Generators emits a mediator. The generator package sets TimeWarpMediatorAssembly=true, which the analyzer reads as membership. The generator does not read that property. A library that holds handlers or requests for a host opts in and does not reference Generators:

[assembly: MediatorAssembly]

That library references TimeWarp.Mediator. The TWM001–TWM004 analyzer ships inside that package.

Request, handler, send

using Microsoft.Extensions.DependencyInjection;
using TimeWarp.Mediator;
using TimeWarp.Mediator.Generated;

ServiceCollection services = new();
services.AddGeneratedMediator();
using ServiceProvider provider = services.BuildServiceProvider();
using IServiceScope scope = provider.CreateScope();

ISender sender = scope.ServiceProvider.GetRequiredService<ISender>();
string reply = await sender.Send(new Ping("hi"));

public sealed record Ping(string Message) : IRequest<string>;

public sealed class PingHandler : IRequestHandler<Ping, string>
{
  public ValueTask<string> Handle(Ping request, CancellationToken cancellationToken) =>
    ValueTask.FromResult(request.Message + " pong");
}

AddGeneratedMediator() is an internal extension in the generated namespace (default TimeWarp.Mediator.Generated, class TimeWarpMediatorGeneratedServiceCollectionExtensions). Call it from the host. The dispatcher is transient. Handlers, behaviors, behavior chains, and HandlerCache are scoped. A singleton dispatcher was not faster than a reused transient instance on the net10.0 send benchmark, so the method does not take a ServiceLifetime (why: task 020 measurement 2026-10-28). Resolve ISender from a scope.

ICommand, ICommand<T>, IQuery<T>, IAction, and IIdempotentCommand / IIdempotentCommand<T> are markers. Handlers implement IRequestHandler. Kind is on MediatorManifest.

Notifications

IPublisher publisher = scope.ServiceProvider.GetRequiredService<IPublisher>();
await publisher.Publish(new OrderPlaced(42));

public sealed record OrderPlaced(int OrderId) : INotification;

public sealed class EmailOnOrderPlaced : INotificationHandler<OrderPlaced>
{
  public ValueTask Handle(OrderPlaced notification, CancellationToken cancellationToken) =>
    ValueTask.CompletedTask;
}

Publish awaits handlers sequentially in display-name order, most-derived notification type first, including handlers of base types and INotification.

Pipeline behaviors

[assembly: MediatorBehavior(typeof(LoggingBehavior<,>))]

public sealed class LoggingBehavior<TRequest, TResponse> : IPipelineBehavior<TRequest, TResponse>
  where TRequest : notnull
{
  public async ValueTask<TResponse> Handle(
      TRequest request,
      MessageHandlerDelegate<TRequest, TResponse> next,
      CancellationToken cancellationToken)
  {
    TResponse response = await next(request, cancellationToken);
    return response;
  }
}

Constraints select the requests a behavior wraps (where TRequest : ICommand, where TRequest : IIdempotent). A constraint that matches nothing is TWM011.

Named pipelines

Pipelines are empty marker types.

[assembly: MediatorBehavior(typeof(ClientStampBehavior<,>), Scope = typeof(ClientPipeline))]

services.AddGeneratedMediator();
services.AddGeneratedMediator<ClientPipeline>();

ISender<ClientPipeline> client = scope.ServiceProvider.GetRequiredService<ISender<ClientPipeline>>();
string reply = await client.Send(new ClientPing());

public sealed class ClientPipeline
{
}

[MediatorScope(typeof(ClientPipeline))]
public sealed class ClientPing : IRequest<string>
{
}

Details: m2-named-pipelines.md.

Manifest

MediatorManifest is internal in the generated namespace. Version is 2. There is no profile field. Request(displayName) returns kind, response type, scope, and the ordered behavior list. The host assembly carries [assembly: GeneratedMediator(typeof(Mediator))].

3. Diagnostics

Full text: diagnostics.md.

Id Meaning Fix
TWM001 Request in a member assembly has no handler Add one IRequestHandler, or delete the request
TWM002 More than one handler for a request Keep exactly one
TWM003 Handler and message name different [MediatorScope] markers Make them match, or scope only one side
TWM004 ISender<TScope>.Send (or unscoped ISender in a host) sends a request from another pipeline Inject the matching sender, or move the request
TWM007 Member-assembly type is inaccessible from the host Make it public, or [assembly: InternalsVisibleTo("Host")]
TWM008 TimeWarp.Mediator or MS.DI Abstractions is missing. Nothing is generated Reference TimeWarp.Mediator and Microsoft.Extensions.DependencyInjection.Abstractions
TWM010 (warning) [MediatorBehavior] type is not an IPipelineBehavior<,> Fix the type or remove the attribute
TWM011 (warning) Behavior constraints match no request in its pipeline Fix the constraints or Scope, or remove it
TWM012 GeneratedHandlerAttribute names a handler that is not a constant, is not a type name, is not an IRequestHandler for that request, or still does not exist after generation In another assembly, add a constructor parameter named handlerTypeName. Otherwise make the name a constant type name relative to the request's containing type, and emit that handler

In a generator host the generator reports TWM001–TWM003 and an unreadable TWM012. The analyzer reports TWM004 there, TWM012 when the named handler is missing, and TWM001–TWM004 in a library. A library reports TWM012 only for an unreadable name. TWM005, TWM006, and TWM009 are retired.

4. Gotchas

5. Migrating

migration.md has the package table and the TimeWarp.State, TimeWarp.Architecture, and TimeWarp.Nuru sections. Breaking changes with finding numbers: 15.0.0.md.