Shiny.NET | Blog

Introducing Shiny.AiConversation — AI Conversation

Wed, 06 May 2026 00:00:00 GMT

Building an AI-powered app today means stitching together a chat client, speech recognition, text-to-speech, audio playback, message persistence, and state management — across platforms, with proper lifecycle handling. That’s a lot of plumbing before you write your first prompt.

Shiny.AiConversation wraps all of that into a single IAiConversationService interface. Text chat, voice chat, hands-free wake word activation, configurable audio feedback, and persistent chat history — registered with one DI call, consumed through one service.

The Problem

Every AI chat app ends up building the same infrastructure:

An authenticated chat client that handles token refresh
Speech-to-text so users can talk instead of type
Text-to-speech so the AI can respond out loud
Sound effects for state transitions (thinking, responding, error)
A wake word listener for hands-free mode
Message persistence for chat history
State management so the UI knows what’s happening
Thread safety so nothing blows up

Each of these is a separate library, a separate abstraction, and a separate set of platform quirks. You spend weeks on infrastructure before you ship a single feature.

The Solution

// Register your chat client in DI
builder.Services.AddChatClient(new OpenAIClient("your-api-key").GetChatClient("gpt-4o").AsIChatClient());

builder.Services.AddShinyAiConversation(opts =>
{
    opts.SetMessageStore<MyMessageStore>(); // optional
});

That’s it. The service registers IAiConversationService with all the wiring — speech services from Shiny.Speech, chat completions from Microsoft.Extensions.AI, audio playback, time provider, and optional message persistence. The default IChatClientProvider resolves IChatClient straight from DI, so for most apps you just register your chat client and go. For advanced scenarios (on-demand auth, token refresh), you can still implement IChatClientProvider directly.

What You Can Do

Text Chat

The simplest path. Send a message, get a streaming response:

aiService.AiResponded += response =>
{
    if (response.Response.Text is { } text)
        Console.WriteLine($"AI: {text}");
};

await aiService.TalkTo("What is .NET MAUI?", cancellationToken);

The service handles the full lifecycle — acquires the chat client, prepends system prompts, streams the response, stores both messages if a message store is configured, fires the event, and manages state transitions throughout.

Voice Chat (Push-to-Talk)

One method call captures speech and sends it to the AI:

await aiService.ListenAndTalk(cancellationToken);

The service activates speech-to-text, waits for the user to stop speaking, sends the transcribed text through TalkTo(), and optionally reads the response aloud via text-to-speech. If the AI responds with a question, the service automatically keeps listening for the user’s reply — creating a natural back-and-forth conversation without requiring another button press.

Hands-Free Wake Word

This is the “Hey Siri” experience:

await aiService.StartWakeWord("Hey Copilot");

The service enters a continuous loop: listen for the wake phrase, capture the utterance that follows, send it to the AI, loop back. If the AI asks a follow-up question, the loop skips wake word detection and listens directly for the user’s reply. The user never touches the screen. Call StopWakeWord() when you’re done.

Four Acknowledgement Modes

Control how the AI delivers responses:

Mode	What Happens
`None`	Silent — text only, delivered via the `AiResponded` event
`AudioBlip`	Short sound effects at each state transition
`LessWordy`	Text-to-speech with a “be concise” system prompt
`Full`	Full text-to-speech of the complete response

Sound effects are driven by string file names and a SoundResolver callback — the library stays platform-agnostic while you provide the stream:

aiService.SoundResolver = name => FileSystem.OpenAppPackageFileAsync(name);
aiService.ThinkSound = "think.mp3";
aiService.OkSound = "ok.mp3";

Voice Interruption

During TTS playback, the service listens for voice interruptions. Say a “quiet word” like “stop” or “cancel” and TTS is silenced immediately, breaking out of the conversation. Say anything else and TTS stops, but your new utterance is sent to the AI as the next message — the conversation continues seamlessly.

// Default quiet words: cancel, quiet, shut up, stop, nevermind, never mind, hush
// Customize or disable:
aiService.QuietWords = ["stop", "cancel"];
aiService.QuietWords = null; // disable interruption

Quiet words only trigger when they’re the user’s entire utterance. “Cancel this appointment” won’t interrupt — it’ll be treated as a new message to the AI.

Chat History with AI Self-Lookup

Register an IMessageStore and every message is automatically persisted. But the interesting part is the AI chat lookup tool — it’s an AITool that lets the AI search its own conversation history:

“What did we talk about yesterday?” “Find the recipe you gave me last week.”

The tool is registered automatically when you call SetMessageStore(). The AI gets search parameters (text, date range, limit) and queries your store directly.

Observable State

The service exposes its current state and fires events:

aiService.StatusChanged += state =>
{
    // state: Idle, Listening, Thinking, Responding
    UpdateUI(state);
};

This is what powers the “Aura” visualization in our sample app — a pulsing orb that changes color based on what the AI is doing.

Bring Your Own Backend

The library doesn’t care which AI you use. By default, it resolves IChatClient from DI — just register one and you’re done. For advanced auth scenarios, implement IChatClientProvider to return any IChatClient from Microsoft.Extensions.AI:

OpenAI — new OpenAIClient(apiKey).GetChatClient("gpt-4o").AsIChatClient()
GitHub Copilot — OAuth device code flow with Copilot API token exchange
Azure OpenAI — Managed identity or API key
Ollama — Local model, no auth needed
Anything else — If it implements IChatClient, it works

The sample apps include a complete GitHub Copilot implementation with device code flow, token caching, automatic re-authentication, and the custom HTTP headers the Copilot API requires.

Cross-Platform from Day One

The library targets plain net10.0 — no MAUI dependency in the library itself. Shiny.Speech handles the platform abstraction for speech and audio, so the same IAiConversationService works on:

MAUI — Android, iOS, Windows, Mac Catalyst
Blazor — Server-side and WebAssembly (speech via Web Audio API)

We ship two sample apps that prove it: a full MAUI sample with chat, settings, and an animated aura visualization, plus a Blazor Server sample with the same features translated to Razor components and CSS animations.

AOT Compatible

The library is built with IsAotCompatible=true. Generic type parameters on SetChatClientProvider<T>() and SetMessageStore<T>() carry [DynamicallyAccessedMembers] attributes so the trimmer knows what to keep. No reflection surprises at runtime.

Get Started

dotnet add package Shiny.AiConversation

The library is MIT licensed and open source. We’d love to hear what you build with it.

The Feedback Service — One Hook to Rule Them All

Sun, 03 May 2026 00:00:00 GMT

Every tap, swipe, and keystroke in your app is an opportunity. An opportunity to confirm the user’s action, guide their attention, or add a layer of polish that separates “functional” from “delightful.” Most apps handle this with scattered HapticFeedback.Default.Perform() calls sprinkled across code-behind files. It works — until you want text-to-speech for accessibility, sound effects for a kiosk app, analytics for product telemetry, or different feedback for different controls. Then you’re threading conditional logic through every view in your app.

Shiny Controls v1.0 ships with IFeedbackService — a single injectable service that every interactive control in the library already calls. You implement it once. Every control uses it automatically.

How It Works

Every Shiny control that supports feedback has a UseFeedback property (default: true). When a user interaction occurs — a message sent, a pin digit entered, a panel opened — the control calls IFeedbackService.OnRequested() with three things:

public interface IFeedbackService
{
    void OnRequested(object control, string eventName, object? args = null);
}

control — the actual control instance, not a Type. Pattern match directly: control is ChatView, control is SecurityPin.
eventName — what happened: "MessageReceived", "DigitEntered", "Opened".
args — contextual data. For ChatView, this is the full ChatMessage object. For standard MAUI controls, it’s the native EventArgs. For SecurityPin completion, it’s "LongPress".

The default HapticFeedbackService does what you’d expect — click haptic for most events, long press haptic for completion events. But the real power is in replacing it.

Custom Feedback: TTS + Sound Effects

Here’s a real example from our sample app. One service, three behaviors — haptic, text-to-speech for incoming chat messages, and audio cues for PIN entry:

public class MyCustomFeedbackService(
    ITextToSpeechService textToSpeech,
    IAudioManager audioManager
) : HapticFeedbackService
{
    public override async void OnRequested(object control, string eventName, object? args)
    {
        // haptic first — always
        base.OnRequested(control, eventName, args);

        // speak incoming chat messages aloud
        if (control is ChatView && args is ChatMessage { IsFromMe: false } msg)
        {
            await textToSpeech.SpeakAsync(
                $"Message from {msg.SenderId}. {msg.Text}"
            );
        }
        // click and success sounds for PIN entry
        else if (control is SecurityPin)
        {
            var sound = eventName.Equals("completed", StringComparison.OrdinalIgnoreCase)
                ? "pin_success.wav"
                : "pin_click.wav";

            var raw = await FileSystem.OpenAppPackageFileAsync(sound);
            audioManager.CreatePlayer(raw).Play();
        }
    }
}

builder.UseShinyControls(cfg =>
{
    cfg.SetCustomFeedback<MyCustomFeedbackService>();
});

Because control is the live instance and args carries typed data, you can make nuanced decisions without parsing strings. The ChatMessage gives you sender, timestamp, text, and image URL. The SecurityPin instance gives you its current value and length. Cast, match, and go.

Pluggable MAUI Control Hooks

Shiny’s own controls call IFeedbackService internally. But what about standard MAUI controls — Button, Slider, Entry? The MauiControlFeedbackBuilder hooks them in automatically, with an AOT-compatible, fully pluggable design:

All defaults

cfg.AddDefaultMauiControlFeedback();

This registers hooks for 12 standard MAUI controls — Button.Clicked, Entry.TextChanged, Slider.ValueChanged, Switch.Toggled, and more. Each hook passes the control instance as control and the native event args as args.

Defaults + your own

cfg.AddDefaultMauiControlFeedback(x =>
{
    x.Hook<MyCustomControl>(nameof(MyCustomControl.Tapped),
        (c, h) => c.Tapped += h,
        (c, h) => c.Tapped -= h);
});

Only what you need

cfg.AddMauiControlFeedback(x =>
{
    x.Hook<Button>(nameof(Button.Clicked),
        (btn, h) => btn.Clicked += h,
        (btn, h) => btn.Clicked -= h);

    x.Hook<Slider, ValueChangedEventArgs>(nameof(Slider.ValueChanged),
        (s, h) => s.ValueChanged += h,
        (s, h) => s.ValueChanged -= h);
});

Two overloads cover every case:

Hook<TControl>(eventName, subscribe, unsubscribe) for plain EventHandler events
Hook<TControl, TEventArgs>(eventName, subscribe, unsubscribe) for typed EventHandler<TEventArgs> events

Under the hood, each hook uses a ConditionalWeakTable to track handlers per control instance — no leaks, no dictionaries to manage, proper unsubscription when controls leave the visual tree. Zero reflection, fully AOT-safe.

What Ships Built-In

Every Shiny control fires feedback through this system. Here’s the full event catalog:

Control	Events
ChatView	`MessageSent`, `MessageReceived`, `MessageTapped` (all pass `ChatMessage`), `AttachImage`
SecurityPin	`DigitEntered`, `Completed`
FloatingPanel	`Opened`, `Closed`, `DetentChanged`
ImageViewer	`Opened`, `Closed`, `DoubleTapped`
ImageEditor	`ToolModeChanged`, `Undo`, `Redo`, `Rotate`, `Reset`, `CropApplied`, `Saved`
Fab / FabMenu	`Clicked`, `Toggled`
Scheduler	`DaySelected`, `EventSelected`, `TimeSlotSelected`
TableView Cells	`Tapped`
Toast	`Show`

Any control’s feedback can be suppressed per-instance with UseFeedback="False".

The Design Philosophy

Most feedback systems are either too simple (a global haptic toggle) or too complex (per-control event subscriptions scattered across your app). IFeedbackService sits in the sweet spot:

One service, all controls. Implement once, every control calls it.
Instance, not type. You get the actual control, not typeof(Button). Inspect properties, check state, make decisions.
Typed args, not strings. ChatMessage, ValueChangedEventArgs, ToggledEventArgs — not "the message text".
Pluggable hooks, not hardcoded events. Add your own controls to the system with three lambdas.
AOT-safe. No reflection, no expressions, no Delegate.CreateDelegate. Just generics and delegates.

Whether you’re building an accessible app that speaks every incoming message, a kiosk that plays sound effects, or just want consistent haptic feedback across your entire UI — IFeedbackService is one implementation away.

Check out the full documentation and the sample app for a working demo with TTS and audio integration.

DocumentDb AI Tools — Give Your LLM a Database

Thu, 30 Apr 2026 00:00:00 GMT

You have a document store with customers, orders, and products. Now you want an LLM agent to answer questions about that data — or even modify it — without writing custom glue code for every operation. Shiny.DocumentDb.Extensions.AI makes that a one-time setup.

What It Does

The new Shiny.DocumentDb.Extensions.AI package generates Microsoft.Extensions.AI tool functions from your registered document types. Each type can expose up to seven operations: get by ID, query with structured filters, count, aggregate (sum/min/max/avg), insert, update, and delete.

You control everything: which types are visible to the LLM, which operations are allowed, which fields are exposed, and how many results a single query can return.

Setup in 30 Seconds

var jsonContext = new AppJsonContext(new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
});

services.AddDocumentStore(opts =>
{
    opts.DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db");
    opts.JsonSerializerOptions = jsonContext.Options;
});

services.AddDocumentStoreAITools(tools =>
{
    tools.AddType(
        jsonContext.Customer,
        capabilities: DocumentAICapabilities.All,
        configure: b => b
            .Description("Customer records")
            .Property(c => c.Status, "Active, Inactive, or Suspended")
            .IgnoreProperties(c => c.PasswordHash)
            .MaxPageSize(50)
    );

    tools.AddType(
        jsonContext.Order,
        capabilities: DocumentAICapabilities.ReadOnly
    );
});

That registers 11 tools: 7 for Customer (full CRUD) and 4 for Order (read-only). Types not registered are invisible to the LLM.

Structured Filters

The query, count, and aggregate tools accept a structured filter that supports boolean combinators — and, or, not — and leaf comparisons with operators like eq, gt, contains, startsWith, and in. The library translates these JSON filter objects into LINQ expressions against the document store, so they work across all providers (SQLite, MySQL, SQL Server, PostgreSQL).

When an LLM asks “show me customers older than 30 in Portland”, it constructs:

{
  "and": [
    { "field": "age", "op": "gt", "value": 30 },
    { "field": "city", "op": "eq", "value": "Portland" }
  ]
}

This becomes store.Query<Customer>().Where(c => c.Age > 30 && c.City == "Portland") under the hood.

Field Visibility

Not every field should be visible to an LLM agent. Use AllowProperties to create an allowlist or IgnoreProperties to hide specific fields:

// Only expose these fields
b.AllowProperties(c => c.Id, c => c.Name, c => c.Email);

// Or hide sensitive fields
b.IgnoreProperties(c => c.PasswordHash, c => c.InternalNotes);

Hidden fields don’t appear in the tool’s JSON schema, so the LLM doesn’t know they exist and can’t filter on them.

Capability Flags

The DocumentAICapabilities flags enum gives you precise control:

// Read-only: get, query, count, aggregate
tools.AddType(jsonContext.AuditLog, capabilities: DocumentAICapabilities.ReadOnly);

// Full CRUD
tools.AddType(jsonContext.Customer, capabilities: DocumentAICapabilities.All);

// Just query and count
tools.AddType(jsonContext.Config, capabilities: DocumentAICapabilities.Query | DocumentAICapabilities.Count);

AOT-Safe

All tool schemas and serialization use JsonTypeInfo<T> from your source-generated JSON context. No reflection at runtime. The filter translator builds expression trees programmatically — it never calls Expression.Compile() — so the existing JSON-extract SQL translator handles AOT-safe code generation.

Try the Copilot Sample

The repository includes a Sample.CopilotConsole project that authenticates with GitHub Copilot and starts an interactive chat session. The LLM can query customers, create orders, compute aggregates — all through the registered AI tools. Try it:

cd samples/Sample.CopilotConsole
dotnet run

Then ask things like “How many customers do we have?”, “Show me all shipped orders”, or “Add a customer named Eve, age 28”.

Getting Started

Check the AI Tools documentation for the full API reference and the release notes for the complete v4.0 changelog.

Turn Any Interface Into an AI Tool — Shiny DI 3.0

Wed, 29 Apr 2026 00:00:00 GMT

