ExhaustiveMatching.Modern 1.0.1

ExhaustiveMatching.Modern

ExhaustiveMatching.Modern is a Roslyn analyzer that reports missing cases in C# switch statements and switch expressions. It supports enums and closed class or interface hierarchies, including modern logical patterns such as or, and, not, and parenthesized patterns.

This project is a maintained, modernized fork of WalkerCodeRanger/ExhaustiveMatching. It keeps the existing ExhaustiveMatching namespace so applications can migrate without changing their source API.

Install

dotnet add package ExhaustiveMatching.Modern

Install the package in every project that contains exhaustive switches or declares, inherits, or implements types marked with ClosedAttribute.

The package supports projects targeting .NET 8 and .NET 10. The runtime API and analyzer target .NET Standard 2.0, and the analyzer supports Roslyn 4.8 or newer.

Quick start

Mark a switch as intentionally exhaustive by throwing the exception returned by ExhaustiveMatch.Failed from its fallback case:

using ExhaustiveMatching;

public enum CoinFlip
{
    Heads,
    Tails,
}

// EM0001: Enum value not handled by switch: Tails
var result = coinFlip switch
{
    CoinFlip.Heads => "Heads!",
    _ => throw ExhaustiveMatch.Failed(coinFlip),
};

Modern pattern examples

or patterns

Combine multiple declared enum values in one arm:

var category = coinFlip switch
{
    CoinFlip.Heads or CoinFlip.Tails => "Known outcome",
    _ => throw ExhaustiveMatch.Failed(coinFlip),
};

Nullable enum switches can combine logical patterns with an explicit null case:

var message = nullableCoinFlip switch
{
    null => "No result",
    CoinFlip.Heads or CoinFlip.Tails => "Known result",
    _ => throw ExhaustiveMatch.Failed(nullableCoinFlip),
};

Relational and and patterns

Relational patterns are evaluated against the enum's declared values:

public enum Priority
{
    Low = 1,
    Medium = 2,
    High = 3,
    Critical = 4,
}

var queue = priority switch
{
    <= Priority.Medium => "Normal",
    > Priority.Medium and <= Priority.Critical => "Urgent",
    _ => throw ExhaustiveMatch.Failed(priority),
};

The analyzer unions or coverage, intersects and coverage, and complements safe not patterns. Parentheses can be used to control grouping:

// EM0001: Enum value not handled by switch: CoinFlip.Heads
var result = coinFlip switch
{
    not (CoinFlip.Heads) => "Not heads",
    _ => throw ExhaustiveMatch.Failed(coinFlip),
};

Closed type hierarchies

Use ClosedAttribute to define the direct cases of a class or interface:

using ExhaustiveMatching;

[Closed(typeof(Circle), typeof(Rectangle), typeof(Triangle))]
public abstract record Shape;

public sealed record Circle(double Radius) : Shape;
public sealed record Rectangle(double Width, double Height) : Shape;
public sealed record Triangle(double Base, double Height) : Shape;

The analyzer reports any concrete case not covered by the switch:

// EM0003: Subtype not handled by switch: Triangle
var area = shape switch
{
    Circle circle => CalculateArea(circle),
    Rectangle rectangle => CalculateArea(rectangle),
    _ => throw ExhaustiveMatch.Failed(shape),
};

Logical patterns may cover multiple cases:

var kind = shape switch
{
    Circle or Rectangle => "round or rectangular",
    Triangle => "triangular",
    _ => throw ExhaustiveMatch.Failed(shape),
};

A not pattern contributes the safe complement of its operand for class hierarchies:

// EM0003: Subtype not handled by switch: Triangle
var kind = shape switch
{
    not Triangle => "Not a triangle",
    _ => throw ExhaustiveMatch.Failed(shape),
};

Total positional and property patterns can capture data while covering their whole subtype:

var dimensions = shape switch
{
    Circle(var radius) => $"radius={radius}",
    Rectangle { Width: var width, Height: var height }
        => $"{width} x {height}",
    Triangle(var @base, var height) => $"base={@base}, height={height}",
    _ => throw ExhaustiveMatch.Failed(shape),
};

Value constraints are intentionally conservative because they do not cover every instance of a subtype:

// EM0101: this constrained pattern cannot prove full subtype coverage
// EM0003: Circle is still considered unhandled
var description = shape switch
{
    Circle { Radius: > 0 } => "Non-empty circle",
    Rectangle => "Rectangle",
    Triangle => "Triangle",
    _ => throw ExhaustiveMatch.Failed(shape),
};

A case may also cover a closed branch higher in a nested hierarchy. All concrete leaf types below that branch count as handled.

Supported patterns

The analyzer evaluates patterns against the finite set of declared enum values or concrete leaves in a closed hierarchy.

Patterns whose coverage cannot be proven produce EM0101 and do not suppress a missing-case diagnostic. A when guard produces EM0100 and its pattern does not count toward exhaustiveness because the guard may be false.

For nullable enums, null must be handled. For closed reference hierarchies, the analyzer preserves the original behavior and does not require a null case.

Exhaustive switch statements

Switch statements use the same analysis when their default section throws:

switch (shape)
{
    case Circle or Rectangle:
        RenderSimpleShape(shape);
        break;
    case Triangle triangle:
        RenderTriangle(triangle);
        break;
    default:
        throw ExhaustiveMatch.Failed(shape);
}

The analyzer also recognizes the original enum convention using InvalidEnumArgumentException.

Diagnostics

Building

The repository uses the .NET 10 SDK. Install both the .NET 8 and .NET 10 runtimes to run the full test matrix:

dotnet test ExhaustiveMatch.sln --configuration Release
dotnet pack ExhaustiveMatching.Analyzer\ExhaustiveMatching.Analyzer.csproj `
  --configuration Release `
  --output artifacts

License and attribution

This project remains licensed under the BSD 3-Clause License. The original copyright notice and license conditions are retained. The original author's and contributors' names are not used to endorse this fork.