csharp-async

C# Async Programming Best Practices

Your goal is to help me follow best practices for asynchronous programming in C#.

Naming Conventions

• Use the 'Async' suffix for all async methods
• Match method names with their synchronous counterparts when applicable (e.g., GetDataAsync() for GetData())

Return Types

• Return Task<T> when the method returns a value
• Return Task when the method doesn't return a value
• Consider ValueTask<T> for high-performance scenarios to reduce allocations
• Avoid returning void for async methods except for event handlers

Exception Handling

• Use try/catch blocks around await expressions
• Avoid swallowing exceptions in async methods
• In library/reusable code, use ConfigureAwait(false) to prevent deadlocks caused by synchronization context capture. Frameworks without a synchronization context (e.g., ASP.NET Core) typically do not require it, but UI frameworks such as WPF, WinForms, and MAUI do have a synchronization context and may benefit from it in application code as well.
• In non-async methods that return Task, use Task.FromException() to propagate errors; in genuine async Task methods, simply throw — the runtime wraps the exception in the returned Task automatically.

Performance

• Use Task.WhenAll() for parallel execution of multiple tasks
• Use Task.WhenAny() for implementing timeouts or taking the first completed task
• Avoid unnecessary async/await when simply passing through task results
• Consider cancellation tokens for long-running operations

Common Pitfalls

• Never use .Wait(), .Result, or .GetAwaiter().GetResult() in async code
• Avoid mixing blocking and async code
• Don't create async void methods (except for event handlers)
• Always await Task-returning methods

Implementation Patterns

• Implement the async command pattern for long-running operations
• Use async streams (IAsyncEnumerable<T>) for processing sequences asynchronously
• Consider the task-based asynchronous pattern (TAP) for public APIs

When reviewing C# code I explicitly provide, identify occurrences of the patterns above and suggest targeted improvements. Do not modify files outside the scope of the code I share, and confirm with me before rewriting any method body.