C# Recursive Pattern Matching Explained
Learn how recursive patterns in C# simplify complex data inspections with nested positional and property patterns, switch expressions, and pattern combinators.

When inspecting deeply nested data structures, the logic often becomes a chain of type checks, null checks, and property accesses. Recursive patterns in C# let you express that nested validation in a single pattern that follows the shape of the data itself. Instead of writing several if statements to peel apart an object layer by layer, you can describe the expected structure directly in a switch expression or is expression, and the compiler will break it down for you.
A recursive pattern is any pattern that appears inside another pattern. C# uses this term when a pattern contains additional patterns, including further recursive patterns. This is what allows a single pattern to describe a multi-level structure in one expression.
Positional Patterns as the Foundation
A positional pattern matches an input by applying sub-patterns to the values exposed through its deconstructor. For example, a Point record with X and Y properties can be matched with a positional pattern.
public record Point(int X, int Y);
string Classify(Point p) => p switch
{
(0, 0) => "origin",
(0, _) => "on y-axis",
(_, 0) => "on x-axis",
_ => "elsewhere"
};The pattern (0, _) is positional; its sub-patterns are the constant pattern 0 and the discard pattern _. This is already a recursive pattern because the positional pattern contains other patterns. The recursion becomes more visible when you nest positional patterns inside other positional patterns.
Nesting Patterns with Records and Tuples
Records provide a clean way to build nested structures, and they expose deconstructors by default. Consider a Location record that contains a Point and a label.
public record Location(Point Coordinates, string Name);
string Describe(Location loc) => loc switch
{
Location(Point(0, 0), _) => "origin point",
Location(Point(0, var y), _) => $"on y-axis at {y}",
Location(_, string name) when name.StartsWith("HQ") => "headquarters",
_ => "other"
};Inside the Location(Point(0, var y), _) pattern, the inner Point(0, var y) is itself a positional pattern that captures the y-coordinate into a variable. That is a recursive pattern. The compiler recursively decomposes loc first into its Coordinates and Name, then further decomposes Coordinates into its X and Y.
This same nesting works with tuples. A tuple inside a positional pattern can be matched directly, as long as the tuple elements are accessible.
var data = ((1, 2), "pair");
string Explain(((int, int), string) input) => input switch
{
((0, 0), _) => "zero pair",
((var a, var b), string label) => $"{label}: {a},{b}",
_ => "unknown"
};Here ((var a, var b), string label) is a recursive pattern because the outer tuple pattern contains a nested tuple pattern.
Property Patterns for Non-Positional Types
Not every type exposes a deconstructor. Property patterns allow matching on individual property values without needing a positional form. You can combine property patterns with positional patterns to handle mixed types.
public class Customer
{
public string Name { get; set; }
public Address Address { get; set; }
}
public class Address
{
public string City { get; set; }
public string Country { get; set; }
}
string GetRegion(Customer customer) => customer switch
{
{ Address: { Country: "US", City: var city } } => $"US: {city}",
{ Address: { Country: "CA" } } => "Canada",
{ Address: null } or { Address: { Country: null } } => "Unknown",
_ => "Other"
};The { Address: { Country: ... } } pattern is a recursive property pattern. It matches the Address property and then recursively applies another property pattern to Country. This works when you need to inspect read-only properties that do not have a deconstructor.
Combining Type Tests and Recursive Patterns
Recursive patterns are especially useful when a base type has multiple subtypes that have different structures. A positional pattern can start with the subtype name, so the type test and nested decomposition happen in the same pattern.
public abstract class Shape { }
public record Circle(double Radius) : Shape;
public record Rectangle(double Width, double Height) : Shape;
string Describe(Shape shape) => shape switch
{
Circle(0) => "point",
Circle(double r) => $"circle radius {r}",
Rectangle(0, 0) => "empty rectangle",
Rectangle(var w, var h) when w == h => "square",
Rectangle(var w, var h) => $"rectangle {w}x{h}",
_ => "unknown shape"
};Here Circle(0) is a positional pattern that also performs a type check. Rectangle(var w, var h) combines type test, positional decomposition, and variable capture. The when clause adds a guard. This pattern of type testing plus nested decomposition is a common practical use of recursive patterns in C#.
The order of arm evaluation matters. The compiler checks patterns in the order they appear, so more specific patterns must come before more general ones. For instance, Rectangle(0, 0) must appear before Rectangle(var w, var h) because the latter would match everything.
Switch Expressions and Pattern Combinators
Recursive patterns are often used inside switch expressions, but they also work in if statements with the is operator.
if (shape is Rectangle(var w, var h) && w > 0)
{
Console.WriteLine($"Width: {w}");
}You can also use the and, or, and not pattern combinators to build more complex conditions.
string Categorize(object obj) => obj switch
{
int n when n is > 0 and < 100 => "small positive",
string s when s.Length > 0 => "non-empty string",
Point(0, 0) or Point(0, _) => "on y-axis",
_ => "other"
};The or pattern Point(0, 0) or Point(0, _) is redundant because _ matches any value, but it demonstrates that each arm can contain alternative patterns. The not pattern is useful for null checks, for example if (obj is not null). Note that the compiler will flag unreachable patterns or unnecessary conditions in some cases, so it is worth paying attention to warnings.
Compile-Time Exhaustiveness and Warnings
A switch expression over an arbitrary object is not exhaustive unless you provide a catch-all arm. For an enum, a _ arm is also useful because the underlying value may not be one of the declared members. When recursive patterns match only a subset of possible shapes, include a _ arm to avoid runtime exceptions. The compiler will also warn about unreachable arms if an earlier pattern always matches.
For example, Circle(_) will match all Circle instances, so any later Circle(...) pattern is unreachable. The compiler emits a warning for this. Pay attention to those warnings because they often indicate a logic error.
Performance and Overhead Concerns
Recursive pattern matching does not use reflection. The compiler generates direct type checks and property accesses. For a record, the generated deconstructor reads the backing fields. This means recursive pattern matching is typically as fast as manual property access and type checks. There is no dynamic dispatch overhead beyond what the type test requires.
However, the order of property access follows the pattern order. If a pattern matches a property deep in a hierarchy, the compiler still performs earlier checks first. There is no short-circuiting that skips property reads unless the outer pattern fails. For most code, this overhead is negligible. If performance is critical, avoid using patterns that require reading many properties across large collections in a hot loop, because each property access has a cost.
Another point is that pattern matching on nullable value types requires care. int? is not directly supported as a positional pattern, but you can use a property pattern with HasValue and Value.
string Describe(int? value) => value switch
{
{ HasValue: true, Value: var v } when v > 0 => $"positive {v}",
{ HasValue: true, Value: 0 } => "zero",
_ => "null or negative"
};This pattern is recursive because Value is a property that contains another pattern.
Maintainability and Where Recursive Patterns Shine
Recursive patterns reduce boilerplate and keep the validation logic in a single visible place. This is a real maintainability benefit because the pattern mirrors the shape of the data, making the expected structure obvious to readers.
However, there is a tradeoff. When the pattern becomes too large, it can be harder to read than a sequence of if statements, especially for unfamiliar readers. A pattern that spans more than a few lines may be clearer if extracted into a named method:
bool IsOrigin(Point p) => p is (0, 0);You can also use a recursive pattern inside an if with a pattern variable to use later in the block.
if (shape is Rectangle(var w, var h) && w == h)
{
Console.WriteLine($"Square side: {w}");
}Here var w and var h capture the decomposed width and height and can be used in subsequent expressions.
When a structure changes, recursive patterns may require updates in several places. Since the pattern describes the structure you want to match, a new property may not affect the pattern unless you need to match it. This is usually manageable.
Compatibility with Older C# Versions
Recursive patterns depend on the C# language version. C# 7.0 introduced basic is patterns such as constant, type, and var patterns. C# 8.0 added switch expressions, positional patterns, and property patterns, so most of the pattern syntax in this article requires at least C# 8.0. The record types used in the examples were introduced in C# 9.0. The and, or, and not combinators were also added in C# 9.0. C# 10 later added extended property patterns like { Address.City: "Seattle" }, and C# 11 added list patterns.
If your project uses an older LangVersion, adjust the examples accordingly. In C# 7.x, you cannot use switch expressions, positional patterns, or property patterns; use switch statements or is expressions with the patterns that are available in that version.
Be aware that the deconstruct method must be accessible. For a record, the compiler generates it. For a custom class, you must implement an accessible Deconstruct method for positional patterns to work.
public class Pair
{
public int First { get; }
public int Second { get; }
public Pair(int first, int second) => (First, Second) = (first, second);
public void Deconstruct(out int first, out int second) => (first, second) = (First, Second);
}Without Deconstruct, a positional pattern will not compile.
Choosing When to Use Recursive Patterns
Use recursive patterns when the shape of the data is known at compile time and you need to distinguish between a limited set of forms. This is common when parsing abstract syntax trees, handling discriminated unions modeled through inheritance, or validating deserialized DTOs.
Do not use recursive patterns when the structure is highly dynamic and requires reflection every time. The compiler cannot generate efficient code for unknown shapes.
Also consider the readability for future maintainers. A deep pattern is concise, but if the nesting exceeds two or three levels, it might be clearer to break the logic into helper functions. For example, instead of matching Location(Point(0, var y), _), you could extract a method IsOnYAxis(Point p) and call it from the guard:
if (loc is Location(var point, _) && IsOnYAxis(point))
{
// ...
}This separates the decomposition from the condition, making the condition reusable.
Another scenario is when you need to match a property that is itself a collection. The list pattern, introduced in C# 11, allows matching against array or list shapes, and it can be combined with recursive patterns.
int[] numbers = { 1, 2, 3 };
if (numbers is [1, var second, _]) { /* second is 2 */ }While the list pattern is technically a different feature, it uses the same recursive idea: break down structure in a single expression. You can nest list patterns inside positional patterns for complex data structures.
Used with restraint, recursive patterns make code more expressive and less error-prone. The cost is a learning curve and a potential for over-abstraction. For most developers, the syntax becomes natural after a few uses, and the clarity gains outweigh the occasional complexity.
Try matching browser tools
All toolsSmall utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related C# guides
All C# guidesC# Dispose vs Destructor: Key Differences Explained
c# dispose vs destructor: Understand the difference between Dispose and destructors in C#, when each runs, and how to manage unmanaged resources correctly.
C# Variable Declaration: Syntax and Practical Usage
Learn how to declare variables in C# with explicit types, var, and nullable annotations, and understand how defaults, scope, and readability affect your choices.
C# Primary Constructors for Classes: Syntax and Usage
Learn how to use C# primary constructors for classes: syntax, initialization, dependency injection, and limitations with practical examples.
C# IComparer: Custom Sorting with IComparer<T>
Learn how to implement IComparer<T> in C# to define custom sort order for arrays and lists, handle nulls, and avoid common performance pitfalls.
More in C#
All C# guidesThe guides filed next to this one in C#, in library order.