Exception Filters and the When Clause

The when clause on a catch block adds a condition — the exception is only caught if both the type matches AND the condition is true. This is more powerful than checking a condition inside the catch block because when filters are evaluated before the stack is unwound. If the condition is false, the exception continues searching for another handler, keeping the original stack trace intact. This matters for debugging: the exception is observable at its origin, not at some outer catch point.

Exception Filters with When #

// ── Basic when clause ─────────────────────────────────────────────────────
try
{
    await CallExternalApiAsync();
}
catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    // Only catches 404 Not Found — other HttpRequestExceptions propagate
    return null;
}
catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.ServiceUnavailable)
{
    // Only catches 503 Service Unavailable — retry or queue
    await Task.Delay(TimeSpan.FromSeconds(5));
    return await CallExternalApiAsync();
}
catch (HttpRequestException ex)
{
    // Catches all other HttpRequestExceptions
    throw new ExternalServiceException("External API call failed.", ex);
}

// ── Filter on error message ────────────────────────────────────────────────
catch (SqlException ex) when (ex.Message.Contains("Violation of UNIQUE constraint"))
{
    throw new ConflictException("An entry with this title already exists.");
}

// ── Logging filter (observe without catching) ─────────────────────────────
// when with a side-effect method — always returns false so exception propagates
catch (Exception ex) when (LogAndContinue(ex))
{
    // This block is never reached — LogAndContinue always returns false
    // But the exception IS logged before unwinding!
}

bool LogAndContinue(Exception ex)
{
    _logger.LogError(ex, "Exception observed: {Message}", ex.Message);
    return false;   // returning false means "don't catch this exception"
}

Retry Pattern with Exception Filters #

// Retry with exception filter — more expressive than nested try/catch
public async Task<T> RetryAsync<T>(
    Func<Task<T>> operation,
    int maxAttempts = 3,
    Predicate<Exception>? shouldRetry = null)
{
    int attempt = 0;
    while (true)
    {
        try
        {
            return await operation();
        }
        catch (Exception ex)
            when (attempt++ < maxAttempts - 1
                  && (shouldRetry?.Invoke(ex) ?? IsTransient(ex)))
        {
            int delayMs = (int)Math.Pow(2, attempt) * 100;
            _logger.LogWarning(ex,
                "Attempt {Attempt} failed — retrying in {Delay}ms", attempt, delayMs);
            await Task.Delay(delayMs);
        }
        // After maxAttempts, the exception propagates to the caller
    }
}

bool IsTransient(Exception ex) => ex is TimeoutException or HttpRequestException
    or { HResult: unchecked((int)0x80070005) };   // ACCESS_DENIED HRESULT

Common Mistakes #

Mistake 1 — Side-effecting when conditions (may run multiple times) #

❌ Wrong — retryCount may be incremented more than expected:

catch (Exception ex) when (++retryCount < 3)   // ++ in when condition — risky!

✅ Safer — use the post-increment pattern: when (retryCount++ < 3) which reads the value before incrementing.

Mistake 2 — Using when to check a condition that belongs inside the catch body #

❌ Wrong — when is the right tool when you want the exception to propagate if false; use a normal if when you always want to handle the exception:

✅ Correct — use when for conditional catching; use if inside catch for conditional behaviour after catching.