Shiny.NET | Blog

Shiny HTTP Transfers: Background Transfers, and Knowing What They're Doing

Wed, 26 Aug 2026 00:00:00 GMT

The question this library exists to answer is not “how do I upload a file”. It is “why is this data still not here?” — the photo attached twenty minutes ago, the inspection report the office has been refreshing since lunch, the overnight sync that was meant to be finished before anyone looked.

The answer is nearly always that nothing was moving. HttpClient is a fine way to carry bytes right up until the user leaves your app, and then it stops. On iOS the process is suspended within seconds of the app going to the background: threads stop, sockets close. A half-finished 200 MB upload does not pick up where it left off when the user returns — it starts over, on their cellular plan. Android reclaims a backgrounded process the moment memory gets tight. The user did nothing wrong; they answered a text message.

So the data is not late because something broke. It is late because for most of that window nobody was carrying it, and no amount of effort inside your process changes that — the OS is doing exactly what it said it would do. The only thing that helps is not being the one holding the socket.

This is one of the oldest pieces of code in Shiny — it started life in 2016 as a Xamarin plugin, years before Shiny existed, and has been carried forward, rewritten and re-platformed ever since. It is also the module that ends up in the most apps, because sooner or later every app has to move a file at a moment the user is not watching it happen.

Shiny.Net.Http hands the transfer to whatever the platform runs on your behalf, and gives you one API over the lot of them.

builder.Services.AddHttpTransfers<MyTransferDelegate>();

await transferManager.Queue(new HttpTransferRequest(
    "receipt-upload",
    "https://api.example.com/receipts",
    TransferType.UploadMultipart,
    filePath
));

That is the whole thing. Your app can be suspended, backgrounded or terminated a second later and the bytes keep moving.

What is actually carrying the bytes

Platform	Engine
iOS / Mac Catalyst	A background `NSURLSession` — the transfer is owned by the OS daemon, and iOS relaunches your app in the background when it finishes
Android	A managed `HttpClient` loop inside a foreground service, so the process is not a kill candidate while transfers are pending
Windows, Linux, macOS, plain .NET	The same managed loop, gated on `IConnectivity` — every pass re-checks the network and picks transfers back up when it returns
Blazor WASM	Service Worker Background Sync — an IndexedDB queue the SW drains with `fetch()` while the tab is closed

The differences that leak through are the ones that are real, and they are documented rather than smoothed over with a lie:

Cancel deletes the partial file; Pause does not. Pause leaves the transfer in the queue in Paused, and a user-paused transfer stays paused across relaunch and across connectivity coming back. It waits for you to call Resume.
UseMeteredConnection = false keeps a large transfer on Wi-Fi. The managed loop parks it in PausedByCostedNetwork rather than quietly burning someone’s data.

State lives in a Shiny IRepository, so the queue survives a process restart. That matters more than it sounds: on iOS the process that finishes your transfer is frequently not the process that started it.

Android: a foreground service, and a connectivity gate

Android has no transfer daemon to hand the work to. What it does have is the foreground service — the one contract that says this process is doing something the user knows about, do not reclaim it — so that is what the queue runs inside.

HttpTransferService starts on the first Queue(), and again at app start if the repository still holds transfers. It promotes itself as FOREGROUND_SERVICE_TYPE_DATA_SYNC and hosts the managed loop. When the queue empties the loop falls out and the service stops itself, so there is no idle notification left sitting in the shade after the last file lands.

Inside, every pass is gated on IConnectivity before a request is attempted at all:

if (connectivity.IsInternetAvailable())
{
    var full = connectivity.ConnectionTypes.HasFlag(ConnectionTypes.Wifi);
    // ... run each pending transfer
}

No connection means nothing is sent — the pass logs and waits, rather than throwing an HttpRequestException at your delegate for something that is not an error. And when the network dies mid-transfer, that is not treated as a failure either:

catch (IOException ex)
{
    this.PauseTransfer(transfer, "Network Disconnected", ex);
}

The transfer moves to PausedByNoNetwork and stays in the repository. The next pass with connectivity picks it straight back up — and because a download re-asks with Range: bytes=N- against the bytes already on disk, walking into a parking garage costs the length of the outage rather than the whole file.

Four states come out of that gate, and the distinctions between them are the point:

State	Set by	Cleared by
`PausedByNoNetwork`	The connection dropped	Connectivity returning — automatic
`PausedByCostedNetwork`	Metered network, `UseMeteredConnection = false`	Wi-Fi returning — automatic
`Paused`	The user	`Resume()`, and nothing else
`Error`	The server said no	Your delegate

Only the third is sticky. A transfer paused by the network resumes itself; a transfer paused by a person does not, because a person paused it.

The hard limits here are Android’s rather than ours. Android 15 caps dataSync at a six-hour daily budget, and shortService — opt in with HttpTransferService.UseShortService, which skips the type-specific manifest permission and the Play Store declaration — gets roughly three minutes per promotion. Both deliver onTimeout, and failing to stop promptly is an ANR. So the service stops, logs a warning, and leaves the queue in the repository; the next Queue() or app launch re-arms it. A timeout defers the work, it does not lose it.

Why downloads resume and uploads do not

Downloads resume, because HTTP standardised the question long before any of us needed it. Range: bytes=N- is one header, 206 Partial Content is one status code, and essentially every static host, CDN and object store answers both. The managed loop asks, appends when it gets a 206, and — when a server ignores the header and sends the whole body back with a 200 — restarts and says so in the log rather than gluing a second copy of the file onto the first. iOS resumes natively inside the NSURLSession daemon. A 400 MB download that dies at 380 MB in a tunnel therefore costs 20 MB, not 400, and the bytes already on disk are counted in the total via Content-Range so the progress bar comes back where it left off rather than at zero.

Uploads do not, and that is mostly not the client’s decision. Resuming an upload requires the server to say how many bytes it already holds and agree to take the rest from there — that is a protocol, not a header. tus specifies exactly that, and it remains rare: it is not in ASP.NET Core out of the box, nor in Express, FastAPI, Rails or Spring. The object stores come closest, since S3 multipart and Azure block-blob commits have the primitives, but those are per-vendor APIs rather than anything a generic transfer layer can assume about POST /receipts — and the object-store builders below upload in a single PUT today.

So Resume on an upload means “start over”, on every platform. Writing that down beats an API that reads nicely and lies in production. When resumable upload endpoints become ordinary, this will use them.

Object stores, without the object-store SDK

Sooner or later the destination is a bucket, so there are builders for the two everybody ends up on:

var request = new AzureBlobStorageUploadRequest(filePath)
    .WithBlobContainer("myaccount", "receipts")
    .WithSasToken(sasFromYourApi)
    .Build();

await transferManager.Queue(request);

var request = new AwsS3UploadRequest(filePath)
    .WithBucket("receipts", "us-east-1")
    .WithObjectKey($"2026/08/{Guid.NewGuid()}.pdf")
    .WithPresignedUrl(urlFromYourApi)          // or .WithCredentials(...) to sign on-device
    .Build();

Both are pure builders. Each produces an ordinary HttpTransferRequest — a PUT, a URI and a header dictionary — which then goes through the same queue, the same repository, the same NSURLSession or foreground service and the same Live Activity as any other transfer. Neither is a second transfer path.

Why not `Azure.Storage.Blobs` or `AWSSDK.S3`

They are good SDKs. They are also built on an assumption that is false on a phone: that your process is still running.

An SDK upload owns its own HttpClient and its own socket, inside your app, which is precisely the arrangement this library exists to get out of. BlobClient.UploadAsync is an await in your process, and iOS suspends your process — so it dies along with everything else the moment the user switches apps, and there is no seam where a half-finished SDK upload could be handed to NSURLSession instead. The SDK’s retry policy is no help; it stopped running too. You cannot background the thing you are carrying yourself.

The credential model is the second problem, and it is the one with consequences. Both SDKs are shaped around a client that holds an account key or IAM credentials. An app bundle is not a secret — a storage account key shipped inside one has been handed to every user who installs it, and it usually grants far more than “write this one file”. The mobile shape is the inverse: your backend mints a SAS token or a presigned URL, scoped to one blob and expiring shortly, and the device never sees a long-lived credential. At which point the upload is a PUT to a URL with a couple of headers, and there is nothing left for an SDK to do.

What remains is a wire protocol, and the wire protocol is small — which is why the builders are the whole implementation:

Azure wants x-ms-blob-type: BlockBlob, a Content-Length, a Content-Disposition, and either a SAS query string or a shared-key Authorization header.
S3 wants Signature V4 — an HMAC-SHA256 over a canonical request, off a key derived in four chained steps — which is a page of System.Security.Cryptography and no dependencies at all.

The S3 signer takes one deliberate shortcut worth knowing about. It signs with x-amz-content-sha256: UNSIGNED-PAYLOAD:

// S3 allows UNSIGNED-PAYLOAD so we don't need to hash potentially large files
var payloadHash = "UNSIGNED-PAYLOAD";

A literal SigV4 signature covers the SHA-256 of the body, which for a 400 MB video means reading the entire file end to end, on battery, before a single byte leaves the device — and then reading it again to send it. S3 explicitly permits UNSIGNED-PAYLOAD over HTTPS, so the hash is skipped and the transfer starts immediately.

The rest is size and trimming. iOS builds trim aggressively, the vendor SDKs bring wide dependency graphs and reflective serialisation with them, and none of that is much fun to keep working for the sake of a file PUT.

The part to watch: a signature has a clock

A SigV4 header signature is stamped with x-amz-date at Build() time, and AWS rejects it outside roughly a fifteen-minute skew window. A background transfer, by design, may sit in the queue for hours — waiting for Wi-Fi, waiting for the network, waiting for a foreground-service window. Those two facts do not get along, and the result is a 403 in your OnError rather than anything mysterious.

So for anything that might wait, mint a presigned URL or SAS on the server with an expiry chosen for the wait — long enough to cover an overnight queue. WithCredentials and WithSharedKeyAuthorization are for transfers you expect to run promptly, and for desktop or server processes, where credentials belong in the first place.

Why not a background job?

Fair question — Shiny ships a perfectly good job scheduler. Use it for work; don’t use it for blobs.

A job is a time window. A background transfer is a handoff. That distinction is the whole answer, and on iOS it is not subtle.

Shiny.Jobs on iOS is a BGProcessingTaskRequest submitted to BGTaskScheduler. iOS decides when the window opens — usually when the device is idle, often overnight, throttled by how often the user actually launches your app — and iOS decides when it closes. When it closes, ExpirationHandler fires, the CancellationToken handed to your job cancels, and the stream you were copying stops wherever it happened to be. A 200 MB upload does not fit inside a discretionary window that the OS is entitled to revoke, and the user who tapped Send thirty seconds ago is not expecting it to go tonight while they sleep.

A background NSURLSession has no window. The daemon owns the socket, keeps moving bytes while your app is suspended, keeps moving them after your app is terminated, and iOS relaunches your process in the background to hand you the result. Nothing relaunches a terminated app to run a job.

Downloads reach the same conclusion from the other direction. Expire a job 380 MB into a 400 MB file and there is nothing usable to hand back unless the job itself wrote the Range bookkeeping and persisted the byte counts — at which point it has become a transfer layer, only without the daemon that would have kept it moving through the suspension. Handed over instead, the resume, the partial file and the persisted counts are simply there for whichever process picks the transfer up next.

Android differs in the mechanics and arrives in the same place. Jobs there are a WorkManager PeriodicWorkRequest — a fifteen-minute floor on the period and a worker that gets stopped at around ten minutes of execution. A large file on a poor connection will not reliably finish inside that, and starting over every fifteen minutes is not progress. Transfers run under a foreground service instead, which is the contract Android actually offers for this will take a while and the user knows about it.

	Jobs	Transfers
Starts	When the OS feels like it — discretionary, usage-throttled	Immediately
Time limit	iOS expiration handler; ~10 min WorkManager worker	None imposed on the transfer
Survives app termination	No	Yes — iOS relaunches your app to deliver the result
Resume	Whatever you write yourself	`Range` requests, or native on iOS; byte counts persisted
Progress to the user	Nothing to show	Live Activity / foreground notification

Where jobs are genuinely right is around the transfer rather than instead of it: reconciling state after the fact, cleaning up finished files, deciding what to queue next. Queue the blob and let the platform carry it.

Metrics

Once a transfer is out of your process, “is it working?” stops being a rhetorical question. Every update carries a TransferProgress:

manager.UpdateReceived += (_, result) =>
{
    var p = result.Progress;
    Console.WriteLine($"{p.PercentComplete:P0} · {p.BytesPerSecond} B/s · {p.EstimatedTimeRemaining} left");
};

Value	How it is arrived at
`BytesTransferred` / `BytesToTransfer`	Bytes written so far, and the total — from `Content-Length`, or from `Content-Range` on a resumed download so the total counts the part already on disk
`IsDeterministic`	Whether a total is known at all. A chunked response has no `Content-Length`, and a progress bar that invents one is worse than an indeterminate one
`BytesPerSecond`	Sampled, not averaged over the whole transfer — see below
`PercentComplete`	`transferred / total`, or `-1` when the total is unknown. Not `0` — a caller must be able to tell “nothing yet” from “no idea”
`EstimatedTimeRemaining`	`bytesRemaining / BytesPerSecond`, and `TimeSpan.Zero` when there is no honest answer

Throughput is sampled on a rolling window

The managed loop counts bytes into an accumulator and only publishes when the stopwatch passes two seconds, then divides and resets both:

else if (stop.Elapsed.TotalSeconds > 2)
{
    var bps = Convert.ToInt64(totalSince / stop.Elapsed.TotalSeconds);
    this.PublishProgress(transfer, new TransferProgress(bps, totalBytes, totalBytesXfer));
    totalSince = 0;
    stop.Restart();
}

Two things fall out of that. The rate is current throughput rather than a cumulative average, so a transfer that recovers from a slow patch reports the recovery instead of dragging its history along. And the update rate is bounded at the source — an 8 KB read loop on a fast connection would otherwise fire thousands of events a second at your UI thread.

On iOS and Mac Catalyst the number comes from the platform instead — NSProgress.Throughput on the task, in DidSendBodyData / DidWriteData — because the daemon moving the bytes is in a better position to measure them than we are.

Every progress tick also writes byte counts back to the repository, which is what lets the app relaunch mid-transfer and show a bar that is already in the right place. A late tick for a transfer that has since been paused or removed is dropped rather than resurrecting it.

Three ways to consume it

// 1. the firehose — every transfer, every tick (remember to -= it)
manager.UpdateReceived += handler;

// 2. one transfer, awaited to a terminal state
var result = await manager.WatchTransfer("receipt-upload");

// 3. a bindable collection for UI
await monitor.Start(syncContext: SynchronizationContext.Current);
// monitor.Transfers -> HttpTransferObject : INotifyPropertyChanged

HttpTransferMonitor seeds itself from the repository, follows repository adds and removes as well as progress ticks, marshals to a SynchronizationContext if you hand it one, and can evict completed, cancelled or errored rows on its own. It is the one to reach for when a screen needs to show what is in flight; the raw event is for everything else.

The metrics the user sees

The user is not in your app — that is the entire premise — so the numbers have to land somewhere they can see: an iOS Live Activity on the Lock Screen and in the Dynamic Island, or the Android foreground-service notification, promoted on Android 16 to a live update with a status bar chip.

One call, and nothing in your transfer delegate:

builder.Services.AddTransferProgress(opts =>
{
    opts.Scope       = TransferProgressScope.Summary;   // one surface for a batch, or PerTransfer
    opts.Fields      = TransferProgressFields.Default;  // file, direction, %, bytes, speed, ETA
    opts.ShortStatus = TransferProgressShortStatus.Percent;
});

TransferProgressManager is deliberately one class for every platform. It subscribes at startup — not on first use, because on iOS the surface has to be moved to its final state by a process that was relaunched in the background — coalesces the firehose to one update a second and one percent of movement, aggregates a batch into a single figure (finished transfers stay in the aggregate so the bar never walks backwards when one of five completes), and starts, updates and retires the surface. An ITransferProgressRenderer owns nothing but the drawing. The aggregation and lifetime rules are exactly the things that would silently diverge if each platform kept its own copy.

Fields is a flags enum over the human-readable text, so switching off Speed removes it from the Lock Screen without touching any Swift. The raw culture-invariant values (bps, percent, etaSeconds, bytes, total, …) ride along in TransferProgressContent.Data for a custom widget to format itself, and TransferProgressContentBuilder.FormatBytes / FormatRate / FormatDuration are public statics you can reuse in ordinary in-app UI so the numbers read the same everywhere.

The measurement problem iOS hands you

A background NSURLSession delivers no progress callbacks while your app is suspended. DidWriteData stops firing; iOS wakes you when the transfer completes. A fraction-based bar therefore sits frozen for most of a long transfer, which reads as “broken” rather than “backgrounded”.

So progress is emitted as a time range the system animates by itself, anchored in the past — at the point a constant-rate transfer would have started — so the bar already sits at the true fraction and keeps moving without further updates. Anchoring at “now” would snap it back to zero on every tick. Each real callback re-anchors it, and it falls back to a plain fraction when the transfer is stalled, paused, of unknown size, or when the projection exceeds an hour and stops being a measurement. Android resolves the range straight back to a fraction, since its foreground service is alive the whole time and real numbers keep arriving.

For uploads there is an exact answer available: your server knows how many bytes actually landed. Turn on RequestPushToken and it can push byte-accurate progress through the entire suspended window. It buys nothing for downloads — no server knows how far the device got.

Where to go next

The HTTP Transfers docs cover the delegate and retry model, monitoring, progress surfaces, and the Azure and S3 builders.

DocumentDB in Aspire

Mon, 24 Aug 2026 00:00:00 GMT

DocumentDb has always been able to run on ten-odd backends. The awkward part was that choosing one is a line of C# inside the service:

options.DatabaseProvider = new PostgreSqlDatabaseProvider(connectionString);

Which is fine until dev wants SQLite, CI wants a throwaway container, and production wants managed PostgreSQL — and now the thing that differs between environments is compiled into your app. That is a deployment decision wearing a source-code costume.

The Aspire integration moves it where it belongs. The AppHost picks the backend and gates the seeding; the consuming service gets one provider-agnostic line, with a health check and OpenTelemetry already wired.

The AppHost picks the backend

var store = builder
    .AddPostgresDocumentStore("orders")     // provisions Postgres and models the store
    .WithSeeder(async (ctx, ct) =>
    {
        // Runs once, after the DB is ready, before dependents start.
        // ctx => (StoreName, Provider, ConnectionString)
    });

builder.AddProject<Projects.Api>("api")
    .WithReference(store);

Swapping the backend is one call, and the consuming service is untouched:

builder.AddSqliteDocumentStore("orders", "orders.db");   // local dev — no container at all
builder.AddSqlServerDocumentStore("orders");
builder.AddMySqlDocumentStore("orders");

If you already model the database resource yourself, wrap it — the provider is auto-detected, or you name it explicitly:

var pg    = builder.AddPostgres("orders-server").AddDatabase("orders-db");
var store = pg.AsDocumentStore("orders");    // name MUST differ from the DB resource name

CockroachDB and MariaDB have no first-party Aspire hosting resource and can’t be auto-detected (a plain AddPostgres / AddMySql resource detects as Postgres / MySql), so model the container yourself and pass DocumentProviderKind.CockroachDb / MariaDb to select the wire-compatible variant.

The service gets one line

// Api Program.cs
builder.AddDocumentStore("orders", configureOptions: o =>
    o.ConfigureDocument<Order>(cfg => cfg.Table = cfg.TypeName));

The store is registered keyed by name, so resolve it with [FromKeyedServices]:

public class OrdersService([FromKeyedServices("orders")] IDocumentStore store)
{
    public Task<Order?> Get(string id) => store.Get<Order>(id);
}

Nothing in that service knows which database it’s talking to, and it isn’t a leaky abstraction that stops working the moment you need something real — configureOptions is the full DocumentStoreOptions surface.

The contract underneath

There’s no magic here, and it’s worth knowing the shape because you can drive it by hand if you need to. The hosting resource implements IResourceWithConnectionString over its backing database, and WithReference publishes two things to the consumer:

Key	Value
`ConnectionStrings:orders`	the backing database’s connection string
`Shiny:DocumentDb:orders:Provider`	the `DocumentProviderKind` name

The client reads both, maps the kind to an IDatabaseProvider, and registers the keyed store. A connection string with no matching provider key is ignored — so a Redis or blob reference in the same AppHost doesn’t turn into a junk store.

And because the client owns the registration, it also attaches the things you’d otherwise wire by hand: a SELECT 1 health check, plus the Shiny.DocumentDb meter and ActivitySource into OpenTelemetry, so query metrics and trace spans land in the Aspire dashboard with no further work.

Settings

builder.AddDocumentStore("orders", settings =>
{
    settings.MultiTenant = true;
    settings.DisableHealthChecks = true;
});

Setting	Effect
`ConnectionString` / `Provider`	Override what the AppHost injected
`DisableHealthChecks`	Skips the `SELECT 1` probe
`DisableTracing` / `DisableMetrics`	Skips the OpenTelemetry wiring
`MultiTenant`	Shared-table multi-tenancy — adds a `TenantId` column, filters every query by the current tenant, resolved from a registered `ITenantResolver`
`PortableSpatial`	Forces the dependency-free spatial tier — no PostGIS, no native geometry column. For when you can’t install the backend’s spatial extension

When configuration depends on other registered services — an interceptor with its own dependencies, say — use configureServiceOptions, which runs with the resolved IServiceProvider when the keyed store is first created:

builder.AddDocumentStore(
    "orders",
    configureServiceOptions: (sp, o) => o.AddInterceptor(sp.GetRequiredService<AuditInterceptor>()));

Typed `DocumentContext` on an Aspire resource

If you use the source-generated typed context, AddDocumentContextProvider returns the Action<DocumentStoreOptions> the generated Add{Context} method takes — same injected connection string, same health check and telemetry, same settings:

builder.Services.AddOrdersContext(builder.AddDocumentContextProvider("orders"));
builder.Services.AddInvoicesContext(builder.AddDocumentContextProvider("invoices"));

Each context registers its store keyed by the context type, so several contexts backed by different Aspire resources coexist without shadowing each other. That’s the multi-store story, and it’s two lines.

An entire Orleans silo, pointed at the same store

The previous post covered running the whole Orleans persistence stack on IDocumentStore — membership, grain storage, reminders, grain directory and streams. Under Aspire, pointing all of it at the provisioned store is one line:

// Silo Program.cs
builder.AddDocumentStore("orleans");

builder.UseOrleans(silo => silo.UseAspireDocumentDb("orleans"));

UseAspireDocumentDb wires each Orleans provider’s StoreFactory to resolve the keyed IDocumentStore, so the silo’s persistence shares the one Aspire-managed store — its connection, its health check, its telemetry. On the AppHost the silo is just another consumer:

var store = builder.AddPostgresDocumentStore("orleans");
builder.AddProject<Projects.Silo>("silo").WithReference(store);

Because DocumentDb is schema-free there are no setup scripts — the membership and storage tables are created on demand. Take a subset with the feature flags if you don’t want all four:

silo.UseAspireDocumentDb(
    "orleans",
    DocumentDbOrleansFeatures.GrainStorage | DocumentDbOrleansFeatures.Reminders);

Streams are the one piece that is not in All, and that’s deliberate rather than an oversight:

