NetFabric/NetFabric.Numerics / .agents/skills/csharp-best-practices
csharp-best-practices
VerifiedModern .NET and C# best practices for code quality, performance, and correctness. USE FOR: choosing struct/class/record/readonly-record-struct; nullable reference types; pattern matching; primary constructors; collection expressions; required members; init-only properties; file-scoped namespaces; global usings; async/await patterns; ConfigureAwait; ValueTask vs Task; CancellationToken propagation; IAsyncEnumerable; Span<T>/Memory<T> usage; avoiding boxing; readonly struct; ArrayPool<T>; FrozenDictionary/FrozenSet; LINQ vs loops in hot paths; ArgumentNullException.ThrowIfNull; ThrowIfNegative; ThrowIfZero; IReadOnlyList return types; error handling patterns; GeneratedRegex; LoggerMessage; source generators for regex and logging; avoiding Math/MathF in favor of static methods on the numeric type. DO NOT USE FOR: generic math interfaces (use dotnet-generic-math); ASP.NET Core middleware; EF Core modeling.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/async.md | markdown | 3.8 KB |
| references/language-features.md | markdown | 3.9 KB |
| references/performance.md | markdown | 4.2 KB |
| references/source-generators.md | markdown | 3.5 KB |
references/async.md
View on GitHub# Async / Await
## Core Rules
| Rule | Rationale |
|------|-----------|
| Never `async void` (except event handlers) | Exceptions are unobservable; prefer `async Task` |
| Never `.Result` / `.Wait()` on a `Task` | Deadlocks in sync contexts (ASP.NET, UI) |
| Pass `CancellationToken` as last param | Propagate from caller to every I/O call |
| Await every `Task` returned | Suppress only with explicit `_ = FireAndForget()` and a reason |
| Don't `await` in a `finally` block | Use `IAsyncDisposable` instead |
## ConfigureAwait
```csharp
// Library code — always use ConfigureAwait(false) to avoid deadlocks
public async Task<Data> LoadAsync(CancellationToken ct = default)
{
var raw = await _client.GetAsync(url, ct).ConfigureAwait(false);
return await ParseAsync(raw, ct).ConfigureAwait(false);
}
// Application code (ASP.NET Core, console) — omit ConfigureAwait(false)
// ASP.NET Core has no SynchronizationContext so it doesn't matter, but
// omitting is conventional in app code.
```
## ValueTask vs Task
| Scenario | Use |
|----------|-----|
| Result is usually available synchronously (cache hit, memory) | `ValueTask<T>` |
| Always async (network, disk I/O) | `Task<T>` |
| Fire-and-forget | `Task` (never `void`) |
| Hot path, allocation-sensitive, sync fast-path | `ValueTask` |
```csharp
// ValueTask — avoid awaiting more than once or storing for later
public ValueTask<int> ReadCachedAsync(string key, CancellationToken ct = default)
{
if (_cache.TryGetValue(key, out var val))
return ValueTask.FromResult(val); // no allocation on cache hit
return new ValueTask<int>(FetchFromDbAsync(key, ct));
}
```
Never call `.Result` on a `ValueTask`; never await a `ValueTask` more than once.
## CancellationToken
```csharp
// Accept as last param with default
public async Task ProcessAsync(string input, CancellationToken ct = default)
{
ct.ThrowIfCancellationRequested(); // fast check before work
var result = await _service.CallAsync(input, ct).ConfigureAwait(false);
await _store.SaveAsync(result, ct).ConfigureAwait(false);
}
// Link timeouts with cancellation
using var cts = CancellationTokenSource.CreateLinkedTokenSource(externalCt);
cts.CancelAfter(TimeSpan.FromSeconds(30));
await ProcessAsync(data, cts.Token);
```
## IAsyncEnumerable\<T\>
```csharp
// Producer — yield inside async method
public async IAsyncEnumerable<Record> StreamAsync(
[EnumeratorCancellation] CancellationToken ct = default)
{
await foreach (var batch in _db.ReadBatchesAsync(ct))
foreach (var item in batch)
yield return item;
}
// Consumer
await foreach (var record in source.StreamAsync(ct))
await ProcessAsync(record, ct);
```
`[EnumeratorCancellation]` lets callers pass a token via `.WithCancellation(ct)` on the consumer side.
## Parallelism
```csharp
// Concurrent independent tasks — collect then await all
var taskA = _svc.GetA(ct);
var taskB = _svc.GetB(ct);
await Task.WhenAll(taskA, taskB);
var (a, b) = (taskA.Result, taskB.Result); // safe after WhenAll
// Bounded parallel with Parallel.ForEachAsync (.NET 6+)
await Parallel.ForEachAsync(items, new ParallelOptions
{
MaxDegreeOfParallelism = Environment.ProcessorCount,
CancellationToken = ct
}, async (item, innerCt) =>
{
await ProcessAsync(item, innerCt).ConfigureAwait(false);
});
```
## Common Anti-patterns
| Anti-pattern | Fix |
|-------------|-----|
| `async Task Foo() { return await Bar(); }` | `Task Foo() => Bar();` (drop async/await) |
| `Task.Run(() => Foo())` to go async | Expose truly async API; don't wrap sync code |
| `Task.Delay(0)` to yield | `await Task.Yield()` (explicit) |
| `new Task(...)` + `.Start()` | `Task.Run(...)` |
| Catching `TaskCanceledException` to swallow | Re-throw or handle intentionally |
| `async` lambda in `List.ForEach` | `foreach` loop with `await` |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |