Csharp Async

Cancellation

• Propagate CancellationToken through the entire call chain.
• Call cancellationToken.ThrowIfCancellationRequested() in loops or before expensive operations.
• Make delays cancelable: await Task.Delay(ms, cancellationToken).
• For timeouts, use a linked CancellationTokenSource with CancelAfter rather than Task.WhenAny with a timer task.
• When cancellation is observed, let OperationCanceledException propagate; do not swallow it.

ConfigureAwait

• Use ConfigureAwait(false) in reusable library code and helper methods that do not need the original synchronization context.
• Omit ConfigureAwait in ASP.NET Core application code, which has no synchronization context by default.
• Omit ConfigureAwait in UI application code (WPF, WinForms, MAUI) when the continuation needs the UI thread.

Sync-Over-Async Prevention

• Never use .Wait(), .Result, or .GetAwaiter().GetResult() on a task in code that could run on a thread-pool or UI thread.
• If a synchronous API boundary is unavoidable, consider Task.Run as a last resort in desktop apps, and document why.
• In ASP.NET Core, there is no sync context — but blocking still wastes thread-pool threads and can cause starvation under load.

Exception Handling

• Catch exceptions at meaningful boundaries, not around every await.
• Do not swallow exceptions in async methods; log and rethrow or let them bubble.
• Use Task.FromException<T>() or ValueTask.FromException<T>() when returning a faulted task from a non-async method.
• Be aware that exceptions in async Task methods are captured in the returned task, while async void exceptions crash the process.

Parallel and Concurrent Execution

• Use Task.WhenAll() to await multiple independent tasks concurrently.
• Use Parallel.ForEachAsync() (.NET 6+) for data-parallel async work with a configurable degree of concurrency.
• Use Task.WhenAny() when racing tasks; always observe or cancel the losing tasks.
• Avoid creating excessive concurrent tasks without a concurrency limit.

Async Streams

• Use IAsyncEnumerable<T> and await foreach for sequences produced asynchronously.
• Pass [EnumeratorCancellation] CancellationToken to async iterator methods.
• Use WithCancellation(token) at the consumption site.
• Prefer yielding from an async iterator over collecting into a list and returning it.

Channel-Based Concurrency

• Use Channel<T> for producer-consumer patterns instead of BlockingCollection<T> in async code.
• Choose bounded channels with a back-pressure strategy (BoundedChannelFullMode) for load control.
• Use unbounded channels only when the producer rate is known to be safe.
• Complete the channel writer when production is finished so consumers can exit cleanly.

Async Disposal

• Implement IAsyncDisposable and dispose resources with await using when the cleanup involves I/O.
• In DisposeAsync, cancel ongoing work, flush buffers, and release async resources.
• When a type implements both IDisposable and IAsyncDisposable, prefer await using in async code paths.

Task Eliding

• When a method has no work after the awaited call and no using / try-finally, consider returning the task directly without async / await to avoid the state-machine overhead.
• Do not elide async / await when the method has a using statement, a try block, or disposes resources — the state machine is needed to keep the scope alive.

Performance Considerations

• Prefer ValueTask<T> over Task<T> only in hot paths where the result is cached or synchronously available most of the time.
• Do not cache or await a ValueTask more than once.
• Use Task.CompletedTask or ValueTask.CompletedTask to avoid allocations for synchronous completions.
• Use StringBuilder or pooling for I/O buffers in async loops rather than allocating per iteration.

Review Priorities

1. No sync-over-async patterns (.Result, .Wait(), .GetAwaiter().GetResult()).
2. CancellationToken is accepted and propagated where cancelable work exists.
3. Async methods return Task or ValueTask, never async void (except event handlers).
4. Resources are disposed with await using or using appropriately.
5. Concurrent work uses Task.WhenAll or bounded parallelism, not unbounded Task.Run loops.
6. ConfigureAwait(false) is used correctly in library code.

Completion Criteria

• All async methods follow naming conventions and return correct types.
• Cancellation flows through the call chain end-to-end.
• No sync-over-async or fire-and-forget patterns exist.
• Async streams and channels are used where they simplify producer-consumer flows.
• Exception handling is deliberate and does not swallow errors.
• Performance-sensitive patterns are applied only where measured beneficial.