C# async/await Complete Guide — Task, ValueTask, ConfigureAwait

// Synchronous — blocks a thread for the entire duration of the DB call
public Product GetProduct(int id)
{
    return _db.Products.Find(id)!; // Thread is stuck here waiting for DB
}
 
// Asynchronous — thread is freed while waiting for DB
public async Task<Product?> GetProductAsync(int id)
{
    return await _db.Products.FindAsync(id); // Thread returns to pool here
}

// Async method returning a value
public async Task<string> FetchUserNameAsync(int userId)
{
    var user = await _db.Users.FindAsync(userId);
    return user?.Name ?? "Unknown";
}
 
// Async method with no return value
public async Task SendWelcomeEmailAsync(string email)
{
    var message = BuildMessage(email);
    await _emailService.SendAsync(message);
}
 
// Calling async methods
var name = await FetchUserNameAsync(42);
await SendWelcomeEmailAsync("user@example.com");

// Task — no return value
public async Task ProcessOrderAsync(int orderId)
{
    var order = await _db.Orders.FindAsync(orderId)
        ?? throw new ArgumentException($"Order {orderId} not found");
 
    order.Status = OrderStatus.Processing;
    await _db.SaveChangesAsync();
    await _notificationService.NotifyAsync(order.UserId, "Order is processing");
}
 
// Task<T> — returns a value
public async Task<OrderSummary> GetOrderSummaryAsync(int orderId)
{
    var order = await _db.Orders
        .Include(o => o.Items)
        .FirstOrDefaultAsync(o => o.Id == orderId)
        ?? throw new KeyNotFoundException($"Order {orderId} not found");
 
    return new OrderSummary(order.Id, order.Items.Sum(i => i.Price), order.Status);
}

// Sequential — each awaits before the next starts (slow)
var user = await GetUserAsync(userId);         // Wait for this...
var orders = await GetOrdersAsync(userId);     // Then wait for this
var recommendations = await GetRecsAsync(userId); // Then this
 
// Concurrent — all start immediately, then wait for all (fast)
var userTask = GetUserAsync(userId);
var ordersTask = GetOrdersAsync(userId);
var recsTask = GetRecsAsync(userId);
 
await Task.WhenAll(userTask, ordersTask, recsTask);
 
var user = await userTask;
var orders = await ordersTask;
var recommendations = await recsTask;

// Complete when any task finishes — useful for timeouts
var dataTask = FetchDataAsync();
var timeoutTask = Task.Delay(TimeSpan.FromSeconds(5));
 
var completed = await Task.WhenAny(dataTask, timeoutTask);
 
if (completed == timeoutTask)
    throw new TimeoutException("Data fetch timed out after 5 seconds");
 
var data = await dataTask; // Safe to await — already completed

// Using Task<T> — always allocates a Task on the heap
public async Task<string?> GetCachedValueAsync(string key)
{
    if (_cache.TryGetValue(key, out var cached))
        return cached;  // Synchronous path still allocates a Task
 
    var value = await _redis.GetAsync(key);
    _cache.Set(key, value);
    return value;
}
 
// Using ValueTask<T> — no allocation on the synchronous (cache hit) path
public ValueTask<string?> GetCachedValueAsync(string key)
{
    if (_cache.TryGetValue(key, out var cached))
        return ValueTask.FromResult(cached);  // Zero allocation
 
    return FetchAndCacheAsync(key);  // Async path still uses Task internally
}
 
private async ValueTask<string?> FetchAndCacheAsync(string key)
{
    var value = await _redis.GetAsync(key);
    _cache.Set(key, value);
    return value;
}

// WRONG — ValueTask can only be awaited once
var vt = GetCachedValueAsync("key");
var result1 = await vt;  // OK
var result2 = await vt;  // UNDEFINED BEHAVIOR
 
// WRONG — Cannot await the same ValueTask from multiple places
// WRONG — Cannot .Result on a ValueTask safely
 
// RIGHT — Await immediately, or convert to Task if you need to reuse
var task = GetCachedValueAsync("key").AsTask();
var result1 = await task;
var result2 = await task;  // Safe with Task

// Without ConfigureAwait — captures and restores the synchronization context
public async Task<Data> GetDataAsync()
{
    var result = await httpClient.GetFromJsonAsync<Data>("/api/data");
    return result!;
}
 
// With ConfigureAwait(false) — no context capture, slightly faster
public async Task<Data> GetDataAsync()
{
    var result = await httpClient.GetFromJsonAsync<Data>("/api/data")
                                 .ConfigureAwait(false);
    return result!;
}

// NuGet library — always use ConfigureAwait(false)
public static class MyLibrary
{
    public static async Task<string> FetchAsync(string url)
    {
        using var client = new HttpClient();
        var response = await client.GetAsync(url).ConfigureAwait(false);
        var content = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
        return content;
    }
}

// None == ConfigureAwait(false); ContinueOnCapturedContext == ConfigureAwait(true)
await task.ConfigureAwait(ConfigureAwaitOptions.None);
 
// SuppressThrowing — await completes without throwing even if the task
// faulted or was canceled. Useful for "wait for cleanup, ignore its errors".
await task.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
 
