handling-async-operations

.NET Asynchronous Programming

A guide for APIs and patterns for efficient asynchronous programming.

Quick Reference: See QUICKREF.md for essential patterns at a glance.

1. Core APIs

2. Task vs ValueTask

2.1 When to Use Task

• Most async operations
• When actual async work always occurs

2.2 When to Use ValueTask

• When synchronous completion is frequent (cache hits)
• High-frequency call methods

// 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

// ❌ 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

// 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)

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.WriteLine(data);
}