From 13025ad3580011ef36ae904254c9e8300d3bcd59 Mon Sep 17 00:00:00 2001 From: rpetrusha Date: Mon, 6 Mar 2017 15:41:24 -0800 Subject: [PATCH 1/2] documented when keyword --- .../language-reference/keywords/when.md | 71 +++++++++++++++ .../language-reference/keywords/when/catch.cs | 30 ++++++ .../language-reference/keywords/when/when.cs | 91 +++++++++++++++++++ 3 files changed, 192 insertions(+) create mode 100644 docs/csharp/language-reference/keywords/when.md create mode 100644 samples/snippets/csharp/language-reference/keywords/when/catch.cs create mode 100644 samples/snippets/csharp/language-reference/keywords/when/when.cs diff --git a/docs/csharp/language-reference/keywords/when.md b/docs/csharp/language-reference/keywords/when.md new file mode 100644 index 0000000000000..342f41d736951 --- /dev/null +++ b/docs/csharp/language-reference/keywords/when.md @@ -0,0 +1,71 @@ +--- +title: "when (C# Reference) | Microsoft Docs" +ms.date: "2017-03-07" +ms.prod: .net +ms.technology: + - "devlang-csharp" +ms.topic: "article" +f1_keywords: + - "when_CSharpKeyword" + - "when" +dev_langs: + - "CSharp" +helpviewer_keywords: + - "when keyword [C#]" +ms.assetid: dd543335-ae37-48ac-9560-bd5f047b9aea +caps.latest.revision: 30 +author: "BillWagner" +ms.author: "wiwagn" +translation.priority.ht: + - "cs-cz" + - "de-de" + - "es-es" + - "fr-fr" + - "it-it" + - "ja-jp" + - "ko-kr" + - "pl-pl" + - "pt-br" + - "ru-ru" + - "tr-tr" + - "zh-cn" + - "zh-tw" +--- + # when (C# Reference) + +You can use the `when` contextual keyword to specify a filter condition in two contexts: + +- In the `catch` statement of a [try/catch](try-catch.md) or [try/catch/finally](try-catch-finally.md) block. +- In the `case` label of a [switch](switch.md) statement. + +## `when` in a `catch` statement + +Starting with C# 6, `When` can be used in a `catch` statement to specify a condition that must be true for the handler for a specific exception to execute. Its syntax is: + +```cs +catch ExceptionType [e] when (expr) +``` +where *expr* is an expression that evaluates to a Boolean value. If it returns `true`, the exception handler executes; if `false`, it does not. + +The following example uses the `when` keyword to conditionally execute handlers for an @System.Net.HttpRequestException depending on the text of the exception message. + + [!code-cs[when-with-catch](../../../../samples/snippets/csharp/language-reference/keywords/when/catch.cs)] + +## `when` in a `switch` statement + +Starting with 7, `case` labels no longer need be mutually exclusive, and the order in which `case` labels appear in a `switch` statement can determine which switch block executes. The `when` keyword can be used to specify a filter condition that causes its associated case label to be true only if the filter condition is also true. Its syntax is: + +```cs +case (expr) where (when-condition): +``` +where *expr* is a constant pattern or type pattern that is compared to the match expression, and *when-condition* is any Boolean expression. + +The following example uses the `when` keyword to conditionally execute a switch section when a `Shape` object is `null` or has no area. + + [!code-cs[when-with-case#1](../../../../samples/snippets/csharp/language-reference/keywords/when/when.cs#1)] + +## See also + [switch statement](switch.md) + [try/catch statement](try-catch.md) + [try/catch/finally statement](try-catch-finally.md) + diff --git a/samples/snippets/csharp/language-reference/keywords/when/catch.cs b/samples/snippets/csharp/language-reference/keywords/when/catch.cs new file mode 100644 index 0000000000000..d7a755b0f978b --- /dev/null +++ b/samples/snippets/csharp/language-reference/keywords/when/catch.cs @@ -0,0 +1,30 @@ +using System; +using System.Net.Http; +using System.Threading.Tasks; + +class Program +{ + static void Main() + { + Console.WriteLine(MakeRequest().Result); + } + + public static async Task MakeRequest() + { + var client = new System.Net.Http.HttpClient(); + var streamTask = client.GetStringAsync("https://localHost:10000"); + try { + var responseText = await streamTask; + return responseText; + } + catch (HttpRequestException e) when (e.Message.Contains("301")) { + return "Site Moved"; + } + catch (HttpRequestException e) when (e.Message.Contains("404")) { + return "Page Not Found"; + } + catch (HttpRequestException e) { + return e.Message; + } + } +} diff --git a/samples/snippets/csharp/language-reference/keywords/when/when.cs b/samples/snippets/csharp/language-reference/keywords/when/when.cs new file mode 100644 index 0000000000000..b8b0c062364ff --- /dev/null +++ b/samples/snippets/csharp/language-reference/keywords/when/when.cs @@ -0,0 +1,91 @@ +// +using System; + +public abstract class Shape +{ + public abstract double Area { get; } + public abstract double Circumference { get; } +} + +public class Rectangle : Shape +{ + public Rectangle(double length, double width) + { + Length = length; + Width = width; + } + + public double Length { get; set; } + public double Width { get; set; } + + public override double Area + { + get { return Math.Round(Length * Width,2); } + } + + public override double Circumference + { + get { return (Length + Width) * 2; } + } +} + +public class Square : Rectangle +{ + public Square(double side) : base(side, side) + { + Side = side; + } + + public double Side { get; set; } +} + +public class Example +{ + public static void Main() + { + Shape sh = null; + Shape[] shapes = { new Square(10), new Rectangle(5, 7), + sh, new Square(0) }; + foreach (var shape in shapes) + ShowShapeInfo(shape); + } + + private static void ShowShapeInfo(Shape sh) + { + switch (sh) + { + case Shape shape when shape == null: + Console.WriteLine($"An uninitialized shape"); + break; + case Shape shape when sh.Area == 0: + Console.WriteLine($"The shape: {sh.GetType().Name} with no dimensions"); + break; + case Rectangle r when sh.Area > 0: + Console.WriteLine("Information about rectangle:"); + Console.WriteLine($" Dimensions: {r.Length} x {r.Width}"); + Console.WriteLine($" Area: {r.Area}"); + break; + case Square sq when sh.Area > 0: + Console.WriteLine("Information about square:"); + Console.WriteLine($" Length of a side: {sq.Side}"); + Console.WriteLine($" Area: {sq.Area}"); + break; + case Shape shape when sh != null: + Console.WriteLine("A {sh.GetType().Name} shape"); + break; + default: + Console.WriteLine($"The {nameof(sh)} variable does not represent a Shape."); + break; + } + } +} +// The example displays the following output: +// Information about rectangle: +// Dimensions: 10 x 10 +// Area: 100 +// Information about rectangle: +// Dimensions: 5 x 7 +// Area: 35 +// The sh variable does not represent a Shape. +// The shape: Square with no dimensions +// From fd65975e534d9394a55f7fbb8abbb0dfca7081ee Mon Sep 17 00:00:00 2001 From: rpetrusha Date: Mon, 6 Mar 2017 23:36:00 -0800 Subject: [PATCH 2/2] Incorporated review comments --- .../language-reference/keywords/when.md | 2 +- .../language-reference/keywords/when/when.cs | 49 ++++++++++--------- 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/csharp/language-reference/keywords/when.md b/docs/csharp/language-reference/keywords/when.md index 342f41d736951..9ee9d5f26e287 100644 --- a/docs/csharp/language-reference/keywords/when.md +++ b/docs/csharp/language-reference/keywords/when.md @@ -60,7 +60,7 @@ case (expr) where (when-condition): ``` where *expr* is a constant pattern or type pattern that is compared to the match expression, and *when-condition* is any Boolean expression. -The following example uses the `when` keyword to conditionally execute a switch section when a `Shape` object is `null` or has no area. +The following example uses the `when` keyword to test for `Shape` objects that have an area of zero, as well as to test for a variety of `Shape` objects that have an area greater than zero. [!code-cs[when-with-case#1](../../../../samples/snippets/csharp/language-reference/keywords/when/when.cs#1)] diff --git a/samples/snippets/csharp/language-reference/keywords/when/when.cs b/samples/snippets/csharp/language-reference/keywords/when/when.cs index b8b0c062364ff..1fc3157784d2b 100644 --- a/samples/snippets/csharp/language-reference/keywords/when/when.cs +++ b/samples/snippets/csharp/language-reference/keywords/when/when.cs @@ -45,47 +45,50 @@ public static void Main() { Shape sh = null; Shape[] shapes = { new Square(10), new Rectangle(5, 7), - sh, new Square(0) }; + new Rectangle(10, 10), sh, new Square(0) }; foreach (var shape in shapes) ShowShapeInfo(shape); } - private static void ShowShapeInfo(Shape sh) + private static void ShowShapeInfo(Object obj) { - switch (sh) + switch (obj) { - case Shape shape when shape == null: - Console.WriteLine($"An uninitialized shape"); + case Shape shape when shape.Area == 0: + Console.WriteLine($"The shape: {shape.GetType().Name} with no dimensions"); break; - case Shape shape when sh.Area == 0: - Console.WriteLine($"The shape: {sh.GetType().Name} with no dimensions"); - break; - case Rectangle r when sh.Area > 0: - Console.WriteLine("Information about rectangle:"); + case Rectangle r when r.Area > 0: + Console.WriteLine("Information about the rectangle:"); Console.WriteLine($" Dimensions: {r.Length} x {r.Width}"); Console.WriteLine($" Area: {r.Area}"); break; - case Square sq when sh.Area > 0: - Console.WriteLine("Information about square:"); + case Square sq when sq.Area > 0: + Console.WriteLine("Information about the square:"); Console.WriteLine($" Length of a side: {sq.Side}"); Console.WriteLine($" Area: {sq.Area}"); break; - case Shape shape when sh != null: - Console.WriteLine("A {sh.GetType().Name} shape"); + case Shape shape: + Console.WriteLine($"A {shape.GetType().Name} shape"); + break; + case null: + Console.WriteLine($"The {nameof(obj)} variable is uninitialized."); break; default: - Console.WriteLine($"The {nameof(sh)} variable does not represent a Shape."); + Console.WriteLine($"The {nameof(obj)} variable does not represent a Shape."); break; } } } // The example displays the following output: -// Information about rectangle: -// Dimensions: 10 x 10 -// Area: 100 -// Information about rectangle: -// Dimensions: 5 x 7 -// Area: 35 -// The sh variable does not represent a Shape. -// The shape: Square with no dimensions +// Information about the rectangle: +// Dimensions: 10 x 10 +// Area: 100 +// Information about the rectangle: +// Dimensions: 5 x 7 +// Area: 35 +// Information about the rectangle: +// Dimensions: 10 x 10 +// Area: 100 +// The obj variable is uninitialized. +// The shape: Square with no dimensions //