# Background work, streaming responses, caching and Native AOT

Verified 2026-09 against <https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services>,
<https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-10.0>,
<https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid> and
<https://learn.microsoft.com/en-us/aspnet/core/fundamentals/native-aot>.

## 1. In-process work queue with `Channel<T>`

Never `_ = DoWorkAsync()` from a request: the task outlives the request scope, its exceptions are
unobserved, and shutdown does not wait for it. Hand the work to a bounded channel instead.

```csharp
using System.Threading.Channels;

public sealed class WorkQueue
{
    private readonly Channel<Func<IServiceProvider, CancellationToken, ValueTask>> _channel =
        Channel.CreateBounded<Func<IServiceProvider, CancellationToken, ValueTask>>(
            new BoundedChannelOptions(capacity: 1_000)
            {
                FullMode = BoundedChannelFullMode.Wait,   // back-pressure, never silently drop
            });

    public ValueTask EnqueueAsync(
        Func<IServiceProvider, CancellationToken, ValueTask> work, CancellationToken ct) =>
        _channel.Writer.WriteAsync(work, ct);

    public IAsyncEnumerable<Func<IServiceProvider, CancellationToken, ValueTask>> ReadAllAsync(
        CancellationToken ct) => _channel.Reader.ReadAllAsync(ct);
}
```

A bounded channel is a decision, not a detail: unbounded means a slow consumer turns into an
out-of-memory kill. `FullMode.Wait` makes the producer feel the back-pressure.

## 2. `BackgroundService` that survives its own failures

```csharp
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public sealed class WorkQueueWorker(
    WorkQueue queue,
    IServiceScopeFactory scopeFactory,
    ILogger<WorkQueueWorker> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var work in queue.ReadAllAsync(stoppingToken))
        {
            await using var scope = scopeFactory.CreateAsyncScope();
            try
            {
                await work(scope.ServiceProvider, stoppingToken);
            }
            catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
            {
                break;                                    // shutdown, not a failure
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Background work item failed");
            }
        }
    }
}
```

Registered with `builder.Services.AddSingleton<WorkQueue>();` and
`builder.Services.AddHostedService<WorkQueueWorker>();`.

Three rules the sample encodes:

1. **A scope per iteration.** The worker is a singleton; `DbContext` is scoped. Resolving it directly
   is the captive-dependency bug ("Cannot consume scoped service … from singleton").
2. **Catch inside the loop.** Since .NET 6 an unhandled exception in `ExecuteAsync` stops the whole
   host (`HostOptions.BackgroundServiceExceptionBehavior`), so one poison item kills the service.
3. **Distinguish cancellation from failure.** `OperationCanceledException` during shutdown is normal;
   logging it as an error wakes people at 3 a.m.

For work that must survive a restart, the queue belongs in a broker or a job store — see
`messaging-patterns`.

## 3. Streaming a large result with `IAsyncEnumerable<T>`

Return the sequence directly; ASP.NET Core serialises it as a JSON array without buffering every row.

```csharp
app.MapGet("/orders/export", (IOrderQueries queries, CancellationToken ct) =>
    queries.StreamAllAsync(ct));      // IAsyncEnumerable<OrderDto>
```

The query side must stream too — `AsAsyncEnumerable()` on the EF query, `AsNoTracking()`, and no
`ToListAsync()` anywhere in between, or you have only moved the buffer.

```csharp
public IAsyncEnumerable<OrderDto> StreamAllAsync(CancellationToken ct) =>
    db.Orders.AsNoTracking()
        .OrderBy(o => o.Id)
        .Select(o => new OrderDto(o.Id, o.Status))
        .AsAsyncEnumerable();
```

## 4. Server-sent events (.NET 10)

```csharp
using System.Runtime.CompilerServices;

app.MapGet("/orders/{id:guid}/events", (Guid id, IOrderEvents events, CancellationToken ct) =>
    TypedResults.ServerSentEvents(Stream(id, events, ct), eventType: "order-status"));

static async IAsyncEnumerable<OrderStatusChanged> Stream(
    Guid id, IOrderEvents events, [EnumeratorCancellation] CancellationToken ct)
{
    await foreach (var change in events.SubscribeAsync(id, ct))
    {
        yield return change;
    }
}
```

`[EnumeratorCancellation]` is required, otherwise the client disconnecting never cancels the producer
and the connection leaks. SSE connections hold a thread-free but real socket for their lifetime: cap
concurrent subscriptions and set an idle timeout at the proxy.

## 5. `HybridCache` for shared read-mostly data

Package `Microsoft.Extensions.Caching.Hybrid` (targets .NET Standard 2.0, so it runs on .NET 8 too).
`AddHybridCache()` alone gives in-process caching plus stampede protection; register an
`IDistributedCache` (Redis, SQL Server, Postgres) and it becomes the second tier automatically.

```csharp
builder.Services.AddHybridCache(options =>
{
    options.MaximumPayloadBytes = 1024 * 1024;
    options.DefaultEntryOptions = new HybridCacheEntryOptions
    {
        Expiration = TimeSpan.FromMinutes(5),          // distributed tier
        LocalCacheExpiration = TimeSpan.FromMinutes(1) // in-process tier
    };
});
```

```csharp
using Microsoft.Extensions.Caching.Hybrid;

public sealed class CatalogService(HybridCache cache, ICatalogSource source)
{
    public ValueTask<ProductDto> GetAsync(int id, CancellationToken ct) =>
        cache.GetOrCreateAsync(
            $"catalog/product/{id}",
            async token => await source.LoadAsync(id, token),
            tags: ["catalog"],
            cancellationToken: ct);

    public ValueTask InvalidateCatalogAsync(CancellationToken ct) =>
        cache.RemoveByTagAsync("catalog", ct);
}
```

Two things that surprise people: `GetOrCreateAsync` calls the factory **once** per key across
concurrent callers (that is the stampede protection you are buying), and `RemoveByTagAsync` is a
*logical* invalidation — entries stay in memory until they expire but are treated as misses. Tag
invalidation reaches the distributed tier and the current process, not other processes' local tier, so
keep `LocalCacheExpiration` short when freshness matters.

Never build a cache key from raw user input; use internal identifiers, as in the sample.

## 6. Native AOT: what actually has to be true

`PublishAot` is not a flag you flip on an existing API. Prerequisites, all of them:

- **Minimal APIs only.** MVC, Razor Pages, SignalR and Blazor Server are not supported.
- **Source-generated JSON.** A `JsonSerializerContext` covering every DTO, wired with
  `builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default));`
  Reflection-based serialisation fails at runtime after trimming.
- **EF Core needs a compiled model** (`dotnet ef dbcontext optimize`); runtime model building uses
  reflection. Several providers still have gaps — test on the target, do not assume.
- **Every library must be AOT-clean.** Set `<IsAotCompatible>true</IsAotCompatible>` on your own
  projects to get the trim/AOT analyzer warnings at build time instead of crashes in production.
- **No `Assembly.Load`, `Type.GetType(string)` or dynamic proxies** anywhere on the start-up path,
  including in DI containers and mapping libraries.

If any of these is a problem, `PublishReadyToRun` gives most of the start-up win with none of the
constraints. Measure start-up before and after; that is the only reason to take on AOT at all.
