handling-async-operations

# .NET Asynchronous Programming A guide for APIs and patterns for efficient asynchronous programming. **Quick Reference:** See [QUICKREF.md](QUICKREF.md) for essential patterns at a glance. ## 1. Core APIs | API | Purpose | |-----|---------| | `Task` | Async operation (no return value) | | `Task<T>` | Async operation (with return value) | | `ValueTask<T>` | Optimization for high-frequency calls | | `IAsyncEnumerable<T>` | Async streams | --- ## 2. Task vs ValueTask ### 2.1 When to Use Task<T> - Most async operations - When actual async work always occurs ### 2.2 When to Use ValueTask<T> - When synchronous completion is frequent (cache hits) - High-frequency call methods ```csharp // Use ValueTask when cache hits are frequent public ValueTask<Data> GetDataAsync(string key) { if (_cache.TryGetValue(key, out var cached)) { // Synchronous return (no Heap allocation) return new ValueTask<Data>(cached); } // When async work is needed return new ValueTask<Data>(LoadFromDbAsync(key)); } ``` ### 2.3 ValueTask Cautions ```csharp // ❌ Bad example: Awaiting ValueTask multiple times var task = GetDataAsync("key"); var result1 = await task; var result2 = await task; // May cause error! // ✅ Good example: Await only once var result = await GetDataAsync("key"); ``` --- ## 3. ConfigureAwait ```csharp // Use ConfigureAwait(false) in libraries public async Task<string> FetchDataAsync() { var response = await _httpClient.GetAsync(url) ...