Tratamento de Exceções Async em C# — O Guia Completo

public async Task<string> FetchDataAsync(string url)
{
    try
    {
        using var client = new HttpClient();
        // Se GetStringAsync lançar, a exceção é capturada na Task retornada.
        // Quando fazemos await, a exceção é relançada aqui.
        return await client.GetStringAsync(url);
    }
    catch (HttpRequestException ex)
    {
        _logger.LogError(ex, "Requisição HTTP falhou para {Url}", url);
        throw; // Relançar para preservar o stack trace original
    }
}

// RUIM: A exceção de ProcessAsync() nunca é observada.
// Sem crash, sem log, nada. O bug é invisível.
_ = ProcessAsync();
 
// MELHOR: No mínimo, adicione uma continuação para registrar falhas
Task.Run(ProcessAsync).ContinueWith(t =>
{
    if (t.IsFaulted)
        _logger.LogError(t.Exception, "Task em segundo plano falhou");
}, TaskContinuationOptions.OnlyOnFaulted);

public async Task DoWorkAsync(string input)
{
    // Esta ArgumentNullException é capturada na Task, NÃO lançada sincronamente.
    // O chamador deve fazer await na task para observá-la.
    if (input is null) throw new ArgumentNullException(nameof(input));
 
    await Task.Delay(100);
}
 
// O chamador vê a exceção apenas ao fazer await:
try
{
    await DoWorkAsync(null); // Exceção surge aqui
}
catch (ArgumentNullException ex)
{
    Console.WriteLine(ex.Message);
}

// Ponto de entrada público — síncrono, lança imediatamente em entrada inválida
public Task DoWorkAsync(string input)
{
    if (input is null) throw new ArgumentNullException(nameof(input));
    return DoWorkCoreAsync(input);
}
 
private async Task DoWorkCoreAsync(string input)
{
    await Task.Delay(100);
    // ... trabalho real
}

// PERIGOSO: A exceção não pode ser capturada pelos chamadores
private async void OnButtonClick(object sender, EventArgs e)
{
    await Task.Delay(100);
    throw new InvalidOperationException("Isso vai crashar o processo");
}
 
// Este bloco catch NÃO FAZ NADA para exceções de async void:
try
{
    OnButtonClick(this, EventArgs.Empty); // Retorna imediatamente (void)
}
catch (InvalidOperationException)
{
    // Nunca alcançado. A exceção foi elevada no SynchronizationContext.
}

// Aceitável: handler de evento, mas proteja todo o corpo
private async void OnButtonClick(object sender, EventArgs e)
{
    try
    {
        await LoadDataAsync();
        UpdateUI();
    }
    catch (Exception ex)
    {
        // Tratar graciosamente — não podemos deixar isso escapar
        MessageBox.Show($"Erro: {ex.Message}");
    }
}

// Interface que você não pode mudar
public interface IProcessor
{
    void Process(string data);
}
 
// Implementação que precisa de trabalho async
public class DataProcessor : IProcessor
{
    // Padrão: fire-and-forget mas trata exceções inline
    public void Process(string data)
    {
        // NÃO torne este método async void.
        // Em vez disso, inicie a task e adicione tratamento de erros.
        _ = ProcessInternalAsync(data).ContinueWith(
            t => _logger.LogError(t.Exception, "Processamento falhou para {Data}", data),
            TaskContinuationOptions.OnlyOnFaulted
        );
    }
 
    private async Task ProcessInternalAsync(string data)
    {
        await Task.Delay(50);
        // trabalho async real
    }
}

var tasks = new[]
{
    Task.FromException(new ArgumentException("Erro A")),
    Task.FromException(new InvalidOperationException("Erro B")),
    Task.FromException(new TimeoutException("Erro C")),
};
 
try
{
    await Task.WhenAll(tasks); // Apenas ArgumentException ("Erro A") é relançada!
}
catch (Exception ex)
{
    // ex é ArgumentException — Erro B e Erro C ficam inalcançáveis
    // porque nunca guardamos uma referência à task combinada
    Console.WriteLine(ex.Message); // "Erro A"
}

