C# Property Pattern with Examples
Learn how to use the C# property pattern to match objects based on their properties, with practical examples and common pitfalls.

The C# property pattern lets you match an object against a set of property values within a pattern-matching expression. It was introduced in C# 8.0 as part of recursive pattern matching and is useful for writing concise, readable validation logic without manually chaining if-statements. This article covers the syntax, practical usage, and trade-offs of the property pattern for working developers.
Property Pattern Syntax
The property pattern extends the is expression and the switch statement or expression. Instead of matching a type only, you can match against one or more properties. The basic syntax looks like this:
public record Order(int Id, string Customer, decimal Total);
bool IsLargeOrder(Order order) => order is { Total: > 1000 };Here, order is { Total: > 1000 } checks that order is not null and that the Total property is greater than 1000. The property pattern uses a nested pattern for each property. You can combine multiple properties with commas:
bool IsPriorityOrder(Order order) => order is { Total: > 1000, Customer: "VIP" };This checks both conditions. If order is null, the is pattern returns false. The property pattern is recursive, meaning the property value can itself be matched with another pattern, including another property pattern.
Using Property Patterns in Switch Expressions
Property patterns are particularly useful in switch expressions, where they replace multiple if-else conditions. Consider a shipping cost calculator:
public enum DeliveryZone { Local, Regional, International }
record Package(double Weight, DeliveryZone Zone);
decimal CalculateShipping(Package pkg) => pkg switch
{
{ Zone: DeliveryZone.Local } => 5.0m,
{ Zone: DeliveryZone.Regional, Weight: <= 10 } => 10.0m,
{ Zone: DeliveryZone.Regional, Weight: > 10 } => 15.0m,
{ Zone: DeliveryZone.International, Weight: <= 5 } => 20.0m,
{ Zone: DeliveryZone.International, Weight: > 5 } => 35.0m,
_ => throw new ArgumentException("Unknown shipping scenario")
};Each arm uses a property pattern. The _ discard acts as the default case. The switch expression evaluates arms in order, so the first matching arm wins. This ordering matters when patterns overlap; for instance, if you had a broad match before a specific one, the specific one would never run.
When writing property patterns in a switch expression, you do not need to include a type name explicitly if the input type is already known, but you can add it for clarity or to filter by type:
string Describe(object obj) => obj switch
{
Order { Total: > 1000 } => "Large order",
Order => "Regular order",
_ => "Not an order"
};Combining with Other Patterns
The property pattern can be nested with other patterns, such as type patterns, relational patterns, and logical patterns. For example, you can match a specific derived type and its properties:
abstract class Shape { }
class Circle : Shape { public double Radius { get; init; } }
class Rectangle : Shape { public double Width { get; init; } public double Height { get; init; } }
string Classify(Shape shape) => shape switch
{
Circle { Radius: > 0 } => "Valid circle",
Rectangle { Width: > 0, Height: > 0 } => "Valid rectangle",
_ => "Unknown or invalid shape"
};You can also use logical operators and, or, and not within property values:
bool IsSpecialOrder(Order order) => order is { Total: > 100 and < 5000, Customer: not "Internal" };This checks that Total is between 100 and 5000, and that the customer is not "Internal". The not pattern is useful for excluding a specific value.
Practical Example: Validation Logic
A common use for property patterns is to validate input objects at the boundary of an application. Instead of writing a long series of if-statements, you can express all rules in one switch expression. Suppose you have a request object:
record CreateUserRequest(string Email, string Name, int Age);
string Validate(CreateUserRequest request) => request switch
{
null => "Request is required",
{ Email: null or "" } => "Email is required",
{ Name: null or "" } => "Name is required",
{ Age: < 18 } => "Must be at least 18",
{ Age: > 120 } => "Age is unrealistic",
_ => "Valid"
};This approach keeps all validation in one place and makes it easy to see all rules at once. However, it returns only the first failing rule. If you need to collect all validation errors, a switch expression is not ideal; you would need a loop or a collection of predicates. For single-error validation, this pattern is clean and less error-prone than scattered if-statements.
Nested Property Patterns
Property patterns can be nested to access nested objects. For example, if an Order has a Customer object with an Address, you can match on the address's city directly:
record Customer(string Name, Address Address);
record Address(string City, string Country);
record Order(Customer Customer, decimal Total);
bool ShipsToSeattle(Order order) => order is { Customer.Address.City: "Seattle" };The dotted syntax is an extended property pattern, available in C# 10 and later. It is equivalent to the nested property pattern order is { Customer: { Address: { City: "Seattle" } } }, which you can use in C# 8 or 9. Both forms avoid null checks on intermediate objects because the pattern automatically returns false if any intermediate property is null.
Performance and Runtime Cost
The property pattern compiles to code that performs a null check and then accesses the relevant members. Each member access is a simple read or getter call. There is no reflection involved, so the runtime cost is minimal, comparable to writing the equivalent manually. However, in hot paths, consider that accessing a member may trigger side effects if the getter is expensive. The pattern does not cache member values; it calls the getter each time the pattern is evaluated. For simple auto-properties backed by fields, this is negligible. For members that compute values or perform I/O, the property pattern can be as expensive as the member access itself. In practice, you should use property patterns where you would otherwise write manual checks; the performance difference is negligible. Avoid using property patterns with members that have side effects, because the pattern may evaluate the getter multiple times if used in a compound condition. The compiler may optimize some cases, but it is not guaranteed.
Field and Property Access
Property patterns test readable properties or fields that are accessible at the call site. They do not work with methods or indexers. If you have a type with public fields, you can use those fields in a pattern similarly to properties. The property pattern is synchronous; it does not perform asynchronous property retrieval.
Common Pitfalls and Limitations
One common mistake is to forget the null check. The property pattern implicitly checks for null if the object reference is not known to be non-null. However, if you have a nullable reference type, the compiler may warn but still allow. Also, the property pattern does not handle null property values gracefully in some cases: if you match a property against a pattern that expects a non-null value, the pattern fails only if the property is null. For example, { Name: "John" } fails if Name is null, but { Name: not null } succeeds. The is pattern with a property pattern does not throw if the object is null; it simply returns false. But in a switch expression, if all arms fail and there is no discard arm, an exception is thrown. This is a runtime SwitchExpressionException. Always include a default _ arm unless you can prove one of the patterns always matches.
A property pattern can capture the matched object when you add a variable designation after the pattern:
if (order is { Total: > 1000 } largeOrder)
{
// largeOrder is the same object as order, but only if the pattern matched.
}This is redundant when order is already in scope, but useful when matching a nested value or an expression. Property patterns do not deconstruct the matched object into separate local variables; for that, use positional patterns with a deconstructor.
Maintainability and When to Use Property Patterns
Using property patterns reduces the number of lines and makes the logic more declarative. However, for complex validation that requires returning multiple errors, a more traditional approach may be more readable. As a rule, use property patterns when:
- The logic is a simple equality or range check on one or two properties.
- The logic is a decision table that can be expressed as a switch expression.
- The input type is known and you want to avoid nested ifs.
Avoid property patterns when:
- You need to perform complex side-effectful validation.
- You need to collect all validation errors.
- The property getters are expensive or have side effects.
Property patterns integrate well with records, which provide value-based equality and concise syntax. However, pattern matching is not dependent on records; it works with any class or struct. For .NET developers working with C# 8 or later, property patterns are a valuable tool for writing intent-revealing code.
Advanced Usage: Property Patterns with List Patterns
While the property pattern is designed for object members, you can combine it with list patterns in C# 11 to match collections. For example, you can check if the first element of an array is a certain type and has a property:
string DescribeList(object[] items) => items switch
{
[Order { Total: > 100 }, ..] => "Starts with large order",
_ => "Other"
};This uses a list pattern and a property pattern. The .. slice matches the rest of the list. List patterns work with arrays, List<T>, Span<T>, and other types that expose Length or Count and an integer indexer; they do not directly work on IEnumerable<T>. Use such combinations sparingly, as they can hurt readability if overused.
Compatibility and Version Requirements
The basic property pattern requires C# 8.0 or later. Some examples use newer syntax: logical patterns (and, or, not) require C# 9.0, records require C# 9.0, extended property patterns with dotted access require C# 10.0, and list patterns require C# 11.0. Choose the language version that matches your project. The examples as a whole compile with C# 11 and .NET 7 or later.
The property pattern is a compact way to write branch logic that would otherwise require multiple conditionals. Understanding how it compiles and when to apply it will help you write code that is easier to maintain and less prone to null-reference mistakes. For code that requires performance-critical checks, remember that the property pattern is not a free lunch; it calls getters. But for most business logic, the clarity gain outweighs the minor cost.
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.