dotnet-performance (decision layer)

Two performance-aware design calls that are cheap to get right up front and expensive to retrofit: how a type allocates, and how bytes cross a boundary. This hub decides whether the call is worth spending on here and routes to the depth - it does not restate it.

• Type allocation / memory layout -> references/type-design.md
• Serialization-format choice -> references/serialization.md
• .NET Framework 4.8 caveats (the 'slow span', NuGet-only fast-path packages) -> references/net-framework-48.md

The language baseline (naming, async, records, disposal, DI) is csharp; the full .NET map is dotnet.

Measure first

Do not optimize on a hunch. A performance change is only earned by a measurement: a BenchmarkDotNet microbenchmark for a hot path, a profiler or dump for a live regression, allocation counts under load. Reach for dotnet-diagnostics before you tune. Most 'slow' code is a bad query or an N+1, not a struct-vs-class problem - profile before you touch a type, because optimizing the wrong layer buys nothing and costs readability.

When allocation and memory layout matter (type design)

Spend on the type-design defaults when a type sits on a hot path - a per-request allocation inside a tight loop, a high-throughput pipeline, a BackgroundService draining a channel (dotnet-hosted-services), a serializer inner loop. There the choices pay their way: seal by default, a small immutable value becomes a readonly struct, byte work moves to Span, a usually-cached async result returns ValueTask, static lookup data becomes a FrozenDictionary.

Off the hot path, do not contort a domain model for allocations you never measured - correctness and clarity win. The seal-by-default and immutable-return defaults still apply everywhere, though, because they cost nothing and prevent whole classes of bug. Load references/type-design.md for the rules and the anti-patterns.