public async Task ProcessAllAsync(IEnumerable<string> items)
{
    var tasks = items.Select(ProcessItemAsync).ToList();
 
    // Guardar a task agregada antes de fazer await
    var allTasks = Task.WhenAll(tasks);
 
    try
    {
        await allTasks;
    }
    catch
    {
        // allTasks.Exception é o AggregateException completo com TODAS as exceções internas
        if (allTasks.Exception is not null)
        {
            foreach (var inner in allTasks.Exception.InnerExceptions)
            {
                _logger.LogError(inner, "Task falhou: {Message}", inner.Message);
            }
        }
 
        // Relançar ou tratar conforme necessário
        throw;
    }
}

// Tasks filhas anexadas são a fonte clássica de agregados genuinamente aninhados
var parent = Task.Factory.StartNew(() =>
{
    Task.Factory.StartNew(
        () => throw new InvalidOperationException("da filha anexada"),
        TaskCreationOptions.AttachedToParent);
});
 
try
{
    parent.Wait();
}
catch (AggregateException ex)
{
    // ex.InnerExceptions[0] é OUTRO AggregateException — não o erro real.
    // Flatten() colapsa a hierarquia para uma lista plana de InnerExceptions:
    foreach (var inner in ex.Flatten().InnerExceptions)
    {
        Console.WriteLine($"{inner.GetType().Name}: {inner.Message}"); // InvalidOperationException
    }
}

public async Task<(List<T> Results, List<Exception> Errors)> WhenAllSafeAsync<T>(
    IEnumerable<Task<T>> tasks)
{
    // Envolver cada task para que nunca falhe — captura sucesso ou falha
    var safeTasks = tasks
        .Select(async t =>
        {
            try
            {
                return (Value: await t, Error: (Exception?)null);
            }
            catch (Exception ex)
            {
                return (Value: default(T)!, Error: ex);
            }
        })
        .ToList();
 
    var outcomes = await Task.WhenAll(safeTasks);
 
    var results = outcomes
        .Where(o => o.Error is null)
        .Select(o => o.Value)
        .ToList();
 
    var errors = outcomes
        .Where(o => o.Error is not null)
        .Select(o => o.Error!)
        .ToList();
 
    return (results, errors);
}

var pending = Task.Delay(5_000).ContinueWith(_ => "resultado lento");
var alreadyFaulted = Task.FromException<string>(new InvalidOperationException("falha rápida"));
 
// winner É alreadyFaulted — WhenAny significa "primeira concluída", e uma falha
// conclui imediatamente. Note que este await NÃO lançou.
var winner = await Task.WhenAny(pending, alreadyFaulted);
 
// A exceção aparece apenas quando você faz await no próprio vencedor
try
{
    var result = await winner;
    Console.WriteLine(result);
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Vencedor falhou: {ex.Message}");
}
// Nota: as outras tasks ainda estão executando! Suas exceções ficam não observadas
// a menos que você as trate explicitamente.

public async Task<string> RaceWithFallbackAsync(CancellationToken ct)
{
    var primary = FetchFromPrimaryAsync(ct);
    var secondary = FetchFromSecondaryAsync(ct);
 
    var first = await Task.WhenAny(primary, secondary);
 
    // Observar a outra task para prevenir avisos de exceção não observada
    _ = first == primary
        ? secondary.ContinueWith(t => { /* ignorar ou registrar */ }, ct)
        : primary.ContinueWith(t => { /* ignorar ou registrar */ }, ct);
 
    // Lançará se first falhou
    return await first;
}

public record TaskOutcome<T>(T? Value, Exception? Error, string TaskId);
 
public async Task<IReadOnlyList<TaskOutcome<T>>> RunAllAsync<T>(
    IReadOnlyList<(string Id, Func<Task<T>> Factory)> work)
{
    var tasks = work.Select(async item =>
    {
        try
        {
            var value = await item.Factory();
            return new TaskOutcome<T>(value, null, item.Id);
        }
        catch (Exception ex)
        {
            return new TaskOutcome<T>(default, ex, item.Id);
        }
    });
 
    return await Task.WhenAll(tasks);
}
 
// Uso:
var outcomes = await RunAllAsync(new[]
{
    ("user-1", () => FetchUserAsync(1)),
    ("user-2", () => FetchUserAsync(2)),
    ("user-3", () => FetchUserAsync(3)),
});
 
var successful = outcomes.Where(o => o.Error is null).ToList();
var failed = outcomes.Where(o => o.Error is not null).ToList();
 