silo.UseAspireDocumentDb("orleans", DocumentDbOrleansFeatures.All | DocumentDbOrleansFeatures.Streams);

Streams need a backend with row-level pessimistic locking, and the silo refuses to start without it. Folding that into All would turn a working SQLite or DuckDB Aspire app into one that won’t boot, purely because it took a package update. configureStreams is for tuning only — the store always comes from Aspire.

The admin UI as a resource

Shiny.DocumentDb.Aspire.Hosting also models ShinyDocDbMyAdmin as a resource, so it comes up with the rest of your app and every store you reference is already connected — no connection strings pasted in by hand:

var store = builder.AddPostgresDocumentStore("orders");

builder.AddDocumentDbAdmin(port: 8085)
       .WithReference(store)
       .WaitFor(store);

WithReference is the same contract a consuming service uses, so nothing special was needed to make this work. Referenced stores appear under a from host badge and can’t be edited or deleted from the UI — they’re declared in the AppHost, so that’s where they change. WithDataVolume() keeps saved connections and queries across runs, and the image tag defaults to the hosting package’s own version, so upgrading the integration brings the matching UI with it.

Or the terminal one, no container

New in 13.4: Aspire 13.5 added interactive terminal sessions, which was the missing piece for modelling the terminal front end as a process rather than a container:

#pragma warning disable ASPIRETERMINAL001
builder.AddDocumentDbAdminTerminal()
       .WithReference(store)
       .WithStartupProfile(store)
       .WaitFor(store);

aspire config set features.terminalCommandsEnabled true
aspire terminal attach documentdb-terminal

WithStartupProfile passes --profile, so attaching lands you on that database rather than the connection list. Locally this replaces the container outright, and it’s the only one of the two that can open a file-backed store — SQLite, SQLCipher, DuckDB — without a bind mount. It does not deploy: terminal sessions are a dev-loop feature, so the resource is excluded from the manifest and anything you publish still wants AddDocumentDbAdmin. DocumentDbAdminTerminalTool.Local covers a repo that pins the tool in its local manifest instead of expecting a global install.

Note that 13.4 moves the hosting package’s Aspire floor to 13.5, since WithTerminal doesn’t exist before it.

What it deliberately doesn’t do

This is a server-tier convenience. It does nothing for DocumentDb’s offline-first core — SQLite on device, LiteDB, IndexedDB in the browser — because those never touch an AppHost. And it covers the relational providers plus SQLite (PostgreSQL, CockroachDB, SQL Server, MySQL, MariaDB, SQLite); MongoDB and Cosmos need divergent client-registration paths and are a planned follow-up.

Within that scope, though, the payoff is real: the provider choice and the seed strategy live in the AppHost, and the consuming code is a single line that works regardless of which one the AppHost picked.

dotnet add package Shiny.DocumentDb.Aspire.Hosting   # AppHost
dotnet add package Shiny.DocumentDb.Aspire.Client    # service
dotnet add package Shiny.DocumentDb.Aspire.Orleans   # silo

DocumentDB in .NET Orleans

Fri, 21 Aug 2026 00:00:00 GMT

Microsoft Orleans is excellent at the part that is hard — virtual actors, placement, transparent activation. Persistence is the part it leaves to you, and it leaves it to you five separate times: cluster membership, grain storage, reminders, the grain directory, and streams are five independent provider contracts, historically satisfied by five different packages with five different setup conventions, storage layouts and operational stories.

Shiny.DocumentDb.Orleans implements all five against a single abstraction — IDocumentStore. One connection string, one backup, one set of tables, and everything Orleans persists is structured JSON you can query rather than an opaque serialized blob.

dotnet add package Shiny.DocumentDb.Orleans

Five contracts, one store