What if every service interface you already have could become an AI tool with a single attribute? Shiny Extensions DI 3.0 makes that happen — no adapter classes, no hand-rolled schemas, no registration boilerplate. Mark your interface with [Tool], add [Description] to the methods that matter, and the source generator handles the rest.

The Problem

You’ve built your services. Clean interfaces, proper DI registration, everything wired up. Now someone asks you to expose a few of those operations as AI tools for an LLM agent. Suddenly you’re writing AIFunction subclasses by hand — one per operation — each with a constructor that takes the service, a metadata property with hand-written parameter schemas, and an InvokeCoreAsync override that extracts arguments from a dictionary and forwards them to your service method.

For one or two tools, it’s fine. For ten or twenty, it’s tedious. And every time you change a method signature, you have to remember to update the corresponding tool class. The schema drifts, the argument parsing breaks, and the bugs only show up when the LLM calls the tool at runtime.

The Solution: `[Tool]` + `[Description]`

[Tool]
[Description("Manages customer orders")]
public interface IOrderService
{
    [Description("Places a new order for a customer")]
    Task<OrderResult> PlaceOrderAsync(
        [Description("The customer identifier")] Guid customerId,
        [Description("The product SKU")] string sku,
        [Description("Number of units to order")] int quantity
    );

    [Description("Cancels an existing order")]
    Task CancelOrderAsync(
        [Description("The order to cancel")] Guid orderId,
        [Description("Reason for cancellation")] string reason
    );

    // No [Description] — not exposed as a tool
    Task<List<Order>> GetInternalAuditLogAsync();
}

That’s it. The source generator produces a fully typed AIFunction subclass for each described method, wires up the parameter metadata, and generates a registration extension — all at compile time.

What Gets Generated

For PlaceOrderAsync above, the generator emits a class like this:

public class IOrderServicePlaceOrderAsyncAITool : AIFunction
{
    private readonly IOrderService _service;

    private static readonly AIFunctionMetadata _metadata =
        new AIFunctionMetadata("IOrderServicePlaceOrderAsync")
        {
            Description = "Places a new order for a customer",
            Parameters = new AIFunctionParameterMetadata[]
            {
                new("customerId")
                {
                    Description = "The customer identifier",
                    ParameterType = typeof(Guid),
                    IsRequired = true
                },
                new("sku")
                {
                    Description = "The product SKU",
                    ParameterType = typeof(string),
                    IsRequired = true
                },
                new("quantity")
                {
                    Description = "Number of units to order",
                    ParameterType = typeof(int),
                    IsRequired = true
                }
            }
        };

    public Guid CustomerId { get; set; }
    public string Sku { get; set; }
    public int Quantity { get; set; }

    public IOrderServicePlaceOrderAsyncAITool(IOrderService service)
    {
        _service = service;
    }

    public override AIFunctionMetadata Metadata => _metadata;

    protected override async Task<object?> InvokeCoreAsync(
        IEnumerable<KeyValuePair<string, object?>>? arguments,
        CancellationToken cancellationToken)
    {
        // argument extraction and service call
        return await _service.PlaceOrderAsync(
            this.CustomerId, this.Sku, this.Quantity);
    }
}

A second class is generated for CancelOrderAsync. The GetInternalAuditLogAsync method is skipped because it has no [Description].

Registration

All generated tools are registered with a single call:

services.AddGeneratedAITools();

This registers each tool as Transient<AITool, GeneratedToolClass>. You can then resolve all tools and pass them to any IChatClient:

var tools = serviceProvider.GetServices<AITool>().ToList();
var options = new ChatOptions { Tools = tools };
var response = await chatClient.GetResponseAsync(messages, options);

Conditional Generation

The AI tool code is only generated when Microsoft.Extensions.AI is referenced in your project. If you don’t reference it, the [Tool] attribute still compiles (it’s just an attribute), but no AIFunction classes or registration code are emitted. This means existing projects that add the DI package won’t get unexpected dependencies.

AOT-Safe Argument Extraction

The generated InvokeCoreAsync handles the JsonElement-vs-already-deserialized argument problem that trips up most hand-written AI tools. For every standard type, the generator emits a direct JsonElement accessor:

Type	Extraction	Reflection-free
`string`	`GetString()`	Yes
`int`, `long`, `short`, `byte`	`GetInt32()`, `GetInt64()`, etc.	Yes
`bool`	`GetBoolean()`	Yes
`double`, `float`, `decimal`	`GetDouble()`, `GetSingle()`, `GetDecimal()`	Yes
`Guid`	`GetGuid()`	Yes
`DateTime`	`GetDateTime()`	Yes
`DateTimeOffset`	`GetDateTimeOffset()`	Yes
`DateOnly`, `TimeOnly`, `TimeSpan`	`Parse(GetString())`	Yes
Enums	`Enum.Parse<T>(GetString())`	Yes
Complex types	`JsonSerializer.Deserialize<T>()`	Needs `JsonSerializerContext`

If the argument arrives as a JsonElement (common when the framework hasn’t pre-deserialized), the correct accessor is used. If it arrives already typed (some frameworks do this), a direct cast is used. Both paths are handled with a single is JsonElement check — no try/catch, no Convert.ChangeType.

CancellationToken Handling

If your service method accepts a CancellationToken, the generator does the right thing automatically:

[Description("Searches products")]
Task<List<Product>> SearchAsync(
    [Description("Search query")] string query,
    CancellationToken cancellationToken  // not exposed as a tool parameter
);

The CancellationToken is excluded from the tool’s parameter metadata and properties. In InvokeCoreAsync, it’s passed through from the framework’s cancellation token — not extracted from the argument dictionary.

Methods Without `[Description]` Are Skipped

Only methods with [Description] become tools. This gives you fine-grained control over what’s exposed to the LLM. Internal methods, admin operations, or anything you don’t want an AI agent calling — just don’t add the attribute.

Works With Your Existing DI Setup

The [Tool] attribute goes on interfaces, while [Singleton] / [Scoped] / [Transient] go on implementation classes — same as before. You keep using AddGeneratedServices() for your service registrations and add AddGeneratedAITools() alongside it:

services.AddGeneratedServices();
services.AddGeneratedAITools();  // only if M.E.AI is referenced

The two generators are independent. AI tool generation doesn’t affect or depend on your service registrations.

Getting Started

Add [Tool] to the interface
Add [Description] to the interface and the methods you want exposed
Add [Description] to parameters (optional but recommended — it helps the LLM)
Reference Microsoft.Extensions.AI in your project
Call services.AddGeneratedAITools() at startup
Resolve IEnumerable<AITool> and pass to your chat client

Check the DI documentation for the full setup guide and the release notes for the complete changelog.

One Contract, Three Transports — Mediator AI Tooling

Tue, 28 Apr 2026 00:00:00 GMT

What if you could write a single C# record and have it automatically become a fully typed AI tool — with zero adapter code? That’s what Shiny Mediator 6.3 delivers.

The Problem

Building AI tool calling today means writing repetitive adapter code. You define a JSON schema by hand, parse arguments from the LLM response, validate them, call your business logic, and serialize the result back. If you already have a mediator contract for the same operation, you’re duplicating intent across two representations. Multiply that by every tool your agent needs — ten, twenty, fifty tools — and it becomes a real maintenance problem.

Worse, the schema and the code drift apart. You rename a property in your contract but forget to update the JSON schema. You add a new required parameter but the tool adapter still treats it as optional. The LLM hallucinates a parameter name that used to exist, and your hand-written parser silently swallows the error. These bugs are subtle, hard to test, and only surface at runtime.

The Contract-First Approach

In Shiny Mediator, a contract is a plain record that describes an operation:

[Description("Get the current weather forecast for a given city")]
public record GetWeather(
    [property: Description("The city name to get weather for")]
    string City,

    [property: Description("Temperature unit: 'celsius' or 'fahrenheit'")]
    string Unit = "celsius"
) : IRequest<WeatherResult>;

public record WeatherResult(string City, double Temperature, string Unit, string Condition);

And a handler implements the logic:

[MediatorSingleton]
public partial class GetWeatherHandler : IRequestHandler<GetWeather, WeatherResult>
{
    public async Task<WeatherResult> Handle(
        GetWeather request, IMediatorContext context, CancellationToken ct)
    {
        // your logic here
    }
}

That’s the only code you write. From here, source generators take over.

AI Tool Generation

Add a [Description] attribute to your contract and set ShinyMediatorGenerateAITools=true in your project:

<PropertyGroup>
    <ShinyMediatorGenerateAITools>true</ShinyMediatorGenerateAITools>
</PropertyGroup>

The source generator produces a fully typed AIFunction subclass compatible with Microsoft.Extensions.AI:

// auto-generated
internal sealed class GetWeatherAIFunction : AIFunction
{
    private readonly IMediator _mediator;

    private static readonly JsonElement _jsonSchema =
        JsonDocument.Parse("""
        {
            "type": "object",
            "properties": {
                "city": { "description": "The city name to get weather for", "type": "string" },
                "unit": { "description": "Temperature unit", "type": "string", "default": "celsius" }
            },
            "required": ["city"]
        }
        """).RootElement.Clone();

    public override string Name => "GetWeather";
    public override string Description => "Get the current weather forecast for a given city";
    public override JsonElement JsonSchema => _jsonSchema;

    protected override async ValueTask<object?> InvokeCoreAsync(
        AIFunctionArguments arguments, CancellationToken cancellationToken)
    {
        var json = JsonSerializer.SerializeToElement(arguments);

        var contract = new GetWeather(
            City: json.GetProperty("city").GetString()!,
            Unit: json.TryGetProperty("unit", out var u) && u.ValueKind != JsonValueKind.Null
                ? u.GetString()! : "celsius"
        );

        var (_, result) = await _mediator.Request<WeatherResult>(contract, cancellationToken);
        return result;
    }
}

A registration extension is also generated:

builder.Services.AddShinyMediator(x => x
    .AddMediatorRegistry()
    .AddGeneratedAITools()   // registers every [Description] contract as an AITool
);

Then pass the tools to any IChatClient:

var tools = services.GetServices<AITool>().ToList();
var options = new ChatOptions { Tools = tools };
var response = await chatClient.GetResponseAsync(history, options);

Middleware Runs on AI Tool Calls Too

Because the generated AI tools dispatch through the mediator pipeline, every middleware you’ve already configured applies to AI tool calls automatically. Logging, validation, authorization, exception handling, caching — all of it fires without any extra wiring.

This is a significant advantage over hand-rolled AIFunction implementations. When you write a tool adapter manually, it typically calls your service layer directly, bypassing cross-cutting concerns. With the mediator approach, an AI tool call follows the same pipeline as a UI-triggered action or an API call. Your audit log captures it. Your validation middleware rejects bad input before the handler runs. Your error handling middleware catches exceptions and returns structured errors the LLM can interpret.

You can even write middleware that targets AI calls specifically — for example, injecting a MediatorContext value that tells the handler the call originated from an LLM, so you can apply tighter authorization or rate limiting for AI-initiated operations.

Scaling to Many Tools

The real power shows when your agent needs many tools. Instead of maintaining dozens of AIFunction subclasses with hand-written schemas, you just add [Description] to your existing contracts. Every contract with a description attribute becomes a tool at the next build.

Adding a new tool to your agent is the same workflow as adding any new mediator operation:

Define the contract record with [Description]
Implement the handler
Done — the tool is registered automatically

No schema files to maintain. No adapter classes to write. No registration code to update. The source generator handles the JSON schema, argument parsing, DI wiring, and AIFunction implementation.

This also means removing a tool is just deleting the [Description] attribute (or the contract itself). There are no orphaned adapters or stale schema definitions to clean up.

Beyond AI: The Same Contract Powers HTTP Too

The same contract-first approach extends beyond AI tooling. Shiny Mediator also generates HTTP clients and ASP.NET endpoints from your contracts — meaning a single record and handler can serve as an AI tool, a typed HTTP client, and a REST endpoint simultaneously. The transports are generated; you write the logic once.

Why This Matters

Traditional tool-calling setups require you to maintain parallel definitions:

Layer	Without Mediator	With Mediator
Business logic	Handler class	Handler class
AI tool schema	Manual JSON schema	Generated from contract
AI tool adapter	Manual AIFunction subclass	Generated
Argument parsing	Manual deserialization	Generated
DI registration	Manual for each tool	Generated
Middleware/validation	Manual per tool	Automatic via pipeline

With the contract-first approach, adding a new capability to your application — whether it’s exposed as an AI tool, an HTTP endpoint, or both — is one record and one handler.

Full AOT Compliance

The generated AIFunction classes are fully Native AOT compatible. Here’s what makes that possible:

No reflection. The generator reads [Description] attributes, property types, nullability, and default values at compile time. It emits direct property access code — json.GetProperty("city").GetString()! — instead of relying on JsonSerializer.Deserialize<T>() or reflection-based binding.

Static JSON schema. The schema is a compile-time constant string parsed once into a JsonElement on first use. There’s no runtime schema construction, no JsonSerializerOptions configuration, and no dynamic type inspection.

Constructor-based hydration. The generated code constructs the contract using its primary constructor with named arguments. No Activator.CreateInstance, no FormatterServices, no property setters via reflection.

Concrete types throughout. Each generated class is a sealed, non-generic concrete type. The DI registrations are explicit AddSingleton<AITool>(sp => new GetWeatherAIFunction(...)) calls — no open generics or service descriptor scanning at runtime.

This means your AI tools work in trimmed, ahead-of-time compiled applications — including .NET MAUI apps targeting iOS and Android — without linker warnings or runtime failures. The same tools that power your cloud API also run on-device in a fully native binary.

Supported Type Mappings

The generator handles the full range of C# types in your contracts:

C# Type	JSON Schema	Notes
`string`, `Guid`, `Uri`, `DateTime`	`"string"`
`bool`	`"boolean"`
`int`, `long`, `short`, `byte`	`"integer"`
`float`, `double`, `decimal`	`"number"`
`enum`	`"string"` with `"enum"` array	All values listed for the LLM
`T[]`, `IEnumerable<T>`	`"array"`
Nullable types (`T?`)	Omitted from `"required"`
Default values	Included as `"default"` in schema	Fallback used when LLM omits the parameter

ICommand contracts are also supported — the generated tool returns a success message string instead of a typed result.

Getting Started

Add the [Description] attribute to your contracts and their properties
Set <ShinyMediatorGenerateAITools>true</ShinyMediatorGenerateAITools> in your project file
Reference Microsoft.Extensions.AI
Call .AddGeneratedAITools() during mediator setup
Resolve IEnumerable<AITool> from DI and pass to your chat client

Every contract with a [Description] attribute automatically becomes a tool. Add a new contract, and the next build picks it up — no registration changes, no schema files, no adapter classes.

Check out the Sample.CopilotConsole for a working example that wires up AI tools with a chat loop, or browse the Mediator documentation for the full setup guide.

AI-Powered Navigation in Shiny MAUI Shell

Sun, 26 Apr 2026 00:00:00 GMT

What if your app could understand “My furnace is broken — it’s urgent!” and automatically open the right form with the description filled in and the priority set to Urgent? That’s exactly what the new AI integration in Shiny MAUI Shell does.

The Idea

Mobile apps have dozens of pages. Users have to know where things are, tap through menus, and manually fill in fields. But with AI chat becoming the norm, we asked: what if the AI could navigate your app for you?

Shiny Shell’s source generator already knows every route in your app and every parameter each page accepts. We just needed to make that metadata available to an AI model — and give it a way to act on what it discovers.

Two Tools, Any Number of Pages

Instead of registering a separate AI tool for every page (which doesn’t scale), we generate just two:

GetAiToolApplicableGeneratedRoutes() — returns all routes that have intent descriptions and parameters. The AI calls this to discover what pages exist and what they do.
NavigateToRoute() — accepts a route name and a Dictionary<string, string> of parameters. The AI calls this to navigate and pre-fill the form.

That’s it. Add a new page with [ShellMap] descriptions and [ShellProperty] inference hints, and the AI automatically discovers it. No tool registration changes needed.

Describe Intent, Not Pages

The key insight is that descriptions should express user intent, not page names:

