Add introductory interactive pattern matching tutorial

docs/csharp/toc.yml

@@ -19,6 +19,8 @@ items:
       href: tour-of-csharp/tutorials/branches-and-loops.md
     - name: List collections
       href: tour-of-csharp/tutorials/list-collection.md
+    - name: Pattern matching
+      href: tour-of-csharp/tutorials/pattern-matching.md
   - name: C# language strategy
     href: tour-of-csharp/strategy.md
   - name: Learn C# for Java developers

docs/csharp/tour-of-csharp/tutorials/index.md

@@ -1,7 +1,7 @@
 ---
 title: Interactive tutorials
 description: Learn C# in your browser, and get started with your own development environment
-ms.date: 03/20/2025
+ms.date: 04/23/2025
 ---
 # Introduction to C\#
 
@@ -37,6 +37,10 @@ The [Branches and loops](branches-and-loops.md) tutorial teaches the basics of s
 
 The [List collection](list-collection.md) lesson gives you a tour of the List collection type that stores sequences of data. You'll learn how to add and remove items, search for items, and sort the lists. You'll explore different kinds of lists.
 
+## Pattern matching
+
+The [Pattern matching](pattern-matching.md) lesson provides an introduction to *pattern matching*. Pattern matching enables you to compare an expression against a pattern. The success of the match determines which program logic to follow. Patterns can compare types, properties of a type, or contents of a list. You can combine multiple patterns using `and`, `or`, and `not` logic. Patterns provide a rich vocabulary to inspect data and make decisions in your program based on that inspection.
+
 ## Set up your local environment
 
 After you finish these tutorials, set up a development environment. You'll want:

docs/csharp/tour-of-csharp/tutorials/pattern-matching.md

