MetadataReader: add remarks and example (#4140)

* MetadataReader: add remarks and example

* Bump .NET Core version to support C# 8.0

Co-authored-by: Andy De George <[email protected]>

Author: MSDN-WhiteKnight

samples/snippets/csharp/api/system.reflection.metadata/metadatareader/MetadataReaderSnippets.cs

@@ -0,0 +1,30 @@
+using System;
+using System.IO;
+using System.Collections.Generic;
+using System.Reflection.Metadata;
+using System.Reflection.PortableExecutable;
+
+namespace MetadataReaderSnippets
+{
+    class MetadataReaderSnippets
+    {
+        public static void Run()
+        {
+            //<SnippetMetadataReader>
+            using var fs = new FileStream("Example.dll", FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
+            using var peReader = new PEReader(fs);
+
+            MetadataReader mr = peReader.GetMetadataReader();
+
+            foreach (TypeDefinitionHandle tdefh in mr.TypeDefinitions)
+            {
+                TypeDefinition tdef = mr.GetTypeDefinition(tdefh);
+
+                string ns = mr.GetString(tdef.Namespace);
+                string name = mr.GetString(tdef.Name);
+                Console.WriteLine($"{ns}.{name}");
+            }
+            //</SnippetMetadataReader>
+        }
+    }
+}

samples/snippets/csharp/api/system.reflection.metadata/metadatareader/MetadataReaderSnippets.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.Reflection.Metadata" Version="1.8.0" />
+  </ItemGroup>
+
+</Project>

samples/snippets/csharp/api/system.reflection.metadata/metadatareader/Program.cs

@@ -0,0 +1,12 @@
+using System;
+
+namespace MetadataReaderSnippets
+{
+    class Program
+    {
+        static void Main()
+        {
+            MetadataReaderSnippets.Run();
+        }
+    }
+}

xml/System.Reflection.Metadata/MetadataReader.xml

@@ -22,7 +22,23 @@
   <Interfaces />
   <Docs>
     <summary>Reads metadata as defined by the ECMA 335 CLI specification.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+## Remarks
+<xref:System.Reflection.Metadata.MetadataReader> reads the contents of tables and heaps from the specified CLI metadata. It operates low-level constructs such as type and method definitions. For a higher level API to inspect the contents of assemblies using reflection constructs, see <xref:System.Reflection.MetadataLoadContext>.
+
+You can use constructors, such as <xref:System.Reflection.Metadata.MetadataReader.%23ctor(System.Byte%2A,System.Int32)>, to create an instance of <xref:System.Reflection.Metadata.MetadataReader> for a given memory location. To read metadata from the Portable Executable assembly file, create <xref:System.Reflection.PortableExecutable.PEReader> and use the <xref:System.Reflection.Metadata.PEReaderExtensions.GetMetadataReader(System.Reflection.PortableExecutable.PEReader)> extension method.
+
+The format of CLI metadata is defined by the ECMA-335 specification. For more information, see [Standard ECMA-335 - Common Language Infrastructure (CLI)](http://www.ecma-international.org/publications/standards/Ecma-335.htm) on the Ecma International Web site.
+
+## Examples
+This example shows how to create <xref:System.Reflection.Metadata.MetadataReader> for an assembly and read all type definitions from it:
+
+[!code-csharp[](~/samples/snippets/csharp/api/system.reflection.metadata/metadatareader/MetadataReaderSnippets.cs#MetadataReader)]
+
+ ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">