зеркало из https://github.com/microsoft/CsWinRT.git
Update docs (#1723)
* Update docs * Rename * Make table * Fix * Fix * Fix again * Update * Update versions * Line break * Make version consistent * Update with exception note
This commit is contained in:
Manodasan Wignarajah
GitHub
Родитель
98122be462
Коммит
ad6c15a97a
|
|
@ -0,0 +1,57 @@
|
|||
# .NET trimming and AOT support in C#/WinRT
|
||||
|
||||
## Overview
|
||||
|
||||
As of CsWinRT **2.1.1** and Windows SDK projection 10.0.<sdk_ver>.**38**, generated projections are AOT compatible and various trimming issues have been addressed as part of it. This Windows SDK projection version is included in the .NET SDK starting from the following versions: 6.0.134, 6.0.426, 8.0.109, 8.0.305 or 8.0.402.
|
||||
|
||||
Until these versions are available, you can use the updated Windows SDK projection by specifying the [WindowsSdkPackageVersion property](https://learn.microsoft.com/dotnet/core/project-sdk/msbuild-props#windowssdkpackageversion) and by adding the `Microsoft.Windows.CsWinRT` package reference to enable the source generator used to make WinRT scenarios trimming and AOT compatible. Once you moved to one of the .NET SDK versions that come with it by default, you can remove the `WindowsSdkPackageVersion` property and also the `Microsoft.Windows.CsWinRT` package reference if you added it for the source generator.
|
||||
|
||||
Projections can choose to mark their projects as [IsAotCompatible](https://learn.microsoft.com/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#aot-compatibility-analyzers) to run the relevant .NET AOT analyzers on them. Similarly, C# libraries using C#/WinRT authoring support with the new version are also AOT compatible and can be published for AOT using the [PublishAOT property and running publish](https://learn.microsoft.com/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#publish-native-aot-using-the-cli).
|
||||
|
||||
## Consuming projected types and being trimming and AOT compatible
|
||||
|
||||
If your app or library has non-WinRT classes that implement C#/WinRT projected interfaces or implement WinRT mapped built-in .NET interfaces and are passed across the ABI to other WinRT functions, the class needs to be marked `partial`. 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 produce diagnostics when such types are not marked `partial`. The severity and scope of the diagnostics are determined by `CsWinRTAotWarningLevel`:
|
||||
|
||||
| Level | Meaning |
|
||||
| ----- | ------- |
|
||||
| 0 | Info diagnostics |
|
||||
| 1 | Warnings for types not marked partial that implement C#/WinRT projected interfaces. |
|
||||
| 2 | Warnings from level 1 plus warnings for types not marked partial that implement WinRT mapped built-in .NET interfaces. |
|
||||
|
||||
It is recommended to set the `CsWinRTAotWarningLevel` to 2 and go through all the warnings and mark such types `partial` or suppress the warning if those types are not passed across the WinRT ABI. By default, if you reference the CsWinRT package, the `CsWinRTAotWarningLevel` is set to 1. If you don't have a CsWinRT package reference, then the .NET default is to set `CsWinRTAotWarningLevel` to 1 if you have marked your binary as AOT compatible either by using `IsAotCompatible` or `PublishAot`. Even though it is only by default enabled as warnings for AOT scenarios, you should manually set it to 1 or 2 if you support trimming and address them.
|
||||
|
||||
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.
|
||||
|
||||
## ICustomPropertyProvider type support on AOT (WinUI binding)
|
||||
|
||||
Non source generated WinUI binding scenarios (i.e not `x:bind`) such as `DisplayMemberPath` make use of `ICustomPropertyProvider`. The implementation for this was reflection based and therby not AOT safe. CsWinRT provides an AOT safe implementation for this support. To make use of this, any classes which are provided as the source for such scenarios should be made `partial` and marked with the `GeneratedBindableCustomProperty` attribute to make the CsWinRT source generator aware that this type is used in such scenarios and it should generate the AOT safe implementation for it. By default, with the empty constructor, the generated implementation will support all public properties. You are able to scope down the supported public properties by manually specfying the property names and indexer types in the constructor. For example: `[GeneratedBindableCustomProperty([nameof(Name), nameof(Value)], [typeof(int)])]`. To help determine the impacted scenarios, we added an exception that gets thrown when you rely on the non AOT safe version of this feature while `PublishAot` is set.
|
||||
|
||||
## 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 directly passing them across the ABI by wrapping them 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](https://github.com/manodasanW/WinUI-Gallery/blob/16ed717700b929dcb6591d32a4f10cd8b102aa07/WinUIGallery/VtableInitialization.cs#L57-L75) and [here](https://github.com/manodasanW/WinUI-Gallery/blob/16ed717700b929dcb6591d32a4f10cd8b102aa07/WinUIGallery/VtableInitialization.cs#L87-L90).
|
||||
|
||||
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.
|
||||
|
||||
## 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](https://learn.microsoft.com/dotnet/core/deploying/ready-to-run#how-is-the-set-of-precompiled-assemblies-chosen) to exclude `WinRT.Runtime.dll` from R2R when building for ARM64.
|
||||
|
||||
## Known issues in general
|
||||
|
||||
1. When the source generator runs, it may produce code that makes use of `unsafe` depending on scenario. If you do not already have the property `AllowUnsafeBlocks` set to `true`, you will see `error CS0227: Unsafe code may only appear if compiling with /unsafe`. To address this, you should set the property `AllowUnsafeBlocks` to `true`. In future builds, we will instead look at producing a diagnostic for this rather than resulting in a compiler error.
|
||||
|
||||
2. In WPF scenarios where you are not building a projection, you may see duplicate type errors where the same generated types are getting generated twice. This is due to a WPF targets issue where the same source generator is ran twice due to the file conflict of it being in multiple packages not being resolved. We are investigating addressing this, but in the mean time, you can workaround it by adding a target similar to the below:
|
||||
|
||||
```
|
||||
<Target Name="RemoveCsWinRTPackageAnalyzer" BeforeTargets="CoreCompile">
|
||||
<ItemGroup>
|
||||
<Analyzer Remove="@(Analyzer)" Condition="%(Analyzer.NuGetPackageId) == 'Microsoft.Windows.CsWinRT'" />
|
||||
</ItemGroup>
|
||||
</Target>
|
||||
```
|
||||
27
docs/aot.md
27
docs/aot.md
|
|
@ -1,27 +0,0 @@
|
|||
# .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](https://learn.microsoft.com/dotnet/core/project-sdk/msbuild-props#windowssdkpackageversion). Projections can choose to mark their projects as [IsAotCompatible](https://learn.microsoft.com/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#aot-compatibility-analyzers) 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](https://learn.microsoft.com/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#publish-native-aot-using-the-cli).
|
||||
|
||||
## 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](https://github.com/manodasanW/WinUI-Gallery/blob/16ed717700b929dcb6591d32a4f10cd8b102aa07/WinUIGallery/VtableInitialization.cs#L57-L75) and [here](https://github.com/manodasanW/WinUI-Gallery/blob/16ed717700b929dcb6591d32a4f10cd8b102aa07/WinUIGallery/VtableInitialization.cs#L87-L90).
|
||||
|
||||
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](https://learn.microsoft.com/dotnet/core/deploying/ready-to-run#how-is-the-set-of-precompiled-assemblies-chosen) to exclude `WinRT.Runtime.dll` from R2R when building for ARM64.
|
||||
|
|
@ -18,7 +18,19 @@ Windows SDK package update version refers to the assembly file version for **Mic
|
|||
|
||||
| CsWinRT version* | Windows SDK <br> package update version | .NET SDK version(s) | Windows App SDK version(s) |
|
||||
|-|-|-|-|
|
||||
| 1.6.3 | 25 | TBA | |
|
||||
| 2.1.1* | 38 (.NET 6) <br> 41 (.NET 8) <br> 39 (.NET 9) | 8.0.402 <br> 8.0.305 <br> 8.0.109 <br> 6.0.426 <br> 6.0.134 | 1.6.0 |
|
||||
| 2.0.8 | 34 | 8.0.400 <br> 8.0.304 <br> 8.0.108 <br> 6.0.425 <br> 6.0.133 | |
|
||||
| 2.0.7 | | | |
|
||||
| 2.0.6 | 33 | | |
|
||||
| 2.0.5 | | | |
|
||||
| 2.0.4 | 31 | 8.0.100 <br> 7.0.403 <br> 7.0.310 <br> 7.0.113 <br> 6.0.416 <br> 6.0.319 <br> 6.0.124 | |
|
||||
| 2.0.3 | 29 | 7.0.305 <br> 7.0.108 <br> 6.0.411 <br> 6.0.314 <br> 6.0.119 | 1.4.4 |
|
||||
| 2.0.2 | | | |
|
||||
| 2.0.1 | 28 | 7.0.101 <br> 6.0.404 <br> 6.0.307 <br> 6.0.112 | |
|
||||
| 2.0.0* | 27 | 6.0.401 <br> 6.0.304 <br> 6.0.109 | 1.2.0 |
|
||||
| 1.6.5 | | | |
|
||||
| 1.6.4 | 26 | 6.0.400 <br> 6.0.302 <br> 6.0.107 | |
|
||||
| 1.6.3 | 25 | 6.0.203 <br> 6.0.105 <br> 5.0.408 <br> 5.0.214 | |
|
||||
| 1.6.1* | 24 | 6.0.202 <br> 6.0.104 <br> 5.0.407 <br> 5.0.213 | 1.1.0-preview2 <br> 0.8.7 |
|
||||
| 1.5.0 | 23 | 6.0.201 <br> 6.0.103 <br> 5.0.406 <br> 5.0.212 | 1.1.0-preview1 <br> |
|
||||
| 1.5.0-prerelease.220124.4 | 23-preview| N/A | 0.8.7-preview1
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче