contexture csharp.instructions.md

csharp rules

Auto-loaded by Copilot when editing files matching **/*.cs. Generated from architectural-rules/csharp/ — do not hand-edit.

C# async

Async methods return Task / Task<T> (or ValueTask<T> for hot paths). Never async void except event handlers — an exception in async void cannot be caught and tears down the process. Name async methods with the Async suffix (LoadAsync). The suffix is the contract that the method is awaitable. Library code calls ConfigureAwait(false) on awaits — it does not capture the caller's synchronization context, which prevents deadlocks in callers that block. Application/UI code that needs the context omits it. Never block on async with .Result / .Wait() / GetAwaiter().GetResult(). Sync-over-async deadlocks on a captured context. Await all the way up, or make the entry point async. Long-running async work takes a CancellationToken and honours it. Cancellation is part of the contract, not an afterthought.

Why: async bugs in C# are silent until production — a swallowed async void exception or a sync-over-async deadlock looks fine in tests and hangs under load. Source: Microsoft .NET async guidance.

C# collections and LINQ

LINQ queries use deferred execution — they do not run until enumerated. The query captures variables by reference; the result reflects state at enumeration time, not definition time. Materialize with ToList() / ToArray() once when you need to iterate multiple times or capture a snapshot. Enumerating a query twice re-runs it. Beware multiple enumeration of an IEnumerable, especially over DB/IO sources — each pass re-queries. Accept IReadOnlyList<T> / IReadOnlyCollection<T> in signatures when callers will enumerate more than once. Prefer LINQ over hand-rolled loops where it reads clearer (filter/project/aggregate). Drop back to a loop when the operation is imperative, has side effects, or the LINQ becomes harder to read than the loop.

Why: deferred execution and silent re-enumeration are the two LINQ footguns that turn a clean query into an N+1 or a stale snapshot. Source: Microsoft .NET LINQ guidance.