// Good — the AI matches "my pipe burst" to this route
[ShellMap<WorkOrderPage>(description: "Use when the user reports something broken,
    malfunctioning, needing repair, maintenance, or service")]

// Bad — the AI has to guess what "Work order page" means
[ShellMap<WorkOrderPage>(description: "Work order page")]

Similarly, property descriptions tell the AI how to infer values from natural language. Properties can use real types — enums, ints, bools — and the generator handles conversion automatically:

public enum WorkOrderPriority { Low, Medium, High, Urgent }

[ShellProperty("Summarize what is broken based on what the user said", required: true)]
public string Description { get; set; } = string.Empty;

[ShellProperty("Infer urgency from the user's tone. Must be: Low, Medium, High, or Urgent", required: true)]
public WorkOrderPriority Priority { get; set; } = WorkOrderPriority.Medium;

The AI sends "Urgent" as a string, and the generated NavigateToRoute converts it to WorkOrderPriority.Urgent via case-insensitive Enum.Parse. The same works for int, bool, double, DateTime, Guid, and other common types.

Note that AI-compatible ViewModels do not need to implement IQueryAttributable. The generated NavigateToRoute sets [ShellProperty] properties directly on the ViewModel instance — no query attribute plumbing required.

What Gets Generated

The source generator produces GeneratedRouteInfo metadata with full parameter schemas:

public record GeneratedRouteInfo(
    string Route,
    string Description,
    GeneratedRouteParameter[] Parameters
);

public record GeneratedRouteParameter(
    string ParameterName,
    string Description,
    string TypeName,
    bool IsRequired
);

The AI model sees the route descriptions, parameter names, types, requirements, and inference hints — everything it needs to match intent and extract values.

Wiring It Up

AI extensions are now enabled by default — just install Microsoft.Extensions.AI:

dotnet add package Microsoft.Extensions.AI

builder.UseShinyShell(x => x
    .AddGeneratedMaps()
    .AddAiTools()          // registers AiMauiShellTools as singleton
);

Then inject AiMauiShellTools wherever you need AI-powered navigation. It provides a Prompt property (pre-formatted route descriptions for seeding system messages) and a Tools property (ready-to-use AITool[]):

public class ChatViewModel(AiMauiShellTools aiTools)
{
    // Seed the system prompt
    history.Add(new ChatMessage(ChatRole.System, aiTools.Prompt));

    // Use the tools
    var options = new ChatOptions { Tools = [.. aiTools.Tools] };
}

The class name is customizable via the ShinyMauiShell_AiToolsClassName MSBuild property if AiMauiShellTools doesn’t fit your naming conventions.

Try It in the Sample

The sample app includes a full working demo with GitHub Copilot authentication. Users authenticate with their own GitHub account through the OAuth device flow, and the app uses the Copilot API as the chat backend. Try saying things like:

“My furnace is not working! URGENT” — opens the work order form with description and priority filled in
“I’d like to discuss a partnership. My name is Allan, email allan@test.com” — opens the contact form with fields populated

Get Started

Check out the AI Integration documentation for the full setup guide, or browse the sample code on GitHub.

Shiny Client v4 - Windows Support, .NET 10, and a Ton of Improvements

Thu, 26 Mar 2026 00:00:00 GMT

It’s been a long road, but Shiny Client v4 is here. This is a major release that brings Windows support, moves to .NET 10, and packs in a significant number of fixes and enhancements across almost every module. Let’s dig in.

Windows Support

The headline feature of v4 — BluetoothLE, BLE Hosting, HTTP Transfers, and Locations all now work on Windows. Background support isn’t available yet on the Windows platform, but foreground scenarios are fully supported. This opens up a whole new set of use cases for desktop and kiosk applications built with .NET MAUI.

.NET 10

v4 enforces net10.0 target frameworks across the board. This is a breaking change, so make sure your projects are targeting .NET 10 before upgrading.

Configuration Extensions

HTTP Remote Configuration has been moved directly into Shiny.Extensions.Configuration. No more separate package — remote config is now a first-class citizen in the configuration stack.

Locations

Locations got a lot of love in this release, particularly on iOS where we’ve adopted the newer Apple APIs:

iOS 18+ now uses CLMonitor for GPS — the modern replacement for the legacy location APIs
New geofence registration mechanics for iOS 17+ using the new CLMonitor API
Geofence Manager RequestState now works correctly on the new CLMonitor API
GPS background permission on iOS is now requested immediately instead of waiting
GpsDelegate now has a boolean to detect if the device is stationary — useful for battery optimization and movement detection
GpsDelegate batch fix — the base calculations could receive a batch and trigger multiple calculations. This is now a synchronized operation
Android background location permission — no longer requests ACCESS_BACKGROUND_LOCATION unless realtime GPS with less than API 31 or standard background tracking is being used

HTTP Transfers

HTTP Transfers received some of the most impactful enhancements in v4:

New transfer types — Transfers can now be UploadMultipart, UploadRaw (body is raw bytes), or Download. The UploadRaw type is critical for sending directly to services like Azure Blob Storage
Azure Blob Storage helper — AzureBlobStorageRequest.CreateForAzureBlobStorage static helper method makes it dead simple to queue uploads to Azure Blob Storage
New HttpTransferDelegate — allows you to set retries and detect denied authorization, enabling you to refresh your token and issue a new request
Thread-safe HttpTransferMonitor — now uses a thread-safe BindingList
Android file validation — uploads now verify the file exists before queuing, and download directories are checked before queuing
iOS special character fix — filenames with special characters are now sent properly, along with improved form data upload

Push Notifications

iOS raw notification data — you can now #if IOS to get an AppleNotification that contains the raw NSDictionary for full access to the push payload
Azure Notification Hubs now supports template registrations for more flexible push scenarios

BluetoothLE

ManagedScanResult now includes the full advertisement data, giving you access to native internals when you need them
Improved manufacturer data parsing on Android
BLE Delegate now reports proper status changes for adapter enabled state on Android
Legacy scanning disabled on newer Android versions for better scan performance
Multiple thread safety improvements for ManagedScan- Peripheral cleanup on Android now matches iOS behavior for consistency

Jobs

Android fix — successful jobs that run too long often had the Android completion handler already disposed. This has been resolved.

Upgrading

The main thing to watch for:

Update your target frameworks to net10.0
If you were using the separate remote config package, switch to Shiny.Extensions.Configuration
HTTP Transfer Request types have changed — review the new UploadMultipart, UploadRaw, and Download options

Check out the full release notes for every detail, and head over to our documentation to get started.

As always, feedback and contributions are welcome on GitHub.

Shiny DocumentDb v3: One API, Four Databases

Mon, 23 Mar 2026 00:00:00 GMT

Shiny.SqliteDocumentDb has been rewritten as Shiny.DocumentDb — a multi-provider document store that keeps the same developer-friendly API while supporting four database backends.

What’s new in v3

SQL Server support via Shiny.DocumentDb.SqlServer
MySQL support via Shiny.DocumentDb.MySql
PostgreSQL support via Shiny.DocumentDb.PostgreSql
SQLite continues to work via Shiny.DocumentDb.Sqlite
Same API — IDocumentStore, fluent queries, projections, aggregates, transactions, AOT support — all provider-agnostic
DI extensions bundled into each provider package — no separate DI package needed

Provider setup

Each provider follows the same pattern — install the provider package and register with DI:

SQLite

dotnet add package Shiny.DocumentDb.Sqlite

using Shiny.DocumentDb.Sqlite;
services.AddSqliteDocumentStore("Data Source=mydata.db");

SQL Server

dotnet add package Shiny.DocumentDb.SqlServer

using Shiny.DocumentDb.SqlServer;
services.AddSqlServerDocumentStore("Server=localhost;Database=mydb;Trusted_Connection=true;");

MySQL

dotnet add package Shiny.DocumentDb.MySql

using Shiny.DocumentDb.MySql;
services.AddMySqlDocumentStore("Server=localhost;Database=mydb;User=root;Password=pass;");

PostgreSQL

dotnet add package Shiny.DocumentDb.PostgreSql

using Shiny.DocumentDb.PostgreSql;
services.AddPostgreSqlDocumentStore("Host=localhost;Database=mydb;Username=postgres;Password=pass;");

Migration from v2

Package changes

v2 Package	v3 Package
`Shiny.SqliteDocumentDb`	`Shiny.DocumentDb.Sqlite`
`Shiny.SqliteDocumentDb.Extensions.DependencyInjection`	(included in provider package)

Code changes

1. Update using statements:

// Before
using Shiny.SqliteDocumentDb;
using Shiny.SqliteDocumentDb.Extensions.DependencyInjection;

// After
using Shiny.DocumentDb;
using Shiny.DocumentDb.Sqlite;

2. Update DI registration:

// Before
services.AddSqliteDocumentStore("Data Source=mydata.db");
services.AddSqliteDocumentStore(opts => opts.ConnectionString = "Data Source=mydata.db");

// After
services.AddSqliteDocumentStore("Data Source=mydata.db"); // simple overload unchanged
services.AddSqliteDocumentStore(opts =>
{
    opts.DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db");
});

3. Update direct instantiation:

// Before
var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db"
});

// After
var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db")
});

// Or use the convenience constructor (unchanged)
var store = new SqliteDocumentStore("Data Source=mydata.db");

4. IDocumentStore usage is unchanged — all query, CRUD, projection, aggregate, and transaction code works exactly the same.

Documentation

Full documentation is available at /data/documentdb/.

Shiny.SqliteDocumentDb v2.0.0

Sun, 22 Mar 2026 00:00:00 GMT

v2.0.0 is now available. This release focuses on flexibility — you can now map document types to dedicated SQLite tables, use custom Id properties, diff objects against stored documents, batch insert collections efficiently, customize the default table name, and use the core library without any dependency injection framework.

Breaking Changes

DI Extensions Moved to a Separate Package

Microsoft.Extensions.DependencyInjection support has been extracted into its own package:

dotnet add package Shiny.SqliteDocumentDb.Extensions.DependencyInjection

The core Shiny.SqliteDocumentDb package no longer depends on Microsoft.Extensions.DependencyInjection.Abstractions. If you use AddSqliteDocumentStore(), add the new package. If you instantiate SqliteDocumentStore directly, no changes are needed.

New Features

Convenience Constructor

You can now create a store with just a connection string:

var store = new SqliteDocumentStore("Data Source=mydata.db");

Custom Default Table Name

The shared document table is no longer hardcoded to "documents". Set TableName on options to use any name:

var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db",
    TableName = "my_documents"
});

Table-Per-Type Mapping

You can now map specific document types to their own dedicated SQLite tables. Unmapped types continue to share the default table.

var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db",
    TableName = "documents"
}.MapTypeToTable<User>()           // auto-derives table name → "User"
 .MapTypeToTable<Order>("orders")  // explicit table name
);

MapTypeToTable<T>() — auto-derives the table name from the type using the configured TypeNameResolution
MapTypeToTable<T>(string tableName) — maps to an explicit table name
Fluent API — calls chain for concise configuration
Duplicate protection — mapping two types to the same table throws ArgumentException
AOT-safe — type names are resolved at registration time, not at runtime

Tables are lazily created on first use with the same schema (Id, TypeName, Data, CreatedAt, UpdatedAt) and composite primary key. This works seamlessly with all store operations including transactions, the fluent query builder, projections, indexes, and streaming.

Custom Id Properties

Types mapped to a dedicated table can use an alternate property as the document Id instead of the default Id. The property must be Guid, int, long, or string — the same types supported for the standard Id property.

var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db"
}.MapTypeToTable<Customer>("customers", c => c.CustomerId)
 .MapTypeToTable<Sensor>("sensors", s => s.DeviceKey)
);

All four MapTypeToTable overloads support this:

Overload	Description
`MapTypeToTable<T>()`	Auto-derive table name, default `Id` property
`MapTypeToTable<T>(tableName)`	Explicit table name, default `Id` property
`MapTypeToTable<T>(idProperty)`	Auto-derive table name, custom Id property
`MapTypeToTable<T>(tableName, idProperty)`	Explicit table name, custom Id property

Auto-generation rules still apply — Guid and numeric Ids are auto-generated when default, and the value is written back to the mapped property after insert. Custom Id remapping is only available through MapTypeToTable, keeping the shared table convention simple.

Example: Mixed Mapped and Unmapped Types

var options = new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db"
}.MapTypeToTable<User>()
 .MapTypeToTable<Order>("orders")
 .MapTypeToTable<Device>("devices", d => d.SerialNumber);

var store = new SqliteDocumentStore(options);

// Users are stored in the "User" table (Id property)
await store.Insert(new User { Id = "u1", Name = "Alice", Age = 25 });

// Orders are stored in the "orders" table (Id property)
await store.Insert(new Order { Id = "o1", CustomerName = "Alice", Status = "Pending" });

// Devices are stored in the "devices" table (SerialNumber property as Id)
await store.Insert(new Device { SerialNumber = "SN-001", Model = "Sensor-X" });

// Settings go to the default "documents" table
await store.Insert(new AppSettings { Id = "global", Theme = "Dark" });

// Queries, transactions, indexes — everything works per-table
var users = await store.Query<User>().Where(u => u.Age > 18).ToList();

DI Registration with Table Mapping

services.AddSqliteDocumentStore(opts =>
{
    opts.ConnectionString = "Data Source=mydata.db";
    opts.MapTypeToTable<User>();
    opts.MapTypeToTable<Order>("orders");
    opts.MapTypeToTable<Device>("devices", d => d.SerialNumber);
});

Document Diffing with GetDiff

Compare a modified object against the stored document and get an RFC 6902 JsonPatchDocument<T> describing the differences. Returns null if the document doesn’t exist. Powered by SystemTextJsonPatch.

var proposed = new Order
{
    Id = "ord-1", CustomerName = "Alice", Status = "Delivered",
    ShippingAddress = new() { City = "Seattle", State = "WA" },
    Lines = [new() { ProductName = "Widget", Quantity = 10, UnitPrice = 8.99m }],
    Tags = ["priority", "expedited"]
};

var patch = await store.GetDiff("ord-1", proposed);
// patch.Operations:
//   Replace /status → Delivered
//   Replace /shippingAddress/city → Seattle
//   Replace /shippingAddress/state → WA
//   Replace /lines → [...]
//   Replace /tags → [...]

// Apply the patch to any instance of the same type
var current = await store.Get<Order>("ord-1");
patch!.ApplyTo(current!);

The diff is deep — nested objects produce individual property-level operations (e.g. /shippingAddress/city), while arrays and collections are replaced as a whole. Works with table-per-type, custom Id, and inside transactions.

Batch Insert

BatchInsert inserts multiple documents in a single transaction with prepared command reuse for optimal performance. Returns the count inserted. If any document fails (e.g. duplicate Id), the entire batch is rolled back. Auto-generates IDs for Guid, int, and long Id types.

var users = Enumerable.Range(1, 1000).Select(i => new User
{
    Id = $"user-{i}", Name = $"User {i}", Age = 20 + i
});

var count = await store.BatchInsert(users); // single transaction, prepared command reused

// Inside a transaction — uses the existing transaction
await store.RunInTransaction(async tx =>
{
    await tx.BatchInsert(moreUsers);
    await tx.Insert(singleUser);
    // All committed or rolled back together
});

Migration Guide

If you use DI, add the new package:
```
dotnet add package Shiny.SqliteDocumentDb.Extensions.DependencyInjection
```
The AddSqliteDocumentStore() API is unchanged — just a different package.
If you instantiate directly, no changes required. The default behavior is identical to v1 — all documents go to a table called "documents".
Table-per-type and custom Id are opt-in. Existing databases continue to work without any changes. You can incrementally adopt table mapping for specific types while keeping everything else in the shared table.

Introducing Shiny.Music — Cross-Platform Music Library Access for .NET MAUI

Sun, 01 Mar 2026 00:00:00 GMT

Here’s something that shouldn’t be hard but is: accessing the music library on a user’s device from .NET MAUI.

On Android, you need MediaStore.Audio.Media, a ContentResolver, cursor iteration, and different permission models depending on whether you’re targeting API 33+ or older. On iOS, you need MPMediaQuery, MPMediaItem, AVAudioPlayer, and an NSAppleMusicUsageDescription entry or the app crashes on launch. There’s no MAUI abstraction. No popular NuGet package. You write platform-specific code from scratch every time.

So I built Shiny.Music — a clean, DI-first API that gives you permission management, metadata queries, playback controls, and file export across both platforms.

What Is It?

Two interfaces, one registration call:

IMediaLibrary — request permissions, query all tracks, search by title/artist/album, copy track files to app storage
IMusicPlayer — play, pause, resume, stop, seek, with state tracking and completion events

MauiProgram.cs

builder.Services.AddShinyMusic();

That registers both interfaces as singletons. Inject them anywhere.

Quick Start

public class MusicPage
{
    readonly IMediaLibrary library;
    readonly IMusicPlayer player;

