Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

C# Switch Pattern Matching: Syntax and Use Cases

Learn the syntax and practical use cases of C# switch pattern matching, including type, property, and relational patterns for cleaner branching logic.

~7 min readC#
#C# switch#pattern matching#relational patterns#property patterns
C# switch pattern matching shown as a decision tree branching on object types and property values.

The C# switch pattern matching feature was introduced in C# 7 and expanded in later versions. It lets you express conditional logic more declaratively than a traditional if/else chain. At its core, pattern matching allows a switch to test a value against a series of patterns, not just constants. You can match on the runtime type, on property values, or on ranges of numeric values directly within the switch statement or expression.

Traditional Conditionals vs. Pattern Matching

Before pattern matching, a switch in C# was limited to comparing an integral type, a char, a string, or an enum against constant case labels. This works fine for discrete values but becomes awkward when you need to branch based on a condition, like whether a number falls within a range or whether an object is of a certain type and has a specific property.

Consider a method that returns a string describing a number. The traditional approach might look like this:

csharp
public static string DescribeNumber(object value) { if (value is int i) { if (i >= 0 && i <= 9) return "Single digit"; else if (i >= 10 && i <= 99) return "Two digits"; else return "Many digits"; } else if (value is string s && s.Length > 0) { return "Non-empty string"; } else { return "Unknown"; } }

The logic is correct, but it's dense, and the nested conditionals make it harder to scan. Pattern matching flattens this into a single switch expression:

csharp
public static string DescribeNumber(object value) => value switch { int i when i >= 0 && i <= 9 => "Single digit", int i when i >= 10 && i <= 99 => "Two digits", int i => "Many digits", string s when s.Length > 0 => "Non-empty string", _ => "Unknown" };

This is the switch-expression style that modern C# developers use. The switch keyword followed by value and an arrow => marks a switch expression. Each arm consists of a pattern, an optional when clause, and the result. The _ pattern is the discard pattern, which acts as the default case.

Type Patterns and the Discard Pattern

The type pattern is the foundation of pattern matching. It checks whether the input matches a specific type and, if it does, binds a new variable to the cast value. In the previous example, int i is a type pattern: it matches only if value is an int, and assigns the value to i for use in that arm.

One practical consequence is that you no longer need explicit cast checks before using a value. For instance:

csharp
public static string GetShapeName(object shape) => shape switch { Circle c => $"Circle with radius {c.Radius}", Rectangle r => $"Rectangle {r.Width}x{r.Height}", _ => "Unknown shape" };

The _ discard pattern catches everything that doesn't match any earlier pattern. It is the pattern-matching equivalent of the default case. Placing it first would make all other arms unreachable, so it should always be the last arm.

Property Patterns

Property patterns let you match on the value of a public property of the input. This is useful when you care about a specific state of an object rather than just its type. A common case is handling requests or commands that carry a status flag.

csharp
public static string GetStatusMessage(Order order) => order.Status switch { _ when order.IsExpedited && order.Status == OrderStatus.Shipped => "Expedited shipment on its way", OrderStatus.Pending => "Order pending", _ => "Unknown status" };

Note that the first arm uses a when guard because it combines multiple conditions: it checks the IsExpedited property and the Status property. Property patterns, however, allow you to express such checks directly on the object's shape. Here's the equivalent using a property pattern:

csharp
public static string GetStatusMessage(Order order) => order switch { { Status: OrderStatus.Shipped, IsExpedited: true } => "Expedited shipment on its way", { Status: OrderStatus.Pending } => "Order pending", { Status: OrderStatus.Shipped } => "Order shipped", _ => "Unknown status" };

The pattern { Status: OrderStatus.Shipped, IsExpedited: true } matches any object that has a Status property equal to OrderStatus.Shipped and an IsExpedited property equal to true. This is more readable because the condition appears as a structural description of the object, not as a separate when clause.

Property patterns also allow nesting. You can match nested properties without intermediate casts:

csharp
public static decimal CalculateShipping(Order order) => order switch { { Destination: { Country: "USA" } } => 10.0m, { Destination: { Country: "Canada" } } => 20.0m, _ => 50.0m };

If Destination is null, this nested property pattern simply does not match; it does not throw. Add a separate null or discard pattern only if you need a distinct result for a null destination.

Relational and Logical Patterns

C# 9 introduced relational patterns, which let you compare a value using <, >, <=, and >= within a pattern. Equality is handled by the constant pattern (0 in the example below). This makes range-matching much cleaner than the when clauses we used earlier.

csharp
public static string ClassifyNumber(int number) => number switch { < 0 => "Negative", > 0 => "Positive", 0 => "Zero" };

You can also combine relational patterns with logical combinators and, or, and not:

