# Runtime, GC and hosting settings

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 Size` to 100. Twenty instances is already 2,000 connections.
- `Timeout expired. The timeout period elapsed prior to obtaining a connection from the pool` means
  the pool is exhausted, not that the database is slow. Look for long transactions, a `DbContext`
  kept 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` (via `IHttpClientFactory`) should be minutes, so DNS
  changes are picked up. A `static HttpClient` with no lifetime keeps resolving to a dead endpoint.

## 3. Kestrel

Defaults are sane. The options worth setting are protection, not speed:

```csharp
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.