    public MusicPage(IMediaLibrary library, IMusicPlayer player)
    {
        this.library = library;
        this.player = player;
    }

    async Task LoadAndPlay()
    {
        // 1. Request permission
        var status = await library.RequestPermissionAsync();
        if (status != PermissionStatus.Granted)
            return;

        // 2. Browse the library
        var allTracks = await library.GetAllTracksAsync();

        // 3. Or search
        var results = await library.SearchTracksAsync("Bohemian");

        // 4. Play a track
        await player.PlayAsync(results[0]);

        // 5. Control playback
        player.Pause();
        player.Resume();
        player.Seek(TimeSpan.FromSeconds(30));
        player.Stop();
    }
}

The Media Library

Permissions

Permissions differ between platforms:

Platform	Permission	Notes
Android 13+ (API 33)	`READ_MEDIA_AUDIO`	New granular media permission
Android 12 and below	`READ_EXTERNAL_STORAGE`	Legacy broad storage permission
iOS	Apple Music usage description	Must be in `Info.plist` or app crashes

The library handles this automatically. RequestPermissionAsync() prompts the user with the correct platform permission. CheckPermissionAsync() checks the current status without prompting.

Android AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
                 android:maxSdkVersion="32" />

iOS Info.plist:

<key>NSAppleMusicUsageDescription</key>
<string>This app needs access to your music library to browse and play your music.</string>

Track Metadata

Every track comes back as a MusicMetadata record:

public record MusicMetadata(
    string Id,           // Platform-specific unique ID
    string Title,
    string Artist,
    string Album,
    string? Genre,
    TimeSpan Duration,
    string? AlbumArtUri, // Android only — null on iOS
    string ContentUri    // content:// (Android) or ipod-library:// (iOS)
);

Querying Tracks

// Get everything
var tracks = await library.GetAllTracksAsync();

// Search across title, artist, and album
var results = await library.SearchTracksAsync("Beatles");

On Android, queries go through MediaStore.Audio.Media with ContentResolver. On iOS, they use MPMediaQuery with MPMediaPropertyPredicate.

File Export

Need to copy a track to your app’s storage?

var destination = Path.Combine(FileSystem.AppDataDirectory, "exported.m4a");
bool success = await library.CopyTrackAsync(track, destination);

Returns false if the copy isn’t possible — which brings us to the DRM caveat.

The Music Player

Playback Controls

await player.PlayAsync(track);  // Load and play
player.Pause();                  // Pause at current position
player.Resume();                 // Resume from paused position
player.Seek(TimeSpan.FromMinutes(1));  // Jump to position
player.Stop();                   // Stop and release

State Tracking

PlaybackState state = player.State;       // Stopped, Playing, or Paused
MusicMetadata? current = player.CurrentTrack;
TimeSpan position = player.Position;
TimeSpan duration = player.Duration;

player.StateChanged += (sender, args) =>
{
    // React to state transitions
};

player.PlaybackCompleted += (sender, args) =>
{
    // Track finished — load next?
};

On Android, playback uses Android.Media.MediaPlayer. On iOS, it uses AVAudioPlayer via AVFoundation. Both are properly managed — resources are released on stop and disposal.

The DRM Caveat

This is important to know upfront.

On iOS, Apple Music subscription tracks (DRM-protected) cannot be played or copied through this API. For these tracks:

ContentUri will be an empty string
CopyTrackAsync returns false
PlayAsync throws InvalidOperationException

Only locally synced or purchased (non-DRM) tracks work. The metadata (title, artist, album, duration) is still available for all tracks — you just can’t access the audio data for DRM-protected ones.

On Android, all locally stored music files work without restrictions via ContentResolver.

This is an OS-level limitation, not a library limitation. iOS simply does not expose the audio asset URL for DRM-protected media items.

Platform Support

Platform	Minimum Version	Audio Query	Playback Engine
Android	API 24 (Android 7.0)	`MediaStore.Audio.Media`	`Android.Media.MediaPlayer`
iOS	15.0	`MPMediaQuery`	`AVAudioPlayer`

Both platforms require a physical device for meaningful testing — simulators and emulators don’t have music content.

When to Use It

Good fit:

Music player apps that browse the device library
Apps that need to search or display the user’s music collection
Exporting audio files for processing (transcription, analysis, sharing)
Any app that integrates with locally stored music

Not the best fit:

Streaming music from web sources (use MediaElement or a streaming library)
Audio recording (use Plugin.Maui.Audio or platform audio APIs)
Background audio playback with lock screen controls (this is foreground playback)

Get Started

dotnet add package Shiny.Music

Full source and sample app at the GitHub repository. Documentation coming soon at shinylib.net/client/music.

Introducing Shiny.Spatial — A Dependency-Free Spatial Database and GPS Geofencing for .NET

Sun, 01 Mar 2026 00:00:00 GMT

If you’ve ever tried to do geospatial work on .NET MAUI, you know the options aren’t great. SpatiaLite requires native binaries per platform. NetTopologySuite is a full-featured geometry library — great on the server, but heavy on mobile and hostile to AOT. And the built-in platform geofencing? iOS gives you 20 circular regions. Android gives you 60. That’s it.

I needed something different — a spatial database that works everywhere .NET runs, with zero native dependencies, and a geofencing system that can monitor thousands of polygon regions from a real geographic database. So I built Shiny.Spatial.

What Is It?

Two NuGet packages:

Shiny.Spatial — a spatial database engine that stores geometry in SQLite using R*Tree virtual tables, with all spatial algorithms implemented in pure C#. No SpatiaLite, no NetTopologySuite, no native binaries.
Shiny.Spatial.Geofencing — a GPS-driven geofence monitor that watches spatial database tables for region entry/exit instead of registering individual fences with the OS.

The spatial database targets netstandard2.0 and net10.0, so it runs on MAUI, Blazor, console apps, servers — anywhere SQLite runs. The geofencing package targets iOS and Android via MAUI.

The Spatial Database

Two-Pass Query Pipeline

Every spatial query follows the same pattern:

Pass 1 — R*Tree bounding box filter (SQL, O(log n)). SQLite’s R*Tree virtual table eliminates most candidates based on bounding box overlap. This runs entirely in SQL and is extremely fast.
Pass 2 — C# geometry refinement. Surviving candidates are tested with exact geometric predicates — point-in-polygon (ray-casting), segment intersection (cross-product), Haversine distance — in pure C#.

This two-pass approach is the same strategy PostGIS and SpatiaLite use internally. The difference is that both passes here require zero native extensions.

// What happens under the hood for an Intersecting query:
// Pass 1: SELECT * FROM cities_rtree WHERE min_x <= @maxX AND max_x >= @minX ...
// Pass 2: SpatialPredicates.Intersects(candidate.Geometry, queryGeometry)

Creating a Database

using var db = new SpatialDatabase("locations.db");

var table = db.CreateTable("cities", CoordinateSystem.Wgs84,
    new PropertyDefinition("name", PropertyType.Text),
    new PropertyDefinition("population", PropertyType.Integer)
);

Each table gets a single R*Tree virtual table with auxiliary columns for WKB-encoded geometry and user-defined properties. No separate tables, no JOINs.

Geometry Types

All geometry classes are immutable and sealed:

Point, LineString, Polygon (with holes)
MultiPoint, MultiLineString, MultiPolygon
GeometryCollection

Coordinates use double X (longitude) and double Y (latitude). Polygon supports interior rings (holes) — useful for real geographic boundaries like city limits with excluded areas.

// A simple polygon — Colorado's approximate boundary
var colorado = new Polygon(new[]
{
    new Coordinate(-109.05, 37.0),
    new Coordinate(-109.05, 41.0),
    new Coordinate(-102.05, 41.0),
    new Coordinate(-102.05, 37.0),
    new Coordinate(-109.05, 37.0)  // closed ring
});

Inserting Data

// Single insert
var feature = new SpatialFeature(
    new Point(-104.99, 39.74),
    new Dictionary<string, object?>
    {
        ["name"] = "Denver",
        ["population"] = 715522
    }
);
table.Insert(feature);

// Bulk insert — transaction-wrapped
table.BulkInsert(features);

Querying — The Fluent Builder

table.Query() returns a fluent builder that chains spatial filters, property filters, distance ordering, and paging:

// Find all cities within 50km of Denver, ordered by distance
var nearby = table.Query()
    .WithinDistance(new Coordinate(-104.99, 39.74), 50_000)
    .OrderByDistance(new Coordinate(-104.99, 39.74))
    .Limit(10)
    .ToList();

// Find features inside a polygon
var inColorado = table.Query()
    .Intersecting(coloradoBoundary)
    .ToList();

// Combine spatial + property filters
var largeCities = table.Query()
    .WithinDistance(center, 100_000)
    .WhereProperty("population", ">", 100000)
    .OrderByDistance(center)
    .Limit(20)
    .ToList();

// Paging
var page2 = table.Query()
    .WhereProperty("state", "=", "Colorado")
    .Limit(10)
    .Offset(10)
    .ToList();

Property filters run in SQL (Pass 1), spatial filters run as C# refinement (Pass 2), and distance ordering plus limit/offset are applied after refinement. The query builder composes them automatically.

Direct Query Methods

For simple cases, skip the builder:

var feature = table.GetById(42);
var inBox = table.FindInEnvelope(envelope);
var intersecting = table.FindIntersecting(polygon);
var contained = table.FindContainedBy(polygon);
var nearby = table.FindWithinDistance(center, 10_000); // meters

Performance

All benchmarks on Apple M2, .NET 10, in-memory SQLite, 100K point features:

Query	Mean
FindIntersecting (polygon)	1.15 ms
FindWithinDistance	183 us
FindContainedBy	987 us
GetById	9.4 us
Fluent: spatial + property filter	1.44 ms
Fluent: distance + order + limit	254 us

Insert	Count	Mean
BulkInsert	1,000	9.8 ms
BulkInsert	10,000	93 ms
BulkInsert	100,000	964 ms

The pure algorithms are fast too — Haversine at 28ns, point-in-polygon (5 vertices) at 24ns, segment intersection at 3ns.

Serialization

Geometry is stored as WKB (Well-Known Binary), the same binary format used by PostGIS, SpatiaLite, and every major GIS tool. The built-in WkbReader and WkbWriter handle all seven geometry types.

GPS Geofencing

This is where it gets interesting for MAUI developers.

The Problem with Platform Geofencing

Native geofencing on mobile has hard limits:

	iOS	Android
Max regions	20	60
Shape	Circle only	Circle only
Precision	OS-determined	OS-determined
Timing	OS-determined	OS-determined
Handler time	~4 seconds	Limited
Emulator testing	Works	Unreliable

If your app needs to know when a user enters Denver, you register a circular region around Denver’s center. But Denver isn’t a circle — it’s an irregular polygon. And if your app needs to track entry/exit for 200 cities, you’re out of luck. You’d need 200 regions, but the OS caps you at 20 or 60.

How Shiny.Spatial.Geofencing Works

Instead of registering individual fences with the OS, Shiny.Spatial.Geofencing hooks into GPS updates and queries your spatial databases in real-time:

GPS reading comes in
For each monitored table, query table.Query().Intersecting(point).FirstOrDefault()
Compare the current feature ID with the previously stored feature ID
If they differ — fire exit for the old region and enter for the new one

No OS region limits. No circular approximations. Real polygon boundaries from real geographic data.

Setup

Install the package:

dotnet add package Shiny.Spatial.Geofencing

Create a delegate to handle region changes:

public class MyGeofenceDelegate(
    ILogger<MyGeofenceDelegate> logger,
    INotificationManager notifications
) : ISpatialGeofenceDelegate
{
    public async Task OnRegionChanged(SpatialRegionChange change)
    {
        var name = change.Region.Properties.GetValueOrDefault("name") ?? "Unknown";
        var action = change.Entered ? "Entered" : "Exited";

        logger.LogInformation("{Action} {Region} (table: {Table})", action, name, change.TableName);
        await notifications.Send("Geofence", $"{action}: {name}");
    }
}

builder.Services.AddSpatialGps<MyGeofenceDelegate>(cfg => cfg
    .Add(dbPath, "states")
    .Add(dbPath, "cities")
);

That’s it. The library now monitors both the states and cities tables. When the user crosses a state boundary, you get an exit + enter event. When they enter a city, you get a separate enter event. The two layers are tracked independently.

The API

public interface ISpatialGeofenceManager
{
    bool IsStarted { get; }
    Task<AccessState> RequestAccess();
    Task Start();
    Task Stop();
    Task<IReadOnlyList<SpatialCurrentRegion>> GetCurrent(CancellationToken cancelToken = default);
}

GetCurrent() takes a one-shot GPS reading and tells you which region the device is currently in for each monitored table — useful for initial state on app launch.

Configuration

builder.Services.AddSpatialGps<MyGeofenceDelegate>(cfg =>
{
    cfg.MinimumDistance = Distance.FromMeters(300);  // default
    cfg.MinimumTime = TimeSpan.FromMinutes(1);       // default
    cfg.Add(statesDbPath, "states");
    cfg.Add(citiesDbPath, "cities");
});

MinimumDistance and MinimumTime control how frequently GPS readings trigger spatial queries. The defaults balance battery life with responsiveness.

Multi-Layer Monitoring

Because each table is tracked independently, you get precise layer-specific events:

Drive from Denver suburbs into Denver city limits → Entered: Denver (cities table)
Drive from Denver to Colorado Springs → Exited: Denver, Entered: Colorado Springs (cities table) — no state change event
Drive from Colorado into Kansas → Exited: Colorado, Entered: Kansas (states table) — plus whatever city events apply

Pre-Built Databases

The repo ships with ready-to-use databases:

Database	Table	Geometry	Records
`us-states.db`	states	Polygon	51
`us-cities.db`	cities	Point	100
`ca-provinces.db`	provinces	Polygon	13
`ca-cities.db`	cities	Point	50

Include them as MAUI assets and copy to app data on first launch. Or build your own from any GeoJSON source using the included DatabaseSeeder tool.

Why Not SpatiaLite or NetTopologySuite?

Concern	SpatiaLite	NetTopologySuite	Shiny.Spatial
Native binaries	Yes — per platform	No	No
AOT compatible	Platform-dependent	Reflection-heavy	Yes
Trimmable	N/A	No	Yes
Bundle size	Large (native libs)	Moderate	Small (single dep: Microsoft.Data.Sqlite)
Geometry algorithms	C/C++	C#	C#
*RTree indexing**	Built-in	Separate	Built-in (SQLite)
MAUI-ready	Requires native binding per platform	Works but AOT issues	Works everywhere

The tradeoff is coverage. SpatiaLite and NTS support hundreds of spatial operations — buffer, union, difference, convex hull, spatial joins. Shiny.Spatial covers the operations that matter for mobile apps: intersects, contains, within-distance, nearest-to. If you need computational geometry operations, use NTS on the server and ship the results as a spatial database to the device.

When to Use It

Good fit:

Geofencing beyond OS limits (more than 20/60 regions, polygon shapes)
Location-aware apps that need “which city/state/zone am I in?”
Spatial search (find nearby points of interest, stores, landmarks)
Offline spatial queries without a server round-trip
Shipping pre-built geographic databases with your app

Not the best fit:

Simple circular geofencing with a few regions (use Shiny.Locations IGeofenceManager instead)
Heavy computational geometry (buffer, union, difference) — use NTS on the server
Real-time map rendering — this is a query engine, not a rendering engine

Get Started

dotnet add package Shiny.Spatial
dotnet add package Shiny.Spatial.Geofencing  # for MAUI GPS geofencing

Full documentation at shinylib.net/spatial and the GitHub repository.

Introducing Shiny.SqliteDocumentDb — Schema-Free JSON Documents in SQLite

Sun, 22 Feb 2026 00:00:00 GMT

I’ve been building .NET apps long enough to know that SQLite is the workhorse of local storage. It’s everywhere — mobile apps, desktop apps, embedded systems, even server-side caches. But every time I reach for sqlite-net or raw ADO.NET, I end up in the same loop: design tables, write migrations, manage foreign keys, rehydrate object graphs from JOINs.

For a lot of use cases — settings stores, offline caches, app state, anything with nested data — that ceremony is overkill. What I actually want is to throw an object in and get it back out. So I built Shiny.SqliteDocumentDb.

What Is It?

It’s a lightweight document store that sits on top of SQLite. You give it a .NET object, it serializes it to JSON and stores it. You query it with a fluent LINQ query builder, and it translates those expressions to json_extract SQL under the hood. No schema, no migrations, no table design.

