C# async/await best practices

undaries in the same call stack. If a method performs I/O, database queries, or network calls, mark it async and return Task or ValueTask. Propagate the async signature up to the entry point (controller, background service, or event handler).

// Anti-pattern
public User GetUser(int id)
{
    return _repository.GetAsync(id).Result; // Blocks thread pool
}

// Correct pattern
public async Task<User> GetUserAsync(int id)
{
    return await _repository.GetAsync(id);
}

Step 2: ConfigureAwait Strategy

Library and middleware code must use ConfigureAwait(false) to prevent synchronization context capture. Application layers (UI, ASP.NET Core controllers) may omit it, as the framework manages request context automatically.

public async Task<HttpResponseMessage> FetchDataAsync(HttpClient client, string url)
{
    // Library code: avoid capturing SynchronizationContext
    var response = await client.GetAsync(url).ConfigureAwait(false);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsByteArrayAsync().ConfigureAwait(false);
}

Step 3: Cancellation Token Propagation

Every async I/O operation must accept and propagate CancellationToken. Chain tokens using CancellationTokenSource.CreateLinkedTokenSource when combining user-initiated and system-initiated cancellation.

public async Task<Report> GenerateReportAsync(int id, CancellationToken ct = default)
{
    using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(ct, _appLifetime.ApplicationStopping);
    
    var data = await _db.QueryAsync(id, linkedCts.Token);
    var rendered = await _renderer.RenderAsync(data, linkedCts.Token);
    
    return await _storage.SaveAsync(rendered, linkedCts.Token);
}

Step 4: Exception Boundaries and State Machine Safety

async methods catch exceptions and store them in the returned Task. Never use async void outside of event handlers. Wrap async operations in explicit try/catch blocks where business logic requires error translation or fallback.

public async Task ProcessPaymentAsync(PaymentRequest request, CancellationToken ct)
{
    try
    {
        var result = await _gateway.ChargeAsync(request, ct);
        await _audit.LogAsync(result, ct);
    }
    catch (PaymentGatewayException ex) when (ex.IsRetryable)
    {
        await _retryPolicy.ExecuteAsync(async () => 
            await _gateway.ChargeAsync(request, ct), ct);
    }
}

Step 5: I/O vs CPU-Bound Separation

Use async/await exclusively for I/O-bound work. For CPU-intensive operations, use Task.Run only when necessary, and prefer Parallel.ForEachAsync or IAsyncEnumerable for stream processing.

// I/O-bound: async/await
public async Task<string> FetchFromApiAsync() => await _http.GetStringAsync();

// CPU-bound: Task.Run (use sparingly)
public Task<byte[]> ComputeHashAsync(byte[] data) => 
    Task.Run(() => SHA256.HashData(data));

Architecture Decisions and Rationale

• Prefer ValueTask for hot paths: When methods frequently complete synchronously (e.g., cache hits), ValueTask eliminates heap allocation overhead.
• Avoid lock with async: lock blocks threads and cannot span await boundaries. Use SemaphoreSlim for async-safe throttling.
• Centralize async configuration: Register HttpClient via IHttpClientFactory, configure default timeouts, and inject cancellation tokens through DI scopes.
• Treat async as a contract: Once a method is async, all callers must respect it. Breaking the chain introduces blocking or fire-and-forget anti-patterns.

Pitfall Guide

1. Blocking on Async Code (.Result, .Wait(), .GetAwaiter().GetResult())

Why it fails: Blocks the calling thread while the async operation waits for a thread to schedule its continuation. Under load, this exhausts the thread pool, causing cascading timeouts. Production fix: Replace all blocking calls with await. If forced by a synchronous interface, use Task.Run to offload to a background thread, but treat it as a migration bridge, not a solution.

2. async void in Non-Event Contexts

Why it fails: async void methods cannot be awaited, making exception handling impossible. Unhandled exceptions crash the process or silently corrupt state. Production fix: Restrict async void to UI event handlers. All other methods must return Task or ValueTask.

3. Ignoring CancellationToken Propagation

Why it fails: Abandoned requests continue executing, consuming CPU, memory, and database connections until timeout. This amplifies thread pool pressure and increases cloud costs. Production fix: Pass CancellationToken through every async call. Use HttpContext.RequestAborted in ASP.NET Core and _hostApplicationLifetime.ApplicationStopping in background services.

4. Missing ConfigureAwait(false) in Library Code

Why it fails: Captures the synchronization context, forcing continuations to marshal back to the original context. In ASP.NET Core, this is less critical, but in libraries, it causes deadlocks when called from sync contexts or unit tests. Production fix: Apply ConfigureAwait(false) to all await statements in shared libraries. Use the ConfigureAwaitChecker.Analyzer NuGet package to enforce compliance.

