Pattern matching lets you ask "what shape is this, and what's inside it?" in a single expression.

Think about how much C# code boils down to the same question, asked over and over: "What is this thing, exactly, and what does it look like right now?" Is this order shipped or pending? Is this shape a circle or a rectangle? Is this customer's age over 18 and do they have a verified account? Traditionally, answering that meant a pile of is checks, casts, and property comparisons chained together with && and ||.

Pattern matching gives C# a much more direct way to ask that question. Instead of describing how to check something step by step, you describe what shape you're looking for, and the compiler does the checking and, often, the extraction of the interesting parts.

In this lesson, you'll learn type patterns, property patterns, relational patterns, and the and/or/not pattern combinators — the building blocks for a much richer way of testing and destructuring values with is. (The deep dive into pattern matching inside switch expressions is the next lesson.)

What Is It?

The Simple Explanation

Pattern matching is a way to ask "does this value match a certain shape?" — and if it does, pull the interesting parts out at the same time. You've actually already used the simplest form of it, whether you realized it or not: if (obj is string s) is a pattern — it checks the type and gives you a usable variable s in one step.

Modern C# extends that same is keyword to check far more than just "is this a certain type." You can check the values of properties, whether a number falls in a range, or combine several checks with readable words like and, or, and not.

The Technical Definition

Pattern matching in C# is a language feature (introduced in C# 7, substantially expanded through C# 8–11) that lets an expression be tested against a pattern — a syntactic description of a value's shape — using the is operator (or, as you'll see in the next lesson, a switch). A pattern can test the runtime type of a value, the values of its properties, whether a value falls within a numeric range, or a logical combination of other patterns — and can simultaneously bind matched portions to new variables for use afterward.

Why Does It Exist?

The Problem

Consider deciding a shipping cost based on an order's weight and destination. Written the classic way, you get a wall of type-checks, casts, and conditions where the actual business rule is hard to see through the scaffolding:

decimal GetShippingCost(Order order)
{
    if (order != null)
    {
        if (order.Destination == "International")
        {
            if (order.WeightKg > 20)
            {
                return 75m;
            }
        }
        else if (order.Destination == "Domestic" && order.WeightKg <= 5)
        {
            return 5m;
        }
    }
    return 10m;
}

Every condition needs its own if, its own comparison, its own place in the nesting. As the number of rules grows, this becomes genuinely difficult to read and to verify for completeness.

The Need

Developers needed a way to describe "the shape of a match" — a type, a set of property values, a numeric range, a combination of conditions — as directly and declaratively as possible, so the code reads like the actual rule instead of the mechanics of checking it.

The Solution

Pattern matching lets you write the same rule as a direct description of the shape you're testing for:

bool isExpensiveInternational =
    order is { Destination: "International", WeightKg: > 20 };

One expression, reading almost like the sentence "order is International with weight over 20" — because that's exactly what it checks.

Big Picture

How It Works

object shape = new Circle(5);

if (shape is Circle circle)
{
    // circle is now a usable, typed Circle variable — no separate cast needed
    Console.WriteLine(circle.Radius);
}

if (order is Order { Destination: "International", WeightKg: 20 })
{
    // matches only if BOTH properties equal these exact values
}

if (order is Order { WeightKg: > 20 })
{
    // WeightKg must be strictly greater than 20
}

if (order is { WeightKg: > 0 and <= 5 })       // "and" — a range in a single pattern
if (order is { Destination: "US" or "Canada" })  // "or" — either value matches
if (order is not { Status: "Cancelled" })        // "not" — negates a pattern

Simple Example

public abstract class Shape { }
public class Circle : Shape { public double Radius { get; init; } }
public class Rectangle : Shape { public double Width { get; init; } public double Height { get; init; } }

double Describe(Shape shape)
{
    if (shape is Circle { Radius: > 10 } bigCircle)
    {
        return bigCircle.Radius * 2; // a "large" circle's diameter
    }

    if (shape is Rectangle { Width: var w, Height: var h } && w == h)
    {
        return w; // it's actually a square — return the side length
    }

    return 0;
}