var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db"
});

// Store a document — Id is auto-generated for Guid/int/long types
var user = new User { Id = "alice-1", Name = "Alice", Age = 25 };
await store.Insert(user);

// Fluent query builder
var results = await store.Query<User>()
    .Where(u => u.Name == "Alice")
    .OrderBy(u => u.Age)
    .ToList();

Every document type must have a public Id property of type Guid, int, long, or string. The Id is stored in both the SQLite column and the JSON blob, so query results always include it.

All JsonTypeInfo<T> parameters are optional — configure a JsonSerializerContext once and type info is auto-resolved on every call. No per-call ctx.User needed. Full AOT, fully trimmable, zero reflection.

Why Not Just Use sqlite-net?

sqlite-net is great for flat, single-table CRUD. But the moment your data has structure — an order with line items, a user with addresses, a config with nested sections — things get painful. You need multiple tables, foreign keys, multiple inserts per save, and multiple queries plus manual rehydration per read.

The document store approach collapses all of that into a single operation. One write, one read, one document.

The benchmarks tell the story:

Nested insert (Order + Address + OrderLines + Tags, 100 records):

Method	Mean
DocumentStore	5.69 ms
sqlite-net (3 tables)	176.48 ms

Nested get by ID:

Method	Mean
DocumentStore	5.04 us
sqlite-net (3 queries)	48.26 us

That’s 31x faster inserts and 10x faster reads for nested data. The document store wins because it does one write and one read instead of multiple table operations.

For flat data, sqlite-net can be faster on indexed column queries (it queries columns directly vs. json_extract). Use the right tool for the shape of your data.

What About EF Core on MAUI?

The other question I get is “why not just use EF Core?” On a server, EF Core is a reasonable choice. On .NET MAUI — iOS, Android, Mac Catalyst — it becomes a liability.

AOT is not optional on Apple platforms. iOS, iPadOS, tvOS, and Mac Catalyst all prohibit JIT compilation at the OS level. EF Core relies heavily on runtime reflection and dynamic code generation for change tracking, query compilation, and model building. Its public API is decorated with [RequiresDynamicCode] and [RequiresUnreferencedCode] throughout. That’s a non-starter for fully native AOT deployments on Apple platforms.

Android doesn’t prohibit JIT, but AOT (PublishAot or AndroidEnableProfiledAot) delivers measurably faster startup and lower memory usage — both of which directly affect user experience on mobile.

Migrations solve a problem mobile apps don’t have. On a server, you run migrations against a shared database with a known lifecycle. On a mobile device, the database is created on first launch or ships inside the app bundle. EF Core’s migration pipeline (Add-Migration, Update-Database, __EFMigrationsHistory) adds complexity with no real benefit. A schema-free document store eliminates migrations entirely.

The dependency graph is heavy. EF Core pulls in Microsoft.EntityFrameworkCore, its SQLite provider, design-time packages, and their transitive dependencies. That increases app bundle size — a real concern when app stores enforce download limits and users expect fast installs.

Mobile data is document-shaped. User preferences, cached API responses, offline data queues, local state — this data naturally has nested structure. Forcing it into normalized tables with foreign keys and JOINs adds accidental complexity.

Concern	EF Core	Shiny.SqliteDocumentDb
AOT / trimming	Reflection-heavy; no AOT support	Optional `JsonTypeInfo<T>` on every API; auto-resolves from context
Migrations	Required for every schema change	Not needed — schema-free JSON
Nested objects	Normalized tables, foreign keys, JOINs	Single document, single write, single read
App bundle size	Large dependency tree	Single dependency on `Microsoft.Data.Sqlite`
Startup time	DbContext model building, migration checks	Open connection and go

The .NET trimmer makes this worse. Libraries that depend on reflection break under trimming because the trimmer can’t statically determine which types and members are accessed at runtime. This forces you to either disable trimming (larger binaries) or maintain complex trimmer XML configuration. This library avoids both problems — source-generated JSON serialization means the trimmer can see every type, and there’s no Expression.Compile(), no Reflection.Emit, no dynamic delegates anywhere.

The Fluent Query Builder

This is the heart of the API. store.Query<T>() returns a fluent builder where you chain .Where(), .OrderBy(), .Paginate(), .Select() — then terminate with .ToList(), .ToAsyncEnumerable(), .Count(), .Any(), .ExecuteDelete(), .ExecuteUpdate(), or any aggregate method.

// Filter + sort + paginate
var page = await store.Query<User>()
    .Where(u => u.Age > 18)
    .OrderBy(u => u.Name)
    .Paginate(0, 20)
    .ToList();

// Count matching documents
var count = await store.Query<Order>()
    .Where(o => o.Status == "Pending")
    .Count();

// Delete by predicate — returns count deleted
int deleted = await store.Query<User>()
    .Where(u => u.Age < 18)
    .ExecuteDelete();

// Bulk update a property — returns count updated
int updated = await store.Query<User>()
    .Where(u => u.Age < 18)
    .ExecuteUpdate(u => u.Age, 18);

// Scalar aggregates
var maxAge = await store.Query<User>().Max(u => u.Age);
var avgAge = await store.Query<User>()
    .Where(u => u.IsActive)
    .Average(u => u.Age);

The expression visitor translates C# LINQ expressions into SQLite json_extract SQL, resolving property names from JsonTypeInfo metadata so [JsonPropertyName] and camelCase policies work correctly.

// Nested properties
var portland = await store.Query<Order>()
    .Where(o => o.ShippingAddress.City == "Portland")
    .ToList();
// → json_extract(Data, '$.shippingAddress.city') = @p0

// Collection queries with Any()
var hasWidgets = await store.Query<Order>()
    .Where(o => o.Lines.Any(l => l.ProductName == "Widget"))
    .ToList();
// → EXISTS (SELECT 1 FROM json_each(Data, '$.lines') WHERE ...)

// Collection Count()
var bigOrders = await store.Query<Order>()
    .Where(o => o.Lines.Count() > 5)
    .ToList();
// → json_array_length(Data, '$.lines') > 5

// String methods
var matches = await store.Query<User>()
    .Where(u => u.Name.Contains("li"))
    .ToList();
// → LIKE '%' || @p0 || '%'

Equality, comparisons, logical operators (&&, ||, !), null checks, DateTime/DateTimeOffset, captured variables — they all work. The full expression reference is in the README.

SQL-Level Projections

Need just a few fields from a large document? Chain .Select() to extract only the selected properties at the database level using json_object — no full deserialization.

var summaries = await store.Query<Order>()
    .Where(o => o.Status == "Shipped")
    .OrderBy(o => o.CustomerName)
    .Paginate(0, 50)
    .Select(o => new OrderSummary
    {
        Customer = o.CustomerName,
        City = o.ShippingAddress.City,
        LineCount = o.Lines.Count()
    })
    .ToList();

That Lines.Count() becomes json_array_length(Data, '$.lines') in SQL. You can also use Any(), Any(predicate), Count(predicate), Sum(), Max(), Min(), and Average() inside selectors.

Aggregate Projections

For GROUP BY queries, use the Sql marker class inside .Select():

var stats = await store.Query<Order>()
    .Where(o => o.Status != "Cancelled")
    .Select(o => new OrderStats
    {
        Status = o.Status,            // GROUP BY column
        OrderCount = Sql.Count(),     // COUNT(*)
        TotalRevenue = Sql.Sum(o.TotalAmount),
    })
    .ToList();

Non-aggregate columns are automatically grouped. Sql.Count(), Sql.Max(), Sql.Min(), Sql.Sum(), Sql.Avg() — all available.

Surgical Field Updates

Don’t always need to replace an entire document. SetProperty updates a single field in-place via json_set(), and RemoveProperty strips a field via json_remove() — both without deserializing the document.

// Update a single field
await store.SetProperty<User>("user-1", u => u.Age, 31);

// Nested paths work too
await store.SetProperty<Order>("order-1", o => o.ShippingAddress.City, "Portland");

// Strip a field entirely
await store.RemoveProperty<User>("user-1", u => u.Email);

For multi-field patches, Upsert does RFC 7396 JSON Merge Patch — deep-merging only the provided fields while preserving everything else:

await store.Upsert(new User { Id = "user-1", Name = "Alice", Age = 31 });
// Email and other fields are preserved

Streaming with IAsyncEnumerable

Use .ToAsyncEnumerable() instead of .ToList() to stream results one-at-a-time without buffering the entire set into memory.

await foreach (var order in store.Query<Order>()
    .Where(o => o.Status == "Pending")
    .OrderBy(o => o.CustomerName)
    .ToAsyncEnumerable())
{
    await ProcessOrder(order);
}

The benchmarks show streaming eliminates Gen1 GC collections entirely at 1,000+ documents while maintaining within ~2% of buffered throughput. If you’re processing results incrementally, streaming is free performance.

Expression-Based JSON Indexes

The default query performance is solid, but for hot paths you can create indexes on json_extract expressions:

await store.CreateIndexAsync<User>(u => u.Name);
// CREATE INDEX IF NOT EXISTS idx_json_User_name
// ON documents (json_extract(Data, '$.name'))
// WHERE TypeName = 'User';

Impact on a 1,000-record flat query:

Method	Mean
Without index	270 us
With index	8.52 us

~32x faster. The index lets SQLite use a B-tree lookup instead of scanning every row with json_extract. Works with nested properties too:

await store.CreateIndexAsync<Order>(o => o.ShippingAddress.City);

AOT and Trimming — First Class

All JsonTypeInfo<T> parameters are optional with = null defaults. Configure a JsonSerializerContext once at setup and every method auto-resolves type info — no per-call parameters needed.

[JsonSerializable(typeof(User))]
[JsonSerializable(typeof(Order))]
public partial class AppJsonContext : JsonSerializerContext;

var ctx = new AppJsonContext(new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
});

var store = new SqliteDocumentStore(new DocumentStoreOptions
{
    ConnectionString = "Data Source=mydata.db",
    JsonSerializerOptions = ctx.Options,
    UseReflectionFallback = false // recommended for AOT
});

// Now every call is AOT-safe without passing JsonTypeInfo explicitly
var user = new User { Id = "alice-1", Name = "Alice", Age = 25 };
await store.Insert(user);
var users = await store.Query<User>().Where(u => u.Age > 18).ToList();

Pass ctx.Options to DocumentStoreOptions.JsonSerializerOptions so the expression visitor and serializer share the same naming configuration. That’s the one thing people forget — and then their LINQ queries silently return zero results because property names don’t match.

Set UseReflectionFallback = false for AOT deployments. Instead of opaque runtime failures, you get a clear InvalidOperationException telling you exactly which type is missing from your JsonSerializerContext.

Transactions

Atomic multi-document operations with automatic commit/rollback:

await store.RunInTransaction(async tx =>
{
    await tx.Insert(order); // order.Id must be set
    await tx.Insert(user);  // user.Id must be set
    // Exception → automatic rollback
});

The tx parameter is a full IDocumentStore, so you can use any operation inside the transaction — queries, counts, removes, everything.

DI Registration

One line:

services.AddSqliteDocumentStore("Data Source=mydata.db");

Registers IDocumentStore as a singleton. For full configuration:

services.AddSqliteDocumentStore(opts =>
{
    opts.ConnectionString = "Data Source=mydata.db";
    opts.TypeNameResolution = TypeNameResolution.FullName;
    opts.JsonSerializerOptions = ctx.Options;
    opts.UseReflectionFallback = false;
});

When to Use It

Good fit:

Offline caches and app state
Settings and configuration stores
Data with nested objects and child collections
Rapid prototyping without schema design
Any scenario where you want to store and query object graphs without table design

Not the best fit:

Bulk operations on millions of rows where raw SQL shines
Simple flat-table CRUD where sqlite-net is already working well

Get Started

dotnet add package Shiny.SqliteDocumentDb

Full documentation at shinylib.net/sqlite-docdb and the GitHub repository has the complete README with benchmarks, expression reference tables, and examples.

Introducing Shiny.Maui.TableView — Settings-Style Pages for .NET MAUI, Without the Platform Pain

Sat, 21 Feb 2026 00:00:00 GMT

If you’ve built a .NET MAUI app, you’ve probably needed a settings page. A scrollable list of sections with toggles, text entries, pickers, radio buttons — the kind of UI you see in every iOS Settings screen or Android preferences panel. And if you’ve tried to build one, you know it’s surprisingly painful.

MAUI’s built-in TableView is limited. The community options either depend on native renderers that break across platform updates or haven’t kept up with modern .NET. I wanted something that just worked — pure MAUI, no platform-specific code, full MVVM support, and enough cell types to cover real app scenarios without writing custom templates for everything.

So I built Shiny.Maui.TableView.

What Is It?

It’s a settings-style TableView control built entirely on .NET MAUI layout primitives. No custom handlers, no native renderers, no platform-specific code. It ships with 15 cell types that cover the most common settings UI patterns, a three-level cascading style system, drag-and-drop reordering, dynamic section generation, and full MVVM data binding.

xmlns:tv="http://shiny.net/maui/tableview"

<tv:TableView CellAccentColor="#007AFF">
    <tv:TableRoot>
        <tv:TableSection Title="Network">
            <tv:SwitchCell Title="Wi-Fi"
                           On="{Binding WifiEnabled, Mode=TwoWay}" />
            <tv:SwitchCell Title="Bluetooth"
                           On="{Binding BluetoothEnabled, Mode=TwoWay}" />
        </tv:TableSection>
    </tv:TableRoot>
</tv:TableView>

That’s a fully functional settings section with two-way bound toggles. No custom renderers, no platform init code beyond one line in MauiProgram.cs.

Why Pure MAUI?

The existing community solution — AiForms.Maui.SettingsView — is excellent, but it uses native platform renderers (UITableView on iOS, RecyclerView on Android). That means platform-specific bugs, maintenance burden across OS updates, and behavior differences between platforms.

Shiny.Maui.TableView takes a different approach: everything is built from ContentView, ScrollView, VerticalStackLayout, Grid, and Border. One codebase, identical behavior everywhere. It runs on iOS, Android, and Mac Catalyst with zero platform-specific code.

The tradeoff is no virtualization — this is a full-render model. For settings pages with dozens of items, that’s perfectly fine. This isn’t meant for scrolling through thousands of rows; it’s meant for building the kind of structured, section-based UI that settings and forms demand.

15 Cell Types

The library ships with cell types that cover the breadth of settings UI patterns:

LabelCell — Read-only title/value display
CommandCell — Tappable cell with optional disclosure arrow and command binding
ButtonCell — Full-width button-style action cell

Toggles & Selection

SwitchCell — Toggle with customizable accent color
CheckboxCell — Native checkbox with accent color
SimpleCheckCell — Lightweight checkmark for selection lists
RadioCell — Radio selection within a section or across the entire TableView

Text Input

EntryCell — Inline text entry with placeholder, keyboard type, password masking, and max length

Pickers

DatePickerCell — Native date picker dialog
TimePickerCell — Native time picker dialog
TextPickerCell — Dropdown-style picker from a list of items
NumberPickerCell — Numeric input via dialog with min/max/unit
PickerCell — Full-page selection with single or multi-select, auto-generated display text, and configurable pick-to-close behavior

Custom

CustomCell — Host any MAUI View with optional full-width mode, command binding, and disclosure arrow

Every cell shares a common base with title, description, hint text, icon, background color, selection highlight, and border customization.

Cascading Styles

One of the features I’m most happy with is the three-level cascading style system. Set defaults at the TableView level, override at the section level, and fine-tune on individual cells.

Level 1 — TableView (global defaults):

<tv:TableView
    CellTitleColor="#333333"
    CellTitleFontSize="17"
    CellDescriptionColor="#888888"
    CellValueTextColor="#007AFF"
    CellBackgroundColor="White"
    CellAccentColor="#007AFF"
    HeaderTextColor="#666666"
    SeparatorColor="#C6C6C8">

This sets the look for every cell and header in the entire TableView.

Level 2 — TableSection (section overrides):

<tv:TableSection Title="Important"
                 HeaderBackgroundColor="#E3F2FD"
                 HeaderTextColor="#1565C0">

Level 3 — Individual cell (highest priority):

<tv:LabelCell Title="Warning" TitleColor="Red" />

The resolution logic is simple: cell property wins over section property, section wins over TableView, TableView wins over framework defaults. You set your theme once at the top and only override where you need to.

