Org Skills

Background work, streaming responses, caching and Native AOT

Supporting material for dotnet-development. Agents load it on demand; it ships inside the skill folder.

RawSource

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.

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

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.

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.

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)

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.

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
    };
});
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.