/sota-dotnet

name: sota-dotnet
description: >-
  State-of-the-art C# / .NET engineering rules (.NET LTS releases, modern
  C#) that Claude applies when writing or auditing .NET code. Covers modern
  idioms (records, nullable reference types, pattern matching, spans, file-scoped
  namespaces), API/null/immutability/`IDisposable` design, async/await &
  concurrency (ConfigureAwait, channels, cancellation, TPL), security (OWASP
  .NET, deserialization — BinaryFormatter removed in .NET 9, EF/Dapper SQL
  injection, ASP.NET Core auth, Data Protection, crypto), performance (GC,
  Span and Memory, BenchmarkDotNet, Native AOT), and build/tooling/CI (dotnet
  CLI, NuGet lockfiles & supply chain, Roslyn analyzers, nullable). Trigger
  keywords - C#, .NET, dotnet, ASP.NET Core, async, await, Task, record,
  nullable reference types, Span, EF Core, Dapper, LINQ, NuGet, Roslyn analyzer,
  BinaryFormatter, Native AOT, BenchmarkDotNet, IDisposable, ConfigureAwait. Use
  for BOTH building .NET services/libraries and auditing them.

SOTA C# / .NET (2026)

Expert-level rules for producing and auditing production .NET. The runtime is memory-safe, so risk concentrates in **injection, deserialization, async correctness, and dependency supply chain**. Written for **.NET 10 LTS** (released Nov 2025, supported to Nov 2028) and **C# 14** (records, nullable reference types, pattern matching, spans, extension members, the `field` keyword) — flag where a control needs a specific version. Every rule states the *why*; every rules file ends with an audit checklist of grep/analyzer patterns.

Purpose

Two consumers, one source of truth:

• **BUILD mode** — generating C#/.NET: follow the rules as defaults. Enable

**nullable reference types** and treat analyzer warnings as errors; prefer immutability and the async-all-the-way model. Deviate only with a comment.

• **AUDIT mode** — reviewing existing code: hunt violations with the audit

checklists, classify by severity, report in the finding format below. SQL string-building and legacy deserialization are presumed exploitable.

BUILD mode

1. Before writing, read the rules files relevant to the task (see index). A web API touching untrusted input + a DB + async needs `02`, `03`, `04`; a parser of untrusted bytes also gets a fuzz target ([`rules/06`](rules/06-build-tooling-ci.md) §4). 2. Apply the **top-10 non-negotiables** (below) unconditionally. 3. New projects: target the latest LTS TFM (verify at the .NET support policy page), `<Nullable>enable</Nullable>`, `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`, `<AnalysisLevel>latest-Recommended</AnalysisLevel>` **plus `<AnalysisModeSecurity>All</AnalysisModeSecurity>`** (Recommended alone leaves most security CA rules off — [`rules/06`](rules/06-build-tooling-ci.md) §2), NuGet lockfile + `RestoreLockedMode` in CI, and `dotnet format` from day one ([`rules/06`](rules/06-build-tooling-ci.md)). 4. Async all the way down — never block on async (`.Result`/`.Wait()`/ `GetAwaiter().GetResult()`) ([`rules/03`](rules/03-async-concurrency.md)). Use `CancellationToken` end to end. 5. Prefer the BCL and well-known libraries; parameterize all data access; use the framework's auth/Data Protection rather than rolling your own ([`rules/04`](rules/04-security.md)). 6. When you take a sharp path (reflection, `unsafe`, `DynamicMethod`, suppressing a nullable/analyzer warning), leave a `// NOTE(sota):` explaining why.

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

Work each relevant rules file's audit checklist against the target. Run the greps and the Roslyn analyzers (incl. the security CA rules); confirm hits manually. Check the dependency tree against known-CVE databases.

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | **CRITICAL** | Exploitable on reachable input | SQL via string interpolation/concat into `FromSqlRaw`/`ExecuteSqlRaw`/Dapper, `BinaryFormatter`/`NetDataContractSerializer`/`LosFormatter` or JSON `TypeNameHandling.All` on untrusted data, command injection, deserialization gadget | | **HIGH** | Likely incident or security weakness | Missing auth on an endpoint, disabled cert validation (`ServerCertificateCustomValidationCallback => true`), MD5/SHA-1 or `DES`/ECB for security, `Random` for tokens, blocking on async causing deadlock/thread-pool starvation, secrets in config/source | | **MEDIUM** | Correctness/maintainability hazard | `async void` (non-handler), missing `ConfigureAwait(false)` in a library, `IDisposable` not disposed / no `using`, nullable warnings suppressed with `!`, swallowed exceptions, mutable static state | | **LOW** | Idiom/perf debt | Sync-over-collection LINQ on hot path, needless allocations/boxing, `class` where a `record`/`struct` fits, not using `Span`/pooling on hot path | | **INFO** | Style/doc/hygiene | formatting, naming, missing XML docs, nullable annotations absent (not enabled) |

Finding format

Expands the router's canonical row (`file:line | rule | severity | effort | fix`, which wins on a cross-domain roll-up); evidence block and report order: [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 and §5.

[SEVERITY] File.cs:LINE — short title
  Rule: rules/NN-name.md § section
  Evidence: the offending line(s), verbatim
  Impact: one sentence — what executes/leaks/deadlocks, under what input
  Fix: concrete replacement code or action
  Effort: trivial | small | medium | large

Group findings by severity, CRITICAL first. End with: counts per severity, the three highest-leverage fixes, and which checklists/analyzers were run.

Rules index

| File | Read this when... | |---|---| | [`rules/01-idioms.md`](rules/01-idioms.md) | Writing/reviewing any C#: records & `record struct`, nullable referen