CacheOrchestrator

CacheOrchestrator is domain-based caching for ASP.NET Core: define rules once per domain in configuration, then apply them on endpoints with a single attribute or extension. It orchestrates Output Cache, FusionCache, and client Cache-Control under the same model.

No more scattering TTLs, headers, and backend settings across every controller.

Target	.NET 8 and .NET 10
Try now	samples/CacheOrchestrator.Minimal — zero typing, InMemory only
Explore	samples/CacheOrchestrator.Sample — interactive playground

---

Why domains?

Different data needs different caching — not one global policy:

Domain example	How often it changes	Cache style
Satellite imagery	~ yearly	Very long server + client TTL
OSM / map tiles	~ monthly	Long TTL + scheduled client ramp-down before cutover
Live tracking	seconds	Short TTL

Declare a domain once, apply it with .CacheOutputWithDomain("…") or [CacheDomain("…")].

---

Try it in one minute

Nothing to type into a new project — run the sample:

dotnet run --project samples/CacheOrchestrator.Minimal

Then (second terminal):

curl -i http://localhost:5290/hello
curl -i http://localhost:5290/hello

Request	What you should see
1st	X-Cache: … output=miss (~200 ms simulated work)
2nd	X-Cache: … output=hit (served from Output Cache)

Use curl or DevTools → Disable cache so the browser does not hide server-side hits.

→ Details: samples/CacheOrchestrator.Minimal/README.md

---

Install

dotnet add package CacheOrchestrator

# Optional — Redis Output Cache store + FusionCache L2 / backplane:
dotnet add package CacheOrchestrator.Redis

---

Minimal setup (copy into your app)

InMemory only — no Redis required.

1. appsettings.json

{
  "Cache": {
    "Namespace": "my-app",
    "OutputCache": { "Provider": "InMemory" },
    "FusionCacheInstances": {
      "default": { "Provider": "InMemory" }
    },
    "Domains": {
      "catalog": {
        "Version": "1",
        "ClientCacheability": "Public",
        "ClientTtlSeconds": 60,
        "OutputCacheTtlSeconds": 120,
        "FusionCacheSoftTtlSeconds": 300
      }
    }
  }
}

2. Program.cs

using CacheOrchestrator.DependencyInjection;
using CacheOrchestrator.FusionCache;
using CacheOrchestrator.OutputCache;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCacheOrchestrator(builder.Configuration);

var app = builder.Build();
app.UseCacheOrchestrator(); // after routing middleware is configured

app.MapGet("/api/products", async (HttpContext http, IDomainFusionCache cache) =>
{
    var data = await cache.GetOrSetAsync(http, async ct =>
    {
        // Load from DB / service
        return await LoadProductsAsync(ct);
    });
    return Results.Json(data);
})
.CacheOutputWithDomain("catalog");

app.Run();

That is the happy path: domain in config + one endpoint decoration + GetOrSetAsync.

MVC / controllers: put [CacheDomain("catalog")] on the controller or action and inject IDomainFusionCache the same way.

Redis later: install CacheOrchestrator.Redis, call o.AddRedisBackend(), set "Provider": "Redis" — see docs/backends.md.

More walkthrough: docs/getting-started.md

---

What you get (feature overview)

Everything below is available without opening other pages first. Links go deeper when you need them.

Core

Capability	What it does
Domains	Named packages of rules (TTL, Version, client headers, Fusion instance). Applied via .CacheOutputWithDomain / [CacheDomain]. output-cache
Output Cache (L0)	Full HTTP GET/HEAD response caching (ASP.NET Core).
FusionCache (L1/L2)	Application object cache via IDomainFusionCache — memory ± optional distributed. fusion-cache
Client Cache-Control	Browser/CDN max-age / public / private / no-store from domain settings.
Version stamp	Change Version in config → new key space; old entries age out. invalidation
Invalidation API	ICacheOrchestratorInvalidator — domain, entity, or tags. Structured results + optional observers.
X-Cache header	Diagnostic header (domain, output, data, phase, …). Toggle with EmitDiagnosticsHeaders (default on). observability
Metrics & tracing	Meter / activity source CacheOrchestrator (independent of response headers).
Health checks	AddHealthChecks().AddCacheOrchestrator() — backend probes (e.g. Redis ping).

Advanced

Capability	What it does
Client Cache Schedule	Near a planned cutover (ScheduledUpdateUtc), client max-age ramps from long → short (Calm / Approaching / Hold). Server TTLs unchanged. client-cache-schedule
Snapshot vs dynamic domains	OSM-style generation stamps vs CRUD + per-entity invalidation. domain-profiles
ETag modes	Version (generation), Resource (per URL/id), or None.
Entity / resource id	GetOrSetAsync(http, domain, resourceId, …) + InvalidateEntityAsync.
Auth controls	Default: skip Output Cache for authenticated / Authorization. Opt-in with BypassWhenAuthenticated + VaryOutputCacheByUser.
Named Fusion instances	Map domains to separate Redis clusters (e.g. PII vs catalog). deployment
Redis package	CacheOrchestrator.Redis — OC store + keyed L2 + backplane. Not in core.
Custom backends	ICacheBackendRegistrar / AddBackend — not a drop-in "Provider": "SqlServer" without your registrar. backends · comparison
Fail-safe / soft-hard TTL	Fusion fail-safe, soft/hard duration, jitter, eager refresh, factory timeouts — domain-configured.
Tracking query strip	utm_*, gclid, … ignored in cache keys so campaigns do not fragment the cache.
Multi-instance deployment	InMemory vs Redis topologies, mixed backends, backplane notes. deployment
Pluggable invalidation observers	Hook audit/webhooks on successful invalidations.

---

Documentation

Start here, then go deep only when you need to:

	Doc
Start	docs/getting-started.md · docs/README.md (full index)
Try	Minimal sample · Playground sample
Gotchas	docs/faq.md · docs/comparison.md

Topic	Doc
Domain profiles (snapshot / CRUD)	docs/domain-profiles.md
Client Cache Schedule	docs/client-cache-schedule.md
Configuration reference	docs/configuration.md
Output Cache	docs/output-cache.md
FusionCache	docs/fusion-cache.md
Invalidation	docs/invalidation.md
Backends	docs/backends.md
Observability	docs/observability.md
Deployment	docs/deployment.md
Architecture	docs/architecture.md
Benchmarks	docs/benchmarks/results.md

API reference: XML docs ship with the NuGet packages (CacheOrchestrator, CacheOrchestrator.Redis). DocFX site planned post-1.0.

Project
CHANGELOG.md	Releases
docs/releasing.md	Version tags (MinVer), NuGet publish
CONTRIBUTING.md	Build, test, PRs, community expectations
SECURITY.md	Vulnerability reporting
LICENSE.md	MIT