ConfigureAwait(false) em C# — A Explicação Completa

// Code-behind do WPF — ConfigureAwait(true) é o padrão
private async void Button_Click(object sender, RoutedEventArgs e)
{
    string result = await FetchDataAsync(); // suspende aqui
    // Retoma na thread de UI — seguro para tocar controles
    myLabel.Content = result;
}

string result = await FetchDataAsync().ConfigureAwait(false);
// Retoma em uma thread do pool — NÃO tocar controles de UI aqui

// --- Fluxo com ConfigureAwait(true) ---
// Thread: thread de UI (SynchronizationContext = DispatcherSynchronizationContext)
await Task.Delay(100);
// 1. DispatcherSynchronizationContext é capturado
// 2. Task.Delay conclui na thread do pool T2
// 3. T2 publica a continuação na fila do Dispatcher
// 4. Thread de UI a recolhe da fila
// Thread: thread de UI novamente ✓
 
// --- Fluxo com ConfigureAwait(false) ---
// Thread: thread de UI (SynchronizationContext = DispatcherSynchronizationContext)
await Task.Delay(100).ConfigureAwait(false);
// 1. SynchronizationContext intencionalmente NÃO é capturado
// 2. Task.Delay conclui na thread do pool T2
// 3. Continuação executa diretamente em T2 (sem ida e volta ao Dispatcher)
// Thread: thread do pool T2

// Método de biblioteca — NÃO usa ConfigureAwait(false)
public async Task<string> GetDataAsync()
{
    await Task.Delay(500); // captura AspNetSynchronizationContext
    return "hello";
}
 
// Action do controlador — bloqueia de forma síncrona (má prática, mas acontece)
public ActionResult Index()
{
    // .Result bloqueia a thread da requisição enquanto segura o bloqueio do contexto
    string data = GetDataAsync().Result; // DEADLOCK
    return Content(data);
}

public async Task<string> GetDataAsync()
{
    // NÃO tenta retornar ao AspNetSynchronizationContext
    await Task.Delay(500).ConfigureAwait(false);
    return "hello"; // executa em uma thread do pool — sem contexto necessário
}

// WPF: handler de clique que chama .Result (nunca faça isso em código real)
private void BadButton_Click(object sender, RoutedEventArgs e)
{
    // Thread de UI bloqueia, retém DispatcherSynchronizationContext
    string result = SomeLibraryMethod().Result; // deadlock se a biblioteca usa ConfigureAwait(true)
    myLabel.Content = result;
}
 
// Biblioteca — correto: usa ConfigureAwait(false) em todo lugar
public async Task<string> SomeLibraryMethod()
{
    var data = await HttpClient.GetStringAsync("https://example.com")
        .ConfigureAwait(false); // não tentará publicar de volta ao Dispatcher
    return data.ToUpper();
}

// Controlador do ASP.NET Core — ConfigureAwait(false) não tem efeito aqui
[HttpGet("data")]
public async Task<IActionResult> GetData()
{
    // Comportamento idêntico com ou sem ConfigureAwait(false)
    var result = await _service.FetchAsync();
    return Ok(result);
}

static async Task Main(string[] args)
{
    // Sem SynchronizationContext — ConfigureAwait(false) é redundante
    var data = await File.ReadAllTextAsync("input.txt").ConfigureAwait(false);
    Console.WriteLine(data);
}

// Bom código de biblioteca — agnóstico ao contexto em todo lugar
public class DataClient
{
    private readonly HttpClient _http;
 
    public DataClient(HttpClient http) => _http = http;
 
    public async Task<UserDto> GetUserAsync(int id)
    {
        // ConfigureAwait(false) em cada await — a biblioteca não possui o contexto
        var response = await _http.GetAsync($"/users/{id}").ConfigureAwait(false);
        response.EnsureSuccessStatusCode();
 
        var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
        return JsonSerializer.Deserialize<UserDto>(json)!;
    }
 
    public async Task<IReadOnlyList<OrderDto>> GetOrdersAsync(int userId)
    {
        var response = await _http.GetAsync($"/users/{userId}/orders").ConfigureAwait(false);
        response.EnsureSuccessStatusCode();
 
        await using var stream = await response.Content.ReadAsStreamAsync().ConfigureAwait(false);
        var orders = await JsonSerializer.DeserializeAsync<List<OrderDto>>(stream).ConfigureAwait(false);
        return orders ?? [];
    }
}

public async Task ExampleAsync()
{
    // Ainda no contexto original
    await FirstOperation().ConfigureAwait(false);
 
    // Agora na thread do pool — SynchronizationContext.Current é null
    // Este ConfigureAwait(true) é efetivamente igual a ConfigureAwait(false)
    // porque não há contexto para retornar
    await SecondOperation().ConfigureAwait(true); // redundante — sem contexto presente
    await ThirdOperation(); // também está correto — sem contexto para capturar
}

dotnet add package Microsoft.VisualStudio.Threading.Analyzers

// Aviso VSTHRD111: Use .ConfigureAwait(false) ao aguardar uma tarefa
var result = await SomeTaskAsync(); // ⚠ VSTHRD111