Code → Meaning → Result: shape is Circle { Radius: > 10 } bigCircle checks three things in one breath — is it a Circle, is its Radius greater than 10, and if both are true, capture the whole matched circle as bigCircle so you can use it right away. No separate cast, no separate comparison.

Real-World Example

A shipping-cost calculator that reasons about weight and destination is a natural fit — the rules genuinely are "shapes" of an order:

public class Order
{
    public required string Destination { get; init; }
    public required double WeightKg { get; init; }
    public bool IsMember { get; init; }
}

decimal CalculateShippingCost(Order order)
{
    if (order is { IsMember: true, WeightKg: <= 10 })
        return 0m; // free shipping for members on lighter packages

    if (order is { Destination: "Domestic", WeightKg: > 0 and <= 5 })
        return 5m;

    if (order is { Destination: "Domestic" })
        return 12m;

    if (order is { Destination: "International", WeightKg: > 20 })
        return 75m;

    if (order is { Destination: "International" })
        return 35m;

    return 15m; // fallback for anything unmatched
}

Each rule reads as a direct description of the order shape it targets — "a member with a package of 10kg or less," "domestic and light," "international and heavy" — instead of a maze of boolean logic. The next lesson shows how the same rules collapse further into a single switch expression.

Analogy

Under the Hood

bool matched = false;
Circle? c = shape as Circle;
if (c != null && c.Radius > 10)
{
    matched = true;
}

Common Confusion

1. Pattern and/or vs boolean &&/||

and and or only combine patterns, inside a pattern context (after is, or inside a switch arm). They cannot combine two arbitrary boolean expressions the way && and || can. You can't write x is > 5 and y > 3 mixing an unrelated variable in — every operand around and/or must itself be a valid pattern applied to the same value being tested.

2. A property pattern with no type name still checks the type implicitly

order is { Destination: "Domestic" } (without writing Order before the braces) still works, and it's still safe against null — if order is null, the property pattern simply doesn't match (rather than throwing). You only need to name the type explicitly when you're testing a value whose declared type is a base type or object, and you need to narrow it.

3. Relational patterns only work on values that support comparison

> 20 works on numeric types (and any type implementing the right comparison operators). It doesn't magically apply "greater than" semantics to arbitrary reference types unless those comparisons are actually defined for them.

Common Mistakes

Mistake 1 — Forgetting operator precedence with and/or/not

Assuming not binds looser than it does:

// Intending "not Domestic, and weight over 20" — but precedence groups "not" tightly:
order is not { Destination: "Domestic" } and { WeightKg: > 20 }

Just like boolean operators, not binds tighter than and, which binds tighter than or. Use parentheses around sub-patterns whenever the grouping isn't immediately obvious:

order is (not { Destination: "Domestic" }) and { WeightKg: > 20 }

Mistake 2 — Reaching for a long chain of if (x is ...) when a switch expression fits better

Pattern matching with is is great for one or two conditions, but once you have several mutually exclusive shapes to test, a switch expression (next lesson) expresses that far more clearly and gives the compiler a chance to warn you about gaps — a long if/else if chain of patterns doesn't get that exhaustiveness checking.

Mistake 3 — Using a relational pattern where a simple comparison would already be clearer

if (age is >= 18) for a single, standalone check is technically valid but adds nothing over the plain if (age >= 18) most readers expect. Relational patterns earn their keep when they're part of a richer pattern (a property pattern, a range with and, or a switch arm) — not as a stylistic replacement for every comparison in your codebase.

When Should I Use It?

• When a check involves both a type and its data — "is it a Circle with radius over 10?" — type + property patterns say that in one step.
• When you'd otherwise write a range check (x >= 0 && x <= 100) — a relational pattern with and reads more directly.
• When several conditions genuinely describe one logical shape — combine them with and/or/not rather than nesting ifs.
• It's overkill for a single, simple boolean check that reads perfectly well as a plain comparison — don't force a pattern where a normal expression is already clear.

Mental Model

Key Takeaway

Check Your Understanding

You've seen type, property, and relational patterns, plus the and/or/not combinators. Let's see if the shapes stuck.

You can now describe the "shape" of a value directly in code instead of reconstructing it from scattered if checks. Next up: putting these same patterns to work inside switch expressions.

dotnetmadeeasy.com — Learn C# and .NET, the right way.