NDepend Blog

Improve your .NET code quality with NDepend

C# Pattern Matching Explained

April 11, 2024 7 minutes read


Since the C# version 7, C# has support for pattern matching. C# pattern matching is here to simplify complex if-else statements into more compact and readable code. Pattern matching does not aim at writing code that cannot be written without. Its only purpose is to have more concise and elegant code.

Also keep in mind while reading that Pattern matching expressions are compiled to regular IL code. This point will be detailed later.

I believe the only way to present pattern matching in a proper and complete way is to explain its evolution through C# versions. Else this is cumbersome to illustrate what can be expressed and what cannot. The present post will be updated with future C# evolutions.

C#7: Null, Constant, Type, Discard and Var Patterns

C#7 introduced checking against a null pattern and a constant pattern.

One limitation of pattern matching – also till the latest C# version- is that values embedded in a pattern must be constant. In practice often the values to check against are not hardcoded but retrieved from some configurations. This limitation makes pattern matching useless in a number of situations.


Notice that constant supported by patterns are:

  • an integer or floating-point numerical literal
  • a char or a string literal
  • a boolean value true or false
  • an enumeration value
  • the name of a declared const field or null

C#7 also introduced the type pattern, which is a great improvement, especially to introduce temporary variables in complex bool expressions:

Pattern matching works also with switch statements. This is especially useful to manage control flows through types that aren’t related by an inheritance hierarchy.

Notice the last default: clause that matches when seq is null. This is the discard pattern.

Notice also that the order of the case clauses matters. For example, since the class List<T> implements the interface ICollection<T>, the compiler is smart enough to prevent such mistake:


Also with switch statement the keyword when can be used to add additional conditions that refine the pattern:

Notice that the keyword when cannot be used in if statement -only in switch statement – even with the latest C# versions:


Finally C# 7 introduced the var pattern which is a special type pattern that matches even when null.

It is not recommended to use the var pattern to skip null check because an undefined null state is dangerous. Practically the var pattern is used in complex situations where anonymous types are involved.

C# 8: Switch Expressions and Property, Positional and Tuple Patterns

C#8 improved pattern matching in several ways. First, there is a switch expression:

Arguably the code is more readable because quite a lot of characters are saved here, no more case, no more variable declarations and bodies are expressions. Also compared to a regular expression switch, the compiler warns (but doesn’t emit an error) about not handled possible values. An exception is thrown at runtime when a switch expression reaches the end without a match.

Switch expression fits particularly well with expression-bodied members:

C#8 also introduced extremely useful property patterns.

Notice that:

  • The var pattern can be used to introduce variables to handle property values.
  • A property pattern requires the object reference to be not null. Hence empty property pattern { } is a test for null check.

If the rectangle has a deconstructor, the expression Rectangle { Width: var x, Height: var y } can be simplified to  Rectangle(var x, var y). This is the new C# 8 positional pattern.

Finally C#8 introduced the tuple pattern to test multiple values at the same time:

C# 9: Combinator, Parenthesized and Relational Patterns

C#9 introduced combinator patterns: conjunctive and, disjunctive or and negated not patterns. This is especially useful to avoid repeating a variable in a complex boolean expression.

The code sample above also illustrates the parenthesized pattern. Here you can remove the parenthesis but they make the logic clearer.

Notice that the new negated not pattern constitutes a new syntax for null check: if(obj is not null) { ... }

C#9 also introduced relational patterns < > <= >=.

The relational pattern fits especially well when used with a property pattern as shown by the code sample below. Also, this example illustrates a nice C#9 addition: you can omit the underscore symbol in type pattern for a lighter syntax:

C# 10: Extended Property Pattern

C# 10 introduced an extended property pattern which is useful to nest property calls as illustrated by the code sample below:

C# 11: List and Slice Pattern

C#11 introduced list pattern matching. For example array is [1, 2, 3]  will match an integer array of the length three with 1, 2, 3 as its elements, respectively. Notice that:

  • The new slice pattern .. matches any sequence of zero or more elements.
  • The discard pattern _ matches any single element.


  • the pattern [_, >0, ..] means array.Length >= 2 && array[1] > 0.
  • the pattern [.., <=0, _] means array.Length >= 2 && array[^2] <= 0.

Notice that the slice pattern can only appear at most once in a list pattern.  Two slice patterns cannot check if an array contains a particular item:


List pattern matching can be useful to introduce variables like in this method:

The input of the list pattern matching can be any object that is both countable (with a property Length or count) and indexable (supporting the syntax [int]). For example, it can work on a string. When dealing with your custom types, you can enable them to function as inputs for list patterns by providing the required members.

List pattern matching is a recursive pattern. This means that elements of the list test can also be lists like for example:

Finally, notice that the var pattern can be used to check some patterns on the sub-array of a slice pattern like in the expression [.. var nMinusOneFirstElems, 37]. However, doing so is not recommended because this can lead the compiler to allocate a new array just for the check:

The same way a string can be allocated:


C# 12: No new Pattern Matching syntax

C# 12 didn’t introduce new Pattern Matching syntax. See the list of C# 12 new features here.

Pattern Matching is no magic

Pattern matching is no magic. At first glance, one could think that a pattern expression is like a IQueryable LINQ expression: a language peculiarity that the compiler translates to a parametrized runtime object with special runtime processing. But it is not. Patterns are translated to traditional IL code. For example, let’s decompile these two methods:

Here is the IL code:


Don’t overuse Pattern Matching

C# Pattern matching is to complex if / else statements what C# LINQ is to for / foreach loop: a nice and modern C# improvement to write more concise and readable code. The parallel with C# LINQ can go a little further: the decompiled IL code above shows that pattern matching can emit more verbose code than regular if / else statements for similar behavior. Could pattern matching code be slower than the counterpart if / else code? There are a few evidences found on the web but no real thorough study. However, the same recommendation applies: don’t use LINQ nor Pattern Matching in performance-critical path executed millions or billions of time at runtime.

One of the most prominent pattern matching usage (at least in documentation) is type pattern. Concretely the code should behave differently if a shape is a circle or a rectangle. But one must keep in mind that polymorphism is here for that. It would be terrible design to use pattern matching to compute a shape area instead of providing an abstract Area property within the base class Shape:

This would be a maintenance nightmare since a new kind of shape introduced would need its own area formula (a clear violation of the Open Close Principle). Also, we can expect poor performance since the virtual method table used at runtime to handle polymorphism is certainly faster than type compatibility checking.


Again C# Pattern Matching is to complex if / else statements what C# LINQ is to for / foreach loop: a nice and modern C# improvement to write more concise and readable code.

However, you should avoid pattern matching in performance-critical situations where usual checks can perform better at runtime. At least do benchmark such usage.

Also, type pattern is not a replacement for polymorphism. You can keep it only for peculiar situations.

Finally – as underlined in the C# 7 section – C# pattern matching suffers from the limitation that only constant expressions can be used to match against. Maybe the C# team will relax this in the future but they need to find a good experience around exhaustiveness, particularly in switch expressions. With a non-compile-time-constant pattern, how the compiler could determine if the expression handles all cases? Another concern is when matching against values that trigger side effects – or even worse non-constant values – which would lead to undefined behavior.





  1. Thanks for the clear summary! It’s nice to see how well C# is coming along, and I’m looking forward to playing around with the newer pattern types soon.

Leave a Reply

Your email address will not be published. Required fields are marked *