[*.cs]
dotnet_diagnostic.VSTHRD111.severity = error

dotnet add package Roslynator.Analyzers

[*.cs]
# CA2007: Considere chamar ConfigureAwait na tarefa aguardada
dotnet_diagnostic.CA2007.severity = warning

// ConfigureAwaitOptions.None == ConfigureAwait(false)
await task.ConfigureAwait(ConfigureAwaitOptions.None);
 
// ConfigureAwaitOptions.ContinueOnCapturedContext == ConfigureAwait(true)
await task.ConfigureAwait(ConfigureAwaitOptions.ContinueOnCapturedContext);
 
// Novo: conclui o await mesmo que a task tenha falhado ou sido cancelada — não
// relança a exceção. Só é válido em Task não genérica (uma Task<T> não teria
// resultado para te devolver).
await task.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
 
// Novo: sempre cede o controle, mesmo que a task já tenha concluído — o await nunca
// continua sincronamente. Útil para forçar justiça ou sair de um caminho com lock.
await task.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
 
// São flags, então se combinam:
await task.ConfigureAwait(
    ConfigureAwaitOptions.SuppressThrowing | ConfigureAwaitOptions.ForceYielding);

<!-- Directory.Build.props — aplica a todos os projetos na árvore de diretório -->
<Project>
  <PropertyGroup>
    <!-- Tratar ConfigureAwait faltante como erro de compilação em todo o repositório -->
    <WarningsAsErrors>$(WarningsAsErrors);CA2007</WarningsAsErrors>
    <EnableNETAnalyzers>true</EnableNETAnalyzers>
    <AnalysisMode>All</AnalysisMode>
  </PropertyGroup>
</Project>

// NÃO faça isso por "performance" no ASP.NET Core — adiciona ruído sem benefício
public async Task<string> GetDataAsync()
{
    return await _cache.GetAsync("key").ConfigureAwait(false); // inútil no ASP.NET Core
}

public async Task DemonstrateExceptionAsync()
{
    try
    {
        // Exceção lançada dentro de FetchAsync é relançada aqui,
        // independentemente de ConfigureAwait
        await FetchAsync().ConfigureAwait(false);
    }
    catch (HttpRequestException ex)
    {
        // Ainda é capturada — ConfigureAwait não afeta o fluxo de exceções
        _logger.LogError(ex, "Fetch failed");
        throw;
    }
}

public class WeatherApiClient
{
    private readonly HttpClient _http;
    private readonly ILogger<WeatherApiClient> _logger;
 
    public WeatherApiClient(HttpClient http, ILogger<WeatherApiClient> logger)
    {
        _http = http;
        _logger = logger;
    }
 
    public async Task<WeatherForecast?> GetForecastAsync(
        string city,
        CancellationToken cancellationToken = default)
    {
        // Código de biblioteca: ConfigureAwait(false) em cada await
        var url = $"/api/weather?city={Uri.EscapeDataString(city)}";
 
        using var response = await _http
            .GetAsync(url, cancellationToken)
            .ConfigureAwait(false);
 
        if (!response.IsSuccessStatusCode)
        {
            _logger.LogWarning("Weather API returned {StatusCode}", response.StatusCode);
            return null;
        }
 
        await using var stream = await response.Content
            .ReadAsStreamAsync(cancellationToken)
            .ConfigureAwait(false);
 
        return await JsonSerializer
            .DeserializeAsync<WeatherForecast>(stream, cancellationToken: cancellationToken)
            .ConfigureAwait(false);
    }
}

public class MainViewModel : INotifyPropertyChanged
{
    private string _status = string.Empty;
    public string Status
    {
        get => _status;
        set { _status = value; OnPropertyChanged(); }
    }
 
    public async Task LoadDataAsync()
    {
        // Await simples, deliberadamente: este método define estado vinculado à UI
        // depois, então precisa voltar à thread de UI. Os ConfigureAwait(false) vão
        // DENTRO de _apiClient (código de biblioteca) — a fronteira entre "I/O sem
        // contexto" e "atualização de UI com contexto" é a fronteira da API,
        // não uma linha deste método.
        var data = await _apiClient.GetForecastAsync("London");
 
        // Retomado na thread de UI — seguro tocar estado vinculado
        Status = data?.Summary ?? "Sem dados";
    }
}

public class UserRepository
{
    private readonly AppDbContext _context;
 
    public UserRepository(AppDbContext context) => _context = context;
 
    public async Task<User?> GetByIdAsync(int id, CancellationToken ct = default)
    {
        // EF Core suporta ConfigureAwait(false) — seguro em código de biblioteca
        return await _context.Users
            .AsNoTracking()
            .FirstOrDefaultAsync(u => u.Id == id, ct)
            .ConfigureAwait(false);
    }
 
    public async Task<int> CreateUserAsync(User user, CancellationToken ct = default)
    {
        _context.Users.Add(user);
        await _context.SaveChangesAsync(ct).ConfigureAwait(false);
        return user.Id;
    }
}