Verified 2026-09 against https://learn.microsoft.com/en-us/dotnet/core/runtime-config/garbage-collector, https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/options, https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run and https://learn.microsoft.com/en-us/aspnet/core/fundamentals/native-aot.
Everything here is a knob with a default that is right most of the time. Change one, measure, and write down why — an undocumented runtime setting outlives everyone who understood it.
1. Garbage collection
| Setting | MSBuild property | Default | Change when |
|---|---|---|---|
| Server vs workstation GC | ServerGarbageCollection |
Workstation, except Microsoft.NET.Sdk.Web sets it to true |
Set it to false for sidecars, CLI tools and small single-purpose processes |
| DATAS (heap sized to live data) | GarbageCollectionAdaptationMode (1/0) |
Enabled with Server GC since .NET 9 | Disable (0) only with a measured throughput regression; it is what keeps container memory sane |
| Background GC | ConcurrentGarbageCollection |
Enabled | Rarely; disabling raises pause times |
| Heap hard limit | System.GC.HeapHardLimit / …Percent (runtimeconfig) |
75% of the container limit | You need headroom for native memory — a large IDistributedCache client, image processing |
| LOH threshold | System.GC.LOHThreshold |
85,000 bytes | Almost never. Raising it hides the real fix, which is pooling the buffer |
The single most common surprise: a container limited to roughly one CPU runs workstation GC even in an ASP.NET Core app, because the runtime picks the flavour from the CPU count it observes. If throughput per core is worse in the small pod than on the developer machine, check this before anything else.
Set CPU and memory limits explicitly on every container. The runtime reads cgroup limits and sizes the heap from them; with no limit it sizes from the node, which is how one pod ends up believing it has 256 GB.
2. Connection pools
Pools are per connection string, per process. The arithmetic that bites:
instances × Max Pool Size ≤ database max_connections − (admin + migrations + other services)
- Npgsql and SqlClient default
Max Pool Sizeto 100. Twenty instances is already 2,000 connections. Timeout expired. The timeout period elapsed prior to obtaining a connection from the poolmeans the pool is exhausted, not that the database is slow. Look for long transactions, aDbContextkept past its scope, or unbounded parallel queries per request.- A serverless host multiplies instances by its own concurrency; put a pooler (PgBouncer, RDS Proxy, SQL Server's own pooling at the gateway) in front rather than raising the limit.
SocketsHttpHandler.PooledConnectionLifetime(viaIHttpClientFactory) should be minutes, so DNS changes are picked up. Astatic HttpClientwith no lifetime keeps resolving to a dead endpoint.
3. Kestrel
Defaults are sane. The options worth setting are protection, not speed:
builder.WebHost.ConfigureKestrel(options =>
{
options.Limits.MaxRequestBodySize = 10 * 1024 * 1024;
options.Limits.MaxConcurrentConnections = 10_000;
options.Limits.KeepAliveTimeout = TimeSpan.FromSeconds(130);
});
KeepAliveTimeout must be longer than the load balancer's idle timeout, or the server closes a
connection the balancer still believes is usable and the client sees a 502. This is the fix for
"random 502s after a deploy" far more often than anything in the application.
HTTP/2 is negotiated over TLS automatically and is what gRPC needs — its multiplexing removes
head-of-line blocking between concurrent calls on one connection. HTTP/3 (QUIC) helps lossy mobile
networks and needs Protocols = HttpProtocols.Http1AndHttp2AndHttp3 plus platform support; behind a
CDN or load balancer that terminates TLS, this is the proxy's decision, not yours.
4. Response compression and streaming
- Compress at the reverse proxy or CDN when there is one. In-process compression costs CPU on the machine you are trying to keep fast.
- If you must compress in the app, know the BREACH-style risk: compressing a response that mixes a secret (a CSRF token) with attacker-influenced content over HTTPS can leak the secret.
- Do not compress already-compressed payloads (images, video,
.zip); you pay CPU for nothing. - For large results, stream (
IAsyncEnumerable<T>, see../../dotnet-development/references/background-and-streaming.md) rather than building a list. Memory then scales with the row, not with the result set.
5. Start-up: ReadyToRun and Native AOT
| Option | Gains | Costs |
|---|---|---|
| Default (JIT + tiered compilation + Dynamic PGO) | Best steady-state throughput | Slowest first requests |
ReadyToRun (<PublishReadyToRun>true</PublishReadyToRun>) |
Much faster start-up, no code constraints | Larger binaries; must publish per runtime identifier |
Native AOT (<PublishAot>true</PublishAot>) |
Fastest start-up, smallest memory, no JIT | Minimal APIs only, source-generated JSON, no runtime reflection, every dependency must be trim-safe |
Take ReadyToRun first — it is a property and a republish. Native AOT is an architectural commitment;
the full prerequisite list is in ../../dotnet-development/references/background-and-streaming.md §6.
Tiered compilation and Dynamic PGO are on by default (since .NET 8) and should stay on. Disabling tiering to "avoid the slow first calls" trades a large steady-state regression for a small start-up win; ReadyToRun is the correct tool for that problem.
6. Thread pool
Leave ThreadPool.SetMinThreads alone. It exists for start-up bursts of unavoidable blocking work,
not as a fix for starvation — raising it lets a blocked service burn more threads before it stalls,
which turns a clear failure into a slow, expensive one. The equivalent environment knobs
(DOTNET_ThreadPool_MinThreads, DOTNET_ThreadPool_MaxThreads) deserve the same suspicion.
If you have genuinely unavoidable blocking work — a synchronous vendor SDK, a native library — give it its own bounded scheduler or a dedicated worker with a queue, so it cannot consume the pool the rest of the service shares.