Newsletter Archive

HybridCache: One API for In-Memory + Distributed Caching

Caching in ASP.NET Core has always meant choosing between IMemoryCache (fast, single-node) and IDistributedCache (shared, slower). In practice you want both: a fast L1 in-memory layer backed by shared L2 storage like Redis. But wiring them together manually means duplicate code, stampede bugs, and serialization headaches.

HybridCache in .NET 9 wraps both layers behind a single call.

Setup

dotnet add package Microsoft.Extensions.Caching.Hybrid

builder.Services.AddHybridCache(options =>
{
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(10),        // L2 (distributed)
        LocalCacheExpiration = TimeSpan.FromMinutes(2) // L1 (memory)
    };
});

// Optional: add a distributed backend
builder.Services.AddStackExchangeRedisCache(o => o.Configuration = "localhost:6379");

Without an IDistributedCache registration, HybridCache still works as an in-memory cache with stampede protection.

Basic Usage

app.MapGet("/products/{id:int}", async (int id, HybridCache cache) =>
{
    var product = await cache.GetOrCreateAsync(
        $"product:{id}",
        async cancel => await LoadProductFromDb(id, cancel));

    return product is not null ? Results.Ok(product) : Results.NotFound();
});

First call: factory runs, result is stored in L1 and L2. Subsequent calls within the local expiration window come straight from memory without touching Redis.

Stampede Protection

This is the headline feature. If 100 concurrent requests all miss the cache for the same key, only one runs the factory. The other 99 wait for that single result. No configuration needed. It’s the default behavior.

Tag-Based Invalidation

Group related entries with tags and invalidate them in one call:

// When caching, attach a tag
var products = await cache.GetOrCreateAsync(
    $"products:category:{category}",
    async cancel => await LoadByCategory(category, cancel),
    tags: ["products"]);

// When data changes, evict everything tagged "products"
await cache.RemoveByTagAsync("products");

For single entries, RemoveAsync clears from both L1 and L2:

await cache.RemoveAsync($"product:{id}");

Key Takeaway

HybridCache gives you L1 + L2 caching, stampede protection, and tag-based invalidation behind a single GetOrCreateAsync call. Stop hand-rolling two-layer cache logic.

Server-Sent Events in ASP.NET Core Minimal APIs

You need to push real-time updates from server to browser. SignalR is the default answer, but sometimes you don’t need bidirectional communication. You just need the server to stream events to the client: a progress bar, a live feed, a notification stream.

Server-Sent Events (SSE) does exactly that. It’s a native browser API built on plain HTTP. No WebSocket upgrade, no SignalR hub, no client library.

The Basics

Set the content type to text/event-stream and write data: lines followed by double newlines:

app.MapGet("/events/progress", async (HttpContext context, CancellationToken ct) =>
{
    context.Response.ContentType = "text/event-stream";
    context.Response.Headers.CacheControl = "no-cache";

    string[] steps = ["Validating", "Processing", "Confirming"];

    for (int i = 0; i < steps.Length; i++)
    {
        var json = JsonSerializer.Serialize(new { step = steps[i], percent = (i + 1) * 33 });
        await context.Response.WriteAsync($"data: {json}\n\n", ct);
        await context.Response.Body.FlushAsync(ct);
        await Task.Delay(1500, ct);
    }
});

The CancellationToken fires when the client disconnects, so you stop doing work immediately.

Named Events

Add an event: line to categorize messages:

await context.Response.WriteAsync($"event: progress\ndata: {json}\n\n", ct);

The client can then listen for specific event types.

The Client Side

The browser’s native EventSource API handles connection and auto-reconnection:

const source = new EventSource('/events/progress');

source.addEventListener('progress', (e) => {
    const data = JSON.parse(e.data);
    updateProgressBar(data.percent);
});

source.onerror = () => console.log('Reconnecting...');

Auto-reconnect is built into the spec. You get resilience for free.

Streaming with Channels

For fan-out scenarios like live dashboards, pair SSE with System.Threading.Channels:

app.MapGet("/events/orders", async (HttpContext ctx, OrderEventBus bus, CancellationToken ct) =>
{
    ctx.Response.ContentType = "text/event-stream";
    ctx.Response.Headers.CacheControl = "no-cache";

    await foreach (var evt in bus.Subscribe(ct))
    {
        var json = JsonSerializer.Serialize(evt);
        await ctx.Response.WriteAsync($"data: {json}\n\n", ct);
        await ctx.Response.Body.FlushAsync(ct);
    }
});

POST events into the channel from elsewhere, and every connected SSE client receives them in real time.

SSE vs. SignalR

Choose SSE when you only need server-to-client streaming and want the simplest possible setup. Choose SignalR when you need bidirectional messaging, binary data, or group management.

Key Takeaway

SSE is the lightest way to push real-time updates from ASP.NET Core to a browser. Set text/event-stream, write data: lines, flush, and the browser handles the rest, including automatic reconnection.

System.Text.Json Source Generation: AOT-Ready Serialization Without Reflection

System.Text.Json works great out of the box. You call JsonSerializer.Serialize(myObject) and it figures everything out at runtime via reflection. But that runtime discovery has two costs:

1. Slow first call while it builds metadata and converters
2. Incompatible with Native AOT/trimming because the trimmer strips the metadata reflection needs

Source generation moves all of that to compile time.

The Problem

// Reflection-based: slow first call, breaks under trimming
string json = JsonSerializer.Serialize(product);

The Fix

Create a partial class extending JsonSerializerContext and annotate each type you need:

[JsonSerializable(typeof(Product))]
[JsonSerializable(typeof(Product[]))]
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
public partial class AppJsonContext : JsonSerializerContext;

Use the generated type info instead of relying on reflection:

string json = JsonSerializer.Serialize(product, AppJsonContext.Default.Product);
var roundTripped = JsonSerializer.Deserialize(json, AppJsonContext.Default.Product);

AppJsonContext.Default.Product is the generated JsonTypeInfo<Product> - no reflection at any point.

Wiring into ASP.NET Core

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

Inserting at position 0 means source-generated metadata is checked first. Uncovered types fall back to reflection. For fully AOT-safe apps, set it as the sole resolver:

options.SerializerOptions.TypeInfoResolver = AppJsonContext.Default;

Now any unregistered type produces a clear error instead of a silent reflection fallback.

Polymorphism

Use [JsonDerivedType] on the base type:

[JsonDerivedType(typeof(ElectronicProduct), "electronic")]
[JsonDerivedType(typeof(ClothingProduct), "clothing")]
public record Product(int Id, string Name, decimal Price);

public record ElectronicProduct(int Id, string Name, decimal Price, string Warranty)
    : Product(Id, Name, Price);

The serializer emits a $type discriminator and the source generator handles the rest.

Performance

Serializing an array of 100 products:

The big win is that first call: source generation eliminates the reflection warmup entirely. Subsequent calls are comparable or slightly faster, with roughly 15% fewer allocations on the fast path.

Key Takeaway

A partial class, a few [JsonSerializable] attributes, and you get instant first-call performance plus trim/AOT compatibility. If you’re targeting AOT, serverless, or just want faster startup, this is the path.