What are exception filters (catch ... when) in C#? How do they differ from catching and rethrowing, why do they keep the stack unwound state intact, and what are good and bad uses of them?

1. The two-pass model and where filters run

When an exception is thrown, the CLR:

1. Pass 1 (search): walks up the stack frame by frame. For each try region with handlers, it checks catch types and runs filter blocks for clauses with when. Nothing is unwound; finally blocks have not run. The first clause whose type matches and whose filter returns true is the chosen handler.
2. Pass 2 (unwind): unwinds from the throw site to the chosen handler's frame, running finally/fault blocks on the way, then runs the catch body.

If pass 1 finds no handler, the exception is unhandled; the runtime raises AppDomain.UnhandledException and terminates. Because pass 2 never ran, a crash dump taken at that moment contains the full original stack with all locals — the main diagnostic benefit of filters.

2. Filter execution order surprise

static void Inner()
{
    try { throw new InvalidOperationException(); }
    finally { Console.WriteLine("inner finally"); }
}

try { Inner(); }
catch (Exception) when (Print("filter")) { Console.WriteLine("catch"); }

// Output:
// filter
// inner finally
// catch

The filter runs before the inner finally. If the filter depends on state that the inner finally would reset (e.g. a flag, a lock release), it sees the pre-cleanup state. This is why filters must not assume cleanup has happened and shouldn't mutate shared state.

3. IL representation

A catch (T ex) when (cond) compiles to a filter block in the method's exception table:

.try { ... }
filter
{
    isinst T
    // if not T -> push 0
    // else evaluate cond -> push 0/1
    endfilter
}
{   // handler
    ...
}

The type test is part of the filter. VB.NET and F# have had filters since .NET 1.0; C# gained the syntax in C# 6, though the runtime always supported them.

4. Exceptions inside filters

If a filter throws, the runtime catches that exception internally and treats the filter as returning false, then continues searching. The new exception is not reported anywhere. A filter like when (ex.Data["Code"].ToString() == "X") that throws NRE when the key is missing will just never match — a silent bug. Write filters defensively: when (ex.Data["Code"] is "X").

5. Interaction with async

In async methods, exceptions from awaited tasks are rethrown at the await (via ExceptionDispatchInfo), and filters on enclosing catches run then. The "unwound" state is relative to the async method's current frame — the original synchronous stack of the task's execution is already gone, but the preserved stack trace text is intact. Filters still avoid creating an additional rethrow site in your method.

6. Debugging with filters

• Visual Studio's "break when thrown" (first-chance) stops at the original throw. With catch-and-rethrow, it can stop twice.
• dotnet-dump analyze on a crash dump: clrstack -a shows locals of each frame; with filters (no catch), frames from the original throw remain.
• Azure App Service and Application Insights snapshot debugging capture snapshots at the throw site when exceptions are first thrown; fewer catch/rethrow layers mean clearer snapshots.

7. Pattern: transient error classification

static bool IsTransient(Exception ex) => ex switch
{
    HttpRequestException { StatusCode: HttpStatusCode.TooManyRequests or >= HttpStatusCode.InternalServerError } => true,
    HttpRequestException { StatusCode: null } => true,          // network failure, no response
    SqlException sql => sql.Number is 1205 or -2 or 40613 or 40501 or 49918,  // deadlock, timeout, Azure SQL throttling
    TimeoutException => true,
    _ => false
};

catch (Exception ex) when (attempt < 3 && IsTransient(ex))
{
    await Task.Delay(Backoff(attempt), ct);
}

In production I'd usually let a resilience pipeline (Polly / Microsoft.Extensions.Http.Resilience) handle retries, with the same classification as its ShouldHandle predicate.

Try it yourself

1. Run the filter-vs-finally example and confirm the output order.
2. Write a filter that throws and observe that the catch is silently skipped.
3. Compare a crash dump (or Visual Studio exception helper) for catch-and-rethrow vs filter.
4. Implement the logging filter pattern and check that the exception still reaches the global handler.

using System.Net;
using Microsoft.Data.SqlClient;

// 1. Catch only what you can handle
for (int attempt = 1; ; attempt++)
{
    try
    {
        await repository.SaveAsync(order, ct);
        break;
    }
    catch (SqlException ex) when (ex.Number is 1205 or -2 && attempt < 3)   // deadlock or timeout
    {
        await Task.Delay(TimeSpan.FromMilliseconds(100 * attempt), ct);
    }
}

// 2. Branch on HTTP status without catching everything
try
{
    return await http.GetFromJsonAsync<Product>($"products/{id}", ct);
}
catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    return null;
}

// 3. Do not treat shutdown as an error
try
{
    await worker.RunAsync(ct);
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
    logger.LogError(ex, "Worker failed");
    throw;
}

// 4. Log with the stack still intact, without handling
try
{
    Process();
}
catch (Exception ex) when (LogAndReturnFalse(ex))
{
    // never reached
}

bool LogAndReturnFalse(Exception ex)
{
    logger.LogError(ex, "Unhandled in Process");
    return false;
}