The style system covers everything: title, description, hint text, and value text fonts and colors; icon size and radius; accent color for interactive controls; cell backgrounds and selection highlights; header and footer appearance; separator color, height, and inset; section gap height and color; cell padding and borders.

Dynamic Sections

Static XAML is great for fixed settings pages, but sometimes you need sections or cells generated from data. Both TableView and TableSection support ItemsSource with DataTemplate.

Dynamic cells within a section:

<tv:TableSection Title="Devices"
                 ItemsSource="{Binding Devices}">
    <tv:TableSection.ItemTemplate>
        <DataTemplate>
            <tv:LabelCell Title="{Binding Name}"
                          ValueText="{Binding Status}" />
        </DataTemplate>
    </tv:TableSection.ItemTemplate>
</tv:TableSection>

You can mix static and templated cells in the same section using TemplateStartIndex to control where generated cells appear. The binding supports INotifyCollectionChanged, so adding or removing items from your collection updates the UI automatically.

Drag & Sort

Enable reordering with a single property:

<tv:TableView ItemDroppedCommand="{Binding ReorderCommand}">
    <tv:TableRoot>
        <tv:TableSection Title="Priority" UseDragSort="True">
            <tv:LabelCell Title="High" />
            <tv:LabelCell Title="Medium" />
            <tv:LabelCell Title="Low" />
        </tv:TableSection>
    </tv:TableRoot>
</tv:TableView>

Each cell gets up/down arrow controls. The ItemDroppedCommand receives ItemDroppedEventArgs with the section, cell, and from/to indexes so you can update your backing data.

Radio Groups

Radio selection is handled through an attached property that can scope to a section or the entire TableView:

<tv:TableSection Title="Theme"
                 tv:RadioCell.SelectedValue="{Binding SelectedTheme, Mode=TwoWay}">
    <tv:RadioCell Title="Light" Value="Light" />
    <tv:RadioCell Title="Dark" Value="Dark" />
    <tv:RadioCell Title="System" Value="System" />
</tv:TableSection>

Bind RadioCell.SelectedValue to your ViewModel and you get two-way radio group selection with no code-behind.

Full-Page Picker

The PickerCell navigates to a dedicated selection page — useful for long lists or multi-select scenarios:

<tv:PickerCell Title="Interests"
               ItemsSource="{Binding AllInterests}"
               SelectedItems="{Binding SelectedInterests, Mode=TwoWay}"
               SelectionMode="Multiple"
               MaxSelectedNumber="5"
               UsePickToClose="True"
               UseAutoValueText="True"
               PageTitle="Select Interests" />

It auto-generates the value text from your selections, supports single and multi-select modes, and can auto-close when the max selection count is reached.

Setup

Install the NuGet package:

dotnet add package Shiny.Maui.TableView

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseShinyTableView();

Add the XAML namespace and start building:

<ContentPage xmlns:tv="http://shiny.net/maui/tableview">
    <tv:TableView>
        <tv:TableRoot>
            <tv:TableSection Title="General">
                <tv:SwitchCell Title="Notifications"
                               On="{Binding NotificationsEnabled, Mode=TwoWay}" />
                <tv:EntryCell Title="Name"
                              ValueText="{Binding UserName, Mode=TwoWay}"
                              Placeholder="Enter your name" />
                <tv:CommandCell Title="About"
                                Command="{Binding AboutCommand}"
                                ShowArrow="True" />
            </tv:TableSection>
        </tv:TableRoot>
    </tv:TableView>
</ContentPage>

When to Use It

Good fit:

Settings and preferences pages
Form-style data entry screens
Profile editing UIs
Any structured, section-based list with mixed control types
Apps targeting iOS, Android, and Mac Catalyst from a single codebase

Not the best fit:

Long scrolling lists with hundreds or thousands of items (no virtualization)
Data grids or spreadsheet-style layouts
Chat interfaces or feed-style UIs

Get Started

dotnet add package Shiny.Maui.TableView

Full documentation at shinylib.net/tableview and the GitHub repository has the complete source, sample app, and issue tracker.

Shiny Mediator & AOT - Zero Reflection, Full Speed

Tue, 10 Feb 2026 00:00:00 GMT

Native AOT and trimming are no longer “nice to have” — they’re table stakes for modern .NET apps. iOS has never allowed JIT. Blazor WebAssembly ships every byte to the browser. ASP.NET minimal APIs are racing toward sub-10ms cold starts. If your library leans on reflection, you’re the bottleneck.

Shiny Mediator took this personally.

Starting in v5 and fully realized in v6, Shiny Mediator has waged a war on reflection. Every piece of runtime introspection has been replaced with compile-time source generation. The result? A mediator pipeline that is 100% AOT-safe, fully trimmable, and frankly… faster than it has any right to be.

Let’s walk through every source generator and design decision that makes this possible.

1. Handler & Middleware Registration — `[MediatorSingleton]` / `[MediatorScoped]`

The old way of registering handlers meant scanning assemblies, resolving open generics, and hoping the DI container could figure it all out at runtime. That’s… not AOT-friendly.

Shiny Mediator replaces all of that with two attributes:

[MediatorSingleton]
public class GetUserHandler : IRequestHandler<GetUserRequest, UserResponse>
{
    public async Task<UserResponse> Handle(
        GetUserRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // your handler logic
    }
}

At compile time, the source generator discovers every class decorated with [MediatorSingleton] or [MediatorScoped] and emits all the DI registration code for you. No assembly scanning. No typeof() gymnastics. No reflection.

The generated code feeds into a module initializer registry — a static registry that collects every handler and middleware registration across your entire solution. To wire it all up:

services.AddShinyMediator(x => x.AddMediatorRegistry());

One line. Every handler. Every middleware. All generated at compile time.

These attributes also handle middleware registration — so if you have a custom middleware class, slap [MediatorSingleton] on it and it joins the party automatically.

2. Request & Stream Executors

Here’s a fun .NET limitation: you can’t easily resolve a generic type at runtime without knowing the type parameters at compile time. Previous versions of Shiny Mediator used reflection to bridge that gap. It worked, but it was slow and it was the single biggest AOT blocker.

Starting in v5, source generators create typed executors for every request and stream request in your project. These executors know the exact types at compile time, so the mediator can dispatch directly without any MakeGenericType or Activator.CreateInstance shenanigans.

You don’t need to do anything extra — if you’re using [MediatorSingleton] / [MediatorScoped], the executor generation comes along for the ride.

3. JSON Converter Source Generation

AOT’s nemesis is System.Text.Json with reflection-based serialization. The standard fix is JsonSerializerContext and [JsonSerializable] — but here’s the problem: you can’t chain source generators. Shiny Mediator’s source generator runs first, and System.Text.Json’s source generator can’t see the types that were just generated.

So Shiny Mediator built its own JSON serialization source generator.

For HTTP Contracts (OpenAPI)

When you generate HTTP clients from OpenAPI specs, just flip one switch:

<ItemGroup>
    <MediatorHttp Include="MyApi"
                  Uri="https://api.example.com/openapi.json"
                  Namespace="MyApp.Api"
                  GenerateJsonConverters="true"
                  Visible="false" />
</ItemGroup>

Setting GenerateJsonConverters="true" tells the source generator to emit high-performance, AOT-safe JSON converters for every contract and response type it produces. No reflection. No JsonSerializerContext registration. The [JsonConverter] attribute is placed directly on each type.

For Your Own Types

Got your own classes that need serialization — maybe for offline storage, caching, or custom contracts? Use the [SourceGenerateJsonConverter] attribute:

[SourceGenerateJsonConverter]
public partial class WeatherForecast
{
    public string? City { get; set; }
    public double Temperature { get; set; }
    public DateTime Date { get; set; }
}

The class must be partial (the generator needs to attach code to it). That’s it — you get a compile-time JSON converter without ever touching System.Text.Json source generation configuration.

4. Contract Key Source Generation

Middleware like caching, offline storage, and stream replay all need a key to identify unique requests. The “old school” way was implementing IContractKey on your contract:

// Before — manual, tedious, error-prone
public class SearchRequest : IRequest<SearchResult>, IContractKey
{
    public string? Query { get; set; }
    public int? Page { get; set; }
    public DateTime? Since { get; set; }

    public string GetKey()
    {
        var key = "SearchRequest";
        if (Query != null) key += $"_{Query}";
        if (Page != null) key += $"_{Page}";
        if (Since != null) key += $"_{Since:yyyyMMdd}";
        return key;
    }
}

Writing null checks and format strings for every property on every contract gets old fast. And the default IContractKeyProvider used reflection to build keys when you didn’t implement the interface.

The source-generated version:

// After — one attribute, zero reflection
[ContractKey("SearchRequest_{Query}_{Page}_{Since:yyyyMMdd}")]
public partial class SearchRequest : IRequest<SearchResult>
{
    public string? Query { get; set; }
    public int? Page { get; set; }
    public DateTime? Since { get; set; }
}

The source generator handles null checks, ToString() calls, format strings — everything. If a property is null, that portion of the key is replaced with an empty string. The class must be partial, and you can use the same format specifiers you’d use in string interpolation.

Leave the format string blank and it uses all public instance properties automatically.

5. Middleware Attribute Source Generation

This one is subtle but critical. Many of Shiny Mediator’s middleware components are driven by attributes on handler methods:

public partial class GetProductHandler : IRequestHandler<GetProductRequest, Product>
{
    [Cache(MaxAgeSeconds = 300)]
    [OfflineAvailable]
    public async Task<Product> Handle(
        GetProductRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // fetch product from API
    }
}

Reading attributes from methods at runtime requires deep reflection — MethodInfo.GetCustomAttributes() and friends. In an AOT world, that can fail silently or crash spectacularly.

Shiny Mediator’s source generator scans handler methods at compile time, extracts every attribute that inherits from MediatorMiddlewareAttribute, and emits code that makes them available via context.GetHandlerAttribute<T>() — no reflection needed at runtime.

Your handler class must be partial for this to work. That’s the one rule.

Custom Middleware Attributes

Best of all, this works with your own attributes too. Just inherit from MediatorMiddlewareAttribute:

public class AuditLogAttribute : MediatorMiddlewareAttribute
{
    public string Category { get; set; } = "General";
}

public partial class CreateOrderHandler : IRequestHandler<CreateOrderRequest, Order>
{
    [AuditLog(Category = "Orders")]
    public async Task<Order> Handle(
        CreateOrderRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // ...
    }
}

// In your middleware — zero reflection
public class AuditLogMiddleware<TRequest, TResult>
    : IRequestMiddleware<TRequest, TResult> where TRequest : IRequest<TResult>
{
    public async Task<TResult> Process(
        IMediatorContext context,
        RequestHandlerDelegate<TResult> next,
        CancellationToken ct)
    {
        var attr = context.GetHandlerAttribute<AuditLogAttribute>();
        if (attr != null)
        {
            // log with attr.Category
        }
        return await next();
    }
}

6. OpenAPI HTTP Client Generation

The HTTP extension’s OpenAPI source generator is arguably the crown jewel of Shiny Mediator’s AOT story. From a single OpenAPI spec, it generates:

Request contracts with proper HTTP verb, route, query, header, and body annotations
Response types matching the API schema
A typed request handler that uses HttpClient under the hood
JSON converters (when GenerateJsonConverters="true") for every generated type
DI registration via .AddGeneratedOpenApiClient()

All from a csproj item:

<ItemGroup>
    <MediatorHttp Include="PetStore"
                  Uri="https://petstore.swagger.io/v2/swagger.json"
                  Namespace="MyApp.PetStore"
                  ContractPostfix="HttpRequest"
                  GenerateJsonConverters="true"
                  Visible="false" />
</ItemGroup>

services.AddShinyMediator(x =>
{
    x.AddMediatorRegistry();
    x.AddGeneratedOpenApiClient();
});

Now every HTTP call flows through the mediator pipeline — which means caching, offline, validation, performance logging, and every other middleware you’ve configured automatically applies to your API calls. And it’s all AOT-safe because every type is known at compile time.

7. ASP.NET Endpoint Source Generation

On the server side, Shiny Mediator can source-generate minimal API endpoints directly from your handlers:

[MediatorScoped]
public partial class CreateUserHandler : IRequestHandler<CreateUserRequest, UserResponse>
{
    [Post("/api/users")]
    public async Task<UserResponse> Handle(
        CreateUserRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // create user
    }
}

The source generator emits the app.MapPost("/api/users", ...) call and the DI wiring. No controller classes. No manual endpoint mapping. Just your handler with an HTTP attribute and the generator does the rest.

The Big Picture

Here’s what Shiny Mediator source-generates at compile time — and what it doesn’t do at runtime:

Feature	Compile Time (Source Gen)	Runtime (Reflection)
Handler DI Registration	✅ `[MediatorSingleton]` / `[MediatorScoped]`	❌ No scanning
Request/Stream Executors	✅ Typed dispatch	❌ No `MakeGenericType`
JSON Serialization	✅ `[SourceGenerateJsonConverter]`	❌ No reflection-based serializers
Contract Keys	✅ `[ContractKey]`	❌ No property reflection
Middleware Attributes	✅ `[Cache]`, `[OfflineAvailable]`, custom	❌ No `GetCustomAttributes`
HTTP Clients	✅ `MediatorHttp` MSBuild item	❌ No runtime proxy generation
ASP.NET Endpoints	✅ Handler method attributes	❌ No controller discovery

The result is a mediator library that:

Ships on iOS without fighting the linker
Runs in Blazor WASM without bloating the download
Cold-starts fast on ASP.NET because there’s nothing to scan or JIT
Trims clean because every code path is statically reachable

Getting Started with AOT

If you’re already using Shiny Mediator, the path to full AOT is straightforward:

Make handler and contract classes partial — the source generators need this
Add [MediatorSingleton] or [MediatorScoped] to your handlers and middleware
Use [ContractKey] instead of implementing IContractKey manually
Set GenerateJsonConverters="true" on your MediatorHttp items
Use [SourceGenerateJsonConverter] on custom types that need serialization
Call x.AddMediatorRegistry() in your startup instead of manual registration

That’s it. No reflection. No runtime surprises. Just compile-time confidence.

Wrapping Up

AOT and trimming aren’t just performance checkboxes — they’re the foundation of where .NET is heading. Shiny Mediator has gone all-in on source generation to make sure you can take your mediator pipeline anywhere .NET runs: mobile, browser, server, and beyond.

If reflection was the training wheels, source generation is the carbon fiber frame. Time to ride.

Check out the full source generation docs and the HTTP extension docs for all the details.

What's New in Shiny Mediator 6

Tue, 10 Feb 2026 00:00:00 GMT

Shiny Mediator v6 has landed and it’s packed with some exciting new features and improvements. This release is a big step forward for the library, focusing on better source generation, AOT readiness, ASP.NET interop, and some slick new middleware. Let’s dive in.

.NET 8 & 10 Minimum Targets

The biggest (and breaking) change is that Shiny Mediator v6 now targets .NET 8 and .NET 10 as minimum versions. This allows us to take advantage of the latest runtime features for performance, trimming, and AOT compilation. If you’re still on older versions, you’ll need to stay on v5.

Revamped HTTP Client Source Generation

The HTTP client source generation has been completely overhauled. In v5, the OpenAPI generation would produce contracts, but you’d still need to wire up handlers and serialization yourself. In v6, the source generator now produces everything — handlers, contracts, JSON converters, and dependency injection registration.

This is a breaking change because you’ll need to call a new registration method, but the setup through MediatorHttpItem in your csproj remains the same:

<ItemGroup>
    <MediatorHttp Include="OpenApiRemote"
                  Uri="https://yourapi.com/openapi.json"
                  Namespace="My.Namespace"
                  ContractPostfix="HttpRequest"
                  GenerateJsonConverters="true"
                  Visible="false" />
</ItemGroup>

And then in your startup:

builder.Services.AddShinyMediator(x => x.AddGeneratedOpenApiClient());

That’s it. Full HTTP client with AOT-safe serialization, middleware support, and zero boilerplate.

Another nice improvement: if your OpenAPI spec doesn’t have an OperationId, the source generator now infers a name using the HTTP verb and path. For example, GET /user/list becomes GetUserList. No more missing contracts because someone forgot to set an operation ID.

DirectHttpRequest is Gone

The DirectHttpRequest type has been removed. You can still create your own HTTP objects with the [Http] attribute which will source generate a handler for you. This was cleaned up to reduce confusion between the direct approach and the more powerful generated approach.

PublishToBackground

