with one click
shiny-mediator
// Generate Shiny Mediator handlers, contracts, middleware, and scaffold projects for .NET applications
// Generate Shiny Mediator handlers, contracts, middleware, and scaffold projects for .NET applications
| name | shiny-mediator |
| description | Generate Shiny Mediator handlers, contracts, middleware, and scaffold projects for .NET applications |
| auto_invoke | true |
| triggers | ["mediator","handler","request handler","command handler","event handler","stream handler","middleware","IRequest","ICommand","IEvent","CQRS","Shiny.Mediator","server sent events","SSE","EventStream","WaitForSingleEvent","IAsyncEnumerable","IStreamRequest","IServerSentEventsStream","OpenAPI","HTTP client","MediatorHttp","swagger","contract-first","strongly typed HTTP","AI tools","AITool","Microsoft.Extensions.AI","AddGeneratedAITools","ShinyMediatorGenerateAITools"] |
You are an expert in Shiny Mediator, a mediator pattern library for .NET applications.
Invoke this skill when the user wants to:
Documentation: https://shinylib.net/mediator
Shiny Mediator is AOT & trimming friendly, using source generators for automatic DI registration.
| Pattern | Contract | Handler | Usage |
|---|---|---|---|
| Request | IRequest<TResult> | IRequestHandler<TRequest, TResult> | Queries returning data |
| Command | ICommand | ICommandHandler<TCommand> | Void state changes |
| Event | IEvent | IEventHandler<TEvent> | Pub/sub notifications |
| Stream | IStreamRequest<TResult> | IStreamRequestHandler<TRequest, TResult> | IAsyncEnumerable |
Always use registration attributes:
[MediatorSingleton] // Stateless handlers
[MediatorScoped] // Handlers needing per-request services (DbContext)
Critical: Partial Class Requirement
When using any middleware attribute ([Cache], [OfflineAvailable], [Resilient], [MainThread], [TimerRefresh], [Sample], [Throttle]), the handler class must be declared as partial:
[MediatorSingleton]
public partial class MyHandler : IRequestHandler<MyRequest, MyResult> // partial required!
{
[Cache(AbsoluteExpirationSeconds = 60)]
public Task<MyResult> Handle(...) { }
}
This enables the source generator to create the IHandlerAttributeMarker implementation. Without partial, you'll get error SHINY001.
ASP.NET:
builder.Services.AddShinyMediator(x => x
.AddMediatorRegistry()
);
app.MapGeneratedMediatorEndpoints();
MAUI:
builder.AddShinyMediator(x => x
.AddMediatorRegistry()
.UseMaui()
.AddMauiPersistentCache()
.PreventEventExceptions()
);
Blazor:
builder.Services.AddShinyMediator(x => x
.AddMediatorRegistry()
.UseBlazor()
.PreventEventExceptions()
);
When generating Shiny Mediator code:
Always use records for immutability:
public record GetUserRequest(int UserId) : IRequest<UserDto>;
public record CreateUserCommand(string Name, string Email) : ICommand;
public record UserCreatedEvent(int UserId, string Name) : IEvent;
Include all three parameters in Handle method:
[MediatorScoped]
public class GetUserRequestHandler : IRequestHandler<GetUserRequest, UserDto>
{
public Task<UserDto> Handle(
GetUserRequest request,
IMediatorContext context,
CancellationToken cancellationToken)
{
// Implementation
}
}
Apply to handler methods as needed:
[Cache(AbsoluteExpirationSeconds = N)] - Cacheable queries[OfflineAvailable] - Offline storage for mobile[Resilient("policyName")] - Retry/timeout policies[MainThread] - MAUI main thread execution[TimerRefresh(milliseconds)] - Auto-refresh streams[Sample(milliseconds)] - Fixed-window sampling (last event in window executes)[Throttle(milliseconds)] - True throttle (first event executes, cooldown discards rest)[Validate] - Data annotation validationWhen using ANY of these attributes, the handler class MUST be partial:
[MediatorSingleton]
public partial class CachedHandler : IRequestHandler<MyRequest, MyData>
{
[Cache(AbsoluteExpirationSeconds = 60)]
[OfflineAvailable]
public Task<MyData> Handle(...) { }
}
Use [MiddlewareOrder(int)] on custom middleware classes to control execution order. Lower values run first (outermost). Default is 0.
[MiddlewareOrder(-100)] // Runs before middleware with higher order values
[MediatorSingleton]
public class EarlyMiddleware<TRequest, TResult> : IRequestMiddleware<TRequest, TResult>
where TRequest : IRequest<TResult>
{ ... }
Place files in appropriate folders:
Contracts/{Name}Request.cs, Contracts/{Name}Command.csHandlers/{Name}Handler.csMiddleware/{Name}Middleware.csRequest:
var response = await mediator.Request(new GetUserRequest(1));
var user = response.Result;
Command:
await mediator.Send(new CreateUserCommand("John", "john@example.com"));
Event:
await mediator.Publish(new UserCreatedEvent(1, "John"));
Chaining via Context:
public async Task<UserDto> Handle(GetUserRequest request, IMediatorContext context, CancellationToken ct)
{
// Use context to chain operations (shares scope)
await context.Publish(new UserAccessedEvent(request.UserId));
return new UserDto(...);
}
WaitForSingleEvent - Await a single event occurrence (with optional filter):
// Wait for a specific event (blocks until event fires or cancellation)
var evt = await mediator.WaitForSingleEvent<OrderCompletedEvent>(
filter: e => e.OrderId == orderId,
cancellationToken: ct
);
EventStream - Continuous IAsyncEnumerable stream of events (uses Channels internally):
// Consume events as an async stream
await foreach (var evt in mediator.EventStream<PriceUpdatedEvent>(cancellationToken: ct))
{
Console.WriteLine($"New price: {evt.Price}");
}
Subscribe - Manual subscription returning IDisposable:
var sub = mediator.Subscribe<MyEvent>((ev, ctx, ct) =>
{
Console.WriteLine($"Event received: {ev}");
return Task.CompletedTask;
});
// Later: sub.Dispose() to unsubscribe
Stream handlers decorated with [MediatorHttpGet] or [MediatorHttpPost] on an IStreamRequestHandler are automatically generated as SSE endpoints by the source generator via MapGeneratedMediatorEndpoints().
Manual SSE endpoint with EventStream:
app.MapGet("/events", ([FromServices] IMediator mediator) =>
TypedResults.ServerSentEvents(mediator.EventStream<MyEvent>())
);
Stream handler as auto-generated SSE endpoint:
public record TickerStreamRequest : IStreamRequest<int>;
[MediatorScoped]
public class TickerStreamHandler : IStreamRequestHandler<TickerStreamRequest, int>
{
[MediatorHttpGet("/ticker")]
public async IAsyncEnumerable<int> Handle(
TickerStreamRequest request,
IMediatorContext context,
[EnumeratorCancellation] CancellationToken cancellationToken)
{
var i = 0;
while (!cancellationToken.IsCancellationRequested)
{
yield return i++;
await Task.Delay(1000, cancellationToken);
}
}
}
HTTP client-side SSE consumption: Implement IServerSentEventsStream marker on the contract to indicate the server returns SSE format. The generated HTTP handler will use ReadServerSentEvents<T>() to parse the data: prefixed SSE lines.
public record TickerStreamRequest : IStreamRequest<int>, IServerSentEventsStream;
Shiny Mediator generates strongly-typed HTTP client handlers from contract classes decorated with HTTP method attributes. No manual HttpClient code needed.
Decorate request classes with [Get], [Post], [Put], [Delete], [Patch] and use [Query], [Header], [Body] on properties:
[Get("/api/orders/{OrderId}")]
public class GetOrderRequest : IRequest<OrderDto>
{
public int OrderId { get; set; } // Route parameter (matches {OrderId})
[Query("status")]
public string? Status { get; set; } // ?status=value
[Header("Authorization")]
public string? AuthToken { get; set; } // HTTP header
}
[Post("/api/orders")]
public class CreateOrderRequest : IRequest<OrderDto>
{
[Body]
public CreateOrderBody? Body { get; set; } // JSON request body
}
The source generator creates handler classes inheriting BaseHttpRequestHandler that build routes, add query/header parameters, serialize bodies, and call IHttpClientFactory.
Registration:
builder.Services.AddShinyMediator(x => x
.AddMediatorRegistry()
.AddStrongTypedHttpClient() // Registers generated HTTP handlers
);
Generate contracts, models, and handlers directly from OpenAPI/Swagger specs. Add a <MediatorHttp> item in your .csproj:
<ItemGroup>
<!-- Remote URL: Include is a logical name, Uri points to the spec -->
<MediatorHttp Include="MyApi"
Uri="https://api.example.com/swagger/v1/swagger.json"
Namespace="MyApp.ExternalApi"
ContractPostfix="HttpRequest"
GenerateJsonConverters="true"
Visible="false" />
<!-- Local file: Include is the file path, no Uri needed -->
<MediatorHttp Include="./specs/openapi.yaml"
Namespace="MyApp.LocalApi"
Visible="false" />
</ItemGroup>
Include can be a file path (for local specs) or a logical name when Uri is set separately.
MediatorHttp metadata options:
| Metadata | Description |
|---|---|
Uri | URL or local path to OpenAPI JSON/YAML spec |
Namespace | C# namespace for generated types |
ContractPrefix | Prefix for generated contract class names |
ContractPostfix | Postfix for generated contract class names |
UseInternalClasses | Generate internal classes instead of public |
GenerateModelsOnly | Only generate models, no handlers |
GenerateJsonConverters | Generate JsonConverter implementations for enums |
Registration of generated OpenAPI client:
builder.Services.AddShinyMediator(x => x
.AddMediatorRegistry()
.AddGeneratedOpenApiClient() // Registers all OpenAPI-generated handlers
);
Then use like any other mediator request:
var result = await mediator.Request(new GetPetsHttpRequest { Status = "available" });
Shiny Mediator can expose your request and command contracts as AI-callable tools via Microsoft.Extensions.AI. The source generator discovers contracts annotated with [Description] and generates AIFunction wrappers with JSON schemas automatically.
Microsoft.Extensions.AI NuGet package:dotnet add package Microsoft.Extensions.AI
.csproj:<PropertyGroup>
<ShinyMediatorGenerateAITools>true</ShinyMediatorGenerateAITools>
</PropertyGroup>
:::caution
If ShinyMediatorGenerateAITools is enabled but Microsoft.Extensions.AI is not referenced, the source generator emits compiler error SHINYMED100.
:::
Add [Description] to your contracts and their properties to make them discoverable by AI:
using System.ComponentModel;
[Description("Gets the weather forecast for a given city")]
public record GetWeatherRequest(
[property: Description("The city name to get weather for")]
string City
) : IRequest<WeatherResult>;
[Description("Performs a mathematical calculation")]
public record CalculateRequest(
[property: Description("First operand")]
double A,
[property: Description("Math operator: +, -, *, /")]
string Operator,
[property: Description("Second operand")]
double B
) : IRequest<double>;
[Description("Sends a notification to a user")]
public record SendNotificationCommand(
[property: Description("The user ID to notify")]
int UserId,
[property: Description("The notification message")]
string Message
) : ICommand;
Register the generated AI tools with the mediator builder:
builder.Services.AddShinyMediator(cfg =>
{
cfg.AddMediatorRegistry();
cfg.AddGeneratedAITools(); // Registers all [Description]-annotated contracts as AITool instances
});
Retrieve the tools from DI and pass them to any IChatClient:
using Microsoft.Extensions.AI;
var tools = host.Services.GetServices<AITool>().ToList();
var options = new ChatOptions { Tools = tools };
var response = await chatClient.GetResponseAsync(history, options);
For each contract with [Description] that implements IRequest<T> or ICommand, the source generator produces:
AIFunction class — wraps the mediator call with a JSON schema built from the contract's propertiesAddGeneratedAITools() on ShinyMediatorBuilder that registers all generated tools as AITool singletonsThe generated JSON schema includes property types, descriptions, required fields, enum values, and default values.
| Type | JSON Schema Type |
|---|---|
string, Guid, Uri, DateTime, DateTimeOffset, DateOnly | string |
bool | boolean |
int, long, short, byte | integer |
float, double, decimal | number |
| Enums | string with enum values |
Arrays / IEnumerable<T> | array |
| Complex types | object |
partial with middleware attributes - Required for [Cache], [OfflineAvailable], [Resilient], etc.context.Request() not injecting IMediatormediator.EventStream<T>() with TypedResults.ServerSentEvents() for event-driven SSEFor detailed templates and examples, see:
reference/templates.md - Code generation templates (includes SSE endpoint templates)reference/scaffolding.md - Project structure templatesreference/middleware.md - Middleware configurationreference/api-reference.md - Full API, event subscriptions, SSE, and NuGet packagesdotnet add package Shiny.Mediator # Core
dotnet add package Shiny.Mediator.Maui # MAUI
dotnet add package Shiny.Mediator.Blazor # Blazor
dotnet add package Shiny.Mediator.AspNet # ASP.NET
dotnet add package Shiny.Mediator.Resilience # Polly
dotnet add package Shiny.Mediator.Caching.MicrosoftMemoryCache # Caching
dotnet add package Shiny.Mediator.AppSupport # Offline
dotnet add package Microsoft.Extensions.AI # AI Tools