Angzhang/breakingchange (#455)

* breaking change doc

* breaking changes doc

* strong name sign

* Add event accessor change

* remove inconsistent build.cmd note

* Update breakingchanges-rc2.md

winui incompat

* Update breakingchanges-rc2.md

* strong name signing edit

* formatting

* formatting

* update title

Co-authored-by: Scott Jones <sjones@microsoft.com>

README.md

@@ -52,12 +52,14 @@ After a successful command-line build, the cswinrt.sln can be launched from the
 
 **Note:** By default, projection projects only generate source files for Release configurations, where cswinrt.exe can execute in seconds. To generate projection sources for Debug configurations, set the project property GenerateTestProjection to 'true'. In either case, existing projection sources under the "Generated Files" folder will still be compiled into the projection assembly. This configuration permits a faster inner loop in Visual Studio.
 
-**Note:** When building the first time, the build clones the testwinrt project. The build depends on this project, but msbuild doesn't consistently pick up the change when the repo is first cloned repo. You may need to build a second time if this is your first build to address the timing issue.
-
 ## Developer Guidance
 
 Please read the [usage](USAGE.md) and [repository structure](STRUCTURE.md) docs for a detailed breakdown. For additional documentation visit <http://aka.ms/cswinrt>.
 
+**Breaking Changes:**
+
+C#/WinRT breaking changes for .NET 5 RC2 are listed [here](docs/breakingchanges-rc2.md).
+
 ## Related Projects
 
 C#/WinRT is part of the [xlang](https://github.com/microsoft/xlang) family of projects that help developers create APIs that can run on multiple platforms and be used with a variety of languages. The mission of C#/WinRT is not to support cross-platform execution directly, but to support the cross-platform goals of .NET Core. 

docs/breakingchanges-rc2.md

@@ -0,0 +1,19 @@
+# Breaking Changes for C#/WinRT in .NET 5.0 RC2
+
+1. With IDynamicInterfaceCastable support, all projected interfaces can now use a simple C#-style cast. Unprojected interfaces must use the `.As<T>()` extension method.
+
+2. Calling any of the [RuntimeReflectionExtension](https://docs.microsoft.com/dotnet/api/system.reflection.runtimereflectionextensions?view=net-5.0) methods is likely to cause issues. The runtime type of a projected class now carries around some state information and helper methods, and should not be dynamically reflected on.
+
+3. Some WinRT types may have differences in default values when projected. This may raise issues if relying on default values. For example, `Windows.Foundation.DateTime` is projected to `System.DateTimeOffset` in C# and these types have different default values.
+
+4. The latest Roslyn compiler is required for C# projects, which come with the following NuGet package:
+
+ ```xml
+ <PackageReference Include="Microsoft.Net.Compilers.Toolset" Version="3.8.0-4.20472.6"
+ ```
+
+5. In RC2 we have added strong-name signing to the runtime assembly, **winrt.runtime.dll**. Assemblies built with the previous version of **winrt.runtime.dll** are not compatible with this change. This includes **Microsoft.Windows.SDK.Net.dll** (the Windows SDK), **Microsoft.WinUI.dll** (WinUI), and any other C#/WinRT projection assemblies. Builds that combine pre-RC2 and post-RC2 projection assemblies may fail with a `CS0012` error, with the message of a missing reference to an assembly with `PublicIKeyToken=null`. This indicates an older assembly without strong name signing. The solution is to update all dependencies to their .NET 5 RC2 versions.
+
+6. The `add` event accessor return type has changed from `System.Runtime.InteropServices.WindowsRuntime.EventRegistrationToken` to `void`. We no longer project the `System.Runtime.InteropServices.WindowsRuntime` type, as it has been removed from .NET5.
+
+7. This update of C#/WinRT with .NET5 RC2 is not compatible with WinUI 3 Preview 2. This will be fixed in WinUI3 Preview 3.