foreach (var failure in failed)
    _logger.LogError(failure.Error, "Falhou ao buscar {TaskId}", failure.TaskId);

using System.Runtime.ExceptionServices;
 
public class ExceptionRelay
{
    private ExceptionDispatchInfo? _captured;
 
    public void CaptureException(Action work)
    {
        try
        {
            work();
        }
        catch (Exception ex)
        {
            // Captura a exceção E seu stack trace completo neste ponto
            _captured = ExceptionDispatchInfo.Capture(ex);
        }
    }
 
    public void Rethrow()
    {
        // Relança com o stack trace ORIGINAL preservado: o trace mantém os frames
        // de onde a exceção foi lançada pela primeira vez, com este ponto de
        // relançamento acrescentado depois deles.
        _captured?.Throw();
    }
}

public async Task ProcessWithRetryAsync(Func<Task> operation, int maxRetries)
{
    ExceptionDispatchInfo? lastException = null;
 
    for (int attempt = 0; attempt < maxRetries; attempt++)
    {
        try
        {
            await operation();
            return; // Sucesso
        }
        catch (Exception ex) when (IsTransient(ex))
        {
            // Capture preserva o stack trace de cada tentativa
            lastException = ExceptionDispatchInfo.Capture(ex);
            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
        }
    }
 
    // Todas as tentativas esgotadas — relança com stack trace original
    lastException!.Throw();
}

public async Task ExecuteWithFilterAsync()
{
    try
    {
        await RiskyOperationAsync();
    }
    // Captura apenas erros HTTP transitórios — outros propagam normalmente
    catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.ServiceUnavailable)
    {
        await HandleServiceUnavailableAsync();
    }
    // Captura apenas uma mensagem específica — útil durante depuração
    catch (InvalidOperationException ex) when (ex.Message.Contains("timeout"))
    {
        await HandleTimeoutAsync();
    }
    // Captura tudo MAS registra para diagnóstico sem capturar permanentemente
    catch (Exception ex) when (LogAndRethrow(ex))
    {
        // Este bloco não é alcançável se LogAndRethrow sempre retorna false
    }
}
 
// Padrão útil: log-and-rethrow via filtro de exceção
// O filtro executa ANTES de o stack ser desfeito, dando um trace completo
private bool LogAndRethrow(Exception ex)
{
    _logger.LogError(ex, "Exceção em ExecuteWithFilterAsync");
    return false; // Retornar false significa que a exceção NÃO é capturada
}

catch (SqlException ex) when (ex.Number == 1205) // Vítima de deadlock
{
    await RetryAfterDeadlockAsync();
}
 
catch (OperationCanceledException ex) when (ex.CancellationToken == _shutdownToken)
{
    // Captura apenas cancelamentos do NOSSO token, não de outros tokens
    _logger.LogInformation("Encerrando graciosamente");
}

public async Task DemonstrateTaskStatesAsync()
{
    var cts = new CancellationTokenSource();
    cts.Cancel();
 
    var canceledTask = Task.FromCanceled(cts.Token);
    var faultedTask = Task.FromException(new InvalidOperationException("boom"));
 
    Console.WriteLine(canceledTask.Status);  // Canceled
    Console.WriteLine(faultedTask.Status);   // Faulted
 
    try
    {
        await canceledTask;
    }
    catch (OperationCanceledException ex)
    {
        // ex.CancellationToken está preenchido — você pode verificar qual token cancelou
        Console.WriteLine($"Cancelado pelo token: {ex.CancellationToken == cts.Token}");
    }
}

public async Task<Result> ProcessWithCancellationAsync(
    string input, 
    CancellationToken ct)
{
    try
    {
        return await DoProcessAsync(input, ct);
    }
    catch (OperationCanceledException) when (ct.IsCancellationRequested)
    {
        // Esperado — o chamador solicitou cancelamento. Não é um erro.
        _logger.LogDebug("Processamento cancelado para input {Input}", input);
        return Result.Cancelled;
    }
    catch (OperationCanceledException ex)
    {
        // Um token DIFERENTE foi cancelado — ISSO É um erro inesperado
        _logger.LogWarning(ex, "Cancelamento inesperado");
        throw;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Erro inesperado processando {Input}", input);
        throw;
    }
}