siloBuilder
    .AddDocumentDbGrainStorage("Default", o => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbReminders(o           => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbClustering(o          => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbGrainDirectory("Default", o => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbStreams("Default",    o => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs));

Because DocumentDb is schema-free, there are no setup scripts — the tables are created on demand at silo start. Each store has its own default table (orleans_default, orleans_reminders, orleans_membership, orleans_graindirectory, orleans_streams) and they all share the same OrleansStoreOptions shape: give it a relational DatabaseProvider and it builds and owns its store, or give it a StoreFactory and it uses one you built — which is the escape hatch for MongoDB, Cosmos, LiteDB or anything else.

MongoDB and Cosmos also get first-class companion packages, and it’s worth saying plainly that there is no first-party Orleans MongoDB provider, so this fills a real gap:

siloBuilder.AddMongoDbGrainStorage("Default", connectionString, databaseName: "orleans");   // Shiny.DocumentDb.Orleans.MongoDb
siloBuilder.AddCosmosDbGrainStorage("Default", connectionString, databaseName: "orleans");  // Shiny.DocumentDb.Orleans.CosmosDb

Grain state you can query without activating a grain

Orleans grain storage is a point key/value contract — Read / Write / Clear by grain id — by design. The grain is the consistency boundary, so state is meant to be reached through the activation that owns it, and a query surface on the storage provider would both bypass that boundary and require every provider to understand the shape of the state it persists. Three operations keyed by grain id are what make the contract implementable over blob storage, a table, ADO.NET, Redis or a file alike.

The consequence is that cross-grain questions are answered by grains. “Which shopping carts are over $1,000?” means activating every cart — a silo round trip that places the grain, deserializes its state and runs OnActivateAsync — and because the built-in providers write state as an opaque blob, the database cannot answer it instead.

This provider keeps the same contract but stores each grain’s state as structured JSON under $.state, in an ordinary table — so the rows the runtime reads by key are also readable as documents. Point a read-only store at the same table and ask:

var opts = new DocumentStoreOptions
{
    DatabaseProvider      = new PostgreSqlDatabaseProvider(connectionString),
    JsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
};
DocumentDbGrainStorage.ConfigureGrainState(opts, "orleans_default");
var readStore = new DocumentStore(opts);

// Every ShoppingCart grain over 1000 — no grain activated, no silo involved.
var bigCarts = await readStore.Query<GrainStateRecord>(
    "json_extract(Data, '$.state.total') > @min",
    parameters: new { min = 1000 });

Reporting, dashboards, ops tooling, bulk inspection, analytics — everything that is painful-to-impossible when the only door into grain state is activating the grain becomes a plain document query.

A free audit trail

Grain state is a GrainStateRecord document like any other, which means it can opt into DocumentDb’s temporal history. One line gives you a queryable record of every mutation a grain has ever persisted — no event sourcing to design, no extra infrastructure:

opts.ConfigureDocument<GrainStateRecord>(cfg => cfg.MapTemporal(t => t.MaxVersions = 100));

var history = await temporalStore.History<GrainStateRecord>("cart|user-42");

Streams — the piece that completes the set

Persistent Orleans streams landed in 13.2 and are the newest member of the stack. Orleans’ in-memory stream provider doesn’t survive a restart; every durable alternative means running a queue service. This one is durable on the database your cluster already uses.

siloBuilder.AddDocumentDbStreams("Default", o =>
{
    o.DatabaseProvider = new PostgreSqlDatabaseProvider(connectionString);
    // o.TotalQueueCount = 8;                       // default
    // o.Retention       = TimeSpan.FromHours(1);   // default; null keeps everything
});

Producing and consuming is the ordinary Orleans stream API — nothing about the grain code is provider-specific.

Why there’s a counter row and not a `BIGSERIAL`

The obvious implementation of “monotonic position per queue” is an identity column. It is a correctness trap, and it’s worth understanding why. Sequence values are handed out at insert time; rows become visible at commit time, and those two orders are not the same:

Transaction A inserts, takes sequence 5.
Transaction B inserts, takes 6, and commits first.
The receiver reads up to 6 and advances its cursor past 5.
Transaction A commits. Event 5 is behind the cursor and is never delivered.

Silently, and only under load. So instead each queue owns a counter row, and an enqueue reserves its position under a row lock inside the same transaction:

BEGIN
  counter = Get(queueId, LockMode.Update)   -- SELECT … FOR UPDATE
  seq     = counter.Next++
  INSERT the event row with Seq = seq
COMMIT

The lock does double duty: a second producer blocks until the first commits, so assignment order and commit order are the same order by construction, and the sequence is gap-free. The trade is explicit — enqueue throughput per queue is bounded by the lock hold time on one row — and TotalQueueCount is the dial, since each queue has its own counter row.

That row lock is also why the backend list is short: PostgreSQL, SQL Server, MySQL, MariaDB, Oracle and CockroachDB. It’s a capability check (SupportsPessimisticLocking), not a name list, and it’s enforced at silo start rather than on the first event — a cluster that boots and then drops events under load is a much worse failure than one that refuses to boot.

Two things a queue-backed provider can’t do

Rewind past the cache. Behind Azure Queue or SQS the message is gone once it’s handed over, so a subscriber resuming from an old StreamSequenceToken gets QueueCacheMissException. Here the row is still in the table, so the cache replays it:

await stream.SubscribeAsync(handler, lastToken);   // works across a silo restart

The rewind window is exactly Retention — the sweep that bounds table growth is the same thing that bounds how far back you can resume. Set it to the replay window you actually want and size the table for it.

Show you the backlog. Stream events are ordinary documents, so you can look at them. IStreamAdmin is the in-process view, and ShinyDocDbMyAdmin has a Streams screen answering the same questions in both the web and terminal front ends:

var admin = services.GetRequiredKeyedService<IStreamAdmin>("Default");

foreach (var stuck in await admin.StuckStreams(TimeSpan.FromMinutes(5)))
    logger.LogWarning("{Stream}: {Count} undelivered since {Since}",
        stuck.StreamId, stuck.UndeliveredCount, stuck.OldestUndeliveredAt);

Watch oldest undelivered rather than depth — depth alone can’t tell a busy queue from a dead pulling agent, but age can. IStreamAdmin is deliberately read-only: an outbox message is a unit of work someone owns, so requeueing it means something, but a stream event is a position in a gap-free sequence that every subscriber holds a cursor into. Deleting one tears a hole in that sequence. A stuck stream gets fixed on the consumer side.

Concurrency, properly

Orleans’ ETag is the contract that stops two activations clobbering each other during a failover window. It maps onto the document version, and each provider honours it with a genuinely atomic compare-and-swap:

Orleans	Shiny.DocumentDb
document key	`Id = "{stateName}\|{grainId}"`
ETag	`GrainStateRecord.Version` (via `cfg.MapVersionProperty`)
concurrency conflict	`ConcurrencyException` → `InconsistentStateException`
state blob	nested `JsonElement` (queryable, not opaque)

Relational providers fold the version check into UPDATE … WHERE and verify the row count, MongoDB uses an atomic version-predicate filter, and Cosmos uses a native IfMatchEtag. A stale write loses the race and surfaces as InconsistentStateException — exactly what Orleans expects. The PostgreSQL and MongoDB paths, including the stale-write conflict, are covered by integration tests.

Know your backend

Tier	Backends	Notes
Recommended	PostgreSQL, SQL Server, MySQL, Oracle	Atomic CAS folded into `UPDATE … WHERE`; ETag honoured across failover windows
Supported	MongoDB	Good key distribution; atomic CAS via version-predicate filter
Limited / dev	SQLite, LiteDB, IndexedDB, DuckDB	Single-writer / embedded / analytical — fine for dev, single-silo, or edge
Use with care	Cosmos DB	CAS is correct, but it partitions by grain type — weigh the 20 GB / hot-partition trade before large-scale use

Three limits are worth knowing before production:

Membership needs real multi-document transactions. The per-silo rows and the global table-version row are updated together, each gated on its own version, because that’s how Orleans’ table-version protocol works. Relational or a MongoDB replica set — not Cosmos, whose transactional batches are single-partition. Grain storage, reminders and the grain directory have no such requirement.
Streams need row-level locking — see above.
The silo host is not an AOT target. Grain-state and system-store serialization goes reflection-free when you assign a JsonSerializerContext, but Microsoft.Orleans.Runtime is codegen-heavy, so a fully AOT-published silo isn’t a goal here.

Reflection-free serialization when you want it

The provider’s own envelope types — grain-state record, reminders, membership, grain-directory rows — are always source-generated. The one generic piece is your grain state T. Point a JsonSerializerContext at it and that goes reflection-free too:

[JsonSerializable(typeof(CartState))]
[JsonSerializable(typeof(UserPrefs))]
public partial class GrainStateContext : JsonSerializerContext;

siloBuilder.AddDocumentDbGrainStorage("Default", o =>
{
    o.DatabaseProvider      = new PostgreSqlDatabaseProvider(cs);
    o.JsonSerializerOptions = new JsonSerializerOptions { TypeInfoResolver = GrainStateContext.Default };
    o.UseReflectionFallback = false;   // throw on an unregistered state type instead of reflecting
});

Purely opt-in — leave the defaults and you keep the familiar reflection-based behaviour. The same knobs exist on the reminder, clustering, grain-directory and stream options.

And in Aspire, it’s one line

If your silo runs under .NET Aspire, the AppHost provisions the store and the silo points the whole stack at it:

builder.AddDocumentStore("orleans");

builder.UseOrleans(silo => silo.UseAspireDocumentDb("orleans"));

That’s grain storage, reminders, clustering and the grain directory on the Aspire-provisioned store — connection, health check and telemetry included. Streams are one flag away and deliberately opt-in. The next post in this pair covers the Aspire integration properly.

Get started

dotnet add package Shiny.DocumentDb.Orleans

# optional companions
dotnet add package Shiny.DocumentDb.Orleans.MongoDb
dotnet add package Shiny.DocumentDb.Orleans.CosmosDb

Level Up Animation with Keyframes for MAUI & Blazor

Thu, 20 Aug 2026 00:00:00 GMT

Animation in .NET MAUI has always had the same shape: ViewExtensions.FadeTo, a Task, and a bool somewhere tracking whether you are mid-animation. It works right up until someone asks for the thing every design tool does for free — scrub it, reverse it halfway, hold the final pose, export it as a GIF for the marketing page.

This post covers three pieces that ship together and build on each other:

Keyframe — the CSS @keyframes model in XAML and a fluent C# timeline API, where evaluating an animation is a pure function of time.
Motion Icons — 42 animated icons authored once and compiled into a drawn scene on MAUI and real CSS @keyframes on Blazor.
ShinyButton — where the other two land in a real app: press a button, wait for the network, see whether it worked.

Layer 1 — Keyframes

dotnet add package Shiny.Maui.Controls.Keyframe

xmlns:kf="http://shiny.net/maui/keyframe"

There is no builder.Use…() call. That one XAML namespace is the whole installation.

Animate.Keyframes is an attached property on any VisualElement, and it is deliberately a direct analogue of a CSS @keyframes rule plus the animation-* properties that drive it — Duration, Delay, Iterations, Direction, Fill, and per-key easing all behave the way the web spec says they do:

<Border>
    <kf:Animate.Keyframes>
        <kf:Keyframes Duration="0:0:1.2" Iterations="Infinite" Direction="Alternate" Fill="Both">

            <kf:Track Property="Scale">
                <kf:Key Offset="0"   Value="1" />
                <kf:Key Offset="0.5" Value="1.15" Easing="CubicOut" />
                <kf:Key Offset="1"   Value="1" />
            </kf:Track>

            <kf:Track Property="BackgroundColor">
                <kf:Key Offset="0" Value="#2563EB" />
                <kf:Key Offset="1" Value="#EC4899" />
            </kf:Track>

        </kf:Keyframes>
    </kf:Animate.Keyframes>
</Border>

The same thing in C#, because a designer-authored animation and a data-driven one should not be two different engines:

var timeline = TimelineBuilder
    .Create(TimeSpan.FromSeconds(1.2))
    .PingPong()
    .RepeatForever()
    .Fill(FillMode.Both)
    .Animate(box, (v, x) => v.Scale = x, k => k
        .From(1)
        .Key(0.5, 1.15, Easings.CubicOut)
        .To(1))
    .Build();

var player = box.Play(timeline);

The one design constraint

IAnimationNode.Evaluate(t) computes the state at t from the keyframes alone. It never reads the previous frame and it never accumulates. Everything interesting falls out of that single property:

You want to…	Do this	Not this
Scrub from a `Slider` or a gesture	`player.SeekProgress(x)`	Rebuild a timeline at the new position
Reverse mid-flight	`player.Rate = -1`	Build a second, reversed timeline
Export frames	Sample at exact frame times — identical bytes every run	Render off a real-time clock and hope
Test timing	Step a `ManualClock`	`Task.Delay` and a tolerance

Rate scales the per-frame delta rather than the position, so flipping it mid-flight carries on from wherever the animation actually is instead of jumping to a rescaled position. That is the difference between “reverse” and “restart backwards”, and it is the thing you cannot retrofit onto an accumulating animator.

Easing you can paste in

Curves are a plain delegate double EasingFunction(double t), there are 38 named ones, and the string form parses CSS function syntax — because copying a curve out of a design tool or a devtools panel is by far the most common way anyone arrives at one:

<kf:Key Offset="0" Value="-200" Easing="cubic-bezier(0.34, 1.56, 0.64, 1)" />
<kf:Keyframes Easing="steps(8)" ... />
<kf:Keyframes Easing="spring(0.35, 14)" ... />

Easings.Spring is a closed-form solution of the spring ODE rather than a numeric integration — cheap enough to evaluate per frame, and still a pure function of t, so a spring seeks and reverses like every other curve here. An unrecognised easing string throws a FormatException listing every registered name at parse time, rather than silently running linear at runtime.

EasingCatalog.Register("Smoothstep", t => t * t * (3d - 2d * t));

Details that bite in production

A few deliberate choices worth knowing about:

Oklab colour blending by default. sRGB interpolation dips through grey at the midpoint; Oklab does not. ColorInterpolator.Srgb and .LinearRgb are still there when you want them.
Shortest-arc angles. Rotation from 350° to 10° turns forward 20°, not back 340°. Use Spin when multiple turns are the point.
Implicit keyframes. Omit Value on a key and it resolves to the target’s live value when playback starts, so a re-triggered animation continues from where it is instead of snapping.
AOT and trim safe. The animatable-property registry is hand-registered delegates — not reflection, not compiled Expression trees, both of which work in the emulator and vanish on device under Native AOT.
Weak targets. An Iterations="Infinite" animation on a popped page goes inert and gets collected rather than pinning the visual tree, so infinite loops are safe to use freely.
One clock per window. MauiClock.For(element) returns the clock shared by every animation on that element’s dispatcher, and it idles by itself when nothing is listening. Pause() detaches from the clock rather than ignoring ticks, so the platform can stop producing frames entirely.

Storyboards, scenes, and export

Storyboard composes timelines on a shared clock and is itself an IAnimationNode, so storyboards nest — a staggered list entrance can be one item inside a larger sequence:

var storyboard = new Storyboard()
    .Add(introTimeline)
    .Then(mainTimeline, gap: TimeSpan.FromMilliseconds(200))
    .Stagger(cardTimelines, interval: TimeSpan.FromMilliseconds(120));

KeyframeScene runs the same timing model against a layer tree drawn onto a canvas rather than views in the visual tree — the Lottie-shaped lane, for loaders, illustrated micro-animations, progress indicators and shape morphs. Both are IAnimationNodes on the same clock, so one storyboard can sequence real views and scene layers together, and KeyframeView.Progress is two-way, which gives you a scrubber for a Slider binding.

And because sampling is exact, a scene can be rendered offscreen, deterministically:

var exporter = new FrameExporter(scene);
var options = new ExportOptions { Fps = 25, Scale = 2.0 };

GifEncoder.EncodeToFile("out.gif", exporter.Frames(options), options.Fps);

Frames are enumerated lazily, frame times are computed as index / fps in ticks so a long export cannot drift, and the GIF encoder is pure managed code. Export is a separate package because it is the only part of Keyframe that needs a rasterizer — and it targets plain .NET rather than the platform TFMs, so it runs from a console app, a build step, or CI.

Layer 2 — Motion Icons

42 hand-drawn icons that animate. A bell that swings from its crown with the clapper catching up late. A hamburger that morphs into a cross. A tick that draws itself on. A spinner whose arc chases its own tail.

MotionIconView on MAUI, <MotionIcon> on Blazor — both live in the core packages, so there is nothing extra to install and nothing to register.

MAUI

<shiny:MotionIconView Icon="bell" Trigger="Loop" Interval="0:0:1.5" WidthRequest="32" HeightRequest="32" />

Blazor

<MotionIcon Icon="bell" Trigger="MotionTrigger.Loop" Interval="TimeSpan.FromSeconds(1.5)" Size="32" />

MAUI (iOS)

Triggers & code-driven playback	Presets & scrubbing	The icon set

Blazor

Triggers	Driven from code	Two-tone & colour	Presets on any icon

Those are single frames of things that only make sense in motion — the playground is the honest version.

One definition, two very different engines

The artwork and its motion live in Shiny.Controls.MotionIcons.Shared, a dependency-free package both hosts reference. What each host does with that definition could hardly be more different:

	.NET MAUI	Blazor
Rendering	a `KeyframeScene` on a `GraphicsView`	inline SVG
Animation	a keyframe `Timeline`, evaluated per frame	compiled once to CSS `@keyframes`
Driven by	the Keyframe engine’s `Player`, on one shared timer per window	the browser’s compositor
C# per frame	evaluate + redraw	none

That split is the whole point. On the web nothing about a motion icon needs a render loop — once the keyframes are declared the browser composites them off the main thread, at the display’s refresh rate, and keeps going while WebAssembly is busy elsewhere. A C# ticker driving re-renders would be slower, jankier, and would stop dead the moment the app did some work.

On MAUI there is no compositor to hand the work to, so an icon is drawn — but by the Keyframe engine rather than by machinery of its own. Motion icons and hand-written timelines share one clock per window, one set of easing curves, and one implementation of position, rate and baselines. Because both sides compile the same spec, with the same easing curves, an icon looks and moves the same in a MAUI app and in a browser.

Where CSS has a keyword that means exactly the same thing as a MotionEase member, the generated stylesheet uses it. Everything else — the overshoot and bounce curves CSS has no name for — is sampled into a linear() curve rather than approximated with a “close enough” cubic-bezier, which is what would otherwise make a bounce bounce differently in the browser than on the phone.

Triggers

Trigger is a [Flags] enum defaulting to Hover | Press — hover for desktop, press for touch, so an icon does something sensible everywhere without being told.

Trigger	Behaviour
`Loop`	Runs continuously. `Interval` inserts a resting gap between cycles — a bell that rings without pause reads as broken.
`Hover`	Runs while the pointer is over it, then finishes the cycle it is in, so a half-swung bell settles upright instead of snapping.
`Press`	One play per tap or click.
`Appear`	Plays once when the icon first becomes visible — an `IntersectionObserver` on the web, `Loaded` on MAUI.
`Manual`	No automatic trigger. Bind `IsPlaying` to a busy flag, or call `Play()` / `Stop()` / `StopAtCycleEnd()`.

The Interval gap is folded into the animation itself rather than scheduled by a timer. A CSS animation has no way to pause between iterations, so a spec that expressed the gap externally would need a JavaScript timer on the web and a dispatcher timer on MAUI, and the two would drift. Squeezing the keys into the front of a longer cycle and holding the resting pose through the remainder gets the same result out of animation-iteration-count: infinite.

On MAUI, Progress is two-way, so an icon can be scrubbed from a slider or a gesture — dragging morphs the hamburger into a cross and back:

<shiny:MotionIconView Icon="menu" Trigger="Manual"
                      Progress="{Binding Source={x:Reference Scrubber}, Path=Value}" />

<Slider x:Name="Scrubber" Minimum="0" Maximum="1" />

Presets, and your own artwork

A preset is motion that does not need to know what it is animating — Pulse, Beat, Spin, Shake, Wobble, Bounce, Float, Pop, Tada, Flip, Swing, Blink, Draw, Nudge, Jiggle. Every one works on a built-in icon, on raw PathData of your own, and on a MotionIconDefinition you assembled:

<shiny:MotionIconView Icon="star" Motion="Tada" Trigger="Hover" />
<shiny:MotionIconView PathData="M12 2 3 20h18z" Motion="Pop" Trigger="Press" />

Default is a fallback chain rather than a preset: it asks the icon for its own motion first, which is why Icon="bell" rings rather than merely pulsing, and lands on Pulse for artwork that has none.

For custom artwork, an icon splits into parts for exactly one reason — a part is the unit a track can target:

var toggle = new MotionIconDefinition(
    "toggle",
    [
        new MotionIconPart("plate", "M3 8h18v8H3z"),
        new MotionIconPart("knob", "M11 12a3 3 0 1 1 6 0 3 3 0 0 1-6 0z") { Origin = new MotionPoint(14f, 12f) }
    ],
    MotionSpecBuilder.Build(500, m => m
        .MoveX("knob", k => k
            .At(0d, 0d, MotionEase.BackOut)
            .At(0.5d, -6d, MotionEase.BackInOut)
            .At(1d, 0d))));

MotionIconLibrary.Register(toggle);

Register replaces a built-in as well as adding a new one, so an app with its own visual language swaps the artwork for check once at startup rather than passing a definition in at every call site.

There is deliberately no path-morph channel. Every channel — Opacity, TranslateX/Y, Rotate, Scale, ScaleX/Y, StrokeWidth, Trim, plus colour on Fill and Stroke — has a native, identically-behaving implementation on both hosts, which is the only way one icon can be guaranteed to look the same in both. Animating SVG’s d is not supported in every browser, so a morph channel would have meant hand-written fallbacks the moment someone opened Firefox. Hinged and morphing icons are built from separate parts moved by transforms, exactly as they would be in a design tool.

On the web, prefers-reduced-motion: reduce is honoured automatically — the icon still renders and still responds to clicks, it just holds its resting pose. An icon with no Title is marked aria-hidden so a screen reader announces the button’s text once rather than twice.

Layer 3 — ShinyButton

Microsoft.Maui.Controls.Button renders text and one image. There is no way to put a spinner inside it, so the most ordinary interaction in an app — press a button, wait for the network, see whether it worked — gets hand-assembled on every page out of a Grid, an ActivityIndicator, a swapped label, and an IsBusy property on the view model that exists purely for the UI’s benefit.

ShinyButton is that assembly, done once, on both hosts.

MAUI (iOS)

Appearance × Type	Motion icons in the slots	All three busy modes at once

Success state, command state	Shapes & sizes

Blazor

Appearance × Type	Motion icons	Busy modes	Success

Nothing binds IsBusy, because there is no IsBusy

<!-- SaveCommand is an AsyncRelayCommand. That is the entire wiring. -->
<shiny:ShinyButton Text="Save"
                   BusyText="Saving..."
                   LeftMotionIcon="download"
                   Command="{Binding SaveCommand}" />

ButtonState is Normal, Busy, Success or Error. Each non-normal state stands in its own text and its own icon, and Success/Error return to Normal on their own after StateRevertDelay:

<shiny:ShinyButton Text="Submit"
                   State="{Binding SubmitState}"
                   BusyText="Submitting..."
                   SuccessText="Submitted"
                   ErrorText="Failed"
                   SuccessMotionIcon="check"
                   ErrorMotionIcon="warning"
                   StateRevertDelay="0:0:2"
                   Command="{Binding SubmitCommand}" />

Setting IsBusy false only unwinds Busy — it will not cut a Success or Error short. That matters more than it sounds: a view model clearing its busy flag in a finally block is exactly the moment the outcome is on screen, and the naive projection would wipe the tick before anyone saw it.

On Blazor there is no ICommand, so the equivalent is that Clicked is awaited — an async handler holds the button busy for exactly as long as it runs:

<ShinyButton Text="Save" BusyText="Saving..." LeftMotionIcon="download" Clicked="SaveAsync" />

@code {
    async Task SaveAsync() => await http.PostAsJsonAsync("/api/save", model);
}

A synchronous handler never flickers — the returned task is checked for completion before any state change, so a handler that finished inline does not produce a one-frame spinner.

Motion icons in the slots

Each side takes an ImageSource, a motion icon name, or any View. The motion icon is the path worth taking: the button colours it from its own resolved foreground and plays it from its own tap, so a tap anywhere on the button animates the glyph rather than only one that lands on it.

<shiny:ShinyButton Text="Refresh feed"
                   LeftMotionIcon="refresh"
                   RightMotionIcon="chevron-down"
                   Appearance="Outlined" />

This is exactly the case the motion-icon docs warn about: an icon inside a larger tap target should be Manual, with the host playing it. ShinyButton sets that up on both hosts, and MotionIconPlayOnClick="false" turns it off.

On Blazor the icons default to currentColor, so they inherit the button’s CSS color — including hover and disabled — with nothing wired up at all.

Busy modes, and why they are about layout

Mode	Behaviour
`ReplaceLeftIcon` (default)	The indicator takes the left icon’s place and the text stays put. Both are `IconSize` square, so the button cannot change width and a row of buttons cannot reflow.
`ReplaceContent`	The content fades to opacity zero — keeping its layout space — and a centred indicator takes over.
`KeepContent`	The indicator appears after the right icon and nothing else moves.

ReplaceContent uses opacity rather than visibility deliberately. Hiding the content would collapse the button to the width of the spinner and shove the rest of the row sideways mid-operation; keeping it laid out but invisible pins the width with no measuring on your part.

The indicator is, in order: BusyIconView if you set one, a motion icon if BusyMotionIcon is set (default loader), or a platform ActivityIndicator if you clear it.

Appearance is emphasis, Type is meaning

They stay orthogonal on purpose — that is what lets a destructive action be loud (Filled + Critical) or quiet (Text + Critical) without an enum member for every pairing. Appearance is Filled, Tonal, Outlined, Text or Elevated; Type is Primary, Secondary, Success, Warning, Critical or Info.

Everything resolves through the theme tokens — SetDynamicResource on MAUI, --shiny-color-* custom properties on Blazor — so a live theme swap restyles a button with no re-render. Any explicit colour short-circuits its token, which means it survives every theme change; leave them unset unless you mean to pin the colour.

The command integration (MAUI)

Two behaviours, both on by default, and both with a sharper edge than they look:

CanExecute → disabled goes through MAUI’s own IsEnabledCore — the same mechanism Microsoft.Maui.Controls.Button uses — rather than writing IsEnabled. A button that wrote IsEnabled would overwrite your binding, and a command becoming executable again would silently re-enable a button you had deliberately switched off.

AutoBusy solves the fact that ICommand.Execute returns void, so a button handed an async command has no handle on the work it just started. Every async command implementation exposes an ExecutionTask or an IsRunning/IsExecuting flag — MVVM Toolkit’s, Prism’s, ReactiveUI’s, most hand-rolled ones — but there is no shared interface to type against. Rather than put an MVVM framework dependency into the core controls package (landing it in every consumer’s app, whichever framework they actually use), the shape is discovered once per command type and cached. Set AutoBusy="False" and own State yourself for a fully trimmed or NativeAOT build.

Where to go next

Blazor Playground — motion icons and ShinyButton, live, right now.
Keyframe — XAML, easing, timelines & playback, drawn scenes, offscreen export.
Motion Icons — the icon set, triggers, presets, custom artwork.
ShinyButton — states & commands, Blazor usage.

Shiny Controls 1.0 — The Ultra Control Suite for .NET MAUI & Blazor

Mon, 17 Aug 2026 00:00:00 GMT

Shiny Controls 1.0 is here. One control suite, two renderers — native .NET MAUI and real Blazor components — sharing a Material 3 style token contract so a ShinyButton on iOS and a ShinyButton in the browser are the same control with the same API, not two lookalikes maintained in parallel.

Click it before you install it

The whole Blazor gallery is deployed and live. Every control below has a page in it, with the knobs wired up so you can drive the thing rather than read about it:

👉 shinyorg.github.io/controls

It is the same Sample.Blazor project that lives in the repo, published to WebAssembly. The theme selector in the header is not a demo affordance — it swaps the real theme pack stylesheet, and every control on every page restyles itself from the tokens.

The catalogue

There are too many controls to introduce one at a time, so here is the whole suite as a table. Each one links to its own docs, which is where the properties, templates and platform notes live.

Category	Controls
Flagship	TableView · Scheduler · ChatView · ImageEditor
Collections & grids	DataGrid · VirtualizedGrid · StaggeredGrid · ParallaxCollectionView · CarouselGallery · Carousel
Layout & overlays	Stacks & Grid · AppLayout · FloatingPanel · SheetView · Overlay · Fab & FabMenu · TreeView · FrostedGlassView · Toolbar & TabBar · StateView · Wizard · Walkthrough · Tooltip
Input	ShinyButton · TextEntry · AutoCompleteEntry · AddressEntry · CountryPicker · ColorPicker · FontPicker · Slider · RangeSlider · SecurityPin · SignaturePad · MediaPickerButton · DurationPicker · Speech Add-ins
Display & media	CameraView · MediaElement · ShinyImage · ImageViewer · Markdown · Mermaid Diagrams · Barcodes & QR · Keyframe Animation · Motion Icons
Status & feedback	Toast · Dialogs · ProgressBar · SkeletonView · Splash Screen · PillView · BadgeView · Feedback Service
Desktop	Tray Icon · Docking
System	Theming — the token contract and the Basic / Ocean / Material / Terminal / Aurora packs

Below are the three worth stopping on.

ChatView

A full chat surface — bubbles, grouping, avatars, reactions, read receipts, typing indicators, attachments, optimistic send with retry, cursor-based paging that stays stable while messages arrive.

The thing that makes it different from a CollectionView with a bubble template is that it does not bind a Messages collection. You implement an IChatSessionProvider that hands the control a session-scoped IChatSession, and the control subscribes to that session’s live events on attach and disposes it on detach. Paging, live inserts, send verdicts and typing all flow through that one seam, so the control owns the hard part instead of leaving it in your view model.

<shiny:ChatView Provider="{Binding Provider}"
                SessionId="{Binding SessionId}"
                MyBubbleColor="#DCF8C6"
                OtherBubbleColor="White" />

public partial class ChatViewModel(IChatSessionProvider provider) : ObservableObject
{
    public IChatSessionProvider Provider { get; } = provider;
    public string SessionId { get; } = "demo";
}

That is the whole integration. Permissions drive what the UI offers — PermittedEmojis decides whether the reaction row appears at all, BodyPermissions gates the markdown toolbar — so the control never shows an affordance your backend will reject.

MAUI	MAUI — custom templates	Blazor

→ ChatView docs

Walkthrough

Dim the page, cut an animated spotlight around one control at a time, say what it does. Onboarding, feature announcements, and the workflow someone only does once a quarter.

The design decision worth calling out: the steps live together on the walkthrough, in order — they are not attached properties on the controls they describe. On a real screen, with nested layouts and templated cells and a panel that is only sometimes there, attached ordering scatters the sequence across the markup where nothing can see it as a whole. Reordering becomes a hunt, and a step whose control is conditionally hidden silently derails everything after it. Here, reordering is moving a line, and IsVisible="False" drops a step out of the run and re-numbers the counter.

<shiny:Walkthrough RememberRunKey="home-v1" AutoStart="True" OverlayOpacity="0.8">

    <!-- No target: a centred welcome card, no cut-out. -->
    <shiny:WalkthroughStep Title="Welcome"
                           Text="Here is what is new in this release."
                           AnimationIn="Pop" />

    <shiny:WalkthroughStep Target="{x:Reference SearchBox}"
                           Title="Find anything"
                           Text="Search across every project you can see."
                           Placement="Bottom" />

    <!-- No card at all; the cut-out does the pointing. -->
    <shiny:WalkthroughStep Target="{x:Reference Avatar}"
                           Title="Your profile"
                           Text="Settings and sign-out live here."
                           Display="Spotlight"
                           Highlight="Circle" />

    <!-- Live control: the tap reaches it through the hole, and using it advances. -->
    <shiny:WalkthroughStep Target="{x:Reference SaveButton}"
                           Text="Press Save to finish."
                           AllowTargetInteraction="True"
                           AdvanceOnTargetTap="True" />
</shiny:Walkthrough>

RememberRunKey is what makes onboarding run once — it is backed by a replaceable IWalkthroughStore (Preferences on MAUI, localStorage on Blazor), and Restart() clears it. The tour paints into a layer above the page content, so a target inside a scroll view or a card gets highlighted where it actually is instead of being clipped by its container.

Welcome	Popover on a target	Circular spotlight	Live target

Top row MAUI (iOS), bottom row Blazor — same four steps, same XAML-shaped markup.

→ Walkthrough docs

Scheduler

Three views — a monthly calendar grid, a day/multi-day agenda timeline, and a vertically scrolling event list — over one data interface. You write the data layer once and pick the view per screen.

public class MyEventProvider : ISchedulerEventProvider
{
    public async Task<IReadOnlyList<SchedulerEvent>> GetEvents(
        DateTimeOffset start, DateTimeOffset end)
        => await myService.GetEventsAsync(start, end);

    public void OnEventSelected(SchedulerEvent selectedEvent) { /* navigate, show a sheet… */ }

    public bool CanCalendarSelect(DateOnly date) => true;
    public void OnCalendarDateSelected(DateOnly date) { }
    public void OnAgendaTimeSelected(DateTimeOffset time) { }
    public bool CanSelectAgendaTime(DateTimeOffset time) => true;
}

<scheduler:SchedulerCalendarView Provider="{Binding Provider}"
                                 SelectedDate="{Binding SelectedDate}" />

Multi-day events span correctly across all three views, the agenda draws a live current-time marker and supports extra timezone columns with sticky headers, the event list scrolls infinitely in both directions, and every visual element — events, headers, loaders, day pickers — is replaceable with a DataTemplate. Bindings use the static lambda overloads throughout, so it is AOT-safe with no string-based reflection.

Calendar	Agenda	Event list	Agenda + picker

→ Scheduler docs

CameraView

Screenshots of a camera control are famously useless — a picture of a preview is just a picture — so here is what it actually does instead.

CameraView is a cross-platform camera for MAUI (AVFoundation on iOS / Mac Catalyst / macOS, CameraX on Android, Media Capture on Windows) with a matching Blazor WebAssembly control over getUserMedia. Live preview, lens and device selection, pinch-to-zoom, torch, flash, photo capture and video recording with quality/bitrate/frame-rate control are the table stakes.

The two things that set it apart are pluggable pipelines, and they compose with each other:

The frame-analysis pipeline. Assign a single IFrameAnalyzer — declared right in XAML, since the analyzer is the content property of CameraView — and frames stream to it off the UI thread with drop-on-busy back-pressure. Bounding boxes draw continuously via CameraOverlayView, but results are delivered on a gated scan trigger: arm with Scan() and the next confirmed detection fires once. An optional ScanWindow restricts detection to a region and draws an aim reticle. Built-in analyzers cover barcode/QR (native Vision and MLKit, restrictable by symbology), face detection with landmarks, motion clustered into debounced regions, OCR with scan-window crop and upscale for small text, and structured documents — invoices with order lines, receipts with line items and per-tax breakdowns, business cards, AAMVA driver’s licences, province-aware Canadian health cards, credit cards and passport MRZ — each a strong record with nullable fields. When the document is free-form, AiDocumentAnalyzer<T> detects presence cheaply on every frame and sends exactly one frame to a Microsoft.Extensions.AI IChatClient for structured extraction.

The effects pipeline. Effects is an ordered, live collection applied to the preview, captured stills and — on Apple — recorded video. Mutate it while the camera runs and the change lands on the next frame. Eleven colour grades, five spatial GPU looks (comic, sketch, posterize, pixelate, blur), compositing draw effects for watermarks and face masks anchored to tracked facial landmarks, and slow post-capture transforms such as AI photo stylization through an MEAI IImageGenerator. Four extension points let you add your own at the right layer. And because per-platform coverage is genuinely uneven, GetEffectSupport(effect) reports Full / ColorOnly / StillOnly / Unsupported so your UI can grey out what would otherwise silently do nothing.

Two more that are easy to miss: you can record and analyse at the same time on every platform — a dash-cam app reading signs off its own live feed while recording — and VideoRecordingOptions.Overlay burns a watermark, timestamp or telemetry into every encoded frame, drawn with Microsoft.Maui.Graphics so one implementation covers every platform.

→ CameraView docs

Theming ties it together

None of the above is styled by hand. Colour roles, surfaces, shape, elevation, typography, density, borders, state and spacing are a token contract the controls read — SetDynamicResource on MAUI, var(--shiny-*) on Blazor. The core packages define the contract and a built-in Basic theme; Ocean, Material, Terminal and Aurora install as separate NuGet packs and swap the whole app’s look without touching a page.

Basic	Ocean	Material	Terminal	Aurora

Want your own? The Theme Creator takes a few seed colours and exports the theme JSON, the Blazor CSS, or the MAUI C#.

Getting started

dotnet add package Shiny.Maui.Controls     # .NET MAUI
dotnet add package Shiny.Blazor.Controls   # Blazor

Then go press things in the playground, and see the controls documentation for the rest.

Shiny.DocumentDb — Hidden Gems

Thu, 13 Aug 2026 00:00:00 GMT

Every release post covers the headline. Thirteen major versions of those leaves a lot of API that shipped in a bullet list and never got explained — which is a shame, because some of it is the stuff I actually reach for most.

This post is the sweep. Three features get real depth because they change how you’d write the code around them, and the rest are quick hits. Nothing here is new in v13; all of it is in the box today.

1. The store already knows what changed

You have a document in the database and an object in memory that’s been edited by a form, a merge, or an LLM. The question every app asks next is what actually changed? — for an audit line, for a confirmation screen, for an “are you sure, this touches 4 fields” dialog.

The usual answer is to write a comparer. You don’t have to:

var patch = await store.GetDiff<Order>(order.Id, edited);
// JsonPatchDocument<Order>, RFC 6902 — null when no such document exists

foreach (var op in patch!.Operations)
    logger.LogInformation("{Op} {Path} => {Value}", op.Op, op.Path, op.Value);

GetDiff reads the stored document, compares it against the candidate, and hands back a JsonPatchDocument<T> — a real RFC 6902 patch, not a string. Note the shape of it: this is a read. You haven’t written anything yet, so it’s the thing to call before the save, which is exactly when the question gets asked.

Writing only what changed

The write side has the same idea from the other direction. A full Update replaces the stored body; an Upsert deep-merges it, RFC 7396:

// only the non-null properties are touched; everything else stays as stored
await store.Upsert(new Order { Id = id, Status = "shipped" });

That’s the default behaviour of Upsert on every provider. Its inverse — replace-on-update rather than merge — is Upsert(patch, patchIfUpdate: false), which the relational providers implement and the rest refuse rather than fake. There’s a matching Update(document, patch: true) when the document must already exist.

For a genuine partial update through a typed object, remember the type has to be able to express “unset”: JsonIgnoreCondition.WhenWritingNull on the properties, or use the JSON collection lane where the body is a JsonObject and absent means absent.

And when it’s one field, skip the object entirely:

await store.SetProperty<Order>(id, o => o.Status, "shipped");
await store.RemoveProperty<Order>(id, o => o.CancelReason);

Both return bool — false when no such document — and both are a single statement against the JSON column. No read, no round trip, no lost update from the write you didn’t know was concurrent with yours.

Then turn on temporal and it gets silly

Map a type as temporal and every one of those writes leaves a version behind:

options.ConfigureDocument<Order>(cfg => cfg.MapTemporal(o => o.Retention = TimeSpan.FromDays(90)));

var temporal = (ITemporalDocumentStore)store;

await temporal.History<Order>(id);                          // every version
await temporal.AsOf<Order>(id, lastTuesday);                // the document as it was
await temporal.ChangesByActor<Order>("user:42");            // everything one actor touched
await temporal.GetDiffBetween<Order>(id, 3, 7);             // a patch between two versions
await temporal.Restore<Order>(id, version: 3);              // put it back

That’s an audit trail, a point-in-time read, a per-user change log and an undo button, from one line of configuration. It works on every provider — relational, Cosmos, MongoDB, LiteDB, IndexedDB — through ITemporalDocumentStore, which you probe for rather than assume (store is ITemporalDocumentStore).

The reason I keep pointing at this one: almost everybody hand-rolls a ChangeLog table, and it’s almost always worse than this, because a hand-rolled one records the fields somebody remembered to record.

2. Stop deserializing JSON just to serialize it again

Here’s the shape of an enormous number of API endpoints:

app.MapGet("/orders/{id}", async (string id, IDocumentStore store) =>
{
    var order = await store.Get<Order>(id);   // JSON -> Order
    return Results.Ok(order);                 // Order -> JSON
});

The database handed you a perfectly good JSON document. You parsed it into an object graph, allocated every string and list in it, and then serialized it straight back into bytes that are — modulo whitespace — what you started with. Order did no work. It was overhead with a type name.

DocumentDb stores JSON. So take JSON:

app.MapGet("/orders/{id}", async (string id, IDocumentStore store) =>
{
    var raw = await store.Query<Order>().Where(o => o.Id == id).FirstOrDefaultRawJson();
    return raw is null ? Results.NotFound() : Results.Content(raw, "application/json");
});

And for a list, don’t even materialize the list — stream it into the response as it comes off the reader:

ctx.Response.ContentType = "application/json";
await store.Query<Order>()
    .Where(o => o.Status == "open")
    .OrderByDescending(o => o.CreatedAt)
    .WriteJsonArrayTo(ctx.Response.Body, ct);

The point that makes this usable rather than a curiosity: you still build the query with the typed surface. Where, OrderBy, Paginate, global query filters, soft delete, tenancy — all of it applies, because only the terminal changed. You get the compiler checking your predicate and the database handing back bytes.

There’s a node lane too, when you want to touch the JSON before it leaves: ToJsonList, ToJsonAsyncEnumerable, FirstJson / FirstOrDefaultJson, SingleJson / SingleOrDefaultJson, ToJsonCursorPage — all returning JsonObject, all built on the same RawJsonRows primitive the raw lane uses.

The fidelity rules, because they matter

On the relational providers and Cosmos DB, these are the persisted bytes, untouched. Zero parses.
Everywhere else the provider has to materialize T to finish the query, so the body is re-serialized through the type’s JsonTypeInfo. Same JSON, same API — but the round trip is real, and you should expect no win.
Materialized computed properties live outside the body, so they don’t appear. A DocumentBlob shows up as its metadata envelope, not its payload.
A type with encrypted properties throws. The stored body is ciphertext, and only the typed terminals decrypt.

That last group is why there’s a SupportsRawJson flag on the query. Test it rather than catching the throw when the JSON lane is an optimization and the typed path is still correct — which is exactly how the built-in OData and AI surfaces pick a lane.

Trim the fields on the way out

Pair it with the string projection when the caller only wants some of the document:

// a REST ?fields= sparse fieldset, resolved at runtime
var rows = await store.Query<Order>()
    .Project("id, number, total, customer.name as customer, lower(status) as status")
    .ToJsonList();

Dotted paths reach into nested objects and become first-class output keys. Scalar functions from the string grammar (lower, length, substring, year, soundex, …) can be projected too, and require an alias. Relational providers do this in SQL; the document providers do it client-side.

3. Everything soft delete taught me about extensibility

Soft delete shipped in v12 as a one-liner:

options.ConfigureDocument<Customer>(cfg => cfg.AddSoftDelete(x => x.IsDeleted));

Deletes set the flag instead of deleting, and every read hides flagged documents. The part worth writing about is that nothing in any store knows it exists. Here is, essentially, the whole implementation:

options.AddInterceptor(interceptor);       // cancel the delete, set the flag instead
options.AddBulkInterceptor(interceptor);   // same for ExecuteDelete / Clear
options.Mappings.AddQueryFilter("soft-delete", mapping.NotDeleted);

Three public calls. No provider changes, no if (softDelete) anywhere in the query pipeline, and it works identically on all twenty-odd backends because it never went near one.

The two primitives it’s made of are worth knowing on their own.

`ctx.Cancel()` — replace a write, don’t just watch it

An interceptor’s BeforeWrite can substitute itself for the write:

public class ArchiveOnDelete : IDocumentInterceptor
{
    public async Task BeforeWrite(DocumentWriteContext ctx, CancellationToken ct)
    {
        if (ctx.Operation != DocumentOperation.Delete || ctx.DocumentType != typeof(Order))
            return;

        var order = await ctx.Store.Get<Order>(ctx.Id!, cancellationToken: ct);
        if (order != null)
        {
            await ctx.Session
                .Add(new ArchivedOrder { Id = order.Id, Body = order, ArchivedAt = DateTimeOffset.UtcNow })
                .SaveChanges(ct);
        }
        ctx.Cancel();   // the store performs no delete, and reports success to the caller
    }

    public Task AfterWrite(DocumentWriteContext ctx, CancellationToken ct) => Task.CompletedTask;
}

Cancel() means the store does nothing, no AfterWrite runs, and no change notification is published — the caller gets the outcome you name (Cancel(succeeded: false) reports failure). It’s only legal inside BeforeWrite; calling it later throws rather than silently doing nothing. ctx.Session is scoped to the write’s own transaction, so the archive row commits with the operation that caused it, or not at all.

That’s an append-only archive, in about twenty lines, that no provider needed to hear about.

Named query filters — and lifting them one query at a time

A global filter usually gets registered anonymously and then becomes a problem the first time an admin screen needs to see past it. Give it a name:

options.ConfigureDocument<Order>(cfg => cfg.AddQueryFilter("archived", o => !o.IsArchived));

store.Query<Order>().IgnoreQueryFilters("archived");   // just this one
store.Query<Order>().IgnoreQueryFilters();             // all of them

Which is exactly what soft delete’s own IncludeDeleted() does — it’s a one-line extension over IgnoreQueryFilters(SoftDelete.FilterName). Features here are meant to be built this way: extension methods over public hooks, so an optional feature never becomes a member on an options class that every provider has to carry.

Quick hits

ToQueryString() — see what your LINQ actually became, without running it.

var q = store.Query<Order>().Where(o => o.Total > 100).OrderBy(o => o.CreatedAt).ToQueryString();
Console.WriteLine(q.Sql);          // the provider's SQL (or MongoDB's rendered BSON)
Console.WriteLine(q.Parameters);   // the bound values

Relational providers and Cosmos return SQL; MongoDB returns its filter as JSON; the in-memory evaluators (LiteDB, IndexedDB) throw, because there’s nothing to show.

Cursor pagination — Skip/Take gets slower the deeper you go and shifts under concurrent writes. Keyset paging doesn’t:

CursorPage<Order> page = await store.Query<Order>()
    .Where(o => o.Status == "open")
    .OrderByDescending(o => o.CreatedAt)
    .ToCursorPage(cursor, take: 50);

page.Items;        // this page
page.NextCursor;   // opaque token; null means that was the last page
page.HasMore;

O(log n) per page with an index on the sort key, an Id tiebreaker appended for you, and a shape hash so a cursor can’t be replayed against a differently-filtered query. ToJsonCursorPage is the same thing in the JSON lane. There’s no total count — that’s what Paginate is for.

DocumentFunctions.Soundex — fuzzy name matching that pushes down to the engine:

store.Query<Person>().Where(p => DocumentFunctions.Soundex(p.Name) == DocumentFunctions.Soundex("Smith"));

Native SOUNDEX() on SQL Server and MySQL, fuzzystrmatch on PostgreSQL, a registered UDF where there’s nothing built in.

NotifyOnChange() — a change feed scoped to one query, as an IAsyncEnumerable:

await foreach (var change in store.Query<Order>().Where(o => o.Status == "open").NotifyOnChange(ct))
    Console.WriteLine($"{change.ChangeType}: {change.Id}");

IDocumentSeeder — versioned, provider-agnostic seed data with a marker so it runs once:

public class ProductSeeder : IDocumentSeeder
{
    public string Name => "products";
    public int Version => 3;                    // bump to re-run

    public Task SeedAsync(IDocumentStore store, CancellationToken ct)
        => store.BatchInsert(Products, cancellationToken: ct);
}

services.AddDocumentSeeder<ProductSeeder>();    // runs at startup

JSON Schema validation (Shiny.DocumentDb.JsonSchema) — draft 2020-12, checked against the exact bytes about to hit disk:

options.ConfigureDocument<Order>(cfg => cfg.MapJsonSchemaFromFile("schemas/order.json"));

Schema-free doesn’t have to mean unvalidated, and it’s per type — validate the two documents that matter and leave the rest open.

Computed properties — a value derived from other fields that you can still filter and sort on:

options.ConfigureDocument<OrderLine>(cfg =>
    cfg.MapComputedProperty(x => x.LineTotal, x => x.Quantity * x.UnitPrice, indexed: true));

indexed: true asks for a materialized, indexable computed column where the backend has one; without it, it’s an alias expanded into the query.

IDocumentMaintenance — ClearAll() wipes every type including temporal, spatial and vector sidecars (tests and dev resets, not tenant-scoped), and SweepOrphanedBlobs<T>() collects blob rows whose owning document went away out of band. Probe for it: store is IDocumentMaintenance.

And the tools nobody’s seen

The two most under-advertised things in the project aren’t API at all. ShinyDocDbMyAdmin has had a terminal front end since v12.5 — the same tool as the web UI, as a dotnet tool, over SSH — and the web one has shipped as a Docker Desktop extension since 13.0.1, which hands it every database container already running on your machine, connected.

Both deserve their own post with screenshots, and they’re getting one. In the meantime: the admin docs.

Shiny.DocumentDb v13 — Encryption, an Outbox, and a Front Door

Wed, 12 Aug 2026 00:00:00 GMT

v13 is the release where DocumentDb stopped being only a place to put documents and became something you can put in front of things — an HTTP resource, an MCP endpoint, an Orleans stream provider, an outbox that commits with the write that caused it. And underneath all of that, the data can now be encrypted at rest, field by field, on every provider.

Field-level encryption — AES-256-GCM, in the core package, no new dependency. Deterministic mode keeps equality filters working.
Transactional outbox — record “this happened” in the same transaction as the write that made it happen. No second datastore, no dual-write window.
REST + live queries — a document type becomes list / by-id / count / create / replace / merge-patch / delete plus an SSE tail, in one line.
MCP server — point Claude Code, Claude Desktop or Copilot at a store.
ConfigureDocument<T> — every per-type mapping method collapses into one block. Breaking, and the biggest thing to know before you upgrade.
Orleans persistent streams (13.2) — durable, rewindable, inspectable streams on the database the cluster already uses.
VectorData connector — MEVD over any vector-capable backend.
Query terminals (First / Single), multi-property ExecuteUpdate, raw JSON terminals, validate-on-build, real row locks, and multi-tenancy that survives a real deployment.

Full detail is on the release notes. This post walks the headliners.

Field-level encryption

Some documents carry a field that shouldn’t be readable by anyone holding the database file — an SSN, a government id, a bank account. Whole-database encryption (SQLCipher, TDE) protects the file; it does nothing about the DBA, the backup, or the read replica.

v13 encrypts individual properties:

opts.UseEncryptor(new AesGcmDocumentEncryptor("k1", key));

opts.ConfigureDocument<Patient>(cfg =>
{
    cfg.MapProperty(x => x.Ssn, p => p.Encrypt());                              // opaque
    cfg.MapProperty(x => x.Email, p => p.Encrypt(EncryptionMode.Deterministic)); // still queryable
});

And that’s it. Get, ToList, Insert, Update, LINQ — nothing about how you read or write documents changes. The stored body holds enc:1:k1:… where the value used to be.

The mechanism is the part I’m happiest with: it’s installed as a JsonTypeInfo modifier, so every write path is covered by construction — including temporal history and backup export, which are exactly the two places a bolt-on encryption layer forgets. No provider knows it exists.

Deterministic mode keeps equality filters working by rewriting the predicate’s constant into the ciphertext actually stored, so Where(x => x.Email == "a@b.com") still matches. The docs say in bold what that costs you: deterministic ciphertext leaks equality and frequency. Anything that can’t be answered against ciphertext — a range, a Contains, an OrderBy — throws with an explanation rather than quietly matching nothing.

Key rotation is a key ring plus RewrapAsync<T>(), and values written before a property was mapped keep reading, so you can turn it on for a store that already has data. AES-GCM is in the BCL, so there’s no new dependency, and it’s AOT-clean.

Encrypted properties now leave the library as plaintext, not as re-encrypted envelopes. The converters are symmetric, so any code that materialized a document and serialized it again through the store’s own JsonSerializerOptions was silently re-encrypting what it had just decrypted. Three places did: OData responses, the AI query/get/insert tool results, and GetDiff/GetDiffBetween.

GetDiff was outright broken by this — under randomized mode it compared the stored envelope against a freshly-encrypted one, so every mapped property came back as changed, every time.

The fix is right, but it is a disclosure change if you were relying on the old behaviour: a property that went over the wire as an opaque enc:1:… string now goes over it as its value. Check your exposed OData entity sets before upgrading.

A transactional outbox

The dual-write problem: you save an order and publish OrderPlaced. Two systems, no shared transaction. The process dies in between and you have an order nobody was told about, or a message about an order that doesn’t exist.

An outbox fixes it by making the message part of the same transaction as the write:

o.AddOutbox();                                  // maps OutboxMessage → its own "outbox" table
services.AddDocumentOutbox<BusDispatcher>();    // the processor + IOutboxAdmin

await using var session = store.OpenSession();
session.Add(order).Enqueue(new OrderPlaced(order.Id, order.Total));
await session.SaveChanges();                    // both rows commit together, or neither does

Or declaratively, per type: cfg.PublishToOutbox(ctx => new OrderChanged(...)).

Delivery is at-least-once with an attempt counter, exponential backoff and dead-lettering. Claiming is per-message optimistic concurrency, so you scale workers by running more of them — there’s no coordinator. The traceparent captured at enqueue is restored at dispatch, so a consumer’s span links back to the request that caused the message.

On the provider tier, because this one has a real boundary: relational plus LiteDB. Everything else implements a unit of work by compensation, which does precisely nothing for a process that dies mid-unit — which is the exact window an outbox exists to close. Rather than ship a promise that doesn’t hold, a new IDocumentStore.SupportsTransactions capability gates those backends out at host startup, by name. Cosmos DB is a further no: “same transaction” there means “same logical partition”, and the store partitions by type name. Those backends should use IChangeFeedDocumentStore instead.

A front door: REST, SSE and MCP

REST endpoints, in one line

app.MapDocuments<Order>("/orders", o =>
{
    o.Operations = DocumentEndpoints.All;
    o.AllowFilterOn(x => x.Status, x => x.Total);
    o.TypeInfo = AppJsonContext.Default.Order;
    o.Scope<ITenantContext>((tenant, _) => x => x.TenantId == tenant.TenantId);
})
.RequireAuthorization("orders");

List, by-id, count, create, replace, RFC 7396 merge-patch, delete, and a live Server-Sent-Events tail. Plain JSON, framework reference only, AOT-clean.

Filtering uses the store’s own string grammar behind a per-endpoint field allowlist — an unlisted field is a 400, not a table scan. take is clamped to MaxPageSize. Cursor paging, sparse fieldsets, ETag/If-Match concurrency and ProblemDetails errors are all in.

Scope(...) is worth calling out: it’s resolved per request from the request’s DI scope, AND-ed into every operation, and can’t be removed by the caller. Out-of-scope documents are 404, not 403 — a 403 confirms the row exists. MapDocumentCollection does the same for a schema-free JSON collection.

An MCP server

shiny-documentdb-mcp --provider sqlite --connection "Data Source=app.db"

builder.Services.AddDocumentDbMcpServer(mcp => { … }).WithHttpTransport();
app.MapDocumentDbMcp("/mcp").RequireAuthorization("mcp");

Point an MCP client at a store and let it explore. The tools are the same Extensions.AI tools — one implementation, one security model — plus resources (documentdb://types, .../schema, .../sample, documentdb://stats), two prompts, and an audit line per call.

Read-only by default, and writes need two locks: the per-type capability and AllowWrites(). Page caps, property hiding, no raw-SQL tool, no schema mutation. The stdio tool discovers what to expose from the stored TypeName discriminators, so it needs no compiled document classes at all, and it reads connections from the admin tool’s existing profile store.

AI scopes resolved per call

The non-removable per-type Where scope on the AI tools now has a form resolved on every call from the call’s own services — because “which rows may this caller see” almost always lives in a request-scoped service:

t.Where(o => o.TenantId == "acme")                                        // static, as before
 .Where<ITenantContext>((tenant, _) => o => o.TenantId == tenant.TenantId) // resolved per call
 .Where<IPermissionService>(async (perms, ctx) => …);                      // async form

It fails closed. A filter that throws, a service that won’t resolve, or a call with no services fails the tool call rather than running the query unscoped, and registration asserts at startup that each Where<TService> service is actually registered.

One block per document type

This is the breaking change to plan for. Every flat per-type mapping method is gone; the type is named once and its whole configuration reads top to bottom:

options.ConfigureDocument<Patient>(cfg =>
{
    cfg.Table = "Patients";
    cfg.MapIdProperty(x => x.Id);
    cfg.AddSoftDelete(x => x.IsDeleted);
    cfg.MapSpatialProperty(r => r.Location);
    cfg.MapProperty(x => x.Ssn, p => p.Encrypt(EncryptionMode.Deterministic));
    cfg.MapVectorProperty(d => d.Embedding, dimensions: 1536);
    cfg.MapTemporal(o => o.Retention = TimeSpan.FromDays(90));
});

MapTypeToTable / MapTypeToCollection / MapTypeToContainer / MapTypeToStore / MapTypeToPartition, MapIdProperty, MapVersionProperty, AddQueryFilter, AddSoftDelete, MapSpatialProperty, MapVectorProperty, MapFullTextProperty, MapComputedProperty, MapBlob, MapBlobCollection, MapTemporal, MapIndexedProperty, MapEncryptedProperty, MapJsonSchema, OnBeforeWrite and OnAfterWrite all move onto the builder. Store-level configuration is untouched.

The builder is written once against IDocumentStoreOptions, so every provider gets the same surface, and provider packages add their own vocabulary over it (cfg.ToContainer on Cosmos, cfg.ToCollection on MongoDB/LiteDB/Firestore, cfg.ToStore on IndexedDB, cfg.ToPartition and cfg.MapIndexedProperty on Azure Table/DynamoDB). There’s a full old→new table in Migrating v12 → v13.

Two things landed alongside it:

Validate-on-build. One configuration sweep when the store is constructed, reporting every problem together through a DocumentConfigurationException instead of one per restart. It catches features the backend doesn’t have (a vector mapping on LiteDB, cfg.Table on RavenDB) and randomized-encrypted properties used where the database has to read through them — a full-text index, a computed expression, a spatial or vector payload, the concurrency version. DocumentConfigurationValidator.Collect(options) returns the same list without throwing.

A model hook on DocumentContext, so a source-generated context can declare its model next to its [Document] list rather than inside AddDocumentStore:

[Document(typeof(Patient))]
public partial class AppContext : DocumentContext
{
    static partial void OnConfiguring(DocumentModelBuilder model)
        => model.Document<Patient>(cfg => cfg.MapTemporal(o => o.Retention = TimeSpan.FromDays(90)));
}

Query surface

Single-row terminals. First, FirstOrDefault, Single and SingleOrDefault, with predicate (First(x => x.Age == 40)) and string-grammar (First("status == 'open'")) overloads, on every provider.

They are not sugar over ToList(): the row limit reaches the provider, so a relational store emits LIMIT 1 and MongoDB/Cosmos page server-side rather than materializing every match to use the first. Single fetches two rows, so “more than one matched” costs no extra round trip.

ExecuteUpdate sets several properties at once:

await store.Query<Order>()
    .Where(o => o.Status == "open" && o.CreatedAt < cutoff)
    .ExecuteUpdate(b => b
        .Set(o => o.Status, "expired")
        .Set(o => o.ClosedAt, DateTimeOffset.UtcNow));

One statement, one predicate evaluation, atomic — where three separate calls were three statements with a window between them.

Raw JSON terminals end a typed query with JSON instead of T, so a document that only has to reach an HTTP response never becomes an object:

ctx.Response.ContentType = "application/json";
await store.Query<Order>().Where(o => o.Status == "open")
    .WriteJsonArrayTo(ctx.Response.Body, ct);

The whole typed builder still applies — Where, OrderBy, Paginate, query filters, soft delete, tenancy. OData and the AI query tool now read through this lane internally, which took an OData page from two passes per document to one. (There’s more on this in Hidden Gems.)

Multi-tenancy that survives deployment

AddMultiTenantDocumentStore got the hardening it needed: a bounded store cache (LRU + idle eviction, with lease-based deferred disposal so eviction can’t pull a store out from under a running request), an overload taking a built store so tenants can live on any provider, per-tenant initialization, and IDocumentSession / IDocumentSessionFactory wired to the current tenant — they weren’t registered at all before.

services.AddMultiTenantDocumentStore(
    tenantId => new MongoDbDocumentStore(MongoOptionsFor(tenantId)),   // any provider
    o =>
    {
        o.MaxCachedStores = 250;
        o.IdleTimeout = TimeSpan.FromMinutes(30);
        o.SeedFromRegisteredSeeders();      // startup seeders now run per tenant, on first touch
    });

There was also a genuinely nasty bug in here worth naming: the scoped IDocumentStore registration handed the cached store to the DI scope, and the container disposes any IDisposable a scoped factory returns — so a tenant’s shared store was disposed at the end of the first request that touched it. The cache now owns store lifetime and the scope owns a lease.

The consequence is a breaking one: with eviction in play, a captured IDocumentStore from a tenant-routed registration may become disposed while the process lives. Resolve it per scope, or opt out with IdleTimeout = null and MaxCachedStores = int.MaxValue.

Orleans: durable streams (13.2)

siloBuilder.AddDocumentDbStreams("Default", …);

Orleans clusters already use DocumentDb for membership, grain storage and reminders. Now they can use it for streams — no queue service to run, and a backlog you can actually look at when a queue won’t drain.

Two design points I’d defend in a code review:

Sequencing doesn’t use an identity column. Identity hands out values at insert time, but rows appear at commit time — so a late-committing transaction can be stepped over by the receiver’s watermark and its event never delivered. Instead each queue has a counter row whose position is reserved under a row lock inside the enqueue transaction, which makes assignment order and commit order the same order, and the sequence gap-free.

IsRewindable is true. A subscriber can resume from a StreamSequenceToken older than anything still in memory, because the cache replays the events table instead of reporting a cache miss. No queue-backed provider can do that — behind Azure Queue or SQS the message is gone once handed over.

IStreamAdmin reports per-queue depth, lag, retained history and which streams aren’t draining, and the admin tool gained a Streams screen. Backends: PostgreSQL, SQL Server, MySQL, MariaDB, Oracle, CockroachDB — gated at silo start by the new SupportsPessimisticLocking capability, not a hard-coded list. Expect thousands of events/sec on PostgreSQL; this is a database-backed queue, not Kafka.

Which brings up the other 13.2 fix: LockMode now takes a real row lock. It shipped validated but inert — the API demanded a transaction and then issued an ordinary read, so session.Get(id, LockMode.Update) blocked nothing anywhere. It now emits the engine’s own syntax: FOR UPDATE / FOR SHARE on PostgreSQL, MySQL and CockroachDB, LOCK IN SHARE MODE on MariaDB, WITH (UPDLOCK, HOLDLOCK) on SQL Server. Oracle throws for LockMode.Share rather than degrading to an unlocked read.

The admin tools

Two of these have never had a post, so here they are properly.

It reads an encrypted store — without a key

The admin tools shipped before encryption did, so they knew nothing about it. Now they read the envelope, describe it, and refuse to quietly destroy it, all with no key at all.

An enc:1:k1:… value renders as what it is rather than a wall of base64, with a show ciphertext toggle — because pasting a deterministic ciphertext into the filter console is the only predicate that can match one. The Structure tab reports the path’s type as encrypted, not string.

The Encryption card answers the one question RewrapAsync<T>() can’t: did it finish? It counts how many values sit under each key id, how many are still plaintext, and how many are under a key the sample never saw. Retiring a key early makes documents unreadable and nothing else tells you. Mode is reported as deterministic (observed) only when a repeated ciphertext proves it, and never as “randomized”, which is unprovable.

And there’s a downgrade guard on every write: saving a body where a path that held an envelope would go back as clear text throws, unless the caller explicitly allows it. The failure this prevents isn’t an exception — the library reads a non-envelope as pre-encryption plaintext — so it was previously a silent loss of protection.

There’s a terminal front end

Shipped in 12.5 and never blogged: ShinyDocDbMyAdmin.Tui, a dotnet tool that is the same tool as the web UI. Same connection store, same screens, no browser, works over SSH.

The column inference, the explorer tree, the filters — all the same, because both front ends are the same core with a different renderer.

Vectors, geometry, full-text, blobs, import/export, and the new outbox and streams screens are all there too. Full tour: the terminal UI docs.

And a Docker Desktop extension

docker extension install aritchie/shiny-docdb-myadmin-extension

Adds a tab that starts the admin container, waits for it, opens it — and hands it every database container already running on your machine, connected. PostgreSQL (including PostGIS, pgvector and TimescaleDB), MySQL, MariaDB, SQL Server, Oracle Free/XE and CockroachDB are discovered by image, with credentials taken from each container’s own environment. Addressing goes over the Docker network, so a database that never published a port still works.

Marketplace submissions are paused while Docker reviews Marketplace security, so for now you’ll need Settings → Extensions → “Allow only extensions distributed through the Docker Marketplace” turned off to install it. The image is also mirrored to Docker Hub as aritchie/shiny-docdb-myadmin alongside GHCR — one push, same digests, so the two can’t disagree about what a version contains.

VectorData connector

New package: Shiny.DocumentDb.Extensions.VectorData. Point the .NET AI ecosystem (MEAI, the Microsoft Agent Framework, Semantic Kernel) at a document store through MEVD’s VectorStore / VectorStoreCollection<TKey, TRecord>:

builder.Services.AddDocumentDbVectorStore(o =>
{
    o.DatabaseProvider = new SqliteDatabaseProvider("Data Source=app.db") { EnableVectorExtension = true };
    o.MapVectorRecord<Note>();      // reads [VectorStoreKey]/[VectorStoreVector]
});

var notes = sp.GetRequiredService<VectorStore>().GetCollection<string, Note>("Note");
await foreach (var hit in notes.SearchAsync(query, top: 5,
    new VectorSearchOptions<Note> { Filter = n => n.Tag == "release" })) { }

Every other MEVD connector is single-store. This one runs the same record model over any vector-capable DocumentDb backend — SQLite for dev and mobile, PostgreSQL/pgvector or SQL Server for production, Cosmos / Atlas / Redis — swapped by configuration. MEVD’s filter is already an Expression<Func<T, bool>>, so it goes to NearestVectors untouched and still pushes into the ANN search.

Breaking changes

ConfigureDocument<T> replaces every flat per-type mapping method. See Migrating v12 → v13.
Encrypted properties serialize as plaintext out of OData, the AI tools and GetDiff. Check exposed entity sets.
A document type carries one spatial / vector / full-text mapping. A second one used to silently replace the first; it now throws, naming both.
Tenant stores can be disposed while the process lives (idle/LRU eviction). Resolve per scope.
DocumentBulkContext.Assignment → Assignments (an ordered list, since a set-based update can carry several).
IDatabaseProvider.BuildJsonSetExpression() takes the source expression and parameter names, and IDocumentStoreOptions gained SerializerOptions / EnsureSerializerOptions(). Custom providers and options classes only; every in-box one is updated.

There’s also a smaller, quieter one in 13.2.1 that matters if you host DocumentDb over a transport: DocumentPredicate.Compile<T>, DocumentFilter.Parse<T> and DocumentStoreAccessor.GetMappings are now public, in Shiny.DocumentDb.Hosting. Hosts used to need an InternalsVisibleTo entry and a release here to go with it; now a host package can live in any repo. DocumentPredicate.Compile’s contract is that producing the delegate never uses Reflection.Emit — enforced by a Native AOT publish in CI, not a comment — so a host can check a scope against an incoming document on POST/PUT without forfeiting the trim guarantee of the app doing the hosting.

The full changelog is on the release notes page, and if you want the tour of the things that aren’t new but never got explained, that’s Hidden Gems.

Introducing Shiny.Net.HttpServer — HTTP/1.1, HTTP/2 & HTTP/3 Anywhere .NET Runs

Tue, 11 Aug 2026 00:00:00 GMT

ASP.NET Core is heavyweight and does not run on .NET MAUI, or in a number of embedded server scenarios. That is the gap this fills.

Shiny.Net.HttpServer is a dependency-light, AOT- and trim-clean HTTP/1.1, HTTP/2 and HTTP/3 server that runs anywhere .NET runs — plus tunnelling, so a server embedded in a phone app is reachable from the public internet. It is available today in beta.

var server = new HttpServer(new HttpServerOptions { Port = 8080 });
server.MapGet("/ping", ctx => ctx.Response.WriteAsync("pong"));
await server.RunAsync();

Only Microsoft.Extensions.* abstractions are taken as dependencies. Everything else — JSON, crypto, JWT, OpenAPI, HPACK, QPACK — is built on what is in the box. Every shipping project has the trim, AOT and single-file analyzers enabled, so “AOT-clean” is enforced by the build rather than claimed in a readme.

The packages

Package	Description
	The server: protocols, routing, middleware, DI scopes, static files, WebSockets, SSE, sessions, OpenAPI, CORS, rate limiting, IP filtering, tunnelling — plus the compile-time typed-endpoint generator
	JWT authentication on in-box crypto — no `Microsoft.IdentityModel` dependency
	SSH remote-forwarding tunnel provider, including zero-account quick tunnels
	Azure Relay tunnel provider
	Model Context Protocol (Streamable HTTP) transport — host an MCP server without ASP.NET Core
	gRPC and gRPC-Web — unary, client-, server- and bidirectional streaming. Marshalling is supplied, so nothing reflects over your messages
	A directory as an RFC 4918 class 1 & 2 WebDAV mount
	Shiny.Mediator requests, commands and streams as endpoints, bound at compile time
	A Shiny.DocumentDb document type as a complete HTTP resource

dotnet add package Shiny.Net.HttpServer

The typed-endpoint generator ships inside that package under analyzers/ — it runs inside the compiler and never lands in your output.

Four tiers, one app

Each tier is built on the one below, and they compose in the same server. Pick the altitude that suits the endpoint rather than the framework’s opinion.

Tier 0 — a single delegate. No routing at all.

server.OnRequest(async ctx => await ctx.Response.WriteAsync("hello"));

Tier 1 — routing. Templates with constraints, mutable at runtime.

server.MapGet("/api/users/{id:int}", async ctx => { /* … */ });

Tier 2 — middleware. ASP.NET-shaped.

server.UseAuthentication();
server.UseEmbeddedFiles(typeof(App).Assembly, "MyApp.wwwroot");

Tier 3 — source-generated typed endpoints. Constructor injection, typed parameter binding, and OpenAPI metadata, all emitted at compile time.

[Route("/api/users")]
public class UserEndpoints(IUserService users, ILogger<UserEndpoints> logger)
{
    [Get("/{id:int}")]
    public async Task<IActionResult> GetUser(int id, CancellationToken ct)
        => await users.FindAsync(id, ct) is { } u ? new OkObjectResult(u) : new NotFoundResult();
}

app.MapMyAppEndpoints();   // emitted for every [Route] class in the assembly

Results come in both spellings — Results.* and IActionResult.

What is in the box


Protocols	HTTP/1.1, HTTP/2 (own HPACK), HTTP/3 (own QPACK), WebSockets, SSE. Never guessed — ALPN over TLS, connection preface over cleartext
Content	Static files from disk or embedded resources, a published Blazor WASM app, streaming multipart uploads, byte ranges and conditional GETs, a file browser, and brotli/gzip/deflate
Security	Authentication and authorization split ASP.NET-style — Basic, API key, cookie and JWT schemes, policies, roles and claims, plus CORS, rate limiting and IP filtering
TLS	Per-endpoint TLS, self-signed certificates generated in managed code (iOS and Android included), client certificates, and SPKI pinning for your own `HttpClient`
OpenAPI	An OpenAPI 3.0.3 document built entirely from compile-time metadata and your `JsonSerializerContext` — no reflection, no document object model
Formats	Content negotiation both ways — responses from `Accept`, request bodies from `Content-Type`. JSON built in; XML, MessagePack and protobuf one line each
Tunnelling	A pluggable `ITunnelProvider`, the reference relay, SSH remote forwarding, quick tunnels, and Azure Relay
Lifecycle	Start, stop and restart at runtime, serialized and idempotent, with observable state

Route constraints cover byte, short, float, the temporal types and value bounds ({page:range(1,100)}), and a constraint decides whether a route matches rather than converting anything — so a refused segment is a 404 and one that matched but will not parse is a 400. Responses can also send trailing headers on all three protocol versions.

Reaching a device from the internet

A cellular device sits behind carrier-grade NAT with no routable address and no port to forward, and an agent-based tunnel like ngrok or cloudflared cannot run on iOS at all — there is no process to spawn. So tunnelling is built in, and every provider works the same way: the device opens an outbound connection and asks the far end to forward traffic back down it.

The zero-ceremony version needs no account and nothing installed:

builder.Services.AddHttpServer(autoStart: false, configureServer: s => s.MapGet("/", …));
builder.Services.AddQuickTunnel();

// then, from a button:
var url = await tunnel.StartAsync();

QuickTunnel is INotifyPropertyChanged with PublicUrl, State and LastError, so a view binds directly to it. Bind to PublicUrl rather than reading it once — a free tunnel assigns a new address on every reconnect, and a phone reconnects whenever it changes network. See SSH & Quick Tunnels for the host presets and what each one requires.

MCP without ASP.NET Core

The MCP SDK’s own HTTP transport is an ASP.NET Core package, which makes this the piece that genuinely could not be done any other way — an MCP server hosted inside a .NET MAUI app.

builder.Services
    .AddMcpServer(o => o.ServerInfo = new() { Name = "thermostat", Version = "1.0.0" })
    .WithTools<ThermostatTools>()
    .WithHttpTransport();

var app = builder.Build();
app.MapMcp();              // POST/GET/DELETE/OPTIONS on /mcp

One thing the compiler cannot check for you: a tool’s parameter and return types are published to the client as a JSON schema, and building that schema by reflection does not survive trimming. Tools that trade only in primitives need nothing extra — give the rest a source-generated context, and MapMcp() will name any type you missed at startup.

[JsonSerializable(typeof(Query))]
[JsonSerializable(typeof(IReadOnlyList<Reading>))]
public partial class ToolJson : JsonSerializerContext;

.WithTools<ThermostatTools>(ToolJson.Default.Options)

Full detail on MCP.

Formats beyond JSON

JSON is the default and covers most of an HTTP API. For the rest — an integration behind a corporate gateway that speaks XML, a battery-powered client that would rather not spend 40% more radio time on braces, a service already generating protobuf from a .proto — formats plug in on both sides. IOutputFormatter writes responses; IInputFormatter reads request bodies.

builder.Services.AddContentNegotiation(o =>
{
    o.NegotiateByDefault = true;   // Results.Ok(value) honours Accept
    o.AddXml();
    o.AddMessagePack();
});

That is the whole setup, and no endpoint changes. Request bodies are dispatched on Content-Type, so every existing [FromBody] parameter, mediator contract and hand-written handler accepts the registered formats immediately; responses are chosen from Accept.

XmlSerializer could not be used for the XML side at all — it builds its mapping by reflecting over the type at runtime, which is precisely what a trimmed or AOT-published app has thrown away. The same goes for MessagePack-CSharp’s default resolver. Instead both read the source-generated JsonTypeInfo your types already have, so:

No new dependency, and no [XmlRoot], [DataMember] or [MessagePackObject] on your DTOs.
A type gets an XML or MessagePack representation on exactly the same terms as JSON — its metadata was registered.
The representations cannot drift apart, because the property names and converters have one source.

Reading XML is type-directed for the same reason it has to be. XML has no types: <postalCode>01234</postalCode> is text, and only the target member knows whether that is a string, a number or an enum ordinal. Guessing from the text is how a postal code arrives as the number 1234.

Protobuf needs a schema, so its codecs are supplied rather than discovered — field numbers live in the .proto, and the only thing that has them is the code protoc already generated:

o.AddProtobuf(p => p.Add<Reading>(m => m.ToByteArray(), Reading.Parser.ParseFrom));

The same BinaryCodecRegistry carries CBOR, Avro, or MessagePack-CSharp’s native codec under whichever media type you register it as. One behaviour change to note: a body whose Content-Type nothing reads now answers 415 rather than 400 — the difference between sending a caller to fix a header and sending them hunting for a syntax error that is not there. Full detail on Serialization & Formats.

gRPC and gRPC-Web

gRPC runs over the same HTTP/2 stack as everything else, callable from Grpc.Net.Client, grpcurl or any gRPC client in any language — and therefore from a .NET MAUI app, where ASP.NET Core cannot run at all.

app.MapGrpcService("greet.Greeter", svc =>
{
    svc.AddMarshaller<HelloRequest>(m => m.ToByteArray(), HelloRequest.Parser.ParseFrom);
    svc.MapUnary<HelloRequest, HelloReply>("SayHello", (request, ctx) => …);
});

All four method shapes are supported, with streams as IAsyncEnumerable<T> in both directions flushed as each message is yielded, grpc-timeout arriving as the handler’s CancellationToken, per-message compression negotiated from grpc-accept-encoding, and status in trailers. MaxReceiveMessageSize is enforced on the decompressed size as well as the length prefix, since a few compressed kilobytes can otherwise expand into gigabytes.

gRPC-Web is enabled by default in both framings, which is how a browser calls in and how anything on HTTP/1.1 does. It matters more here than on a server: native gRPC needs a tunnel that forwards raw TCP, and most hosted providers terminate HTTP/1.1, so gRPC-Web is generally what reaches a device from the internet.

A directory as a mounted drive

The file browser is a JSON API you drive with curl. WebDAV is the protocol every desktop already has a client for.

app.MapWebDav("/dav", o =>
{
    o.RootPath = FileSystem.AppDataDirectory;
    o.AllowWrite = true;
})
.RequireAuthorization();

Point Finder or Windows Explorer at that URL and the app’s storage appears as a drive, with no client code at all. RFC 4918 compliance classes 1 and 2 — PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK/UNLOCK and the If header.

Class 2 is on by default and is not really optional: Finder and the Windows redirector both mount a class 1 server read-only whatever AllowWrite says. Writes and deletes are opt-in, and PROPFIND with Depth: infinity is refused by default rather than walking a device’s storage into one response — note that a missing Depth header means infinity per the specification, so it gets the same refusal.

Mediator and DocumentDb as endpoints

If you already write Shiny.Mediator handlers, they can be endpoints. It is the Shiny.Mediator.AspNet shape without ASP.NET Core:

[MediatorHttpGroup("/api/gadgets")]
public class GadgetHandlers : IRequestHandler<GetGadget, Gadget>
{
    [MediatorHttpGet("/{id:int}")]
    public Task<Gadget> Handle(GetGadget request, IMediatorContext ctx, CancellationToken ct) => …;
}

app.MapGeneratedMediatorEndpoints();

The binding is the part that had to change. The ASP.NET package uses [AsParameters]/[FromBody], which is reflection over a delegate’s parameters and annotated RequiresDynamicCode; here a source generator writes it out member by member at compile time, so a contract that cannot be bound is a build error rather than a 500. An ICommand answers with a status code and no body; an IStreamRequest<T> becomes a Server-Sent Events response.

And if the data lives in Shiny.DocumentDb, a document type is a complete resource in one line:

app.MapDocuments<Order>("/orders", o =>
{
    o.TypeInfo = AppJson.Default.Order;
    o.AllowFilterOn(x => x.Status, x => x.Total);
    o.Scope<ITenantContext>((tenant, _) => x => x.TenantId == tenant.TenantId);
})
.RequireAuthorization("orders");

List, by-id, count, create, replace, RFC 7396 merge-patch, delete and a live SSE tail, with filtering, cursor paging, sparse fieldsets and ETag/If-Match — plus a schema-free lane for JSON collections with no CLR type. It is a port of Shiny.DocumentDb.AspNetCore onto this server running the same engine, so filters, cursors, scopes and merge semantics are identical on both.

Two differences are deliberate. MapDocuments returns a builder that fans RequireAuthorization, CORS, rate limiting and IP filtering across every route it registered, because this server attaches metadata per route rather than per group — so adding an operation later cannot quietly leave one unprotected. And there is no reflection fallback when TypeInfo is unset, because a fallback that works on a desktop and throws on a trimmed phone is worse than a clear error in both places. Server-side scopes answer 404 rather than 403 for a document outside the scope. The package requires Shiny.DocumentDb 13.2.1 or newer.

Trade-offs worth knowing up front

Two packages are deliberately not AOT- or trim-clean, and they are separate packages for exactly that reason. Shiny.Net.HttpServer.Ssh carries SSH.NET, which brings BouncyCastle and its own algorithm registries. Shiny.Net.HttpServer.AzureRelay pulls in Azure.Identity, MSAL and IdentityModel. Reference either and you accept the weight; leave them out and the core server stays clean AOT.

The other seven are clean, the four newest included — which is much of why gRPC and protobuf ask for marshalling rather than discovering it, and why XML and MessagePack are written against your existing JSON metadata instead of a reflective serializer.

This is a beta. The API surface is settled and the test suite is substantial — around 1,260 tests, run against a live socket rather than an in-memory harness, since most of what a server can get wrong only exists at that boundary. But it has not yet been run in anger by a large number of people — issues and feedback are very welcome.

Finally, the security note that a tunnel makes urgent: a quick tunnel hands a public HTTPS address to anyone who learns it, pointed at a server whose defaults were chosen for loopback. Put authentication in front of it before you open one.

Getting started

Full documentation is at shinylib.net/httpserver, and the source — including a .NET MAUI sample that serves a page, exposes a file browser behind a password, hosts an MCP server and publishes the lot through a tunnel — is at github.com/shinyorg/httpserver.

Shiny.DocumentDb v12 — Doing All The Things!

Mon, 27 Jul 2026 00:00:00 GMT

v12 landed as three releases in three days, and between them they cover an unusually wide spread — a whole new web UI, a new schema-free write/query lane, two new extensibility primitives, a full trim/AOT pass, and the largest internal refactor the library has had.

ShinyDocDbMyAdmin — a phpMyAdmin-style web front end for any relational DocumentDb store, shipped as a container image.
AddDocumentDbAdmin — that UI modelled as an Aspire resource, already connected to every store you reference.
Schema-free JSON collections — store.Collection("orders"). No CLR type, no mapping, no migration.
ctx.Cancel() — interceptors can now replace a write instead of only observing it.
Soft delete — AddSoftDelete<Customer>(x => x.IsDeleted), built entirely out of the two public primitives above.
A shared provider surface — DocumentQueryBase<T>, IDocumentStoreOptions, and a shared write pipeline. ~4,300 lines of duplicated provider code deleted, and four real bugs fell out of the conformance suites that replaced them.
Trim/AOT clean, and verified — every shipping package builds warning-free and declares IsAotCompatible, checked by a real PublishAot run in CI.

The full changelog is on the release notes page. This post walks the headliners, and closes with a summary of everything else DocumentDb does plus the package list.

ShinyDocDbMyAdmin

The schema-free model has always had one rough edge: when something looks wrong in production, there is no shape to inspect. SELECT Data FROM documents gives you a wall of minified JSON, and every SQL engine has a different set of JSON functions to dig into it.

ShinyDocDbMyAdmin is the answer — a phpMyAdmin-style web UI for DocumentDb stores. No user management, no server administration, no query planner. Just the documents.

docker run -p 8085:8080 -v shiny-docdb-myadmin:/data ghcr.io/shinyorg/shiny-docdb-myadmin

It’s a container image and nothing else — there’s deliberately no dotnet tool form, because packaging the native provider binaries for every RID it might run on came out at ~120 MB to deliver what one image delivers for the platform you’re actually on.

Browse

The grid’s columns are inferred by sampling documents, so nested paths like customer.tier become first-class columns instead of hiding inside a JSON blob. Filter on any envelope column or JSON path, or quick-search the string fields.

Numeric filters and sorts compare numerically, which is not free on a schema-free store — the plain JSON extract returns text on most engines, so an unhinted sort would put "100" before "9".

Any row expands into a read-only, syntax-highlighted view of the whole body, with objects and arrays collapsible — native <details> elements, so it still works with scripting off.

Structure

The inferred shape of a type: every path, its type, how often it is actually present, an example value, and one-click create/drop of a JSON property index — named exactly as DocumentDb names its own, so an index you create here is the same index CreateIndexAsync would have made.

Because the store is schema-free this describes what the sampled documents contain, not a contract. A field below 100% is simply absent from some documents — which is frequently the bug you came to find.

History

If the type is mapped with MapTemporal<T>, a History tab appears. Pick a document, pick any two versions, and get a field-by-field diff by dotted path — or the two bodies side by side. Any prior version can be restored behind a two-click confirm.

Writes made in the UI to a temporal-mapped type record a version too, stamped with the actor shiny-docdb-myadmin. That isn’t optional politeness: the admin layer writes SQL directly — it sits below IDocumentStore because it has no CLR type to bind to — so none of the library’s temporal tracking runs on its own. Without that, an edit here would change the row while the history sidecar went on insisting the old body was current, and a quietly wrong audit trail is worse than no History tab at all.

Geometry

Types that store GeoJSON get a map — server-rendered SVG, zoom-to-feature and fit-all, with vertices, length, area, centroid and OGC validity per document.

It reads from the document body, not the {table}_spatial sidecar. The sidecar holds only bounding boxes for index pruning and its shape differs per provider; the GeoJSON in Data is the actual value and is identical everywhere. So the map works on every provider — including the ones with no spatial support at all.

SQL console

Whatever you want to type, in the target database’s own dialect, with @name parameters bound from a JSON box so the types stay honest — 450 binds a number, "450" binds text. There is no statement allow-list, so give the tool a database account with the privileges you actually want it to have.

Plus

Edit (JSON editor with format + validation, insert/duplicate/bulk delete), Blobs (payload listing that never selects the blob column, with inline preview and streamed downloads), Import / Export (JSON, NDJSON, CSV, or round-trippable envelope JSON), and Create for a documents table or a type, so a database whose store has never run isn’t a dead end.

Supported on every relational backend: SQLite, SQLCipher, DuckDB, PostgreSQL, SQL Server, MySQL, MariaDB, Oracle 23ai+ and CockroachDB. The document stores are out of scope — the tool works against the shared Id / TypeName / Data / CreatedAt / UpdatedAt envelope over ADO.NET.

It’s an Aspire resource too

You shouldn’t have to remember a docker run line. Shiny.DocumentDb.Aspire.Hosting models the tool as a resource, so it comes up with the rest of your app and every store you reference is already connected:

var store = builder.AddPostgresDocumentStore("orders");

builder.AddDocumentDbAdmin(port: 8085)
       .WithReference(store)
       .WithDataVolume()                                  // keep saved connections across runs
       .WithHostPath("/Users/me/databases", "/databases") // reach a file-backed store
       .WithSecretKey(builder.AddParameter("admin-key", secret: true))
       .WithReadOnly()
       .WaitFor(store);

WithReference is the same call a consuming service makes — the tool reads the ConnectionStrings:{name} + Shiny:DocumentDb:{name}:Provider pair the hosting integration already emits, so a Redis or blob reference in the same AppHost is ignored rather than turning into a junk connection. Referenced stores show up under a from host badge and can’t be edited or deleted from the UI; they’re declared in the AppHost, so that’s where they change.

The image tag defaults to the hosting package’s own version, so an integration upgrade brings the matching UI with it.

Schema-free JSON collections

Not every document has a CLR type. Generic HTTP intake, message-bus payloads, ETL landing zones, multi-tenant “extra fields” — the shape is decided by whoever sent it.

var orders = store.Collection("orders");

var id  = await orders.Insert(jsonObject);   // returns the stored id
var doc = await orders.Get(id);              // JsonObject?

var rows = await orders.Query()
    .Where("customer.name == 'bob' and total:number > 100")
    .OrderBy("total:number desc")
    .Paginate(0, 50)
    .ToList();                               // IReadOnlyList<JsonObject>

No CLR type, no registered mapping, no migration. The collection name becomes the row’s TypeName, so a schema-free collection shares a table with your typed documents without either seeing the other, and needs zero schema change.

Querying is the string grammar only — there’s no T to write a lambda against — lowered to the same IR and the same SQL as Query<T>().Where("…"). Since no metadata says what a field is, the type is inferred as the expression is built: from an explicit path:type hint, else from the other operand (total > 100 is numeric), else from the function (lower(name) is a string), else string. You need a hint wherever nothing else pins the type — an OrderBy, a min/max, a numeric Project — because on every provider whose plain JSON extract returns text, OrderBy("total") sorts lexicographically.

Ids default to the id property, read case-insensitively and written verbatim; an absent id generates a sortable UUIDv7 string and stamps it into your object.

The same object serves the type-keyed lane — store.Collection(typeof(Order)) — where field paths resolve through the document type’s metadata (naming policies, [JsonPropertyName], leaf types), the body still rides the full write pipeline (tenancy, temporal, versioning/CAS, spatial + vector sidecars, interceptors, change notifications), and the full function set is available including hasflag, the geo predicates and the Lucene functions. That lane gained a fluent query builder and Remove/BatchRemove/ Clear, which it never had.

Relational providers only; everything else throws NotSupportedException, and the tier is pinned by a test per provider.

Interceptors can replace a write

BeforeWrite could previously do exactly two things: mutate the document, or throw. Throwing aborts the write and the surrounding unit, so an interceptor could never change the shape of an operation — turn a delete into an update, route a write somewhere else, swallow one entirely.

Now it can:

public class ArchiveOnDelete : IDocumentInterceptor
{
    public async Task BeforeWrite(DocumentWriteContext ctx, CancellationToken ct)
    {
        if (ctx.Operation == DocumentOperation.Remove && ctx.Document is Invoice inv)
        {
            inv.Archived = true;
            await ctx.Store.Update(inv, ct);   // transaction-bound — commits with the original unit
            ctx.Cancel();                      // "I performed this write myself"
        }
    }
}

Cancel() means the store issues no write for the operation: no AfterWrite, no change notification, no temporal history entry, and later interceptors in the chain are skipped. The caller still gets a normal result — Cancel(false) makes Remove return false, and the bulk form’s Cancel(n) makes ExecuteDelete/ExecuteUpdate/Clear return n. DocumentBulkContext also gained QueryAs<T>(), the originating query with the same predicate and filters, so a set-based write can be re-issued differently.

Supported on every provider.

Soft delete in the box

Which is the whole point of the previous section — soft delete is now shipped, and it’s built out of nothing but public parts:

services.AddDocumentStore(o => o
    .AddSoftDelete<Customer>(x => x.IsDeleted)
);

await store.Remove(customer);                              // sets the flag
await store.Query<Customer>().ToList();                    // flagged documents are invisible
await store.Query<Customer>().IncludeDeleted().ToList();   // read past it
await store.Query<Customer>().OnlyDeleted().ToList();      // just the flagged ones

Remove, query.ExecuteDelete() and Clear<T>() all set the flag instead of deleting. The flag is a bool, or a nullable DateTime/DateTimeOffset stamped from a DI-registered TimeProvider. It comes with SoftDelete<T>(id), Restore<T>(predicate), PurgeDeleted<T>(predicate?), HardDelete<T>(id), and SuppressInterceptors() for a raw write.

It is not built into the stores. It’s a named query filter (soft-delete) plus a cancelling interceptor, composed from the two public building blocks and shipped as an extension method — which means you can write your own variant the same way. A pleasant side effect: because a set-based delete is re-issued as an update over the same query, the spatial/vector/blob sidecar rows stay with the document instead of being orphaned.

One surface, seventeen providers

The least visible change is the biggest. The nine non-relational IDocumentQuery<T> implementations were 70–88% identical — the same builder state, the same client-side terminals, the same interceptor plumbing, retyped per provider. Every document provider’s Insert/Update/Upsert/Remove opened with the same preamble and closed with the same tail, nine times over. That’s why v11.4’s ctx.Cancel() needed 45 hand-edited guards.

v12 collapses all of it:

DocumentQueryBase<T> — providers supply a Clone, an ExecuteAsync(QueryPlan<T>), and two set-based write primitives. Push-down stays explicit: ExecuteAsync returns a QueryExecution<T> declaring how much of the plan the engine satisfied (Complete for MongoDB/Cosmos, Candidates for the key-value stores, Partial in between) and the base applies only the remainder client-side.
IDocumentStoreOptions — a three-method interface (AddInterceptor/AddBulkInterceptor/ AddQueryFilter) implemented by every options class, so a cross-cutting feature is written once. AddSoftDelete<T> collapsed from ten files to one, and MapJsonSchema went from relational-only to every provider for free.
A shared single-document write pipeline on DocumentProviderBase. Persistence, conflict handling and id generation stay per provider — Redis SET NX, Cosmos ETag, DynamoDB conditional writes, Azure Table 409 genuinely differ.

~4,300 lines of duplicated provider code deleted, and DocumentQueryBase<T> is public, so an out-of-repo provider implements four members instead of ~450 lines.

The safety net is a pair of cross-provider conformance suites that assert the IDocumentQuery<T> contract, soft delete, and interceptor cancellation identically on all 17 providers. They found four real bugs on their first run:

Bools in a predicate were broken on MySQL, MariaDB and SQL Server. A bool JSON value was extracted as the text 'true'/'false' and compared against 1/0, so Where(x => x.IsActive) — or any bool query filter, including soft delete’s — failed with Truncated incorrect DOUBLE value: 'false'. SQL Server had its own flavour: BIT is a value, not a condition.
Cosmos ExecuteUpdate 404’d, because the narrowed SELECT c.id, c.data projection dropped typeName — the partition key — before writing back.
Cosmos SetProperty/RemoveProperty ignored global query filters, so a soft-deleted document could still be updated by id.
SetProperty with a date/Guid wrote malformed JSON on the providers that build the value as a JSON literal — an unquoted invariant ToString() that json_set rejected outright.

Every one of those was a real defect that had shipped. That’s the argument for the refactor.

Query builders are immutable everywhere now. Where/OrderBy/Paginate/IgnoreQueryFilters on the relational store used to mutate in place and return the same instance; every document provider has always returned a copy. Both return a copy now — so a builder call used as a statement silently loses its clause. The compiler can’t flag it, so sweep for it:

q.Where(x => !x.IsDeleted);        // ← discarded
q = q.Where(x => !x.IsDeleted);    // ← correct on every provider

Also: composing a query after Select(...)/Project(...) now throws NotSupportedException on the relational providers too, where it used to throw InvalidOperationException.

Trim and AOT, verified

v12.1 was a dedicated pass. The whole src/ tree now builds with zero IL2026/IL2075/IL2090/IL3050 warnings, and packages carry IsAotCompatible — which stamps [AssemblyMetadata("IsTrimmable","True")]. Previously no package declared it, so a consumer’s trimmer kept these assemblies whole instead of trimming into them. The handful whose dependencies rule AOT out declare IsAotCompatible=false honestly rather than silently.

The mapping APIs (MapVersionProperty, MapSpatialProperty, MapVectorProperty, MapFullTextProperty, MapComputedProperty, MapBlob, MapBlobCollection) now declare [DynamicallyAccessedMembers(PublicProperties)] on T, so the properties they resolve by name are actually preserved. Passing a concrete type needs no change; code that forwards its own unannotated generic parameter into them will get IL2091 and should propagate the annotation.

And it’s checked, not assumed: samples/Sample.Aot publishes with PublishAot=true, exercises every mapping kind and query surface once, treats any trim/AOT warning as a build error, and CI publishes and runs it. The Roslyn analyzers can’t see warnings coming out of dependencies or code reachable only through a call graph — a real ILC run can.

Everything else DocumentDb does

If you’re new here, the pitch is one sentence: turn any database into a schema-free JSON document store with LINQ querying, no CREATE TABLE, no migrations, and one API across 19 backends.

Providers — SQLite, SQLCipher, LiteDB, IndexedDB (Blazor WASM), DuckDB, PostgreSQL, CockroachDB, SQL Server, MySQL, MariaDB, Oracle, Cosmos DB, MongoDB, Amazon DocumentDB, Azure Table Storage, DynamoDB, Redis, RavenDB, Google Firestore.

Area	What you get
CRUD	Insert/Update/Upsert/Remove over whole object graphs; RFC 7396 merge-patch vs replace as a flag; `SetProperty`/`RemoveProperty` for surgical field updates; `GetDiff` returning an RFC 6902 patch; batch writes as one set operation
Querying	Fluent LINQ over nested properties, `Any()`, string methods, captured variables; `IAsyncEnumerable` streaming; ordering, pagination and keyset cursors; a string-expression grammar (`Where("…")`) with full parity; Lucene-syntax queries
Projections & aggregates	SQL-level `.Select()` into DTOs; `Max`/`Min`/`Sum`/`Average` terminals; `GroupBy`/`Having` pushed down to real SQL `GROUP BY`
Indexes	Expression-based JSON indexes (up to 30× faster), composite multi-column indexes, computed properties as alias or materialized generated columns
Spatial	Full OGC `Geometry` model, topological predicates (`GeoIntersects`, `GeoWithin`, …), real 2-D indexes on every SQL provider plus Cosmos `ST_*` and Mongo `2dsphere`
Vector	`MapVectorProperty` + `NearestVectors(query, k)` on pgvector, SQL Server 2025 `VECTOR`, Oracle 23ai, Cosmos DiskANN, Mongo Atlas `$vectorSearch`, DuckDB `vss`, `sqlite-vec`; `AutoEmbedOnInsert` via `IEmbeddingGenerator`
Full-text	`MapFullTextProperty` + relevance-ranked `FullTextSearch<T>` on FTS5, `tsvector`+GIN, MySQL `FULLTEXT`, Oracle Text, SQL Server FTS, DuckDB `fts`, Cosmos, Mongo `$text`
Temporal	`MapTemporal<T>` append-only versioning with `History`/`AsOf`/`Restore`/`GetDiffBetween`/`ChangesByActor`, on every provider
Blobs	`DocumentBlob` sidecar storage, loaded on demand, so reads and the change feed never drag the bytes along
Interceptors & filters	Per-document and set-based write hooks running inside the transaction; EF-style global query filters with named `IgnoreQueryFilters`
Change monitoring	`IAsyncEnumerable<DocumentChange<T>>`, per-query `.NotifyOnChange()`, plus native change feeds on PostgreSQL `LISTEN`/`NOTIFY`, SQL Server Change Tracking and Cosmos Change Feed
Context	EF-Core-style typed `DocumentContext` + `DocumentSet<T>`, source-generated from `[Document]` attributes
Backup	Streaming export/import/restore with native bulk-copy fast paths (`COPY`, `SqlBulkCopy`, DuckDB appender); hot file backup on SQLite/SQLCipher/LiteDB
Multi-tenancy	Shared-table `TenantId` filtering or tenant-per-database, resolved via `ITenantResolver`; consumer code unchanged
Concurrency	`MapVersionProperty` optimistic concurrency, ETag/conditional CAS, `OpenSession()` unit of work with explicit transactions and lock modes
Orleans	Grain storage, reminders, cluster membership and grain directory — with grain state queryable without activating grains
AI tools	`Microsoft.Extensions.AI` tool functions per document type, capability-gated, with non-removable per-type filter scopes
OData	`$filter`/`$orderby`/`$top`/`$skip`/`$count`/`$select` onto the fluent query, with per-entity-set governance
Data sync	Offline-first bidirectional sync to an HTTP backend via `Shiny.Data.Sync`
Diagnostics	Always-on OpenTelemetry metrics and `ActivitySource` spans, zero-cost when nobody’s listening
Validation	JSON Schema (draft 2020-12) enforced just before the write
Geo reference data	Embedded US/CA states, provinces and cities that seed straight into any store
Aspire	Provider as a deployment decision, keyed stores with health checks + OTel, and the admin UI as a resource

Packages

Package
`Shiny.DocumentDb`
`Shiny.DocumentDb.Sqlite`
`Shiny.DocumentDb.Sqlite.SqlCipher`
`Shiny.DocumentDb.Sqlite.VectorSupport`
`Shiny.DocumentDb.PostgreSql`
`Shiny.DocumentDb.CockroachDb`
`Shiny.DocumentDb.SqlServer`
`Shiny.DocumentDb.MySql`
`Shiny.DocumentDb.MariaDb`
`Shiny.DocumentDb.Oracle`
`Shiny.DocumentDb.DuckDb`
`Shiny.DocumentDb.LiteDb`
`Shiny.DocumentDb.IndexedDb`
`Shiny.DocumentDb.MongoDb`
`Shiny.DocumentDb.CosmosDb`
`Shiny.DocumentDb.DocumentDb`
`Shiny.DocumentDb.AzureTable`
`Shiny.DocumentDb.DynamoDb`
`Shiny.DocumentDb.Redis`
`Shiny.DocumentDb.RavenDb`
`Shiny.DocumentDb.Firestore`
`Shiny.DocumentDb.Geo`
`Shiny.DocumentDb.JsonSchema`
`Shiny.DocumentDb.Extensions.AI`
`Shiny.DocumentDb.OData`
`Shiny.DocumentDb.AspNetCore.OData`
`Shiny.DocumentDb.AppDataSync`
`Shiny.DocumentDb.Orleans`
`Shiny.DocumentDb.Orleans.MongoDb`
`Shiny.DocumentDb.Orleans.CosmosDb`
`Shiny.DocumentDb.Aspire.Hosting`
`Shiny.DocumentDb.Aspire.Client`
`Shiny.DocumentDb.Aspire.Orleans`

The admin UI isn’t a package — it’s ghcr.io/shinyorg/shiny-docdb-myadmin.

Give Your MAUI Agent Hands — Contacts, Reminders & Location AI Tools

Mon, 06 Jul 2026 00:00:00 GMT

When we shipped Shiny.Health.Extensions.AI, it proved a simple point: a chat model becomes far more useful when it can do things instead of just talk about them. Give it a tool to read step counts and “how did I sleep last week?” stops being a guess and starts being an answer pulled from the device.

So we did the same for three more device services. Three new packages expose Shiny modules as Microsoft.Extensions.AI tool functions:

Shiny.Contacts.Extensions.AI — search and manage the device address book
Shiny.Notifications.Extensions.AI — schedule and cancel reminders
Shiny.Locations.Extensions.AI — read-only GPS: where you are, and how far/long to somewhere else

They all follow the same shape as Health: you opt-in to exactly which operations the model can see (a read/write allow-list you control on behalf of the agent — not an OS permission prompt), it’s read-only by default, and the whole thing is IsAotCompatible — schemas are hand-built and results come back as JsonNode, so there’s no reflection in the tool path.

Contacts

dotnet add package Shiny.Contacts.Extensions.AI

builder.Services.AddContactStore();
builder.Services.AddContactsAITools(tools => tools
    .AddContacts(ContactAICapabilities.ReadWrite)   // Read is the default; ReadWrite adds create/update/delete
);

This generates search_contacts, get_contact, and — when you opt-in to Write — create_contact, update_contact, and delete_contact.

What you’d use it for: a personal-assistant or CRM-lite app where the user talks to the address book instead of tapping through it — “grab that number so I can text them,” “add the person on this business card,” “which of my contacts work at Acme?” The agent looks up an id with search_contacts, then acts on it.

Example questions:

“What’s Jane Doe’s mobile number?”
“Add a contact for my new dentist — Dr. Patel at Bright Smiles Dental, 555-0142.”
“Change my brother Mike’s email to mike@newjob.com.”
“Do I have anyone saved from Acme Corp?”
“Delete the contact for my old landlord.” (destructive — tell the model to confirm first)

Reminders

dotnet add package Shiny.Notifications.Extensions.AI

builder.Services.AddNotifications();
builder.Services.AddNotificationAITools(tools => tools
    .AddReminders(ReminderAICapabilities.ReadWrite, channel: "reminders")   // channel is optional
);

Local notifications, framed as reminders. You get list_reminders, and — with Write — create_reminder (fire now, at a specific date/time, or daily at a set time) and cancel_reminder.

What you’d use it for: any “remind me…” flow in a chat assistant — todo apps, habit and medication trackers, follow-up nudges. The user speaks a reminder in natural language and the model schedules a real local notification; scheduleFor and repeatDailyAt cover one-shot and recurring.

Example questions:

“Remind me to call the plumber at 3pm today.”
“Set a daily reminder to take my meds at 8:30am.”
“What reminders do I have set?”
“Cancel the one about the dentist.”
“Nudge me to water the plants every evening at 6.”

Location

dotnet add package Shiny.Locations.Extensions.AI

builder.Services.AddGps();
builder.Services.AddLocationAITool();   // read-only — there's no write capability for GPS

GPS is read-only, so there’s no builder to configure — a single AddLocationAITool() registers get_current_location, get_distance_to, and estimate_travel_time. The agent can learn where the user is and reason about distance and rough travel time to a destination.

What you’d use it for: travel and field-service apps, delivery/ETA estimates, “am I near…” checks, or any assistant that should be location-aware. One honest caveat baked into the tools: distances are great-circle (straight-line) and travel times use an assumed average speed — the results say so in a note field, so the model caveats its answer rather than pretending to be a routing engine.

Example questions:

“Where am I right now?”
“How far is it from here to 51.4700, -0.4543?”
“Roughly how long to cycle to the park at 51.51, -0.12?”
“Am I within 2 km of the office?”
“What’s my current speed and heading?”

Compose them into one agent

Each package hands you a small bundle you resolve from DI. Concatenate their .Tools and pass the lot to any IChatClient:

var tools = new List<AITool>();
tools.AddRange(sp.GetRequiredService<ContactAITools>().Tools);
tools.AddRange(sp.GetRequiredService<NotificationAITools>().Tools);
tools.AddRange(sp.GetRequiredService<LocationAITools>().Tools);

var response = await chatClient.GetResponseAsync(
    messages,
    new ChatOptions { Tools = tools }
);

Now a single message can fan out across all three:

“I’m meeting Sarah at the office at 5 — how far am I, and remind me to leave in an hour.”

The model calls search_contacts for Sarah if it needs her details, get_distance_to for the office, and create_reminder for the nudge — one turn, three device services.

Permissions still belong to your app

The capability builders (AddContacts(...), AddReminders(...)) are an allow-list for the agent — they decide which operations the model can see. They are not an OS permission prompt. The underlying platform permission must already be granted: call IContactStore.RequestAccess, INotificationManager.RequestAccess, or start a GPS listener from your app before you invoke the agent. The tools assume access is in place and return a clean error object if it isn’t.

Get started

dotnet add package Shiny.Contacts.Extensions.AI
dotnet add package Shiny.Notifications.Extensions.AI
dotnet add package Shiny.Locations.Extensions.AI

Full details on each: Contacts AI Tools, Reminder AI Tools, and Location AI Tools. Same pattern as Health AI Tools — opt-in, read-only by default, AOT-safe, and now your agent has hands.

A NEW CameraView to Rule Them All

Mon, 15 Jun 2026 00:00:00 GMT

A camera control sounds simple until you ship one. You want live preview, zoom, torch, lens selection, photo and video capture — fine. Then you want to scan a barcode, box a face, read a receipt, parse a driver’s license, apply a live filter, and have it all run on iOS, Android, Windows, macOS AppKit, and Blazor WebAssembly without rewriting the pipeline five times.

That’s what CameraView is: one control, one API surface, every platform — with a pluggable frame-analysis pipeline bolted on.

dotnet add package Shiny.Maui.Controls.Camera

builder
    .UseShinyControls()
    .UseShinyCamera();

xmlns:cam="http://shiny.net/maui/camera"

<cam:CameraView x:Name="Camera"
                Facing="Back"
                ScaleMode="AspectFill"
                Filter="None" />

The preview auto-starts (IsActive defaults true) and the control requests camera permission itself — you handle a denial (or any error) through CameraError, and toggle IsActive for lifecycle:

this.Camera.CameraError += (_, e) => status = e.Message;   // e.g. "Camera permission denied"

protected override void OnDisappearing()
{
    base.OnDisappearing();
    this.Camera.IsActive = false;   // release the camera off-screen
}

// JPEG bytes — the current Filter is baked in, so the photo matches the preview
CameraPhoto photo = await this.Camera.CapturePhotoAsync();

// Video (audio optional). Recorded video records the raw, unfiltered feed.
await this.Camera.StartVideoRecordingAsync(new VideoRecordingOptions { IncludeAudio = true });
CameraVideo video = await this.Camera.StopVideoRecordingAsync();   // a file path you can stream

Provider reach

The same CameraView lights up on five hosts, each over the platform’s native stack:

Host	Backend
Apple (iOS / Mac Catalyst)	AVFoundation
macOS (AppKit)	AVFoundation over AppKit
Android	CameraX (min SDK 23)
Windows	Media Capture
Blazor WebAssembly	`getUserMedia` / `MediaRecorder` / `BarcodeDetector`

Facing picks a lens by position (Back / Front / External); CameraId pins an exact device — which is how you choose between multiple back lenses on a phone or a specific USB webcam on macOS:

IReadOnlyList<CameraInfo> cameras = await this.Camera.GetAvailableCamerasAsync();
this.Camera.CameraId = cameras.First(c => c.Name.Contains("USB")).Id;

Live color filters

Set Filter and the look is applied to the live preview and baked into captured photos, so what you see is what you get:

this.Camera.Filter = CameraFilter.Noir;

Eleven filters ship — Mono, Noir, Sepia, Invert, Vivid, Cool, Warm, Fade, Chrome, Instant, Tonal — plus None. A couple of honest platform caveats: recorded video records the unfiltered feed, the Android live-preview filter needs API 31+ (it uses RenderEffect; captured photos are still filtered on older Android), and Windows has no live filter.

Frame analysis — the differentiator

This is where CameraView stops being “a camera” and becomes a platform. Assign an IFrameAnalyzer to Camera.Analyzer and the pipeline streams frames off the UI thread with drop-on-busy back-pressure (only one frame in flight — it never backs up). It’s one analyzer at a time, and you set or swap it freely while the camera is running.

Every analyzer has two channels:

A strongly-typed event carrying the semantic result (the barcodes, the faces, the recognized text, the structured document).
The return value of its analysis: styled OverlayBoxes to draw. A returned set persists until the analyzer returns a different set (replace) or null (clear).

The boxes draw live the whole time the analyzer runs; the typed event is gated on a scan. The analyzer stays quiet until you arm it — Camera.Scan(), or bind a shutter button / Fab to Camera.ScanCommand — and then it delivers its next confirmed detection exactly once. Single-shot is the default, which is usually what you want (“point, tap, get the code”). To keep scanning, give the analyzer an OnDetected handler that returns true:

var barcode = new BarcodeAnalyzer();                 // native — Apple Vision (iOS/macOS) / Android MLKit
barcode.BarcodesDetected += (_, e) =>
    status = $"{e.First.Format}: {e.First.Value}";    // e.Barcodes holds every code in the frame
Camera.Analyzer = barcode;

Camera.Scan();                                        // arm — deliver the next decode, once

// continuous: stay armed as long as the handler returns true
barcode.OnDetected = async e => { await Save(e.First.Value); return true; };

Swapping the analyzer is just an assignment — the running session picks it up:

Camera.Analyzer = new FaceAnalyzer();                 // Apple Vision / Android MLKit / Windows.FaceAnalysis
Camera.Analyzer = new MotionAnalyzer();               // pure-managed frame differencing — every platform

Events are marshalled to the UI thread for you, so handlers can touch UI directly.

To switch the analyzer off without dropping it (keeping its bindings and internal state), set FrameAnalyzer.IsEnabled = false — it resumes instantly when re-enabled, and while disabled the camera behaves as if it had no analyzer (so on Android you can record video). That’s distinct from ShowBoundingBox = false (run and deliver, just draw nothing).

MVVM: declare the analyzer in XAML, bind commands

Analyzers are BindableObjects, and CameraView’s content property is Analyzer, so you can declare it inline under the one cam: prefix and bind its …Command to your ViewModel — fired on the UI thread with the same args as the event. Bind a shutter button to the camera’s ScanCommand to arm it:

<Grid>
    <cam:CameraView x:Name="Camera" Facing="Back" Filter="Chrome">
        <cam:BarcodeAnalyzer BarcodesDetectedCommand="{Binding ScanResultCommand}" />
    </cam:CameraView>
    <Button Text="Scan"
            Command="{Binding Source={x:Reference Camera}, Path=ScanCommand}"
            VerticalOptions="End" />
</Grid>

Bounding boxes for free

Drop a CameraOverlayView over the CameraView in the same Grid cell — it auto-subscribes and redraws:

<Grid>
    <cam:CameraView x:Name="Camera" ScaleMode="AspectFill" />
    <cam:CameraOverlayView Camera="{x:Reference Camera}" InputTransparent="True" />
</Grid>

OverlayBox.Rect is normalized (0..1), upright, and mirror-corrected — the overlay maps it into view space, so you never deal in raw pixels. Set the analyzer’s ScanWindow to a normalized rectangle to restrict detection to a band: only detections centered inside it are reported and drawn, and the overlay dims everything outside it and frames a viewfinder reticle. Want custom styling? Each analyzer exposes an OverlayProvider to return exactly the boxes you want (or null for none):

barcode.OverlayProvider = e => e.First.Value.StartsWith("OK")
    ? [ new OverlayBox(e.First.BoundingBox, Colors.Lime, e.First.Value) ]
    : null;

MotionAnalyzer is a nice example of the pipeline’s range: it clusters movement into separate regions, so motion in two spots yields two boxes rather than one box spanning both — handy for a security-cam view. Tune it with PixelThreshold / AreaThreshold, SampleStride, and GridColumns / CellThreshold.

Document analyzers — structured data, not just text

The Shiny.Maui.Controls.Camera.Documents package turns the camera into a scanner that hands you strongly-typed records, not raw strings. Every document type is its own analyzer with its own typed DocumentDetected event, and every payload is a record with nullable fields — only what was actually found is set. Like every analyzer, delivery is arm-gated, so call Camera.Scan() (or bind ScanCommand) to capture the next read.

dotnet add package Shiny.Maui.Controls.Camera.Documents

var invoice = new InvoiceAnalyzer();
invoice.DocumentDetected += (_, e) =>
{
    Invoice doc = e.Document;
    status = $"Invoice {doc.Number} — total {doc.Total}, {doc.Lines.Count} line(s)";
};
Camera.Analyzer = invoice;
Camera.Scan();                                        // arm — delivers the next parsed invoice

var license = new DriversLicenseAnalyzer();           // PDF417 + AAMVA — deterministic, no ML
license.DocumentDetected += (_, e) =>
    status = $"{e.Document.FirstName} {e.Document.LastName} — {e.Document.Number}";

What ships:

InvoiceAnalyzer → Invoice with order lines in .Lines.
ReceiptAnalyzer → Receipt with purchased line items (.Lines), a per-tax breakdown (.Taxes), and subtotal / tip / discount / total, plus best-effort payment method, last-4, currency, date/time.
DriversLicenseAnalyzer → DriversLicense, decoded from the PDF417 barcode on the back and parsed against the AAMVA standard — fully deterministic. Works for US states and the Canadian provinces that emit an AAMVA PDF417 (BC, AB, SK, MB, NS, NB, PEI, NL); dates auto-switch to Canadian CCYYMMDD order and the province surfaces as Jurisdiction. (Ontario and Quebec licences carry no PDF417, so they don’t scan — use a custom OCR parser for those.)
HealthCardAnalyzer → HealthCard, OCR tuned for Canadian cards: it detects the issuing province from on-card keywords and applies that province’s number format — Quebec/RAMQ, Ontario/OHIP, BC PHN, Alberta/AHCIP, etc. — surfacing Province and Issuer.
CreditCardAnalyzer → CreditCard: brand (Visa/Mastercard/Amex/…) and number validity from the IIN prefix + Luhn are deterministic; name/expiry are best-effort OCR. The CVV lives on the back, so a front scan almost always leaves it null.
PassportAnalyzer → Passport, parsed from the MRZ (the two <<< lines, ICAO TD3) — deterministic.

The deterministic ones (driver’s license PDF417/AAMVA, passport MRZ, credit-card IIN/Luhn) are exactly that — no ML guesswork. The rule-based ones (invoice, receipt, health card) are best-effort, and when you need more accuracy you swap in your own parser without writing a new analyzer:

new InvoiceAnalyzer(new MyInvoiceParser());   // MyInvoiceParser : IDocumentParser<Invoice>

A document analyzer accumulates reads across a few frames before it commits (AccumulationFrames, default 5) — handy when one frame catches half the card and the next catches the rest — and resets after a run of empty frames (ResetAfterEmptyFrames).

Roll your own document type

Need to scan something we don’t ship — a business card, a shipping label, a lab form? Derive from DocumentAnalyzer<TDocument> and supply an IDocumentParser<TDocument>. The base class runs the shared OCR recognizer, calls your parser, raises the typed event (and command) on the UI thread, draws the boxes, and honours arming / IsEnabled / ShowBoundingBox / OverlayProvider. You write the payload and the parse rules — nothing else:

public record BusinessCard(string? Name, string? Company, string? Email, string? Phone, IReadOnlyList<DocumentField> Fields);

public sealed partial class BusinessCardParser : IDocumentParser<BusinessCard>
{
    [GeneratedRegex(@"[\w.+-]+@[\w-]+\.[\w.-]+")] private static partial Regex Email();

    public bool TryParse(IReadOnlyList<RecognizedText> text, out BusinessCard document, out IReadOnlyList<OverlayBox> boxes)
    {
        document = null!; boxes = [];
        var emailLine = text.FirstOrDefault(t => Email().IsMatch(t.Text));
        if (emailLine is null) return false;   // cheap "is this my document?" check — bail fast

        var email  = Email().Match(emailLine.Text).Value;
        var name   = text.FirstOrDefault()?.Text;
        var fields = new List<DocumentField> { new("Name", name, text.FirstOrDefault()?.BoundingBox), new("Email", email, emailLine.BoundingBox) };
        document = new BusinessCard(name, null, email, null, fields);
        boxes = fields.Where(f => f.Bounds is not null).Select(f => new OverlayBox(f.Bounds!.Value, Colors.Lime, f.Label)).ToList();
        return true;
    }
}

public sealed class BusinessCardAnalyzer : DocumentAnalyzer<BusinessCard>
{
    public BusinessCardAnalyzer() : base(new BusinessCardParser()) { }
    public override string Id => "myapp.camera.businesscard";
}

Because the parser is just an interface, an LLM- or service-backed parser is perfectly fine — the analyzer drops frames while one parse is in flight, so a slow remote call won’t pile up.

The analyzer line-up

Analyzer	Package	Engine	Platforms
`BarcodeAnalyzer`	`.Camera.Barcode`	Apple Vision / Android MLKit (native)	iOS, Android, macOS
`FaceAnalyzer`	`.Camera.Face`	Vision / MLKit / Windows.FaceAnalysis	iOS, Android, Windows, macOS
`MotionAnalyzer`	`.Camera.Motion`	managed frame differencing	all
`OcrAnalyzer`	`.Camera.Ocr`	native OCR (Vision / MLKit / Windows.Media.Ocr)	iOS, Android, Windows, macOS
Document analyzers	`.Camera.Documents`	OCR + rules / native PDF417 / MRZ	iOS, Android, Windows, macOS

Add only the packages you need. MotionAnalyzer is pure-managed and runs everywhere; the barcode / face / OCR / document analyzers ride native ML/vision, so they produce results on the device platforms (not bare net10.0) — barcode and the PDF417-based driver’s license are iOS / macOS / Android.

Blazor

The Blazor component mirrors the MAUI control with the same concepts in component clothing — including the single Analyzer and the arm-to-scan model:

<CameraView @ref="camera"
            Facing="CameraFacing.Back"
            Analyzer="barcode"
            ShowOverlay="true"
            Filter="filter"
            BarcodesDetected="OnBarcodes"
            OnError="m => status = m"
            Style="width:100%;height:100%;" />

@code {
    CameraView? camera;
    readonly BarcodeAnalyzer barcode = new();
    CameraFilter filter = CameraFilter.None;

    // await the next code (the gated equivalent of MAUI's Scan)
    async Task Scan()  { var b = await camera!.RequestBarcodeAsync(); status = $"{b.Format}: {b.Value}"; }
    void OnBarcodes(IReadOnlyList<CameraBarcode> codes) => status = $"{codes[0].Format}: {codes[0].Value}";

    async Task Photo() { var jpeg = await camera!.CapturePhotoAsync(); }          // byte[], filtered to match preview
    async Task Rec()   { await camera!.StartRecordingAsync(includeAudio: true); }
    async Task Stop()  { var webm = await camera!.StopRecordingAsync(); }         // byte[] WebM
}

Preview, zoom, filters (CSS), photo, and video capture work in every browser. Barcode scanning uses the browser’s native BarcodeDetector (Chromium today): assign a BarcodeAnalyzer and await RequestBarcodeAsync() for the next code, or handle BarcodesDetected for every code in a frame while a request is outstanding. On Firefox/Safari OnError fires once and preview continues, so feature-detect if you need universal coverage. Face/motion/OCR/document analyzers are MAUI-native.

A few things to know

Permissions are yours to declare — NSCameraUsageDescription on Apple (omitting it crashes iOS instantly), the CAMERA permission on Android, the webcam capability on Windows. getUserMedia needs a secure context (HTTPS or localhost).
Android: video vs. analyzers — CameraX caps concurrent use-cases, so the camera binds either image analysis (while an analyzer is enabled) or video capture. Clear Analyzer or set IsEnabled = false to record; StartVideoRecordingAsync throws a clear error otherwise.
Don’t gate startup on RequestPermissionAsync() — it routes through the handler and returns false before the view is connected (e.g. in OnAppearing on first show), which looks like a denial. Rely on auto-start + CameraError.

Grab the packages, call .UseShinyCamera(), and you’ve got a real camera — preview to structured documents — on every platform you ship to. Full docs are in the CameraView guide.

Shiny Health 2.0 — The Ultimate Cross-Platform Health Library

Mon, 15 Jun 2026 00:00:00 GMT

Reading health data on .NET MAUI means two completely different worlds: Apple HealthKit with its HKQuantityType/HKCategoryType/HKCorrelation zoo, and Android Health Connect with its Kotlin record types, coroutine APIs, and per-record permissions. Shiny Health collapses both behind a single IHealthService — and 2.0 is a big one: 30+ cross-platform data types, dedicated records for the non-numeric stuff, and a new package that turns your health data into tools an LLM can call.

This is our first proper write-up of the library, so let’s cover the whole thing.

One Interface, Two Platforms

dotnet add package Shiny.Health

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder().UseMauiApp<App>().UseShiny();
    builder.Services.AddHealthIntegration();
    return builder.Build();
}

Inject IHealthService, request permissions, and query. Everything is async, cancellation-aware, and AOT-friendly (no reflection — the Android side bridges Kotlin coroutines through a hand-rolled IContinuation).

public class DashboardViewModel(IHealthService health)
{
    public async Task LoadAsync()
    {
        await health.RequestPermissions(DataType.StepCount, DataType.HeartRate, DataType.Calories);

        var end = DateTimeOffset.Now;
        var start = end.AddDays(-1);

        var steps = (await health.GetStepCounts(start, end, Interval.Hours)).Sum(x => x.Value);
        var hr = (await health.GetAverageHeartRate(start, end, Interval.Hours)).Average(x => x.Value);
        var kcal = (await health.GetCalories(start, end, Interval.Days)).Sum(x => x.Value);
    }
}

Numeric metrics are time-bucketed: you pick Interval.Minutes, Hours, or Days and get one result per bucket. Cumulative metrics (steps, calories, distance, hydration, sleep) you .Sum(); point-in-time metrics (heart rate, weight, body fat) you .Average().

30+ Data Types

2.0 expanded the catalog dramatically. Numeric metrics — each with its own Get… method and full read/write/observe support:

Activity — step count, distance, active & basal energy, floors climbed, wheelchair pushes, speed, power
Heart — average heart rate, resting heart rate, heart rate variability
Body — weight, height, body fat %, lean body mass
Vitals — blood pressure, oxygen saturation, blood glucose, body temperature, basal body temperature, respiratory rate, VO2 max
Lifestyle — sleep duration, hydration

Blood pressure is special — it carries two values, so it gets its own result type:

var bp = await health.GetBloodPressure(start, end, Interval.Days); // BloodPressureResult
var avgSystolic = bp.Average(x => x.Systolic);   // mmHg
var avgDiastolic = bp.Average(x => x.Diastolic);

Reproductive & Cycle Tracking

These are categorical and event-based — no Interval bucketing, each with a dedicated record:

await health.RequestPermissions(DataType.MenstruationFlow, DataType.OvulationTest);

var flow = await health.GetMenstruationFlow(start, end);     // MenstrualFlow: None/Light/Medium/Heavy
var ovulation = await health.GetOvulationTests(start, end);  // Positive/Negative/High/Inconclusive
var mucus = await health.GetCervicalMucus(start, end);       // Dry/Sticky/Creamy/Watery/EggWhite
var activity = await health.GetSexualActivity(start, end);   // Protected/Unprotected
var spotting = await health.GetIntermenstrualBleeding(start, end);

// logging
await health.Write(new MenstruationFlowResult(DateTimeOffset.Now, DateTimeOffset.Now, MenstrualFlow.Medium, IsCycleStart: true));

Workouts & Nutrition

var workouts = await health.GetWorkouts(start, end);
foreach (var w in workouts)
    Console.WriteLine($"{w.Workout}: {w.TotalEnergyKilocalories} kcal over {w.End - w.Start}");

await health.Write(new WorkoutResult(start, end, WorkoutType.Running, TotalEnergyKilocalories: 420, TotalDistanceMeters: 7500));

await health.Write(new NutritionResult(
    DateTimeOffset.Now, DateTimeOffset.Now,
    Meal: MealType.Lunch, Name: "Chicken & rice",
    EnergyKilocalories: 550, ProteinGrams: 40, CarbohydratesGrams: 60, TotalFatGrams: 12
));

WorkoutType maps 21 activities that exist on both platforms (running, cycling, swimming, strength training, HIIT, yoga…); anything unmapped reads back as Other.

Writing Data

Every numeric metric writes through NumericHealthResult — pass the DataType and value in its documented unit:

await health.RequestPermissions(PermissionType.Write, DataType.Weight, DataType.Hydration);

await health.Write(new NumericHealthResult(DataType.Weight, DateTimeOffset.Now, DateTimeOffset.Now, 75.0));   // kg
await health.Write(new NumericHealthResult(DataType.Hydration, start, end, 0.5));                              // liters
await health.Write(new BloodPressureResult(DateTimeOffset.Now, DateTimeOffset.Now, 120, 80));                  // mmHg

Permissions are granular: PermissionType.Read, Write, or ReadWrite, requestable uniformly or per-metric in a single call.

Real-Time Observation

Observe streams new samples as they’re recorded via IAsyncEnumerable<HealthResult> — push-based HKAnchoredObjectQuery on iOS, Health Connect change-token polling on Android (interval configurable):

using var cts = new CancellationTokenSource();
await foreach (var result in health.Observe(DataType.HeartRate, cancelToken: cts.Token))
{
    if (result is NumericHealthResult n)
        Console.WriteLine($"❤️ {n.Value} bpm at {n.Start:T}");
}

New in 2.0: AI Tools

This is the headline feature. Shiny.Health.Extensions.AI exposes IHealthService as Microsoft.Extensions.AI tool functions, so an LLM agent can answer “How did I sleep last week?” or “Log a 45-minute run” by calling your health store directly.

It uses a small set of parameterized tools — one get_health_metric tool covers all numeric metrics via a metric enum argument, instead of 25 separate tools — which keeps the model’s tool list short and its selection accurate. Read-only by default; write is opt-in per area.

dotnet add package Shiny.Health.Extensions.AI

builder.Services.AddHealthIntegration();
builder.Services.AddHealthAITools(tools => tools
    .AddAllMetrics()                                          // read every numeric metric
    .AddMetric(DataType.Weight, HealthAICapabilities.ReadWrite)
    .AddBloodPressure(HealthAICapabilities.ReadWrite)
    .AddCycleTracking()
    .AddWorkouts(HealthAICapabilities.ReadWrite)
    .AddNutrition()
);

// hand the tools to any IChatClient
var tools = sp.GetRequiredService<HealthAITools>().Tools;
var response = await chatClient.GetResponseAsync(messages, new ChatOptions { Tools = [.. tools] });

Only the areas you opt-in to are visible to the model, and enum arguments are constrained to exactly what you allowed. The whole thing is IsAotCompatible — schemas are hand-built and results are emitted as JsonNode, so there’s no reflection in the tool path. Full details on the AI Tools page.

Honest About the Platforms

A unified API shouldn’t pretend the platforms are identical. Where they differ, we document it rather than hide it:

Heart rate variability is SDNN on iOS and RMSSD on Android — both milliseconds, but different computations, so don’t compare the numbers across platforms.
Speed/Power are generic on Health Connect; HealthKit has no generic equivalents, so Speed maps to walking speed and Power to cycling power.
A WorkoutResult’s energy/distance are null on Android read — Health Connect stores those as separate records from the exercise session.
MenstrualFlow.None and the IsCycleStart flag are iOS-only.

See Platform Notes for the full list.

Get Started

dotnet add package Shiny.Health
dotnet add package Shiny.Health.Extensions.AI   # optional — for LLM agents

Then head to Reading Data, Writing Data, and AI Tools. One interface, both platforms, 30+ metrics, and now an agent that can read and write them for you.

Orleans on DocumentDb — Query Your Grains Without Waking Them Up

Sat, 13 Jun 2026 00:00:00 GMT

Microsoft Orleans is fantastic at the runtime — virtual actors, automatic placement, transparent activation. But the persistence story has always been a patchwork: a separate provider package per backend, grain state serialized into an opaque blob you can’t query, and no first-party option at all for some databases (looking at you, MongoDB).

Shiny.DocumentDb.Orleans replaces that patchwork with a single idea: build the whole Orleans persistence stack on top of Shiny.DocumentDb’s backend-agnostic IDocumentStore. One set of implementations runs on every DocumentDb backend, grain state is persisted as structured, queryable JSON, and you get capabilities Orleans’ built-in providers simply can’t offer.

dotnet add package Shiny.DocumentDb.Orleans

The headline win: query grain state without activating grains

Orleans grain storage is a point key/value contract — Read/Write/Clear by grain id, with no query surface. Want to know “which shopping carts have a total over $1000?” Normally you can’t ask the store that question at all. You’d have to activate each grain — a silo round-trip that places the grain, deserializes its state, and runs OnActivateAsync — and the first-party providers store state as an opaque serialized blob, so querying the database directly is off the table too.

Because this provider stores each grain’s state as structured JSON in an ordinary table (under $.state), you can run the normal document query API straight against the grain-state table — no grains activated, no silo involved:

// A read-only store pointed at the same database + grain-state table.
var opts = new DocumentStoreOptions
{
    DatabaseProvider      = new PostgreSqlDatabaseProvider(connectionString),
    JsonSerializerOptions = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
};
DocumentDbGrainStorage.ConfigureGrainState(opts, "orleans_default");
var readStore = new DocumentStore(opts);

// Every ShoppingCart grain whose persisted total exceeds 1000 — without activating one.
var bigCarts = await readStore.Query<GrainStateRecord>(
    "json_extract(Data, '$.state.total') > @min",
    parameters: new { min = 1000 });

This unlocks reporting, dashboards, admin/ops tooling, analytics, and bulk inspection — all the things that are painful-to-impossible when your only door into grain state is activating the grain.

One honest caveat: these queries see the last persisted state. An activated grain may hold newer in-memory state it hasn’t flushed yet, and the queries take no grain locks. Treat it as an eventually-consistent read model — perfect for reporting, not a substitute for calling the grain when you need authoritative live state.

A free audit trail for every grain

Grain state is a GrainStateRecord document like any other, so it can opt into DocumentDb’s temporal history. One line gives you a full, queryable audit trail of every mutation — who changed what, and when:

opts.MapTemporal<GrainStateRecord>(t => t.MaxVersions = 100);

// later:
var history = await temporalStore.History<GrainStateRecord>("cart|user-42");

No event sourcing to design, no extra infrastructure to stand up. The version history rides along on the same store.

The whole stack, not just grain storage

Grain storage is the marquee feature, but it’s only a quarter of the package. The same IDocumentStore foundation backs the entire Orleans persistence stack, each with its own silo-builder extension:

siloBuilder
    .AddDocumentDbGrainStorage("Default", o => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbReminders(o      => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbClustering(o     => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs))
    .AddDocumentDbGrainDirectory("Default", o => o.DatabaseProvider = new PostgreSqlDatabaseProvider(cs));

Reminders (IReminderTable) — each reminder is a queryable document; the hash-ring range reads Orleans needs become a fluent query on the stored GrainHash. No multi-document transaction required, so it runs on any backend.
Clustering (IMembershipTable) — per-silo rows and the global table-version row are updated together inside a RunInTransaction, each gated on its own version, honoring Orleans’ table-version protocol.
Grain directory (IGrainDirectory) — a distributed activation registry with per-row version CAS for register/unregister races; again, no cross-document transaction needed.

Instead of stitching together separate provider packages with different conventions, it’s one storage abstraction for the lot.

Backend-agnostic — and it fills a real gap

Because the runtime binds only to IDocumentStore, the same code path serves every backend. Relational providers are built in; MongoDB and Cosmos get first-class companion packages:

Shiny.DocumentDb.Orleans.MongoDb

siloBuilder.AddMongoDbGrainStorage("Default", connectionString, databaseName: "orleans");

// Shiny.DocumentDb.Orleans.CosmosDb
siloBuilder.AddCosmosDbGrainStorage("Default", connectionString, databaseName: "orleans");

There is no first-party Orleans MongoDB provider — so this genuinely fills a gap. And switching from PostgreSQL to SQL Server to MongoDB doesn’t mean rewriting your persistence layer; it means swapping a provider line.

Concurrency that’s actually correct

Orleans’ ETag is the contract that keeps two activations from clobbering each other during a failover window. This provider maps the ETag to the document version and honors it with each backend’s atomic compare-and-swap:

Orleans	Shiny.DocumentDb
document key	`Id = "{stateName}\|{grainId}"`
ETag	`GrainStateRecord.Version` (via `MapVersionProperty`)
concurrency conflict	`ConcurrencyException` → `InconsistentStateException`
state blob	nested `JsonElement` (stays queryable, not opaque)

The relational providers fold the version check into UPDATE … WHERE and verify the row count, MongoDB uses an atomic version-predicate filter, and Cosmos uses a native IfMatchEtag. A stale write loses the race and surfaces as an InconsistentStateException — exactly what Orleans expects, even during a duplicate-activation window. The PostgreSQL and MongoDB paths (including the stale-write CAS conflict) are covered by automated integration tests.

Reflection-free serialization when you want it

The provider’s own envelope types — grain-state record, reminders, membership, grain-directory rows — are always source-generated. The one generic piece is your grain state T. Point a JsonSerializerContext at it and grain-state serialization goes reflection-free too:

[JsonSerializable(typeof(CartState))]
[JsonSerializable(typeof(UserPrefs))]
public partial class GrainStateContext : JsonSerializerContext;

siloBuilder.AddDocumentDbGrainStorage("Default", o =>
{
    o.DatabaseProvider      = new PostgreSqlDatabaseProvider(cs);
    o.JsonSerializerOptions = new JsonSerializerOptions { TypeInfoResolver = GrainStateContext.Default };
    o.UseReflectionFallback = false;   // throw on an unregistered state type instead of reflecting
});

It’s purely opt-in — leave the defaults and you keep the familiar reflection-based behavior.

Know your backend

Not every database is equal for every job. The compatibility tiers are worth a glance before you go to production:

Tier	Backends	Notes
Recommended	PostgreSQL, SQL Server, MySQL, Oracle	Atomic CAS folded into `UPDATE … WHERE`; ETag honored across failover windows.
Supported	MongoDB	Good key distribution; atomic CAS via version-predicate filter.
Limited / dev	SQLite, LiteDB, IndexedDB, DuckDB	Single-writer / embedded / analytical — fine for dev, single-silo, or edge.
Use with care	Cosmos DB	CAS is correct, but it partitions by grain type — weigh the 20 GB / hot-partition tradeoff before large-scale use.

Two limits to keep in mind: membership/clustering needs real multi-document transactions, so it runs on the relational providers or a MongoDB replica set — not Cosmos (grain storage, reminders, and grain directory have no such requirement). And the silo host itself isn’t an AOT target — serialization can be reflection-free, but Microsoft.Orleans.Runtime is codegen-heavy, so a fully AOT-published silo isn’t a goal here.

Get started

dotnet add package Shiny.DocumentDb.Orleans

# optional companions
dotnet add package Shiny.DocumentDb.Orleans.MongoDb
dotnet add package Shiny.DocumentDb.Orleans.CosmosDb

Full setup, the options reference, and the query-without-activation walkthrough are in the Orleans Provider docs. If you’re already on Shiny.DocumentDb, your grains are one siloBuilder call away from a store you can actually query.

Shiny.Data.Sync — Offline-First Record Sync, Built on Jobs & HTTP Transfers

Sat, 13 Jun 2026 00:00:00 GMT

Shiny already had two answers for “do work when the app isn’t in the foreground”:

Shiny Jobs runs periodic background tasks — WorkManager on Android, BGTaskScheduler on iOS, an in-process timer everywhere else.
Shiny.Net.Http moves files in the background — NSURLSession on iOS, a foreground service on Android, a connectivity-driven HttpClient loop elsewhere.

There was a gap in the middle: records. Not a 40 MB video, not a timer that fires every hour — the dozen Create / Update / Delete operations a user generates offline that need to reach a REST API reliably, survive an app kill, and come back with the server’s changes.

Shiny.Data.Sync fills that gap. The important part of this post isn’t “here’s a new library” — it’s that Data Sync deliberately doesn’t reinvent background execution. It rides the exact same OS playbook Jobs and HTTP Transfers already proved out.

Three libraries, one background playbook

iOS and Android take cross-platform “background” promises away from you. Shiny’s answer has always been to match what each OS actually allows rather than pretend a single mechanism works everywhere. All three libraries land on the same per-platform tiers:

Platform	Jobs	HTTP Transfers	Data Sync
iOS / Mac Catalyst	BGTaskScheduler	Background `NSURLSession`	Background `NSURLSession` (upload + download tasks)
Android	WorkManager	Foreground service + `HttpClient`	Foreground service + `HttpClient`
Windows / Linux / macOS	In-process timer	`HttpClient` + connectivity loop	`HttpClient` + connectivity loop
Blazor WASM	In-process (tab alive)	Service Worker Background Sync	`HttpClient` + `LocalStorage` (tab alive)

If you’ve shipped a background download with Shiny.Net.Http, you already understand Data Sync’s runtime model — because it’s the same model. The library description says it outright: where transfers move files, sync moves records, and the two deliberately share their playbook, because the OS guarantees are the same.

How Data Sync uses Jobs

You don’t wire up a background pull yourself. AddDataSync<TDelegate> registers a SyncJob with the Shiny Jobs scheduler for you:

// This is effectively what AddDataSync does under the hood — no AddJob call required:
services.AddJob<SyncJob>(r => r.WithInternet(InternetAccess.Any));

That means periodic inbox pulls keep happening on whatever background cadence the OS allows — WorkManager on Android, BGTaskScheduler on iOS — using the same IJobManager you’d use for any other Shiny job. The job respects each endpoint’s MinPullInterval so it doesn’t hammer your server, and because it’s a normal job you can turn it off through the normal job API when your pulls are push-triggered instead:

var jobs = host.Services.GetRequiredService<IJobManager>();
await jobs.Cancel(nameof(Shiny.Data.Sync.SyncJob));

This is the win of building on Jobs rather than beside it: the scheduler, the runtime criteria (WithInternet, charging, battery), and the platform background hooks are already solved. Data Sync just registers a job and inherits all of it.

How Data Sync mirrors HTTP Transfers

The architectural heart of Shiny.Net.Http is a persistent queue drained by a platform-tiered transport. A transfer is written to disk before any network call, so a process kill mid-transfer leaves the work intact and the next launch (or the OS itself, on iOS) resumes it.

Data Sync uses the identical pattern for its outbox:

public class TodosService(IDataSyncManager sync)
{
    public Task Create(TodoItem item) => sync.Queue(SyncVerb.Create, item);
    public Task Update(TodoItem item) => sync.Queue(SyncVerb.Update, item);
    public Task Delete(TodoItem item) => sync.Queue(SyncVerb.Delete, item);
}

Queue<T> writes a durable SyncOperation to the Shiny repository before touching the network, then returns immediately — the caller never blocks on the round-trip. From there it’s pure HTTP Transfers thinking:

On iOS / Mac Catalyst, queued ops drive NSURLSession upload tasks. Even if Shiny’s in-process queue dies, the OS keeps its own queue and drives the upload to completion, waking the app to dispatch the result — exactly how background file uploads survive suspension.
On Android, ops drain inside a foreground service that spawns on Queue<T> and dies when the queue empties — the same foreground-service contract transfers use to stay alive while work is pending.
On Windows / Linux / macOS / Blazor, an in-process HttpClient loop drains the queue, woken by IConnectivity.Changed, app startup, and Queue<T> itself — the same connectivity loop that drives transfers off-Apple.

Attempts and NextAttemptAt are persisted alongside each op, so even the exponential-backoff window survives a restart. None of that is new machinery — it’s the transfers playbook applied to records.

Where it goes beyond a file transfer is the second direction: an inbox that pulls server deltas keyed by an opaque cursor, draining pages until the server says hasMore: false. A file transfer is one-way; a record sync is two-way, so Data Sync adds the inbox, tombstone streams, conflict resolution, and an operation coalescer on top of the shared foundation.

Setup, end to end

// 1. Entity — one property
public record TodoItem(string Identifier, string Title, bool Completed) : ISyncEntity;

// 2. AOT-safe JSON, once per app
[ShinyJsonContext]
[JsonSerializable(typeof(TodoItem))]
public partial class AppJsonContext : JsonSerializerContext;

// 3. Register — picks the transport for the TFM AND auto-registers SyncJob
builder.Services.AddDataSync<MyDataSyncDelegate>(opts =>
{
    opts.RegisterEndpoint<TodoItem>("https://api.example.com/todos", ep =>
    {
        ep.Direction = SyncDirection.Both;            // PullOnly / PushOnly also valid
        ep.Batch = true;                              // coalesce redundant ops per round-trip
        ep.MinPullInterval = TimeSpan.FromMinutes(5); // throttle the scheduled SyncJob
        ep.MaxAttempts = 8;
        ep.DefaultConflictPolicy = ConflictPolicy.ServerWins;
    });
});

Your one IDataSyncDelegate is the integration seam — OnSent, OnError, OnReceived, OnConflict. Received items arrive already deserialized and strongly typed; you apply them to whatever local store you like (Data Sync is a transport, not a database — pair it with DocumentDB inside OnReceived if you want local query).

So which one do I reach for?

This is the question the three libraries answer together:

You need to…	Use	Why
Run a periodic background task (cleanup, refresh, telemetry flush)	Jobs	A scheduler with runtime criteria. No queue, no HTTP shape.
Move a large file up or down, resumable, in the background	HTTP Transfers	Range-aware resume for multi-megabyte blobs. One-way.
Reliably push record CRUD and pull deltas, offline-first	Data Sync	Persistent outbox + cursor inbox, drain-on-reconnect, conflict handling.

They compose rather than compete. A real offline-first app often uses all three: Jobs for the periodic housekeeping, HTTP Transfers for the user’s photo attachments, and Data Sync for the records those photos belong to — every one of them riding the same NSURLSession / foreground-service / connectivity-loop tiering under the hood.

And the boundary is explicit. Data Sync’s own docs tell you when to step out of it: large blobs go to HTTP Transfers, realtime streams go to SignalR or Push, and a client-of-record backup is a file push, not a sync. Moving records — Create / Update / Delete queued on failure, drained on reconnect, pulled back as deltas — is the lane it’s built for.

Get started

dotnet add package Shiny.Data.Sync

Data Sync — Getting Started
Architecture — why outbox + inbox, why platform-tiered transports
Platform Behavior — what survives an app kill, and the Info.plist / manifest bits
Jobs and HTTP Transfers — the two libraries it builds on

If you already know how Shiny runs work in the background, you already know how Data Sync runs. It just moves records.

Shiny.DocumentDb v6 — Vectors, Filters, Composite Indexes & Real Pooling

Mon, 01 Jun 2026 00:00:00 GMT

Shiny.DocumentDb v6 is out. Same one-line services.AddDocumentStore(...), same zero-schema document model, same AOT story — but the v6 release lands five features that have been on the wish list since v3:

Vector / ANN search that translates to the native engine on every provider (pgvector, SQL Server 2025 VECTOR_DISTANCE, Cosmos DiskANN, Mongo Atlas $vectorSearch, DuckDB vss, sqlite-vec).
Global query filters — AddQueryFilter<T>(u => !u.IsDeleted) and they apply to every read, single-doc fetch, bulk operation, and change-stream subscription. Same shape as EF Core’s HasQueryFilter.
Composite (multi-column) JSON indexes — CreateIndexAsync<T>(ctx.User, u => u.LastName, u => u.FirstName) on every relational provider.
Real connection pooling on server SQL — PostgreSQL, MySQL, and SQL Server stop serializing through a per-store semaphore and start using the ADO.NET driver’s pool. One DocumentStore instance can now actually serve a web app.
Per-query change monitoring — .NotifyOnChange() on any fluent query, filtered by the query’s Where predicates.

The full changelog is on the release notes page. This post walks through the headliners.

Vector / ANN Search

Embedding-search has been the most requested feature since the AI tools shipped in v4. v6 closes that gap.

public class Document
{
    public Guid Id { get; set; }
    public string Content { get; set; } = "";
    public ReadOnlyMemory<float> Embedding { get; set; }
}

var store = new DocumentStore(new DocumentStoreOptions
{
    DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db")
    {
        EnableVectorExtension = true   // loads sqlite-vec on every connection
    }
}.MapVectorProperty<Document>(
    d => d.Embedding,
    dimensions: 1536,
    metric: VectorDistance.Cosine,
    indexKind: VectorIndexKind.Hnsw));

var hits = await store.Query<Document>()
    .Where(d => d.Content.Contains("invoice"))   // pre-filter where supported
    .NearestVectors(queryEmbedding, k: 10);

foreach (var hit in hits)
    Console.WriteLine($"{hit.Score:F4}  {hit.Document.Content}");

The vector type is ReadOnlyMemory<float> everywhere — same shape as Microsoft.Extensions.AI.Embedding<float>.Vector, JSON-round-trips through System.Text.Json without a custom converter, and avoids an float[] allocation on every read.

Provider matrix

Provider	Storage	Index	Filter
PostgreSQL	`pgvector` sidecar	HNSW, IVF	Pre-filter via JOIN
SQL Server 2025	Native `VECTOR(n)` sidecar	DiskANN	Pre-filter via JOIN
Cosmos DB	Embedded in document JSON	DiskANN, QuantizedFlat, Flat	`WHERE` + `ORDER BY VectorDistance(...)`
MongoDB (Atlas)	`$vectorSearch` aggregation	HNSW (Atlas-managed)	Filter inside `$vectorSearch`
DuckDB	`vss` sidecar	HNSW	Pre-filter via JOIN
SQLite	`sqlite-vec` virtual table	None (flat scan)	Post-filter join back
MySQL / LiteDB / IndexedDB	—	—	Throws `NotSupportedException`

Cosine / Euclidean / DotProduct are available everywhere; Hamming is pgvector-only. Cosine distance is always surfaced as [0, 2] regardless of which way the underlying engine likes to count, so ORDER BY score ASC works the same way on every provider.

Auto-embed on insert

If you don’t want to call IEmbeddingGenerator by hand on every write, Shiny.DocumentDb.Extensions.AI ships an AutoEmbedOnInsert<T> helper that hooks the new OnBeforeInsert<T> pipeline:

using Shiny.DocumentDb.Extensions.AI;

opts.MapVectorProperty<Document>(d => d.Embedding, dimensions: 1536)
    .AutoEmbedOnInsert<Document>(
        embeddingGenerator,
        sourceSelector: d => d.Content,
        targetSetter: (d, vec) => d.Embedding = vec,
        targetGetter: d => d.Embedding);   // skip when already set

await store.Insert(new Document { Content = "hello world" });
// Embedding is populated automatically before the row hits the wire.

It runs on Insert, BatchInsert, and Upsert, skips when the source is null/empty, and skips when the target already holds a non-default vector so explicit writes always win.

Tuning knobs

VectorIndexOptions gives you strongly-typed HNSW (M, EfConstruction, EfSearch) and IVF (Lists) settings plus a ProviderHints dictionary for the long tail (sqlite.postFilterMultiplier, atlas.indexName, atlas.numCandidates).

Full design notes are in the Vector docs.

Global Query Filters

If you have shipped anything on Entity Framework Core, you have written this:

modelBuilder.Entity<User>().HasQueryFilter(u => !u.IsDeleted);

Shiny.DocumentDb v6 gets the same surface:

var store = new DocumentStore(new DocumentStoreOptions
{
    DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db")
}
.AddQueryFilter<User>(u => !u.IsDeleted)                         // unnamed
.AddQueryFilter<Order>("tenant", o => o.TenantId == ctx.Current) // named
.AddQueryFilter<Order>("status", o => o.Status != "Archived"));

Filters AND together; the user’s Where is AND’d on top. Captured variables (ctx.Current) are re-read on every translation, so per-request tenant scopes work without rebuilding the store.

What gets filtered

The interesting decision is what isn’t filtered. v6 follows EF Core: every read path enforces the filter, but inserts and raw SQL stay free.

Path	Filtered?
`Query<T>()` + every terminal (`ToList`, `Count`, `ExecuteUpdate`, …)	Yes
`query.NotifyOnChange()`	Yes — only matching documents emit
`Get<T>(id)` / `GetDiff<T>(id, ...)`	Yes — returns `null` if filter fails
`Update<T>`	Yes — throws “not found” if filter fails
`SetProperty<T>` / `RemoveProperty<T>` / `Remove<T>(id)` / `Clear<T>()`	Yes
`Insert<T>` / `BatchInsert<T>` / `Upsert<T>`	No — matches EF Core
`Query<T>(rawSql)` / `QueryStream<T>(rawSql)`	No — your SQL, your call

Per-query opt-out matches EF Core too:

// Disable all filters
var allUsers = await store.Query<User>().IgnoreQueryFilters().ToList();

// Disable a specific named filter (others still apply)
var anyTenant = await store.Query<Order>().IgnoreQueryFilters("tenant").ToList();

This works on every provider that has a real query translator: relational SQL (DocumentStore), LiteDbDocumentStore, CosmosDbDocumentStore, MongoDbDocumentStore, and IndexedDbDocumentStore.

Full reference: Global Query Filters.

Composite JSON Indexes

CreateIndexAsync<T> has accepted a single expression since v3. v6 adds a multi-expression overload:

// Single-column (unchanged)
await store.CreateIndexAsync<User>(u => u.Name, ctx.User);

// Composite — one B-tree over multiple JSON paths
await store.CreateIndexAsync(
    ctx.User,
    u => u.LastName,
    u => u.FirstName);

The composite index name is built by joining the resolved paths with __, so ix_User_LastName__FirstName is the resulting object on disk. Drop the composite index with the matching overload:

await store.DropIndexAsync(ctx.User, u => u.LastName, u => u.FirstName);

How each provider implements it:

SQLite / SQLCipher / PostgreSQL / MySQL / DuckDB — one composite index with one json_extract (or provider equivalent) expression per path. Single statement, single index object.
SQL Server — JSON expression indexes need PERSISTED computed columns. v6 creates one column per path (cc_{indexName}_0, cc_{indexName}_1, …) and indexes them all. The drop path discovers the backing computed columns from sys.index_columns, so single- and multi-column indexes drop through the same code path with no special-case logic.

Existing single-path index names are preserved bit-for-bit, so v5 indexes survive an upgrade without an OBJECT_DROP_FAILED somewhere in production.

Real Connection Pooling on Server SQL

v5 was honest about its limit: a single DocumentStore instance serialized every operation through one semaphore around one long-lived connection. Fine for a phone, miserable for a server.

v6 splits behaviour along the provider:

PostgreSQL, MySQL, SQL Server — open a connection per operation. The ADO.NET driver’s pool multiplexes callers. One store, many concurrent calls, no in-process queueing.
SQLite, SQLCipher, DuckDB — embedded engines that take a database-wide write lock. These keep the v5 model: one long-lived connection, one per-store semaphore. The provider declares which mode it wants via IDatabaseProvider.RequiresSingleConnection.

RunInTransaction pins one connection for the duration of the user callback regardless of provider, so every nested operation shares the transaction.

Table init is now backed by a ConcurrentDictionary<string, Lazy<Task>> — first-touch DDL runs exactly once per table even under concurrent first calls. No more “is the schema there yet?” races on cold start.

A small but important consequence for streaming: on the pooled providers, await foreach (... in store.Query<T>().ToAsyncEnumerable()) holds one connection out of the pool for the lifetime of the iterator instead of holding the whole store. Other callers don’t block. On the embedded engines, behaviour is unchanged — finish the enumeration before issuing another store call.

Per-Query Change Monitoring

IObservableDocumentStore shipped in v5.3 with a global, type-scoped stream of DocumentChange<T>. v6 adds a query-scoped overload — every fluent query now exposes a .NotifyOnChange() that filters the change feed by the query’s own Where predicates:

var pending = store.Query<Order>().Where(o => o.Status == "Pending");

await foreach (var change in pending.NotifyOnChange(ct))
{
    // Only fires when an Order matching Status == "Pending" is inserted or updated.
    UpdateUi(change);
}

OrderBy, Paginate, and GroupBy are ignored because they change result shape, not membership. Calling Select(...) first throws — projecting away the document body breaks the filter.

SetProperty, RemoveProperty, Remove, and Clear don’t carry the full document, so DocumentChange<T>.Document is null for those events. The per-query filter passes them through unconditionally so the consumer can re-query and decide for itself whether the document still matches.

Combined with the new global query filters and the existing IChangeFeedDocumentStore (cross-process change feeds backed by PostgreSQL LISTEN/NOTIFY, SQL Server Change Tracking, and Cosmos DB Change Feed), change observation is now end-to-end coherent: every read goes through the same filter; every change subscription sees only the changes that match.

Other Notable v6 Items

A few smaller things that show up in the release notes but didn’t get their own section:

MapIdProperty<T>(...) — standalone Id-property override that no longer requires MapTypeToTable. Use it when the Id is named Slug or DeviceKey but you still want the type stored in the default shared table.
OnBeforeInsert<T> — async pre-write hook on DocumentStoreOptions. AutoEmbedOnInsert<T> is the headline consumer but it’s a general “compute derived fields” extension point.
SupportsVector on IDocumentStore and IDatabaseProvider, matching the existing SupportsSpatial.
PostgreSQL optimistic concurrency fix — the version check now extracts as a typed int (::BIGINT), no more 42883: operator does not exist.
PostgreSQL and DuckDB multi-tenancy fix — the CAST(@data AS JSONB) / CAST(@data AS JSON) envelopes no longer break the tenant-column rewrite.

Upgrading

v6 is API-compatible with v5 in every place that matters. The semaphore on the server-SQL providers is gone — if you relied on it to serialize writes from one store instance, you’ll want to switch to RunInTransaction for that semantics. Everything else is purely additive.

dotnet add package Shiny.DocumentDb.PostgreSql --version 6.0.0
dotnet add package Shiny.DocumentDb.Sqlite     --version 6.0.0
dotnet add package Shiny.DocumentDb.SqlServer  --version 6.0.0
# etc.

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 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.

Shiny.NET | Blog

Shiny HTTP Transfers: Background Transfers, and Knowing What They're Doing

What is actually carrying the bytes

Android: a foreground service, and a connectivity gate

Why downloads resume and uploads do not

Object stores, without the object-store SDK

Why not Azure.Storage.Blobs or AWSSDK.S3

The part to watch: a signature has a clock

Why not a background job?

Metrics

Throughput is sampled on a rolling window

Three ways to consume it

The metrics the user sees

The measurement problem iOS hands you

Where to go next

DocumentDB in Aspire

The AppHost picks the backend

The service gets one line

The contract underneath

Settings

Typed DocumentContext on an Aspire resource

An entire Orleans silo, pointed at the same store

The admin UI as a resource

Or the terminal one, no container

What it deliberately doesn’t do

DocumentDB in .NET Orleans

Five contracts, one store

Grain state you can query without activating a grain

A free audit trail

Streams — the piece that completes the set

Why there’s a counter row and not a BIGSERIAL

Two things a queue-backed provider can’t do

Concurrency, properly

Know your backend

Reflection-free serialization when you want it

And in Aspire, it’s one line

Get started

Level Up Animation with Keyframes for MAUI & Blazor

Layer 1 — Keyframes

The one design constraint

Easing you can paste in

Details that bite in production

Storyboards, scenes, and export

Layer 2 — Motion Icons

One definition, two very different engines

Triggers

Presets, and your own artwork

Layer 3 — ShinyButton

Nothing binds IsBusy, because there is no IsBusy

Motion icons in the slots

Busy modes, and why they are about layout

Appearance is emphasis, Type is meaning

The command integration (MAUI)

Where to go next

Shiny Controls 1.0 — The Ultra Control Suite for .NET MAUI & Blazor

Click it before you install it

👉 shinyorg.github.io/controls

The catalogue

ChatView

Walkthrough

Scheduler

CameraView

Theming ties it together

Getting started

Shiny.DocumentDb — Hidden Gems

1. The store already knows what changed

Writing only what changed

Then turn on temporal and it gets silly

2. Stop deserializing JSON just to serialize it again

The fidelity rules, because they matter

Trim the fields on the way out

3. Everything soft delete taught me about extensibility

ctx.Cancel() — replace a write, don’t just watch it

Named query filters — and lifting them one query at a time

Quick hits

And the tools nobody’s seen

Shiny.DocumentDb v13 — Encryption, an Outbox, and a Front Door

Field-level encryption

A transactional outbox

A front door: REST, SSE and MCP

Why not `Azure.Storage.Blobs` or `AWSSDK.S3`

Typed `DocumentContext` on an Aspire resource

Why there’s a counter row and not a `BIGSERIAL`

`ctx.Cancel()` — replace a write, don’t just watch it