Skip to content

Latest commit

 

History

History
27 lines (14 loc) · 4.53 KB

aot.md

File metadata and controls

27 lines (14 loc) · 4.53 KB
Raw

.NET AOT support in C#/WinRT

Overview

As of CsWinRT 2.1.0-preview and Windows SDK projection 10.0.<sdk_ver>.35-preview, generated projections are AOT compatible. You can use the preview version of the Windows SDK projection by using the WindowsSdkPackageVersion property. Projections can choose to mark their projects as IsAotCompatible to run the relevant .NET AOT analyzers on them. Similarly, C# libraries using C#/WinRT authoring support with the new versions are also AOT compatible and can be published for AOT using the PublishAOT property and running publish.

Consuming projected types and being AOT compatible

If your app or library has non-WinRT classes that implement C#/WinRT projected interfaces or built-in .NET interfaces that are mapped to WinRT types and are passed across the ABI to other WinRT functions, the class needs to be marked partial in order to be AOT compatible. Marking it partial allows the source generator distributed with C#/WinRT to add an attribute to the class which has the necessary logic to produce the WinRT vtable for it in a way that is both trimming and AOT compatible. To help with this, there is a code fixer that will warn you when such types are not marked partial. The default warning level (CsWinRTAotWarningLevel) for this code fixer is 1 which is to not warn for scenarios involving only built-in types. But if you pass types implementing only built-in interfaces that are mapped to WinRT across the WinRT ABI, it recommended to set the warning level to 2 and mark such types partial or suppress the warning if those types are not passed across the WinRT ABI.

The source generator also detects other scenarios such as boxing of arrays and instantiations of generic WinRT types for which it generates code that will allow the WinRT vtable for it to be looked up when passed across the WinRT ABI.

In general, this also means that if your app or library has a dependency on another library that uses or returns types falling into one of those above scenarios, that library needs to have also been ran with the updated CsWinRT version for your app or library to be AOT compatible. This is similar to the general .NET requirement where all your dependencies need to be AOT compatible for your app or library to be AOT compatible.

Known issues when publishing for AOT

There are a couple issues related to our AOT support that are known with the current release which will be addressed in future updates or be fixed in .NET:

  1. If any built-in .NET private types implementing mapped WinRT interfaces are passed across the WinRT ABI, they will not be detected by the source generator and thereby not be AOT compatible. You can workaround this by either avoiding passing them across the ABI or by registering your own WinRT vtable lookup function using WinRT.ComWrappersSupport.RegisterTypeComInterfaceEntriesLookup and WinRT.ComWrappersSupport.RegisterTypeRuntimeClassNameLookup. An example of this can be seen here and here.

  2. In WinUI apps, you might run into a race condition which triggers a hang during .NET GC needing to restart the app. This is the result of an exception being thrown unexpectedly during GC due to an invalid handle.

  3. If you have an app or library that just consumes WinRT types and doesn't generate a projection, it still needs a CsWinRT package reference in order for the source generator to run on it and make it AOT compatible. We will be looking at addressing this to avoid this requirement for the official version.

Known issues when publishing for JIT

  1. When publishing for ARM64 with ReadyToRun (R2R) enabled while targeting .NET 6, you may see a failed to optimize error. You can workaround this by moving your project to target .NET 8 or by using PublishReadyToRunExclude to exclude WinRT.Runtime.dll from R2R when building for ARM64.