csharp
public static string Grade(int score) => score switch { >= 90 and <= 100 => "A", >= 80 and < 90 => "B", >= 70 and < 80 => "C", < 70 => "F", _ => "Invalid score" };

The and and or patterns allow you to express compound conditions without nesting when clauses. A relational pattern is only valid when the input type implements the relevant comparison operators. For example, you cannot write < 0 for a string because string does not overload that comparison. The pattern is not limited to numeric types; DateTime, for instance, supports relational patterns.

Switch Expressions vs. Switch Statements

So far the examples have used switch expressions, which produce a value. But pattern matching also works with the classic switch statement form, which is useful when each arm must execute multiple statements.

csharp
public static void ProcessShape(object shape) { switch (shape) { case Circle c: Console.WriteLine($"Drawing circle of radius {c.Radius}"); break; case Rectangle r when r.Width > 0 && r.Height > 0: Console.WriteLine($"Drawing rectangle {r.Width}x{r.Height}"); break; default: Console.WriteLine("Cannot draw this shape"); break; } }

Here the case labels use patterns, and each block can contain any number of statements. This form is preferrable when you need to perform side effects or call multiple methods inside an arm.

One important difference is exhaustiveness. If the compiler cannot prove that a switch expression covers every possible input, it issues a warning, and an unhandled input throws SwitchExpressionException at runtime. That is why the _ discard acts as a useful default arm. In the statement form, omitting default is allowed; if no case matches, execution simply continues after the switch block.

Performance and Compiler Optimization

For constant patterns, the compiler can use the same jump-table optimization it uses for traditional switch statements. For type and property patterns, the generated code typically involves a sequence of type checks and conditional jumps. In most cases, the runtime overhead is negligible compared to the readability gains.

However, there is one situation where performance can degrade: when you match against a large number of string or type patterns. The compiler may generate a linear sequence of if checks rather than a hash-based dispatch, resulting in O(n) complexity. If you have many patterns and profiling shows that this method is a hot path, consider restructuring to use a dictionary mapping input types or constants to handlers instead.

One evaluation detail: a switch expression evaluates its input expression once. It then checks arms in order and evaluates only the result expression of the first arm that matches. Nonmatching arms are not evaluated. This matters when result expressions call methods that may throw or have side effects.

When to Use Pattern Matching vs. Traditional Approach

Pattern matching is not always the right tool. If you only need to compare a value against a few constants, a classic switch statement is still fine. Pattern matching shines when the logic branches on types, ranges, or object properties, and when you want to avoid verbose if-else nesting.

Use pattern matching when:

  • You need to test an object's runtime type and bind a variable to that typed reference.
  • You need to check several properties of an object in combination.
  • You want to express numeric range checks without writing comparison chains.
  • You want to keep related branches in a single, readable structure.

Avoid it when the branching depends on complex compound conditions that are clearer as separate expressions, or when the number of patterns is so large that the code becomes difficult to maintain.

One maintainability concern is exhaustiveness. If you later add a new enum member, the compiler can warn that a switch expression does not cover it, provided you haven't used a blanket _ pattern. Using _ suppresses that warning, so omit the discard where you want the compiler to catch missing cases.

Compatibility and Language Version Dependencies

Pattern matching has evolved across C# versions. Here is a quick mapping of when each major feature became available:

Pattern featureC# versionExample
Type patterns, constant patterns, var patternsC# 7.0case int i:
Switch expressions, property patterns, positional patternsC# 8.0value switch { ... }
Relational and logical patternsC# 9.0>= 90 and <= 100
Extended property patternsC# 10.0{ Destination.Country: "USA" }
List patternsC# 11.0[1, 2, ..]

If you are working on a project that targets an older C# language version, you may not have access to all these syntaxes. For example, C# 8 added switch expressions, but relational patterns like > 100 are only available in C# 9. The language version is typically determined by the target framework, but you can also set <LangVersion> explicitly in the project file. Before adopting a newer pattern syntax, verify that the build environment and all team members use a compiler that supports it.

The compiler also uses the static type to determine which patterns are possible. For an input typed as object, a type pattern performs a runtime type check. For a more specific static type, a pattern that can never match is diagnosed at compile time. For example, matching a string value with an int pattern cannot compile.

Handling Null in Pattern Matching

Pattern matching has a few peculiar behaviors with null. The type pattern case string s: does not match null because null has no type. The discard pattern _ matches null as well as any other value. This means you should put a null-specific pattern before a discard if you need to handle null specially.

csharp
public static string Describe(object value) => value switch { null => "Null", int i => $"Integer {i}", _ => "Other" };

Property patterns also fail for null input. If you write { Name: "Alice" } and the value is null, the pattern does not match; it does not attempt to access Name. Add an explicit null pattern if you need distinct handling for null.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.