5. Swallowing Exceptions or Using Fire-and-Forget

Why it fails: Task.Run(() => DoAsync()) without awaiting discards exceptions and completion state. Failed operations appear successful, leading to data inconsistency. Production fix: Use BackgroundService with proper IHostedService lifecycle, or implement explicit fire-and-forget with unobserved exception handlers:

var task = DoAsync();
task.ContinueWith(t => LogError(t.Exception), TaskContinuationOptions.OnlyOnFaulted);

6. Mixing Synchronous and Asynchronous Disposal

Why it fails: IDisposable blocks during cleanup. If disposal involves I/O (closing connections, flushing buffers), it should be IAsyncDisposable. Mixing both creates resource leaks or deadlocks. Production fix: Implement IAsyncDisposable for resources requiring async cleanup. Use await using syntax and avoid synchronous Dispose calls on async resources.

7. Overusing Task.Run for I/O-Bound Work

Why it fails: Task.Run queues work to the thread pool. I/O operations do not require threads; they use OS-level completion ports. Wrapping I/O in Task.Run wastes threads and increases latency. Production fix: Use native async I/O APIs (HttpClient, FileStream.ReadAsync, DbCommand.ExecuteReaderAsync). Reserve Task.Run for CPU-bound calculations.

Production Bundle

Action Checklist

• Audit all .Result, .Wait(), and .GetAwaiter().GetResult() calls and replace with await
• Add ConfigureAwait(false) to all library-level async methods
• Propagate CancellationToken through every async I/O operation
• Replace async void with Task-returning methods in non-event contexts
• Implement IAsyncDisposable for resources requiring async cleanup
• Configure IHttpClientFactory with Polly retry policies and default timeouts
• Enable ConfigureAwaitChecker.Analyzer and Microsoft.VisualStudio.Threading.Analyzers in CI
• Validate async pipelines under load using k6 or Bombardier to detect thread pool starvation

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
ASP.NET Core API Controller	Full async pipeline, omit ConfigureAwait	Framework manages request context; blocking causes request queue saturation	Reduces P99 latency by 60-80%
Shared NuGet Library	ConfigureAwait(false) on all awaits	Prevents context capture and deadlocks in consuming applications	Eliminates 30%+ of production deadlock tickets
Background Worker / IHostedService	CancellationToken propagation + Task.Delay for polling	Ensures graceful shutdown and prevents orphaned operations	Lowers cloud compute costs by 15-25%
High-Throughput I/O Gateway	ValueTask + IAsyncEnumerable + SemaphoreSlim	Minimizes allocations and controls concurrency without thread pool exhaustion	Scales linearly; avoids horizontal scaling costs

Configuration Template

1. Analyzer Setup (Directory.Build.props)

<Project>
  <ItemGroup>
    <PackageReference Include="ConfigureAwaitChecker.Analyzer" Version="5.0.0" PrivateAssets="all" />
    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.10.48" PrivateAssets="all" />
  </ItemGroup>
</Project>

2. HttpClient Factory with Polly

builder.Services.AddHttpClient("ResilientClient", client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddPolicyHandler(Policy.TimeoutAsync<HttpResponseMessage>(TimeSpan.FromSeconds(10)))
.AddPolicyHandler(Policy.Handle<HttpRequestException>()
    .OrResult(msg => !msg.IsSuccessStatusCode)
    .WaitAndRetryAsync(3, retry => TimeSpan.FromMilliseconds(200 * Math.Pow(2, retry))));

3. BackgroundService Base with Cancellation

public abstract class AsyncBackgroundService : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await ProcessWorkAsync(stoppingToken);
            }
            catch (OperationCanceledException) { }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Background work failed");
            }

            await Task.Delay(1000, stoppingToken);
        }
    }

    protected abstract Task ProcessWorkAsync(CancellationToken ct);
}

Quick Start Guide

1. Install Analyzers: Add ConfigureAwaitChecker.Analyzer and Microsoft.VisualStudio.Threading.Analyzers to your solution. Set PrivateAssets="all" to avoid transitive pollution.
2. Configure IHttpClientFactory: Register named or typed clients in Program.cs. Attach Polly timeout and retry policies. Inject via constructor.
3. Refactor Entry Points: Convert controller actions and service methods to async Task. Replace all .Result/.Wait() with await. Add CancellationToken ct = default parameters.
4. Validate Under Load: Run a baseline load test using k6. Monitor thread pool queue length, CPU utilization, and P99 latency. Iterate until thread pool utilization stabilizes below 60% under peak load.