One of the more subtle but impactful additions is PublishToBackground on IMediator. If you’ve ever tried to fire-and-forget an event in ASP.NET, you’ve probably run into scoping issues where the HttpContext or scoped services get disposed before your event handlers finish.

PublishToBackground solves this by spawning a new child scope, so you can fire events without worrying about disposal:

public class MyController(IMediator mediator) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> DoSomething()
    {
        // this returns immediately and the event handlers
        // run in a separate scope
        await mediator.PublishToBackground(new SomethingHappenedEvent());
        return Ok();
    }
}

You can still use the standard Publish to await all event handlers in the same scope.

Async Enumerable Responses & Server-Sent Events

Stream requests now support IAsyncEnumerable<T> responses that can be wired directly to Server-Sent Events endpoints. Just mark your contract with IServerSentEventsStream:

[Get("/api/sse")]
public class ServerSentEventsRequest : IStreamRequest<EventItem>, IServerSentEventsStream
{
}

If your endpoint does not support server-sent events, you can still use IStreamRequest<T> — just drop the IServerSentEventsStream interface and you get a standard async enumerable response.

Event Throttling

The new [Throttle] attribute implements a debounce pattern for event handlers. This is huge for scenarios like search-as-you-type, sensor data processing, or any rapid-fire event where you only care about the latest value:

services.AddShinyMediator(cfg => cfg.AddMediatorRegistry().AddThrottleEventMiddleware());

[MediatorSingleton]
public partial class SearchHandler : IEventHandler<SearchChangedEvent>
{
    [Throttle(300)] // wait 300ms after last event
    public async Task Handle(
        SearchChangedEvent @event,
        IMediatorContext context,
        CancellationToken ct)
    {
        // only fires once the user stops typing for 300ms
        var results = await searchService.Search(@event.Query, ct);
    }
}

How it works:

When an event is published, a timer starts
If the same event fires again before the timer expires, the timer resets and the previous event is discarded
Only after the full delay with no new events does the handler execute with the latest data

Your handler class must be partial for source generation to work.

Middleware Ordering

Previously, middleware executed in DI registration order. That’s fine for simple scenarios, but as your pipeline grows you need more control. The new [MiddlewareOrder] attribute gives you explicit ordering:

[MiddlewareOrder(-100)] // runs first (outermost)
public class ValidationMiddleware<TRequest, TResult>
    : IRequestMiddleware<TRequest, TResult> { ... }

[MiddlewareOrder(0)] // default
public class LoggingMiddleware<TRequest, TResult>
    : IRequestMiddleware<TRequest, TResult> { ... }

[MiddlewareOrder(100)] // runs last (closest to handler)
public class CachingMiddleware<TRequest, TResult>
    : IRequestMiddleware<TRequest, TResult> { ... }

This produces: Validation → Logging → Caching → Handler → Caching → Logging → Validation

Lower values run first. If you don’t use the attribute, everything works exactly as before — it’s fully opt-in.

HTTP Response Cache Middleware

A new built-in middleware that caches HTTP responses based on CacheControl MaxAge headers. If your API sends proper cache headers, Shiny Mediator will respect them automatically without any extra configuration on your part.

Additional Improvements & Fixes

Beyond the headline features, v6 includes a steady stream of refinements:

EventStream redesigned — IMediator.EventStream was dropping events under load. It’s been completely redesigned for speed and reliability.
RuntimeEventRegister is now thread-safe — dynamic event handler registration no longer has race conditions.
BaseHttpRequestHandler now handles commands — not just requests.
OpenAPI source generation fixes — proper URI path generation for PUT/POST, fixed nullable support, TimeSpan handling, and duplicate type issues.
Prism RegionNavigationCommand — contributed by codelisk for region-based navigation in Prism.

Migration Tips

If you’re coming from v5, here’s the key things to watch for:

Update your target framework to .NET 8 or .NET 10
HTTP client registration — call the new AddGeneratedOpenApiClient() method
Remove DirectHttpRequest usages — switch to [Http] attribute-based contracts
OpenAPI contracts may have slightly different names due to the automatic HttpRequest postfix

Wrapping Up

Shiny Mediator v6 continues the push toward zero-boilerplate, AOT-ready mediation for .NET. The revamped HTTP source generation alone is worth the upgrade — and features like event throttling and middleware ordering bring capabilities that would take significant effort to build yourself.

Check out the full documentation and the complete release notes for all the details.

Shiny Mediator - Getting Started

Fri, 30 Jan 2026 00:00:00 GMT

Mediator patterns have been getting a lot of attention lately, and for good reason. They help to decouple components in an application, making it easier to manage complexity and improve maintainability. Mediator patterns also go by the names “Vertical slice architecture” and CQRS (Command Query Responsibility Segregation). The big guy in .NET mediation is obviously MediatR by Jimmy Bogard. It’s an amazing library that has been used by an absolute ton of applications. It recently went to a paid model, which is understandable given the amount of work that goes into maintaining a library of that size.

The reason for building Shiny Mediator was to create a mediation library, but make sure it works with apps built on platforms like .NET MAUI and Blazor WebAssembly while also including some more “batteries included” features. This doesn’t mean I’ve neglected things like ASPNET support, but we’ll get to that in a future article.

The Haters

Many engineers will call mediators “over engineering” or “an anti-pattern”. I disagree. In fact, I think mediators are one of the best patterns for building complex applications without going full bat stuff crazy with microservices out of the gate. You can run in a monolith while still keeping things decoupled and manageable thereby making it easy to “SLICE” a piece out and move it to a microservice as your application traffic grows. Another advantage of a mediation pattern is can remove the “dependency injection hell” of adding a services for things like logging, caching, and other cross cutting concerns. Instead of having to add these services to every handler, you can just add them to the mediator pipeline, configure them or stick an attribute on a handler.

public class MyViewModel(IDataService data, ICacheManager cache, IConfiguration configuration, ILogger<MyViewModel> logger)  {
    public async Task LoadData() {
        this.Data = cache.TryGet("MyKey", ct => await data.GetData());
    }
}

The above code doesn’t look too bad, but

Imagine you have 20 view models that all need these services.
How do I make sure I’m grabbing from the same cache everytime or clearing it for that matter?
Building cache keys can be a pain

[ContractKey("{UserId}-{IsActive}")]
public record GetDataRequest(bool IsActive, string UserId) : IRequest<GetDataResponse>;


public class MyViewModel(IMediator mediator) {
    [Cache(300)]
    public async Task LoadData() {
        var response = await mediator.Send(new GetDataRequest());
        this.Data = response.Result;
    }
}

Homegrown/built in mediation patterns are often added, but require you do the growing. Middleware management is also not a simple process. Creating keys for caching requests, another whamo of complexity. These are all things solved by Shiny Mediator. AI generated code solutions is another one I hear. “Just use AI to generate the code for you”. AI is great at boilerplate or when you give it a very specific input & output, but architecture… it will throw “slop” at you.

Some of the Current Challenges

As with all patterns, there are some trade offs. Mediators map objects to handlers (methods or controllers). It is currently not tool friendly to find a corresponding handler for a contract, so you want to make sure you structure your solution and projects well to find handlers without too much effort. Another problem that can occur is middleware executes in a pipeline, so if you have a lot of middleware, you can end up with performance issues if you’re not careful about managing the middleware to ensure quick execution.

Experience of the Past

I’ve seen some large .NET MAUI applications that had so many engineers working on them, there was constant “fire drills” (the running joke that came to be). Team A would change something that would break Team B’s work. Team C would have to make changes to Team A’s code to update navigation or data retrieval.
Quite often, these breaking changes wouldn’t even be picked up until a regression test.

In this post, we’ll explore how to get started with Shiny Mediator, a library that implements the Mediator pattern with a focus on apps written with .NET.

What are some of the “batteries included”?

Most mediator libraries hand you a pipe and say “good luck”. Shiny Mediator hands you a pipe, a toolbox, a hard hat, and a coffee. Here’s what’s in the box:

Offline Mode

Your users don’t always have internet. Shocking, I know. But building offline support from scratch is the kind of soul-crushing work that makes devs question their career choices. With Shiny Mediator, slap an attribute on your handler and you’re done:

public partial class GetOrdersHandler : IRequestHandler<GetOrdersRequest, IReadOnlyList<Order>>
{
    [OfflineAvailable]
    public async Task<IReadOnlyList<Order>> Handle(
        GetOrdersRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // When online: calls your API, stores the result
        // When offline: returns the last stored result
        // You did nothing. You're welcome.
        return await api.GetOrders(ct);
    }
}

You can also configure it via appsettings.json if attributes aren’t your thing:

{
    "Mediator": {
        "Offline": {
            "MyNamespace.GetOrdersRequest": true
        }
    }
}

Want to know if the data came from the offline store? The context tells you:

var response = await mediator.Request(new GetOrdersRequest());
var offline = response.Context.Offline();
if (offline != null)
{
    // data is from offline store
    // offline.Timestamp tells you WHEN it was stored
    // maybe show a "stale data" indicator to the user
}

Caching

Caching is one of the two hardest problems in computer science (the other being naming things and off-by-one errors). Shiny Mediator makes it embarrassingly easy:

public partial class GetProductsHandler : IRequestHandler<GetProductsRequest, List<Product>>
{
    [Cache(AbsoluteExpirationSeconds = 300, SlidingExpirationSeconds = 60)]
    public async Task<List<Product>> Handle(
        GetProductsRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // This only runs when cache misses.
        // No cache key management. No IMemoryCache injection. No tears.
        return await db.GetProducts(ct);
    }
}

Setup is one line:

services.AddShinyMediator(x => x.AddMemoryCaching());

Need a cache that survives app restarts? The MAUI and Uno extensions have a persistent cache that writes to disk. Same attribute, same config — it just doesn’t evaporate when the user kills your app:

services.AddShinyMediator(x => x.AddMauiPersistentCache());

You can also force a cache refresh when you need fresh data (pull-to-refresh, anyone?):

var response = await mediator.Request(
    new GetProductsRequest(),
    CancellationToken.None,
    ctx => ctx.ForceCacheRefresh()
);
// response.Result is guaranteed fresh

Validation

Validation: where developers go to argue about whether to throw exceptions or return error objects. We support both. Pick your poison.

Data Annotations (built-in, no extra package):

services.AddShinyMediator(cfg => cfg.AddDataAnnotations());

[Validate]
public class CreateUserCommand : ICommand
{
    [Required]
    public string Name { get; set; }

    [Range(1, 150)] // optimistic about human lifespans
    public int Age { get; set; }
}

FluentValidation (for the overachievers):

services.AddShinyMediator(cfg => cfg.AddFluentValidation());

[Validate]
public class CreateUserCommand : ICommand
{
    public string? Name { get; set; }
}

public class CreateUserValidator : AbstractValidator<CreateUserCommand>
{
    public CreateUserValidator()
    {
        RuleFor(x => x.Name).NotEmpty().WithMessage("A user needs a name. Even 'Bob' will do.");
    }
}

Validation runs before your handler ever sees the request. Invalid data never touches your business logic. It’s like a bouncer for your code.

Performance Logging

Want to know which handler is being a lazy bum? Performance logging middleware tracks execution time through built-in diagnostics via Microsoft.Extensions.Diagnostics. No extra setup, no third-party APM required. Your handlers are already emitting telemetry — you just need to listen.

HTTP Client Generation

This one deserves its own blog post (coming soon), but the short version: point Shiny Mediator at your OpenAPI spec and it generates contracts, handlers, JSON converters, and DI registration. No HttpClientFactory plumbing. No System.Text.Json serialization contexts. No Polly setup. Just:

<ItemGroup>
    <MediatorHttp Include="MyApi"
                  Uri="https://myapi.com/openapi.json"
                  Namespace="MyApp.Api"
                  ContractPostfix="HttpRequest"
                  GenerateJsonConverters="true"
                  Visible="false" />
</ItemGroup>

services.AddShinyMediator(x => x.AddGeneratedOpenApiClient());

// Now just use it like any other mediator request
var users = await mediator.Request(new GetUsersHttpRequest());

All your middleware (caching, offline, validation, resilience) works with HTTP requests too. One attribute to cache API calls. One attribute for offline fallback. Your API client just became the most resilient thing in your entire codebase — and you wrote zero infrastructure code.

Getting Started

Enough talk. Let’s build something. I’ll walk you through a .NET MAUI setup since that’s where Shiny Mediator really flexes, but this works just as well with Blazor, ASP.NET, or plain old console apps (we don’t judge).

Step 1: Install the packages

dotnet add package Shiny.Mediator
dotnet add package Shiny.Mediator.Maui

For Blazor, swap Shiny.Mediator.Maui for Shiny.Mediator.Blazor. For ASP.NET or console apps, just Shiny.Mediator on its own is fine.

Step 2: Define your contracts

Contracts are just plain C# records or classes that implement one of the mediator interfaces. Think of them as the “what” — what data goes in, what data comes out.

using Shiny.Mediator;

// A command - fire and forget, no return value
public record CreateTodoCommand(string Title, string Description) : ICommand;

// A request - send something in, get something back
public record GetTodosRequest(bool IncludeCompleted) : IRequest<List<TodoItem>>;

// An event - broadcast to anyone who's listening
public record TodoCreatedEvent(TodoItem Item) : IEvent;

Step 3: Create your handlers

Handlers are where the actual work happens. One handler per command/request, but you can have multiple event handlers.

using Shiny.Mediator;

[MediatorSingleton] // source generator handles DI registration for you
public class CreateTodoHandler : ICommandHandler<CreateTodoCommand>
{
    readonly IMyDatabase db;
    readonly IMediator mediator;

    public CreateTodoHandler(IMyDatabase db, IMediator mediator)
    {
        this.db = db;
        this.mediator = mediator;
    }

    public async Task Handle(
        CreateTodoCommand command,
        IMediatorContext context,
        CancellationToken ct)
    {
        var item = new TodoItem(command.Title, command.Description);
        await db.Insert(item, ct);

        // broadcast that a todo was created
        await mediator.Publish(new TodoCreatedEvent(item));
    }
}

[MediatorSingleton]
public partial class GetTodosHandler : IRequestHandler<GetTodosRequest, List<TodoItem>>
{
    readonly IMyDatabase db;

    public GetTodosHandler(IMyDatabase db) => this.db = db;

    [Cache(AbsoluteExpirationSeconds = 120)]
    [OfflineAvailable]
    public async Task<List<TodoItem>> Handle(
        GetTodosRequest request,
        IMediatorContext context,
        CancellationToken ct)
    {
        // cached for 2 minutes AND available offline
        // two attributes, zero infrastructure code, infinite smugness
        return await db.GetTodos(request.IncludeCompleted, ct);
    }
}

Step 4: Wire it up

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp
            .CreateBuilder()
            .UseMauiApp<App>();

        builder.Services.AddShinyMediator(x =>
        {
            x.UseMaui();
            x.AddMemoryCaching();
            x.AddDataAnnotations();
        });

        // let the source generator register everything
        builder.Services.AddMediatorRegistry();

        return builder.Build();
    }
}

Step 5: Use it

public class TodoListViewModel : BaseViewModel, IEventHandler<TodoCreatedEvent>
{
    readonly IMediator mediator;

    public TodoListViewModel(IMediator mediator)
    {
        this.mediator = mediator;
    }

    public async Task LoadTodos()
    {
        // one line. cached. offline-available. validated.
        var response = await mediator.Request(new GetTodosRequest(IncludeCompleted: false));
        this.Todos = response.Result;
    }

    public async Task CreateTodo(string title, string description)
    {
        await mediator.Send(new CreateTodoCommand(title, description));
        // don't reload manually - the event handler below will fire
    }

    // this fires automatically when TodoCreatedEvent is published
    // no subscription. no unsubscription. no memory leaks. no drama.
    public async Task Handle(
        TodoCreatedEvent @event,
        IMediatorContext context,
        CancellationToken ct)
    {
        await LoadTodos();
    }
}

Notice that the ViewModel implements IEventHandler<TodoCreatedEvent> directly. With the MAUI extension, your ViewModels and Pages automatically participate in event broadcasting without being registered in DI. When the page is popped from navigation, it stops receiving events. No MessagingCenter.Unsubscribe nightmares. No WeakReferenceMessenger gymnastics. It just works.

What’s the Road Ahead

Shiny Mediator has come a long way from its v1 days. We’re now on v6 with full AOT and trimming support baked into the source generators. So what’s next?

