Allow an example to specify that it is expected to throw an exception (#648)

Only the name (without the namespace) is specified; the FQN could be quite long-winded in the metadata.
Towards #646.

Author: jskeet

standard/arrays.md

@@ -129,6 +129,7 @@ Because of array covariance, assignments to elements of reference type arrays in
 
 > *Example*:
 >
+> <!-- Example: {template:"standalone-console", name:"CovarianceException", expectedException:"ArrayTypeMismatchException"} -->
 > ```csharp
 > class Test
 > {

tools/ExampleExtractor/ExampleMetadata.cs

@@ -23,6 +23,7 @@ public class ExampleMetadata
     public List<string> ExpectedErrors { get; set; }
     public List<string> ExpectedWarnings { get; set; }
     public List<string> ExpectedOutput { get; set; }
+    public string ExpectedException { get; set; }
 
     // Information provided by the example extractor
     public string MarkdownFile { get; set; }

tools/ExampleTester/GeneratedExample.cs

@@ -95,11 +95,19 @@ bool ValidateOutput()
 
             var oldOut = Console.Out;
             List<string> actualLines;
+            Exception? actualException = null;
             try
             {
                 var builder = new StringBuilder();
                 Console.SetOut(new StringWriter(builder));
-                method.Invoke(null, arguments);
+                try
+                {
+                    method.Invoke(null, arguments);
+                }
+                catch (TargetInvocationException outer)
+                {
+                    actualException = outer.InnerException ?? throw new InvalidOperationException("TargetInvocationException had no nested exception");
+                }
                 // Skip blank lines, to avoid unnecessary trailing empties.
                 actualLines = builder.ToString().Replace("\r\n", "\n").Split('\n').Where(line => line != "").ToList();
             }
@@ -108,7 +116,31 @@ bool ValidateOutput()
                 Console.SetOut(oldOut);
             }
             var expectedLines = Metadata.ExpectedOutput ?? new List<string>();
-            return ValidateExpectedAgainstActual("output", expectedLines, actualLines);
+            return ValidateException(actualException, Metadata.ExpectedException) &&
+                ValidateExpectedAgainstActual("output", expectedLines, actualLines);
+        }
+
+        bool ValidateException(Exception? actualException, string? expectedExceptionName)
+        {
+            return (actualException, expectedExceptionName) switch
+            {
+                (null, null) => true,
+                (Exception ex, string name) =>
+                    MaybeReportError(ex.GetType().Name == name, $"  Mismatched exception type: Expected {name}; Was {ex.GetType().Name}"),
+                (null, string name) =>
+                    MaybeReportError(false, $"  Expected exception type {name}; no exception was thrown"),
+                (Exception ex, null) =>
+                    MaybeReportError(false, $"  Exception type {ex.GetType().Name} was thrown unexpectedly; Message: {ex.Message}")
+            };
+
+            bool MaybeReportError(bool result, string message)
+            {
+                if (!result)
+                {
+                    Console.WriteLine(message);
+                }
+                return result;
+            }
         }
 
         bool ValidateExpectedAgainstActual(string type, List<string> expected, List<string> actual)