Diagram and winrt.runtime background (microsoft#599)

* update diagrams and description, structure doc for winrt.runtime

* remove line

* wording

* remove netstandard2 references

* remove netstandard2 from structure.md

* COM wrapper management link

* update formatting and add back benchmark project

* add benchmarks proj

Co-authored-by: Manodasan Wignarajah <[email protected]>

README.md

@@ -8,17 +8,19 @@ WinRT APIs are defined in `*.winmd` format, and C#/WinRT includes tooling that g
 
 ## C#/WinRT Architecture
 
-### Component Authors
+The C#/WinRT runtime assembly, `WinRT.Runtime.dll`, is required by all C#/WinRT assemblies.  It provides an abstraction layer over the .NET runtime, supporting .NET 5. The runtime assembly implements several features for all projected C#/WinRT types, including WinRT activation, marshaling logic, and [COM wrapper](https://docs.microsoft.com/dotnet/standard/native-interop/com-wrappers) lifetime management.
 
-Component Authors need to build a C#/WinRT projection for .NET5+ targets.
+### Create and distribute an interop assembly
+
+Component authors need to build a C#/WinRT projection assembly for .NET5+ consumers. In the diagram below, the **cswinrt.exe** tool processes Windows Metadata (`*.winmd`) files in the "Contoso" namespace to create projection source files. These source files are then compiled into an interop projection assembly named `Contoso.projection.dll`. The projection assembly must be distributed along with the implementation assemblies (`Contoso.*.dll`) as a NuGet package.
 
 <img alt="Creating projection"
     src="docs/images/Diagram_CreateProjection.jpg"
     width="70%" height="50%">
 
-### Application Developers
+### Reference an interop assembly
 
-.NET5+ apps reference the NuGet package, which pulls in the projection assembly instead of a winmd.
+Application developers on .NET5+ can reference C#/WinRT interop assemblies by adding a reference to the interop NuGet package. This replaces any `*.winmd` references. The .NET5+ application includes `WinRT.Runtime.dll` which handles WinRT type activation logic.
 
 <img alt = "Adding projection"
     src="docs/images/Diagram_AddProjection.jpg"

docs/structure.md

@@ -4,19 +4,19 @@ This document describes the CsWinRT repository organization. Documentation and s
 
 ## [`nuget`](../nuget)
 
-Contains source files for producing a C#/WinRT NuGet package, which is regularly built, signed, and published to nuget.org by Microsoft.  The C#/WinRT NuGet package contains the cswinrt.exe compiler, and both versions of the winrt.runtime.dll.
+Contains source files for producing a C#/WinRT NuGet package, which is regularly built, signed, and published to nuget.org by Microsoft.  The C#/WinRT NuGet package contains the **cswinrt.exe** compiler and the runtime assembly, `WinRT.Runtime.dll`.
 
 ## [`src/Authoring`](../src/Authoring)
 
 Contains projects for implementing authoring and hosting support.
 
 ## [`src/Benchmarks`](../src/Benchmarks)
 
-Contains benchmarks written using BenchmarkDotNet to track the performance of scenarios in the generated projection.  To run the benchmarks using the CsWinRT projection, run **benchmark.cmd**.  To run the same benchmarks using the built-in WinMD support in NET Core 3.1 to compare against as a baseline, run **benchmark_winmd.cmd**.
+Contains benchmarks written using BenchmarkDotNet to track the performance of scenarios in the generated projection.  To run the benchmarks using the CsWinRT projection, run `benchmark.cmd`.  To run the same benchmarks using the built-in WinMD support in NET Core 3.1 to compare against as a baseline, run `benchmark_winmd.cmd`.
 
 ## [`src/cswinrt`](../src/cswinrt) 
 
-Contains the sources and cswinrt.vcxproj project file for building the C#/WinRT compiler, cswinrt.exe.  The projection's base library is contained in /cswinrt/strings/WinRT.cs, which is processed by /strings.props to generate string literals contained in the compiler.
+Contains the sources and `cswinrt.vcxproj` project file for building the C#/WinRT compiler, **cswinrt.exe**.  The projection's base library is contained in src/cswinrt/strings/WinRT.cs, which is processed by src/Strings.props to generate string literals contained in the compiler.
 
 The compiler uses the [WinMD NuGet package](http://aka.ms/winmd/nuget) for parsing [ECMA-335 metadata](http://www.ecma-international.org/publications/standards/Ecma-335.htm) files.  The WinMD github repo includes a [winmd.natvis](https://github.com/microsoft/winmd/blob/master/vs/winmd.natvis) script for debugging metadata parsing.  A symlink can be used to install the script:
   > for /f "tokens=2*" %i in ('reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal ^| findstr Personal') do @for /f "tokens=2" %k in ('"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\vswhere" -latest ^| findstr catalog_productLineVersion') do @echo %j\Visual Studio %k\Visualizers| for /f "delims=" %l in ('more') do @md "%l" 2>nul & mklink "%l\winmd.natvis" "c:\git\winmd\vs\winmd.natvis" 
@@ -40,16 +40,23 @@ Contains several projects for generating and building projections from the Windo
 
 Contains various testing-related projects:
 
-- [`TestComponentCSharp`](../src/Tests/TestComponentCSharp): This is an implementation of a WinRT test component, defined in class.idl and used by the UnitTest project.  To complement the general TestComponent above, the TestComponentCSharp  tests scenarios specific to the C#/WinRT language projection.
+- [`TestComponentCSharp`](../src/Tests/TestComponentCSharp): This is an implementation of a WinRT test component, defined in `class.idl` and used by the UnitTest project.  To complement the general TestComponent above, the TestComponentCSharp  tests scenarios specific to the C#/WinRT language projection.
 
 - [`UnitTest`](../src/Tests/UnitTest): Unit tests for validating the Windows SDK, WinUI, and Test projections generated above.  All pull requests should ensure that this project executes without errors.
 
 - [`HostTest`](../src/Tests/HostTest): Unit tests for WinRT.Host.dll, which provides hosting for runtime components written in C#.
 
 ## [`src/TestWinRT`](https://github.com/microsoft/TestWinRT/)
 
-C#/WinRT makes use of the standalone [TestWinRT](https://github.com/microsoft/TestWinRT/) repository for general language projection test coverage.  This repo is cloned via **get_testwinrt.cmd** into the `src` folder, so that the cswinrt.sln can resolve its reference to TestComponent.vcxproj.  The resulting `TestComponent` and `BenchmarkComponent` files are consumed by the UnitTest  and Benchmarks projects above.
+C#/WinRT makes use of the standalone [TestWinRT](https://github.com/microsoft/TestWinRT/) repository for general language projection test coverage.  This repo is cloned into the root of the C#/WinRT repo, via `get_testwinrt.cmd`, so that `cswinrt.sln` can resolve its reference to `TestComponent.vcxproj`.  The resulting `TestComponent` and `BenchmarkComponent` files are consumed by the UnitTest and Benchmarks projects above.
 
 ## [`src/WinRT.Runtime`](../src/WinRT.Runtime) 
 
-Contains the WinRT.Runtime project for building the C#/WinRT runtime assembly, winrt.runtime.dll.  There are two versions of this assembly, providing an abstraction layer over both .NET Standard 2.0 and .NET 5 runtimes.  While all code generated by cswinrt.exe is compatible with .NET Standard 2.0, there are runtime differences which must be addressed.  The primary difference is that the .NET 5 winrt.runtime.dll provides Xaml reference tracking support, which is necessary for WinUI 3 applications to manage memory correctly.  Future performance enhancements, such as function pointer support, may also be limited to the .NET 5 winrt.runtime.dll.
+Contains the WinRT.Runtime project for building the C#/WinRT runtime assembly, `WinRT.Runtime.dll`. The runtime assembly provides an abstraction layer over the .NET 5 runtime, and also provides Xaml reference tracking support which is necessary for WinUI 3 applications to manage memory correctly. The runtime assembly implements the following features for all projected C#/WinRT types:
+
+- WinRT activation and marshaling logic
+- Custom type mappings, primarily for WinUI
+- [COM Wrapper](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.comwrappers?view=net-5.0) management
+- IDynamicInterfaceCastable and ComImport casting support
+- Extension methods common to projected types
+