Deeper ASP.NET integration — we’ve already got minimal API endpoint generation from handlers, server-sent events from stream requests, and HTTP response caching middleware. Expect more first-class server scenarios.
Event throttling & middleware ordering — both landed in v6. [Throttle(300)] on your event handlers gives you debounce for free (goodbye, search-as-you-type headaches). [MiddlewareOrder] gives you explicit pipeline control.
Better tooling — finding the handler for a contract is still a navigation exercise. We’re exploring IDE integrations to make this seamless.
More source generation — the goal is zero reflection, zero runtime surprises. If a handler is missing or misconfigured, you should know at compile time, not when your app blows up in production at 2 AM on a Saturday.
Community contributions — shout out to codelisk for Prism region navigation and JeremyBP for MAUI modal stack iteration. Keep ‘em coming.

Wrapping Up

Shiny Mediator isn’t trying to replace MediatR. It’s trying to be the mediator that gives app developers — especially those on MAUI, Blazor, and Uno — a batteries-included experience that “just works” out of the box. Caching, offline, validation, HTTP clients, event broadcasting, source generated registration… all of it designed so you can focus on your actual business logic instead of plumbing.

Give it a spin. Check out the full docs, play with the sample apps, and come yell at me on BlueSky if something doesn’t work.

Happy coding. May your caches always be warm and your pipelines always be clean.

Source generation and full blown AOT. AOT is becoming such an important part of .NET, especially with .NET MAUI and Blazor. We’re working hard on a version 5 release that will be fully AOT compliant out of the box!

Mediator v2.0

Sun, 22 Sep 2024 00:00:00 GMT

The Road Here

Only a little over 3 months, I released v1.0 of Mediator. Since then, I’ve been adding features as fast as they come to mind. The focus on making the Mediator pattern upfront for apps (in my opinion) has been a huge success. I’ve been using it in my MAUI apps for offline, caching, & resiliency middleware. The amount of time it saves me is pretty crazy.

Since version the v1 release, I’ve been adding a ton of features including an ASP.NET extension for HTTP endpoints straight to Mediator request handlers. Quite recently - I found a lot of mediated calls would end up just wrapping HTTP calls done with Refit or Kiota. I decided to add my own source generator to deal with this. Check out the HTTP Extension for more on this.

What’s New in 2.0

So what does 2.0 bring that requires a major version bump? The first major feature is that I’ve brought the offline, stream replay, and user error notification middleware to Blazor webassembly. This middleware was already present in MAUI, but Blazor needed a “connectivity” & “storage” service to match MAUI.

The second major feature is that I’ve been moving a lot of the middleware to be configured via Microsoft.Extensions.Configuration. This allows you to configure middleware and handlers in a global way and without polluting your code with attributes everywhere. Below is an example of all configuration we offer now:

{
    "Mediator": {
        "Http": {
            "My.Namespace.Contract": "https://shinylib.net/newbase",
            "My.Namespace.*" : "https://shinylib.net/therestofhtenamespace",
            "*": "https://shinylib.net/everythingelse"
        },
        "Performance": {
            "*": {
                "ErrorThresholdMilliseconds": 5000
            }
        },
        "Offline": {
            "Sample.Handlers.OfflineRequestHandler": {
                "AvailableAcrossSessions": true
            }
        },
        "ReplayStream": {
            "Sample.Handlers.MyRequest": {
                "AvailableAcrossSessions": true
            }
        },
        "TimerRefresh": {
            "My.Contacts.HttpData": {
                "IntervalSeconds": 10
            }
        },
        "Resilience": {
            "My.Namespace.ResilientContract": {
                "RetryCount": 3,
                "RetryDelay": 500
            }
        },
        "Cache": {
            "My.Contacts.*": {
                "Priority": "High",
                "AbsoluteExpirationSeconds": 300,
                "SlidingExpirationSeconds": 60
            }
        },
        "UserErrorNotifications": {
            "*": {
                "*": {
                    "Title": "ERROR",
                    "Message" : "Failed to do something"
                },
                "fr-CA": {
                    "Title": "ERREUR",
                    "Message" : "Échec de faire quelque chose"
                }
            }
        }
    }
}

So let’s unpack this. The first thing to notice is that we have ”*” to “glob” a namespace or ALL calls. If you want to attack a specific contract, just fully label it. We will find the nearest namespace to your contract before giving up as “not enabled” for a feature to be disabled on a contract.

What’s Next

I’m pretty happy with this release, but I still have a ton of ideas. All the stuff you can do around the handlers with middleware is really exciting. Have an idea for the mediator, head on over to GitHub and add a feature request. I’m always looking for new ideas.

Mediator v1.0

Mon, 10 Jun 2024 00:00:00 GMT

What is it?

Shiny Mediator is something new I’ve been working on. I love Jimmy Bogard’s MediatR library on the server, but I just couldn’t get it to fit the way I wanted for Apps… especially Blazor & .NET MAUI apps.

What is a mediator? It’s a small in-process version of a message bus. MAUI has MessagingCenter, the Community toolkit has the weak message center, and Prism offers an event aggregator. They’re all great, but they lack in areas that I want “more”.

If an event errors, the whole chain dies in the publish
Events are fired in a foreach (mostly)
You have to tie into them and unsubscribe from them or you can leak memory
They don’t provide the concept of command or request/response models (a command can only be responded to by a single handler)
They don’t provide any sort of middleware (pre & post handling)

Sure - they aren’t geared for these things, but the question is “what is”?

Some might say “this is overengineering” or “too complex”. I would counter that comment by saying that this can actually simplify your architecture overall by removing a lot of complex plumbing around services, references, and navigation.

Let’s go over some of the problems that we use mediator to solve within our apps

What Does It Solve

We believe that Shiny Mediator is the answer to these problems. It’s a simple, yet powerful library that allows you to create a mediator in your app

Problem #1 - Service & Reference Hell

Does this look familiar to you?

public class MyViewModel(
    IConnectivity conn,
    IDataService data,
    IAuthService auth,
    IDialogsService dialogs,
    ILogger<MyViewModel> logger
) {
    // ...
    try {
        if (conn.IsConnected)
        {
            var myData = await data.GetDataRequest();
        }
        else {
            dialogs.Show("No Connection");
            // cache?
        }
    }
    catch (Exception ex) {
        dialogs.Show(ex.Message);
        logger.LogError(ex);
    }
}

With a bit of our middleware and some events, you can get here:

public class MyViewModel(IMediator mediator) : IEventHandler<ConnectivityChangedEvent>, IEventHandler<AuthChangedEvent> {
    // ...
    var myData = await mediator.Request(new GetDataRequest());

    // logging, exception handling, offline caching can all be bundle into one nice clean call without the need for coupling
}

Problem #2 - Messages EVERYWHERE (+ Leaks)

Do you use the MessagingCenter in Xamarin.Forms? It’s a great tool, but it can lead to some memory leaks if you’re not careful. It also doesn’t have a pipeline, so any errors in any of the responders will crash the entire chain. It doesn’t have a request/response style setup (not that it was meant for it), but this means you still require other services.

public class MyViewModel
{
    public MyViewModel()
    {
        MessagingCenter.Subscribe<SomeEvent1>(this, @event => {
            // do something
        });
        MessagingCenter.Subscribe<SomeEvent2>(this, @event => {
            // do something
        });

        MessagingCenter.Send(new SomeEvent1());
        MessagingCenter.Send(new SomeEvent2());

        // and don't forget to unsubscribe
        MessagingCenter.Unsubscribe<SomeEvent1>(this);
        MessagingCenter.Unsubscribe<SomeEvent2>(this);
    }
}

Let’s take a look at our mediator in action for this scenarios

public class MyViewModel : IEventHandler<SomeEvent1>, IEventHandler<SomeEvent2>
{
    public MyViewModel(IMediator mediator)
    {
        // no need to unsubscribe
        mediator.Publish(new SomeEvent1());
        mediator.Publish(new SomeEvent2());
    }
}

Our amazing friends over in Prism offer the “best in class” MVVM framework. We’ll them upsell you beyond that, but one of their amazing features is ‘Modules’. Modules help break up your navigation registration, services, etc.

What they don’t solve is providing a strongly typed nature for this stuff (not their job though). We think we can help addon to their beautiful solution.

A normal call to a navigation service might look like this:

_navigationService.NavigateAsync("MyPage", new NavigationParameters { { "MyArg", "MyValue" } });

This is great. It works, but I don’t know the type OR argument requirements of “MyPage” without going to look it up. In a small project with a small dev team, this is fine. In a large project with a large dev team, this can be difficult.

Through our Shiny.Framework library we offer a GlobalNavigationService that can be used to navigate to any page in your app from anywhere, however, for the nature of this example, we’ll pass our navigation service FROM our viewmodel through the mediator request to ensure proper scope.

public record MyPageNavigatonRequest(INavigationService navigator, string MyArg) : IRequest;
public class MyPageNavigationHandler : IRequestHandler<MyPageNavigatonRequest>
{
    public async Task Handle(MyPageNavigatonRequest request, CancellationToken cancellationToken)
    {
        await request.navigator.NavigateAsync("MyPage", new NavigationParameters { { "MyArg", request.MyArg } });
    }
}

Now, in your viewmodel, you can do this:

public class MyViewModel
{
    public MyViewModel(IMediator mediator)
    {
        mediator.Request(new MyPageNavigatonRequest(_navigationService, "MyValue"));
    }
}

Strongly typed. No page required page knowledge from the module upfront. The other dev team of the module can define HOW things work.

Closing

Lastly, we offer some absolutely epic middleware that you can use to do things like logging, caching, error handling, etc.
Check out our middleware documentation for more information.

Check out our overall documentation for more information on how to use the mediator in your app. We think you’ll love it!

April Mad Releases

Mon, 08 Apr 2024 00:00:00 GMT

Shiny v3.3

This release was mainly a large bugfixing release with some cool additions around Push Notifications

However, we did decide to remove two modules from the Shiny offering

Shiny.Logging.AppCenter - this was an easy one. Microsoft is shutting down AppCenter in 2025.
Shiny.SpeechRecognition - this was a tough one. The plugin was never really that great and it was a pain to maintain. The MAUI community toolkit recently released a plugin here that you can use.

We’ve improved the push delegate to handle MORE native stuff, more events like UnRegister to centralize your registration & now the unregistration process.

Release Notes

Apple Privacy Info - May 1, 2024 Deadline is Approaching

Apple has a new privacy requirement that you must disclose what you are doing with the user’s data. This is a requirement for all apps in the App Store. The Shiny templates have been updated to include a new file under the iOS platform that you can fill out to help you comply with this requirement.

We’ve introduced two “guestimate” type helpers to get users rolling. Our Shiny Templates and our App Builder tool will help you generate these files. We generate what most user app requirements will be in terms of user identity info, as well as all of the necessary Shiny & .NET BCL requirements. We also insert any necessary location permissions if you select one of our location based components.

Shiny Templates v2.5

The templates have been great for Shiny discovery. Wiring up all of the permissions with Android & iOS is difficult. I find that I’m constantly using App Builder here on shinylib.net to generate them all for me because I constantly forget them all. Cutting a new proof-of-concept or test with Shiny or any of the whack of 3rd party libraries that are included with the library is a breeze.

This release got the following love:

Removal of AppCenter - maybe this is the opposite of love - but don’t use it since it is officially done in 2025
Updated to the latest versions of many nuget packages
Updated some of the Shiny stuff to 3.3
NEW base template for the upcoming Apple Privacy Manifests under Platforms/iOS

The MAUI Project template is so large that it takes 3 screenshots to get it all.

Check It Out

Push Notification End-to-End Tester for Azure Notification Hubs & Firebase

Setting up push notifications with Apple & Google can be a real pain. This tool will help you test your setup end-to-end. It’s a simple mobile app that will send a push notification to your app using Azure Notification Hubs or Firebase Cloud Messaging. It’s a great way to test your setup without having to write a bunch of code.

It isn’t pretty, but it does a good job of helping you test your setup without having to wire up a backend or write a bunch of code.

GitHub

Firebase - Specifically iOS

There is work being done to create fresh new slim bindings for Firebase on iOS. I’m working with Jon Dick on some SLIM Bindings over at https://github.com/Redth/DotNet.Platform.SlimBindings

Slim bindings are revolutionary by any means, but they allow you to control the native API surface that you have to bind to. With Swift becoming increasingly popular and not having a true native binding solution with .NET at this time, Slim bindings allow us to control this narrative by building swift code, but still marking the code properly with objective-C headers to be able to bind within .NET

If you’re a user of Shiny.Push.FirebaseMessaging, the good news is that there will be a direct nuget package update in v3 that will allow you to continue using Firebase messaging on iOS without any other code updates. This update for Shiny will be available long before the Firebase June 2024 deadline

Shiny 4.0 Roadmap

We are starting to plan out Shiny 4.0. We are looking for feedback on what you would like to see in the next major version of Shiny.

Currently on the roadmap are:

Simplifying the Job framework
Allow for more native configuration of Push & Local Notifications
More BLE methods to help with some of the fun edge cases that have been rolling in
Removing the old Xamarin/Netstandard targets. This will help with new targets moving forward
Continue to improve the hosting model to work with other platform vendors like Uno
Trying to get RX out of the core for those that don’t want the fat (MAYBE)

So it’s a “smaller” major release.

Bonus - ACR User Dialogs

There are still people using my old dinosaur of a package, so I updated it to the latest AndroidX stuff and .NET 8.
Unfortunately, classic Xamarin and netstandard targets are now gone, but at least it pushes the needle forward if you’re still using this package.

We may introduce Windows support back into the mix in the future, but it’s not a priority right now.

Version 3.2 Release

Sun, 10 Dec 2023 00:00:00 GMT

Today, we released version 3.2 of Shiny that targets .NET 8 along with Classic Xamarin targets. We decided to move with the supported version of MAUI. This also makes things easier for specific support targets with AndroidX which can be very difficult to multitarget with.

This release also includes the ability to check for the current setup permission without requesting from the permission from the user. This is surprisingly difficult to implement for all modules, so for now, the following libraries have this:

Shiny.Locations / IGeofenceManager.CurrentAccess
Shiny.Locations / IGeofenceManager.GetCurrentAccess(GpsRequest)
Shiny.BluetoothLE / IPeripheralManager.CurrentAccess
Shiny.BluetoothLE.Hosting / IBleHostingManager.CurrentAdvertisingAccess & IBleHostingManager.CurrentGattAccess

There are other minor fixes in this release. Be sure to checkout our full release notes

Shiny.NET | Blog

Introducing Shiny.AiConversation — AI Conversation

The Problem

The Solution

What You Can Do

Text Chat

Voice Chat (Push-to-Talk)

Hands-Free Wake Word

Four Acknowledgement Modes

Voice Interruption

Chat History with AI Self-Lookup

Observable State

Bring Your Own Backend

Cross-Platform from Day One

AOT Compatible

Get Started

The Feedback Service — One Hook to Rule Them All

How It Works

Custom Feedback: TTS + Sound Effects

Pluggable MAUI Control Hooks

All defaults

Defaults + your own

Only what you need

What Ships Built-In

The Design Philosophy

DocumentDb AI Tools — Give Your LLM a Database

What It Does

Setup in 30 Seconds

Structured Filters

Field Visibility

Capability Flags

AOT-Safe

Try the Copilot Sample

Getting Started

Turn Any Interface Into an AI Tool — Shiny DI 3.0

The Problem

The Solution: [Tool] + [Description]

What Gets Generated

Registration

Conditional Generation

AOT-Safe Argument Extraction

CancellationToken Handling

Methods Without [Description] Are Skipped

Works With Your Existing DI Setup

Getting Started

One Contract, Three Transports — Mediator AI Tooling

The Problem

The Contract-First Approach

AI Tool Generation

Middleware Runs on AI Tool Calls Too

Scaling to Many Tools

Beyond AI: The Same Contract Powers HTTP Too

Why This Matters

Full AOT Compliance

Supported Type Mappings

Getting Started

AI-Powered Navigation in Shiny MAUI Shell

The Idea

Two Tools, Any Number of Pages

Describe Intent, Not Pages

What Gets Generated

Wiring It Up

Try It in the Sample

Get Started

Shiny Client v4 - Windows Support, .NET 10, and a Ton of Improvements

Windows Support

.NET 10

Configuration Extensions

Locations

HTTP Transfers

Push Notifications

BluetoothLE

Jobs

Upgrading

Shiny DocumentDb v3: One API, Four Databases

What’s new in v3

Provider setup

SQLite

SQL Server

MySQL

The Solution: `[Tool]` + `[Description]`

Methods Without `[Description]` Are Skipped