Skip to main content
October 13, 2020
Uncategorized

C#/WinRT Version 0.8 and the .NET5 RC2 Release

We have several important updates to share with the latest release of C#/WinRT. This release is feature complete for consumption scenarios, which means that all features for using our generated Windows SDK projections to call WinRT APIs are now in their final form. We expect C#/WinRT to have parity with .NET Native and .NET Core 3, and we encourage customers to update to .NET5 RC2 and give us feedback before our final release in November.

First, with the latest CsWinRT NuGet package we have added tooling improvements for component authors. These improvements make it easy for component authors to generate a C# projection by simply referencing the NuGet package and specifying a few project properties.  To demonstrate this functionality, we have added an end-to-end sample for component authors to the CsWinRT repo.

Second, we have made runtime updates that ship in the .NET5 RC2 release. The runtime and generated projection code now take advantage of many .NET5 features such as Function Pointers for improved performance and IDynamicInterfaceCastable (IDIC) to implement natural C#-style casts. The latter has allowed us to fix several bugs involving InvalidCastExceptions. These latest C#/WinRT updates have been integrated into the Windows SDK projections for .NET5 RC2. To use these latest updates, install the newest release of Visual Studio, version 16.8 Preview 4, which includes the .NET5 RC2 SDK.


C#/WinRT Tooling Experience

Improved C#/WinRT Tooling

We have improved the C#/WinRT tooling experience for component authors. Component authors can now add a reference to the CsWinRT NuGet package and specify a few project properties to easily generate a projection, which can then be consumed in a .NET5 application.

The following C# project file code snippet demonstrates how to use this updated tooling with a C++/WinRT component project named “SimpleMathComponent” in your solution. To build the projection using C#/WinRT, all you need is a project reference to the component project and the CsWinRTIncludes property which specifies which namespaces to project.

<ItemGroup>
  <ProjectReference Includes = “..\SimpleMathComponent\SimpleMathComponent.vcxproj”>
</ItemGroup>

<PropertyGroup>
  <CSWinRTIncludes>SimpleMathComponent</CSWinRTIncludes>
</PropertyGroup>

Building a project with these properties along with a reference to the CsWinRT NuGet package will invoke the cswinrt.exe tool behind the scenes, generating your C# interop code and assembly. The generated assembly can then be used in a .NET5 application.

You can also specify additional project properties to customize the behavior of C#/WinRT, such as which namespaces to exclude from building the projection and the location for generated project source files. For more details on this updated tooling, refer to this document.

Component Author Sample

We have added an end to end sample for component authors to our repo. This sample expands upon the example code snippet above using a “SimpleMathComponent” with basic math operations. It shows component authors how to generate a .NET5 projection and NuGet package from the C++/WinRT component, and how to consume the NuGet package from a .NET5 console application. The projection C# project file in this sample demonstrates how to invoke cswinrt.exe with the new tooling support.

To use this sample, you can follow along with the associated walkthrough in our docs.


C#/WinRT Runtime Updates

New Features

We have recently completed feature work for IDynamicInterfaceCastable (IDIC) in our latest .NET5 projections. This makes it possible to now use natural C# style casts for projected interfaces. With IDIC we have also been able to fix several InvalidCastException bugs that early adapters have run into.

Here is an example using the new IDIC functionality in a .NET5 C# project:

var agileObject = (IAgileObject)(object)new 
Windows.Foundation.WwwFormUrlDecoder("https://www.microsoft.com");

In this example, we cast an object of type Windows.Foundation.WWWFormUrlDecoder from the Windows Runtime APIs to IAgileObject, which is a type projected by C#/WinRT. With IDIC we are now able to make this cast, whereas before you would have to explicitly use the method object.As().

C#/WinRT now also uses function pointers in the runtime and the projection code it generates, resulting in improved performance.


Breaking Changes

There are a few breaking changes with our latest C#/WinRT projections for the .NET5 RC2 release, including some of the updates mentioned above. A list of known breaking changes has been added to the CsWinRT repo.

The main changes for .NET5 RC2 include the following:

  • We have added strong name signing to the SDK and runtime assembly, winrt.runtime.dll. This means that assemblies built with previous versions of winrt.runtime.dll are not compatible, including the Windows SDK and WinUI. All dependencies will have to be updated to the latest .NET5 RC2 versions.
  • Some WinRT types may have differences in default values when projected, which may raise issues if relying on default values. For example, Foundation.DateTime is projected to System.DateTimeOffset in C# and these types have different default values.
  • The add event accessor return type has changed from Runtime.InteropServices.WindowsRuntime.EventRegistrationToken to void. We no longer project the System.Runtime.InteropServices.WindowsRuntime namespace, as it has been removed from .NET5.
  • Projected XAML classes still require an explicit registration in the app startup path. This will be fixed in the RTM release. Here is an example of the code you would need to add:
public App() {
   WinRT.ComWrappersSupport.RegisterProjectionAssembly(typeof(App).Assembly);
}


Known Issues

Known issues to note with this release of C#/WinRT include:

  • ReadyToRun is not supported for applications using the .NET5 Windows 10 TFM. These applications should install the latest .NET5 SDK from the RTM branch to get the fix. More details can be found in this issue.
  • .NET5 RC2 is not compatible with WinUI 3 Preview 2. This will be resolved in WinUI 3 Preview 3.


Summary

These newest updates with C#/WinRT version 0.8 and the .NET5 RC2 release have introduced improved tooling for component authors, closed feature gaps with .NET5, and addressed several bugs that developers have been facing. We continue to work on fixing bugs and improving performance for the .NET5 RTM release in November, as well as adding project support for Authoring & Hosting.

To stay updated with the latest on C#/WinRT or to provide any feedback, visit the CsWinRT repo and the developer docs.