C# 6.0 Exception Filter and when Keyword

C# 6.0 introduces a new feature exception filter and a new keyword when. Many C# features/keywords are syntactic sugars, but exception filter/when keyword is not.

To examine this feature, a few helper methods can be created:

1
internal static partial class ExceptionFilter
2
{
3
    private static void A() => B();
4

5
    private static void B() => C();
6

7
    private static void C() => D();
8

9
    private static void D()
10
    {
11
        int localVariable1 = 1;
12
        int localVariable2 = 2;
13
        int localVariable3 = 3;
14
        int localVariable4 = 4;
15
        int localVariable5 = 5;
16
        throw new OperationCanceledException(nameof(ExceptionFilter));
17
    }
18

19
    private static bool Log(this object message, bool result = false)
20
    {
21
        Trace.WriteLine(message);
22
        return result;
23
    }
24
}

These methods can make up a call stack, with some local variables. The Log method can log a Exception object and return a specified bool value.

Syntax#

The when keyword works like if. A when condition is a predicate expression, which can be appended to a catch block. If the predicate expression is evaluated to be true, the associated catch block is executed; otherwise, the catch block is ignored.

1
private static void Filter()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (OperationCanceledException exception) when (string.Equals(nameof(ExceptionFilter), exception.Message, StringComparison.Ordinal))
8
    {
9
    }
10
}

In the earlier preview of C# 6.0, the if keyword was used. In the final release, if is replaced by when, because some improper format can make catch-if confusing, e.g.:

1
private static void Filter()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (OperationCanceledException exception)
8
 // {
9
        if (string.Equals(nameof(ExceptionFilter), exception.Message, StringComparison.Ordinal))
10
        {
11
        }
12
 // }
13
}

The above code format looks just like a if statement inside the catch block.

Now it is already March 2016, the MSDN document for C# exception filter still uses the if keyword in the examples:

Compilation#

Before C# 6.0, it is very common to catch an exception, then log or filter it, and re-throw:

1
private static void Catch()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (Exception exception)
8
    {
9
        exception.Log();
10
        throw;
11
    }
12
}

C# 6.0 provides a way to log or filter an exception before catching it:

1
private static void When()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (Exception exception) when (exception.Log())
8
    {
9
    }
10
}

Here the Log method will log the exception, and return false. So the catch block will not be executed.

ILSpy and ildasm (located in C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.6.1 Tools\) can be used to view the compiled IL. In the Catch method, the catch-log-throw pattern will be compiled to:

1
.method private hidebysig static void  Catch() cil managed
2
{
3
    .maxstack  2
4
    .locals init ([0] class [mscorlib]System.Exception exception)
5
    IL_0000:  nop
6
    .try
7
    {
8
        IL_0001:  nop
9
        IL_0002:  call       void Dixin.Console.Program::A()
10
        IL_0007:  nop
11
        IL_0008:  nop
12
        IL_0009:  leave.s    IL_0017
13
    }  // end .try
14
    catch [mscorlib]System.Exception
15
    {
16
        IL_000b:  stloc.0
17
        IL_000c:  nop
18
        IL_000d:  ldloc.0
19
        IL_000e:  ldc.i4.0
20
        IL_000f:  call       bool Dixin.Console.Program::Log(object,
21
                                                            bool)
22
        IL_0014:  pop
23
        IL_0015:  rethrow
24
    }  // end handler
25
    IL_0017:  ret
26
} // end of method Program::Catch

There is nothing new or surprising. And When method is compiled to:

1
.method private hidebysig static void  When() cil managed
2
{
3
    .maxstack  2
4
    .locals init ([0] class [mscorlib]System.Exception exception,
5
                [1] bool V_1)
6
    IL_0000:  nop
7
    .try
8
    {
9
        IL_0001:  nop
10
        IL_0002:  call       void Dixin.Console.Program::A()
11
        IL_0007:  nop
12
        IL_0008:  nop
13
        IL_0009:  leave.s    IL_002a
14

15
    }  // end .try
16
    filter
17
    {
18
        IL_000b:  isinst     [mscorlib]System.Exception
19
        IL_0010:  dup
20
        IL_0011:  brtrue.s   IL_0017
21

22
        IL_0013:  pop
23
        IL_0014:  ldc.i4.0
24
        IL_0015:  br.s       IL_0024
25

26
        IL_0017:  stloc.0
27
        IL_0018:  ldloc.0
28
        IL_0019:  ldc.i4.0
29
        IL_001a:  call       bool Dixin.Console.Program::Log(object,
30
                                                            bool)
31
        IL_001f:  stloc.1
32
        IL_0020:  ldloc.1
33
        IL_0021:  ldc.i4.0
34
        IL_0022:  cgt.un
35
        IL_0024:  endfilter
36
    }  // end filter
37
    {  // handler
38
        IL_0026:  pop
39
        IL_0027:  nop
40
        IL_0028:  rethrow
41
    }  // end handler
42
    IL_002a:  ret
43
} // end of method Program::When

The catch keyword is gone, and C# when condition is compiled to a IL filter block. In the filter block, it checks if the exception is of Exception type. If so, it calls the Log method. Apparently, exception filter is not syntactic sugar. It is a CLR feature.

Runtime: stack unwinding#

The catch block and when predicate refers to the same exception object. In the following example:

1
internal static void Log()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (Exception exception) when (exception.Log(true))
8
    {
9
        exception.Log();
10
        throw;
11
    }
12
}

In the when predicate, the Log method returns true, so in the catch block, Log will be called again. These 2 Log calls print out exactly the same information:

System.OperationCanceledException: ExceptionFilter at Dixin.Common.ExceptionFilter.D() in D:\OneDrive\Works\Drafts\CodeSnippets\Dixin\Common\ExceptionFilter.cs 21 at Dixin.Common.ExceptionFilter.C() in D:\OneDrive\Works\Drafts\CodeSnippets\Dixin\Common\ExceptionFilter.cs 12 at Dixin.Common.ExceptionFilter.B() in D:\OneDrive\Works\Drafts\CodeSnippets\Dixin\Common\ExceptionFilter.cs 10 at Dixin.Common.ExceptionFilter.A() in D:\OneDrive\Works\Drafts\CodeSnippets\Dixin\Common\ExceptionFilter.cs 8 at Dixin.Common.ExceptionFilter.Log() in D:\OneDrive\Works\Drafts\CodeSnippets\Dixin\Common\ExceptionFilter.cs 91

Apparently, in both cases, the exception object’s StackTrace property has the call stack of A/B/C/D methods, as expected.

The real difference is the CLR stack (not the exception object’s StackTrace string property). To demonstrate this, set 2 breakpoints at 2 Log calls:

When the exception filter is executed:

The current stack (again, not the exception object’s StackTrace property) is:

ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.Log() Line 93 [Native to Managed Transition] ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.D() Line 21 ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.C() Line 12 ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.B() Line 10 ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.A() Line 8 ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.Log() Line 91 ConsoleApplication2.exe!Dixin.Console.Program.Main() Line 110

Next, when the catch block is executed:

The current stack becomes:

ConsoleApplication2.exe!Dixin.Common.ExceptionFilter.Log() Line 95 ConsoleApplication2.exe!Dixin.Console.Program.Main() Line 110

This magic here is called stack unwinding: exception filter does not unwind the stack, and catch block does unwind. When executing catch block, this catch block’s method becomes the top frame of the stack. As a result, all the methods called by current method are removed from the stack. In contrast, exception filter can be helpful for runtime debugging. For example, if above Catch method is executed:

1
private static void Catch()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (Exception exception)
8
    {
9
        exception.Log();
10
        throw;
11
    }
12
}

at runtime the debugger breaks at the throw statement in the catch block:

The stack is unwound. As a result the debugger cannot see the exception is actually thrown by D.

When executing the other When method:

1
private static void When()
2
{
3
    try
4
    {
5
        A();
6
    }
7
    catch (Exception exception) when (exception.Log())
8
    {
9
    }
10
}

The Log method always returns false, so that the stack will not be unwound by catch block. This time the debugger breaks in method D, where the exception is actually thrown:

Notice in the Locals windows and Call Stack window, all information are available for debugger.

Conclusion#

C# 6.0 exception filter and when keyword is not a syntactic sugar. It is a CLR feature. Unlike catch block, exception filter does not unwind the call stack, which is helpful at runtime.