var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
 
try
{
    var response = await _httpClient.GetAsync(url, cts.Token);
}
catch (TaskCanceledException ex)
{
    if (cts.Token.IsCancellationRequested)
    {
        // Pedimos cancelar — ou nosso timeout de 30s foi ativado
        throw new TimeoutException("Requisição expirou", ex);
    }
    // Token interno do HttpClient — normalmente não deveria chegar aqui
    throw;
}

// Program.cs — registrar no startup
TaskScheduler.UnobservedTaskException += (sender, args) =>
{
    // args.Exception é o AggregateException envolvendo as exceções não observadas
    foreach (var ex in args.Exception.InnerExceptions)
    {
        _logger.LogCritical(ex, "Exceção de task não observada");
    }
 
    // Chame SetObserved() para evitar que a exceção seja relançada
    // pelo thread do finalizador (o que crasharia o processo em versões antigas do .NET)
    args.SetObserved();
};

AppDomain.CurrentDomain.UnhandledException += (sender, args) =>
{
    var ex = args.ExceptionObject as Exception;
    // args.IsTerminating é true quando o runtime está prestes a abortar
    _logger.LogCritical(ex, "Exceção fatal não tratada. IsTerminating={IsTerminating}", 
        args.IsTerminating);
 
    // Descarregar logs sincronamente — o processo está encerrando
    Log.CloseAndFlush();
};

var builder = WebApplication.CreateBuilder(args);
// ... registro de serviços
 
var app = builder.Build();
 
// Handlers globais — registrar antes de app.Run()
AppDomain.CurrentDomain.UnhandledException += OnUnhandledException;
TaskScheduler.UnobservedTaskException += OnUnobservedTaskException;
 
app.Run();
 
static void OnUnhandledException(object sender, UnhandledExceptionEventArgs e)
{
    var logger = /* resolver do DI ou usar logger estático */;
    logger.LogCritical(e.ExceptionObject as Exception, "Exceção não tratada");
}
 
static void OnUnobservedTaskException(object? sender, UnobservedTaskExceptionEventArgs e)
{
    var logger = /* resolver do DI ou usar logger estático */;
    logger.LogError(e.Exception, "Exceção de task não observada");
    e.SetObserved();
}

public class ExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionHandlingMiddleware> _logger;
 
    public ExceptionHandlingMiddleware(
        RequestDelegate next,
        ILogger<ExceptionHandlingMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }
 
    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (OperationCanceledException) when (context.RequestAborted.IsCancellationRequested)
        {
            // Cliente desconectou — não é um erro, sem necessidade de resposta
            _logger.LogDebug("Requisição cancelada pelo cliente: {Path}", context.Request.Path);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Exceção não tratada para {Method} {Path}",
                context.Request.Method,
                context.Request.Path);
 
            await WriteErrorResponseAsync(context, ex);
        }
    }
 
    private static async Task WriteErrorResponseAsync(HttpContext context, Exception ex)
    {
        // Não sobrescrever uma resposta que já começou a ser transmitida
        if (context.Response.HasStarted) return;
 
        context.Response.StatusCode = ex switch
        {
            ArgumentException => StatusCodes.Status400BadRequest,
            UnauthorizedAccessException => StatusCodes.Status401Unauthorized,
            KeyNotFoundException => StatusCodes.Status404NotFound,
            _ => StatusCodes.Status500InternalServerError
        };
 
        context.Response.ContentType = "application/json";
 
        var response = new
        {
            error = ex.Message,
            traceId = context.TraceIdentifier
        };
 
        await context.Response.WriteAsJsonAsync(response);
    }
}

// Program.cs
app.UseMiddleware<ExceptionHandlingMiddleware>();
 
// Ou use o UseExceptionHandler integrado para casos simples:
app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        var exceptionFeature = context.Features.Get<IExceptionHandlerFeature>();
        var ex = exceptionFeature?.Error;
 
        context.Response.StatusCode = 500;
        context.Response.ContentType = "application/json";
 
        await context.Response.WriteAsJsonAsync(new
        {
            error = "Ocorreu um erro inesperado",
            traceId = context.TraceIdentifier
        });
    });
});

public class AppExceptionHandler : IExceptionHandler
{
    private readonly ILogger<AppExceptionHandler> _logger;
 
