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)
        .ConfigureAwait(false);
    return await response.Content.ReadAsStringAsync()
        .ConfigureAwait(false);
}
```

---

## 4. Async Streams (IAsyncEnumerable)

```csharp
public async IAsyncEnumerable<Data> GetDataStreamAsync(
    [EnumeratorCancellation] CancellationToken ct = default)
{
    await foreach (var item in _source.ReadAllAsync(ct))
    {
        yield return await ProcessAsync(item);
    }
}

// Consuming
await foreach (var data in GetDataStreamAsync(ct))
{
    Console.WriteLi