// ForceYielding — never continue synchronously, even if already complete.
await task.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
 
// They compose:
await task.ConfigureAwait(
    ConfigureAwaitOptions.SuppressThrowing | ConfigureAwaitOptions.ForceYielding);

// DANGEROUS — exceptions are unobserved and crash the process
public async void LoadData()
{
    var data = await FetchAsync(); // Exception here kills the app
    Process(data);
}
 
// CORRECT — return Task so callers can observe exceptions
public async Task LoadDataAsync()
{
    var data = await FetchAsync();
    Process(data);
}
 
// async void is ONLY acceptable for event handlers
button.Click += async (sender, e) =>
{
    await DoWorkAsync(); // Event handlers must be void
};

// DEADLOCK in ASP.NET Classic / WinForms / WPF
public string GetData()
{
    return FetchDataAsync().Result;  // Blocks the current thread
    // FetchDataAsync tries to resume on this thread — DEADLOCK
}
 
// CORRECT — go async all the way
public async Task<string> GetDataAsync()
{
    return await FetchDataAsync();
}

// BUG — fire-and-forget, exceptions are silently swallowed
public async Task ProcessAsync()
{
    SaveToDatabase();  // Not awaited! Runs but errors are lost
    LogActivity();     // Also not awaited
}
 
// CORRECT
public async Task ProcessAsync()
{
    await SaveToDatabaseAsync();
    await LogActivityAsync();
}

// WRONG — can't await in constructor
public class DataService
{
    public DataService()
    {
        _data = await LoadDataAsync(); // Compile error
    }
}
 
// CORRECT — static factory method
public class DataService
{
    private readonly Data _data;
 
    private DataService(Data data) => _data = data;
 
    public static async Task<DataService> CreateAsync()
    {
        var data = await LoadDataAsync();
        return new DataService(data);
    }
}
 
// Usage
var service = await DataService.CreateAsync();

public async Task ProcessOrderAsync(int orderId)
{
    try
    {
        var order = await _db.Orders.FindAsync(orderId)
            ?? throw new KeyNotFoundException($"Order {orderId} not found");
 
        await _paymentService.ChargeAsync(order.TotalAmount);
        await _emailService.SendConfirmationAsync(order.CustomerEmail);
    }
    catch (PaymentException ex)
    {
        _logger.LogError(ex, "Payment failed for order {OrderId}", orderId);
        throw; // Re-throw to let the caller handle it
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Unexpected error processing order {OrderId}", orderId);
        throw;
    }
}

public async Task ProcessMultipleOrdersAsync(int[] orderIds)
{
    // Materialize with ToList() — this is load-bearing. Select is lazy, so
    // re-enumerating `tasks` in the catch block would call ProcessOrderAsync
    // AGAIN, starting every order a second time and inspecting fresh tasks that
    // haven't faulted yet. Enumerate once, here.
    var tasks = orderIds.Select(id => ProcessOrderAsync(id)).ToList();
 
    try
    {
        await Task.WhenAll(tasks);
    }
    catch (Exception)
    {
        // await threw only the first exception. Inspect the same materialized
        // task list to collect ALL of them.
        var allExceptions = tasks
            .Where(t => t.IsFaulted)
            .SelectMany(t => t.Exception!.InnerExceptions)
            .ToList();
 
        foreach (var ex in allExceptions)
            _logger.LogError(ex, "Order processing failed");
 
        throw;
    }
}

public async Task<List<Product>> GetProductsAsync(CancellationToken cancellationToken = default)
{
    return await _db.Products
        .Where(p => p.IsActive)
        .ToListAsync(cancellationToken);
}
 
// With timeout
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(10));
try
{
    var products = await GetProductsAsync(cts.Token);
}
catch (OperationCanceledException)
{
    _logger.LogWarning("GetProducts timed out after 10 seconds");
}

catch (TaskCanceledException ex) when (ex.InnerException is TimeoutException)
{
    // HttpClient.Timeout fired — not your caller's cancellation
}

// Producing an async stream
public async IAsyncEnumerable<Order> GetOrdersStreamAsync(
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    await foreach (var order in _db.Orders.AsAsyncEnumerable().WithCancellation(cancellationToken))
    {
        yield return order;
    }
}
 
// Consuming an async stream
await foreach (var order in GetOrdersStreamAsync(cancellationToken))
{
    await ProcessOrderAsync(order);
}

// Process up to 10 items at a time
var semaphore = new SemaphoreSlim(10);
 
var tasks = orderIds.Select(async id =>
{
    await semaphore.WaitAsync();
    try
    {
        return await ProcessOrderAsync(id);
    }
    finally
    {
        semaphore.Release();
    }
});
 
await Task.WhenAll(tasks);

// Initialize once, share across requests
public class ConfigService
{
    private readonly Lazy<Task<AppConfig>> _config;
 
    public ConfigService(IConfigLoader loader)
    {
        _config = new Lazy<Task<AppConfig>>(loader.LoadAsync);
    }
 
    public Task<AppConfig> GetConfigAsync() => _config.Value;
}