    public AppExceptionHandler(ILogger<AppExceptionHandler> logger)
    {
        _logger = logger;
    }
 
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken)
    {
        _logger.LogError(exception, "Exceção ocorreu: {Message}", exception.Message);
 
        var (statusCode, title) = exception switch
        {
            ArgumentException => (StatusCodes.Status400BadRequest, "Bad Request"),
            KeyNotFoundException => (StatusCodes.Status404NotFound, "Not Found"),
            UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
            _ => (StatusCodes.Status500InternalServerError, "Internal Server Error")
        };
 
        var problemDetails = new ProblemDetails
        {
            Status = statusCode,
            Title = title,
            Detail = exception.Message,
            Instance = httpContext.Request.Path
        };
 
        httpContext.Response.StatusCode = statusCode;
        await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
 
        // Retornar true = exceção tratada, false = passar para o próximo handler
        return true;
    }
}
 
// Registro em Program.cs:
builder.Services.AddExceptionHandler<AppExceptionHandler>();
builder.Services.AddProblemDetails();
 
app.UseExceptionHandler();

public class ResilientApiClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<ResilientApiClient> _logger;
 
    public async Task<T?> GetAsync<T>(string endpoint, CancellationToken ct = default)
    {
        const int MaxRetries = 3;
        ExceptionDispatchInfo? lastCapture = null;
 
        for (int attempt = 1; attempt <= MaxRetries; attempt++)
        {
            try
            {
                using var response = await _httpClient.GetAsync(endpoint, ct);
                response.EnsureSuccessStatusCode();
                return await response.Content.ReadFromJsonAsync<T>(cancellationToken: ct);
            }
            catch (OperationCanceledException) when (ct.IsCancellationRequested)
            {
                // Chamador cancelou — parar de tentar imediatamente
                _logger.LogDebug("Requisição cancelada: {Endpoint}", endpoint);
                throw;
            }
            catch (HttpRequestException ex) when (IsRetryable(ex))
            {
                _logger.LogWarning(ex, "Tentativa {Attempt}/{Max} falhou para {Endpoint}",
                    attempt, MaxRetries, endpoint);
 
                // Preservar stack trace para o relançamento final
                lastCapture = ExceptionDispatchInfo.Capture(ex);
 
                if (attempt < MaxRetries)
                    await Task.Delay(TimeSpan.FromSeconds(attempt * 2), ct);
            }
        }
 
        // Todas as tentativas esgotadas — relançar com stack trace original
        lastCapture!.Throw();
        return default; // Inatingível, mas satisfaz o compilador
    }
 
    private static bool IsRetryable(HttpRequestException ex) =>
        ex.StatusCode is HttpStatusCode.ServiceUnavailable or HttpStatusCode.TooManyRequests
        || ex.StatusCode is null; // Falhas em nível de rede
}

public async Task<BatchResult<T>> ProcessBatchAsync<T>(
    IReadOnlyList<string> itemIds,
    Func<string, CancellationToken, Task<T>> processor,
    int concurrency = 10,
    CancellationToken ct = default)
{
    using var semaphore = new SemaphoreSlim(concurrency);
    var results = new ConcurrentBag<(string Id, T? Value, Exception? Error)>();
 
    var tasks = itemIds.Select(async id =>
    {
        await semaphore.WaitAsync(ct);
        try
        {
            var value = await processor(id, ct);
            results.Add((id, value, null));
        }
        catch (OperationCanceledException) when (ct.IsCancellationRequested)
        {
            throw; // Propagar cancelamento
        }
        catch (Exception ex)
        {
            // Isolar a falha — outros itens continuam sendo processados
            results.Add((id, default, ex));
        }
        finally
        {
            semaphore.Release();
        }
    });
 
    await Task.WhenAll(tasks);
 
    return new BatchResult<T>(
        Successes: results.Where(r => r.Error is null)
                          .Select(r => (r.Id, r.Value!))
                          .ToList(),
        Failures: results.Where(r => r.Error is not null)
                         .Select(r => (r.Id, r.Error!))
                         .ToList()
    );
}
 
public record BatchResult<T>(
    IReadOnlyList<(string Id, T Value)> Successes,
    IReadOnlyList<(string Id, Exception Error)> Failures
);