@@ -0,0 +1,75 @@
+---
+title: Pattern matching
+description: In this tutorial about pattern matching, you use your browser to learn C# interactively. You're going to write C# code and see the results of compiling and running your code directly in the browser.
+ms.date: 05/02/2025
+---
+# Match data against patterns
+
+This tutorial teaches you how to use pattern matching to inspect data in C#. You write small amounts of code, then you compile and run that code. The tutorial contains a series of lessons that explore different kinds of types in C#. These lessons teach you the fundamentals of the C# language.
+
+> [!TIP]
+> When a code snippet block includes the "Run" button, that button opens the interactive window, or replaces the existing code in the interactive window. When the snippet doesn't include a "Run" button, you can copy the code and add it to the current interactive window.
+
+The preceding tutorials demonstrated built-in types and types you define as tuples or records. Instances of these types can be checked against a *pattern*. Whether an instance matches a pattern determines the actions your program takes. Let's start to explore how you can use patterns.
+
+## Match a value
+
+All the examples in this tutorial use text input that represents a series of bank transactions as comma separated values (CSV) input. In each of the samples you can match the record against a pattern using either an `is` or `switch` expression. This first example splits each line on the `,` character and then *matches* the first string field against the value "DEPOSIT" or "WITHDRAWAL" using an `is` expression. When it matches, the transaction amount is added or deducted from the current account balance. To see it work, press the "Run" button:
+
+:::code language="csharp" interactive="try-dotnet-method" source="./snippets/PatternMatching/Program.cs" id="FirstExample":::
+
+Examine the output. You can see that each line is processed by comparing the value of the text in the first field. The preceding sample could be similarly constructed using the `==` operator to test that two `string` values are equal. Comparing a variable to a constant is a basic building block for pattern matching. Let's explore more of the building blocks that are part of pattern matching.
+
+## Enum matches
+
+Another common use for pattern matching is to match on the values of an `enum` type. This next sample processes the input records to create a *tuple* where the first value is an `enum` value that notes a deposit or a withdrawal. The second value is the value of the transaction. To see it work, press the "Run" button:
+
+> [!WARNING]
+> Don't copy and paste. The interactive window must be reset to run the following samples. If you make a mistake, the window hangs, and you need to refresh the page to continue.
+
+:::code language="csharp" interactive="try-dotnet" source="./snippets/PatternMatching/FirstEnumExample.cs" id="IsEnumValue":::
+
+The preceding example also uses an `if` statement to check the value of an `enum` expression. Another form of pattern matching uses a `switch` expression. Let's explore that syntax and how you can use it.
+
+## Exhaustive matches with `switch`
+
+A series of `if` statements can test a series of conditions. But, the compiler can't tell if a series of `if` statements are *exhaustive* or if later `if` conditions are *subsumed* by earlier conditions. The `switch` expression ensures both of those characteristics are met, which results in fewer bugs in your apps. Let's try it and experiment. Copy the following code. Replace the two `if` statements in the interactive window with the `switch` expression you copied. After you've modified the code, press the "Run" button at the top of the interactive window to run the new sample.
+
+:::code language="csharp" interactive="try-dotnet" source="./snippets/PatternMatching/EnumSwitchExample.cs" id="SwitchEnumValue":::
+
+When you run the code, you see that it works the same. To demonstrate *subsumption*, reorder the switch arms as shown in the following snippet:
+
+```csharp
+currentBalance += transaction switch
+{
+    (TransactionType.Deposit, var amount) => amount,
+    _ => 0.0,
+    (TransactionType.Withdrawal, var amount) => -amount,
+};
+```
+
+After you reorder the switch arms, press the "Run" button. The compiler issues an error because the arm with `_` matches every value. As a result, that final arm with `TransactionType.Withdrawal` never runs. The compiler tells you that something's wrong in your code.
+
+The compiler issues a warning if the expression tested in a `switch` expression could contain values that don't match any switch arm. If some values could fail to match any condition, the `switch` expression isn't *exhaustive*. The compiler also issues a warning if some values of the input don't match any of the switch arms. For example, if you remove the line with `_ => 0.0,`, any invalid values don't match. At run time, that would fail. Once you install the .NET SDK and build programs in your environment, you can test this behavior. The online experience doesn't display warnings in the output window.
+
+## Type patterns
+
+To finish this tutorial, let's explore one more building block to pattern matching: the *type pattern*. A *type pattern* tests an expression at run time to see if it's the specified type. You can use a type test with either an `is` expression or a `switch` expression. Let's modify the current sample in two ways. First, instead of a tuple, let's build `Deposit` and `Withdrawal` record types that represent the transactions. Add the following declarations at the bottom of the interactive window:
+
+:::code language="csharp" interactive="try-dotnet" source="./snippets/PatternMatching/FinalExampleProgram.cs" id="RecordDeclarations":::
+
+Next, add this method after the `Main` method to parse the text and return a series of records:
+
+:::code language="csharp" interactive="try-dotnet" source="./snippets/PatternMatching/FinalExampleProgram.cs" id="ParseToRecord":::
+
+Finally, replace the `foreach` loop in the `Main` method with the following code:
+
+:::code language="csharp" interactive="try-dotnet" source="./snippets/PatternMatching/FinalExampleProgram.cs" id="TypePattern":::
+
+Then, press the "Run" button to see the results. This final version tests the input against a *type*.
+
+Pattern matching provides a vocabulary to compare an expression against characteristics. Patterns can include the expression's type, values of types, property values, and combinations of them. Comparing expressions against a pattern can be more clear than multiple `if` comparisons. You explored some of the patterns you can use to match expressions. There are many more ways to use pattern matching in your applications. First, visit the [.NET site](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/intro) to download the .NET SDK, create a project on your machine, and keep coding. As you explore, you can learn more about pattern matching in C# in the following articles:
+
+- [Pattern matching in C#](../../fundamentals/functional/pattern-matching.md)
+- [Explore pattern matching tutorial](../../tutorials/patterns-objects.md)
+- [Pattern matching scenario](../../fundamentals/tutorials/pattern-matching.md)

docs/csharp/tour-of-csharp/tutorials/snippets/PatternMatching/EnumSwitchExample.cs

@@ -0,0 +1,76 @@
+namespace EnumSwitchExample;
+
+// <IsEnumValue>
+public static class ExampleProgram
+{
+    const string bankRecords = """
+    DEPOSIT,   10000, Initial balance
+    DEPOSIT,     500, regular deposit
+    WITHDRAWAL, 1000, rent
+    DEPOSIT,    2000, freelance payment
+    WITHDRAWAL,  300, groceries
+    DEPOSIT,     700, gift from friend
+    WITHDRAWAL,  150, utility bill
+    DEPOSIT,    1200, tax refund
+    WITHDRAWAL,  500, car maintenance
+    DEPOSIT,     400, cashback reward
+    WITHDRAWAL,  250, dining out
+    DEPOSIT,    3000, bonus payment
+    WITHDRAWAL,  800, loan repayment
+    DEPOSIT,     600, stock dividends
+    WITHDRAWAL,  100, subscription fee
+    DEPOSIT,    1500, side hustle income
+    WITHDRAWAL,  200, fuel expenses
+    DEPOSIT,     900, refund from store
+    WITHDRAWAL,  350, shopping
+    DEPOSIT,    2500, project milestone payment
+    WITHDRAWAL,  400, entertainment
+    """;
+
+    public static void Main()
+    {
+        double currentBalance = 0.0;
+
+        foreach (var transaction in TransactionRecords(bankRecords))
+        {
+            // <SwitchEnumValue>
+            currentBalance += transaction switch
+            {
+                (TransactionType.Deposit, var amount) => amount,
+                (TransactionType.Withdrawal, var amount) => -amount,
+                _ => 0.0,
+            };
+            // </SwitchEnumValue>
+            Console.WriteLine($"{transaction.type} => Parsed Amount: {transaction.amount}, New Balance: {currentBalance}");
+        }
+    }
+
+    static IEnumerable<(TransactionType type, double amount)> TransactionRecords(string inputText)
+    {
+        var reader = new StringReader(inputText);
+        string? line;
+        while ((line = reader.ReadLine()) is not null)
+        {
+            string[] parts = line.Split(',');
+
+            string? transactionType = parts[0]?.Trim();
+            if (double.TryParse(parts[1].Trim(), out double amount))
+            {
+                // Update the balance based on transaction type
+                if (transactionType?.ToUpper() is "DEPOSIT")
+                    yield return (TransactionType.Deposit, amount);
+                else if (transactionType?.ToUpper() is "WITHDRAWAL")
+                    yield return (TransactionType.Withdrawal, amount);
+            }
+            yield return (TransactionType.Invalid, 0.0);
+        }
+    }
+}
+
+public enum TransactionType
+{
+    Deposit,
+    Withdrawal,
+    Invalid
+}
+// </IsEnumValue>

docs/csharp/tour-of-csharp/tutorials/snippets/PatternMatching/FinalExampleProgram.cs

@@ -0,0 +1,79 @@
+public static class ExampleProgram
+{
+    const string bankRecords = """
+    DEPOSIT,   10000, Initial balance
+    DEPOSIT,     500, regular deposit
+    WITHDRAWAL, 1000, rent
+    DEPOSIT,    2000, freelance payment
+    WITHDRAWAL,  300, groceries
+    DEPOSIT,     700, gift from friend
+    WITHDRAWAL,  150, utility bill
+    DEPOSIT,    1200, tax refund
+    WITHDRAWAL,  500, car maintenance
+    DEPOSIT,     400, cashback reward
+    WITHDRAWAL,  250, dining out
+    DEPOSIT,    3000, bonus payment
+    WITHDRAWAL,  800, loan repayment
+    DEPOSIT,     600, stock dividends
+    WITHDRAWAL,  100, subscription fee
+    DEPOSIT,    1500, side hustle income
+    WITHDRAWAL,  200, fuel expenses
+    DEPOSIT,     900, refund from store
+    WITHDRAWAL,  350, shopping
+    DEPOSIT,    2500, project milestone payment
+    WITHDRAWAL,  400, entertainment
+    """;
+
+    public static void Main()
+    {
+        double currentBalance = 0.0;
+
+        // <TypePattern>
+        foreach (var transaction in TransactionRecordType(bankRecords))
+        {
+            currentBalance += transaction switch
+            {
+                Deposit d => d.Amount,
+                Withdrawal w => -w.Amount,
+                _ => 0.0,
+            };
+            Console.WriteLine($" {transaction} => New Balance: {currentBalance}");
+        }
+        // </TypePattern>
+    }
+
+    // <ParseToRecord>
+    public static IEnumerable<object?> TransactionRecordType(string inputText)
+    {
+        var reader = new StringReader(inputText);
+        string? line;
+        while ((line = reader.ReadLine()) is not null)
+        {
+            string[] parts = line.Split(',');
+
+            string? transactionType = parts[0]?.Trim();
+            if (double.TryParse(parts[1].Trim(), out double amount))
+            {
+                // Update the balance based on transaction type
+                if (transactionType?.ToUpper() is "DEPOSIT")
+                    yield return new Deposit(amount, parts[2]);
+                else if (transactionType?.ToUpper() is "WITHDRAWAL")
+                    yield return new Withdrawal(amount, parts[2]);
+            }
+            yield return default;
+        }
+    }
+    // </ParseToRecord>
+}
+
+public enum TransactionType
+{
+    Deposit,
+    Withdrawal,
+    Invalid
+}
+
+// <RecordDeclarations>
+public record Deposit(double Amount, string description);
+public record Withdrawal(double Amount, string description);
+// </RecordDeclarations>

docs/csharp/tour-of-csharp/tutorials/snippets/PatternMatching/FirstEnumExample.cs

@@ -0,0 +1,72 @@
+namespace FirstEnumExample;
+
+// <IsEnumValue>
+public static class ExampleProgram
+{
+    const string bankRecords = """
+    DEPOSIT,   10000, Initial balance
+    DEPOSIT,     500, regular deposit
+    WITHDRAWAL, 1000, rent
+    DEPOSIT,    2000, freelance payment
+    WITHDRAWAL,  300, groceries
+    DEPOSIT,     700, gift from friend
+    WITHDRAWAL,  150, utility bill
+    DEPOSIT,    1200, tax refund
+    WITHDRAWAL,  500, car maintenance
+    DEPOSIT,     400, cashback reward
+    WITHDRAWAL,  250, dining out
+    DEPOSIT,    3000, bonus payment
+    WITHDRAWAL,  800, loan repayment
+    DEPOSIT,     600, stock dividends
+    WITHDRAWAL,  100, subscription fee
+    DEPOSIT,    1500, side hustle income
+    WITHDRAWAL,  200, fuel expenses
+    DEPOSIT,     900, refund from store
+    WITHDRAWAL,  350, shopping
+    DEPOSIT,    2500, project milestone payment
+    WITHDRAWAL,  400, entertainment
+    """;
+
+    public static void Main()
+    {
+        double currentBalance = 0.0;
+
+        foreach (var transaction in TransactionRecords(bankRecords))
+        {
+            if (transaction.type == TransactionType.Deposit)
+                currentBalance += transaction.amount;
+            else if (transaction.type == TransactionType.Withdrawal)
+                currentBalance -= transaction.amount;
+            Console.WriteLine($"{transaction.type} => Parsed Amount: {transaction.amount}, New Balance: {currentBalance}");
+        }
+    }
+
+    static IEnumerable<(TransactionType type, double amount)> TransactionRecords(string inputText)
+    {
+        var reader = new StringReader(inputText);
+        string? line;
+        while ((line = reader.ReadLine()) is not null)
+        {
+            string[] parts = line.Split(',');
+
+            string? transactionType = parts[0]?.Trim();
+            if (double.TryParse(parts[1].Trim(), out double amount))
+            {
+                // Update the balance based on transaction type
+                if (transactionType?.ToUpper() is "DEPOSIT")
+                    yield return (TransactionType.Deposit, amount);
+                else if (transactionType?.ToUpper() is "WITHDRAWAL")
+                    yield return (TransactionType.Withdrawal, amount);
+            }
+            yield return (TransactionType.Invalid, 0.0);
+        }
+    }
+}
+
+public enum TransactionType
+{
+    Deposit,
+    Withdrawal,
+    Invalid
+}
+// </IsEnumValue>

docs/csharp/tour-of-csharp/tutorials/snippets/PatternMatching/PatternMatching.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>