.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

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

• 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); }

5. Cancellation Token

public async Task<Data> LoadDataAsync(CancellationToken ct = default) { ct.ThrowIfCancellationRequested(); return await _httpClient.GetFromJsonAsync<Data>(url, ct); }

// Setting timeout using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30)); await LongRunningOperationAsync(cts.Token);

6. Concurrency Control

private readonly SemaphoreSlim _semaphore = new(maxCount: 10);

public async Task ProcessWithThrottlingAsync(Data data) { await _semaphore.WaitAsync(); try { await ProcessAsync(data); } finally { _semaphore.Release(); } }

7. Anti-patterns

// ❌ No async void (cannot handle exceptions) public async void BadMethod() { }

// ✅ async Task public async Task GoodMethod() { }

// ❌ No .Result, .Wait() (deadlock risk) var result = GetDataAsync().Result;

// ✅ Use await var result = await GetDataAsync();

// ❌ Unnecessary async/await public async Task<Data> GetDataAsync() { return await _repository.GetAsync(); }

// ✅ Direct return public Task<Data> GetDataAsync() { return _repository.GetAsync(); }

8. References

• Task-based Asynchronous Pattern

• ValueTask