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:
- A scope per iteration. The worker is a singleton;
DbContextis scoped. Resolving it directly is the captive-dependency bug ("Cannot consume scoped service … from singleton"). - Catch inside the loop. Since .NET 6 an unhandled exception in
ExecuteAsyncstops the whole host (HostOptions.BackgroundServiceExceptionBehavior), so one poison item kills the service. - Distinguish cancellation from failure.
OperationCanceledExceptionduring 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
JsonSerializerContextcovering every DTO, wired withbuilder.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.