---
name: csharp-best-practices
description: C# best practices. Use when reading or editing any .cs file.
disable-model-invocation: true
---
# C# best practices
Apply the **type-system-discipline** principle skill first; this skill grounds it in C# syntax. Follow the repository's language version, analyzers, and libraries (Scrutor, MediatR, FluentValidation, OpenTelemetry) over the defaults below.
## Types
| Rule | Summary |
|------|---------|
| Nullable reference types | `enable` with `nullable` in `WarningsAsErrors`. `T?` means absent is a real case; `T` means never null. |
| No `!` | The null-forgiving operator is C#'s `as` cast. Prove non-null by narrowing, or change the type so null can't arrive. |
| Closed hierarchies | Model variants as an `abstract record` with a private constructor and nested `sealed record` cases. No optional-field bags, no `bool IsX` plus nullable payload. |
| Exhaustiveness | Enums: switch expression with no `_` arm, `CS8509` as an error, `CS8524` suppressed. Records: the compiler can't see the closure, so put an abstract member on the base that each case overrides, or use the repository's exhaustiveness analyzer. |
| Strongly typed ids | `readonly record struct OrderId` with a private constructor and a static `Parse`/`TryParse`. Validate once at creation. |
| Constructive modeling | Build the shape so the illegal value can't be constructed: `NonEmpty(T Head, IReadOnlyList Tail)`, start plus `TimeSpan` for a range. |
| Simplest total type | Keep `IReadOnlyList` while every operation stays total. Strengthen only where the loose type forces `!`, `.First()`, or a "should never happen" throw. |
| No casts | `(T)x`, `x as T` followed by a dereference, and `dynamic` are runtime crashes waiting. Use pattern matching. |
| Narrowing hierarchy | Switch expression on a closed type > property pattern > `is T t` > `TryX(out)` > cast. |
| Try pattern | `bool TryX(..., [NotNullWhen(true)] out T? value)` is C#'s type guard. It must verify the claim it makes. |
| Boundary validation | Deserialize into a DTO, map once into domain types, trust types inside. DTOs and EF entities don't cross into the domain. See the **boundary-discipline** principle skill. |
| Schemas before guards | Use the repository's contract and validation stack (System.Text.Json with `RespectNullableAnnotations`, DataAnnotations, FluentValidation, generated clients) before hand-writing field checks. |
| Immutable by default | `record`, `init`, `required`, `IReadOnlyList`. Mutate with `with`. |
| Named arguments | Same-typed or `bool` parameters get named arguments at the call site. Replace `bool` flags with an enum; past three parameters, pass a record. |
## Designing for decorators
| Rule | Summary |
|------|---------|
| Depend on the interface | Consumers take `IOrderService`, never `OrderService`. Register the concrete type only behind the interface. |
| Seal, don't subclass | Concrete services are `sealed`. Extend behavior by wrapping the interface, not with `virtual`/`protected` hooks. |
| Narrow interfaces | One operation or one cohesive group per interface, so a decorator forwards a few members, not twenty. For many similar operations, use a generic `ICommandHandler` and one open-generic decorator. |
| Async with cancellation | Every decorated member returns `Task`/`ValueTask` and takes `CancellationToken cancellationToken` last, so decorators can await, time, retry, and time out. |
| Outcomes in the return type | Expected failures are a closed result type, not exceptions or side-channel state, so decorators tag outcomes without catching. |
| No default interface members | A decorator that doesn't override a default member runs the default instead of forwarding to the inner service. Keep decorated interfaces abstract-only. |
| No hidden statics | Inject `TimeProvider`, `IMeterFactory`, and caches. Static state can't be wrapped or faked. |
| Core stays clean | The core class holds business logic only: no `Stopwatch`, `Meter`, catch-log-rethrow, or retry loops. Log from the core only when the message needs internal state a decorator can't see. |
| Transparent decorators | Same result, same exception (`throw;`), same `CancellationToken`. One concern per decorator. A decorator never disposes its inner service. |
| Deliberate order | The chain is written once at registration and is part of the design. Logging outermost sees the final outcome; metrics outside a retry measure caller latency, inside it measure attempts. |
## Logging and metrics
| Rule | Summary |
|------|---------|
| Structured templates | `logger.LogInformation("Placed {OrderId}", orderId)` with a constant template. No interpolation or concatenation in log calls (CA2254). No `Console.WriteLine` in shipped code. |
| Log context, not payloads | Ids, counts, durations, outcomes. No request bodies, tokens, or personal data. Stable PascalCase placeholder names, since they become query keys. |
| Exceptions once | Pass the exception as the `Exception` argument. One layer owns the error log: if a decorator logs and rethrows, the host must not log it again. |
| Instruments once | Inject `IMeterFactory`; create the `Meter` and its instruments in a singleton holder class, not per call or per scoped decorator. |
| Durations as histograms | `Histogram` in seconds (`unit: "s"`), timed with `Stopwatch.GetTimestamp()`. A histogram already counts calls; skip the twin counter. |
| Bounded tags | Tag `outcome`, `operation`, `error.type`. Never ids, user input, or exception messages. |
| Record in `finally` | Failures and cancellations are measured too. |
| Correlate with `Activity` | Correlate through tracing (`ActivitySource`) and the logger's activity tracking, not hand-built per-call scopes. |
## Services and tests
| Rule | Summary |
|------|---------|
| Constructor injection | Constructors take dependencies and do no work. No `IServiceProvider` in business code. |
| Lifetimes | A singleton never captures a scoped service. Enable `ValidateScopes` and `ValidateOnBuild`. |
| Validated options | `AddOptions().Bind(...).ValidateDataAnnotations().ValidateOnStart()`. Config is a boundary. |
| Async all the way | No `.Result`, `.Wait()`, or `async void` outside event handlers. Pass `cancellationToken` to every call that accepts one. |
| Real tests | `WebApplicationFactory`, a real database via the repository's test containers, `FakeTimeProvider`, `FakeLogger`, `MetricCollector`. Mock only what you can't run locally. |
Examples: `references/patterns.md` (types, services) and `references/decorators.md` (decorators, logging, metrics).