[Windows] Improve NativeAOT support

[morning4coffe-dev]

NativeAOT is publishing option in .NET and WinAppSDK 1.6 that introduced official support for AOT on Windows. However, MAUI’s Windows target currently requires a lot of manual adjustments to build and run successfully under NativeAOT.

This issue proposes improving out-of-the-box support so that enabling PublishAot=true works without extra steps as current gaps lead to build errors, analyzer warnings, and runtime crashes out of the box (unless developers manually tweak/trim project files and MAUI package).

Current State / Findings

Platform/Packaging

• On .NET 10 Preview 5/6, NativeAOT only worked with packaged apps (based on observations/discussions)
• With MAUI AOT, packaging + signing must be performed after publish
  • In my tests, I included CreateMsixAfterPublish
  • Open question: Can/should we standardize this and enable it as part of publish if it still has issues?

Build Configuration / Properties

• Runtime Identifier
  RuntimeIdentifierOverride must be set (e.g. p:RuntimeIdentifierOverride=win10-x64)

Errors observed:

• RuntimeIdentifier 'win10-x64' is not recognized
• Ahead-of-time compilation is not supported for the target runtime identifier 'win10-x64'

PRI Resource Generation

• Publishing sometimes fails due to a PRI resource generation error
• Workaround: set EmbedXbfInPri=false.

Symbols Included in Package

• Debug symbols are getting included, nearly doubling package size
• Workaround: disable symbols on user project to reduce size:

<DebugSymbols>false</DebugSymbols>
<DebugType>None</DebugType>

Observed MAUI Codebase Gaps

• General nativeAOT support improvements #31228 Many core projects are not marked IsAotCompatible, so no AOT incompatibility warnings are surfaced

• General nativeAOT support improvements #31228 Several important classes are missing partial declarations

• General nativeAOT support improvements #31228 Some projects require AllowUnsafeBlocks due to generated code that uses unsafe for trimming (e.g., LoopableCollectionView.cs, RelativeLayout.cs, …)

• Misc nativeAOT Windows stability adjustments #31274 MauiNavigationView OnApplyTemplate types need DynamicDependency attributes

• Misc nativeAOT Windows stability adjustments #31274 Font loading issues observed in FindFontFamilyName (invoking Win2D CanvasFontSet)

• CollectionView issues observed when used in a NativeAOT app

• ShellView items dynamic loading issue, some initial work explored in this commit: https://github.com/dotnet/maui/blob/0ce34239378075553082d5fb90e18f313cb7b07f/src/Controls/src/Core/Handlers/Shell/ShellItemHandler.Windows.cs

• Additional findings expected after updating CsWinRT to 2.3.0-prerelease.250720.1:
  Various types in Maui.Networking (Connectivity.Native.uwp.cs) use in a cast operation is a [ComImport] interface which is not compatible with CsWinRT objects

• part Misc nativeAOT Windows stability adjustments #31274 Add "Build Configuration / Properties" to msbuild/docs

Tests & Documentation

• Add Windows to nativeAOT template integration test #31250 Integration Tests: Add coverage in AOTTemplateTest to validate packaged publish + run for Windows
• Docs: Update documentation with:
  • Remaining manual steps that cannot be moved into .targets
  • Known issues and mitigations
  • Common pitfalls (RIDs, PRI generation, symbol size) and recommended defaults

Benefits

• Simplifies developer experience: no manual csproj edits apart PublishAot or obscure analyzer fixes
• Aligns MAUI with .NET’s AOT strategy and WinAppSDK’s capabilities
• Improves startup performance and drastically reduces app size on Windows
• In my simple sample app I was able to achieve a reduction from 89.5 MiB to 37 MiB with a noticeable startup time boost

Info

• Tested on my side with .NET: 10.0.100-preview.6
• Microsoft.WindowsAppSDK: 1.7.250606001

References

• Related MAUI issues: How to Publish Trimmed or AOT on Windows? #26031, Does Maui Support NativeAOT Now? #29263, nativeaot failed on windows #29651

[morning4coffe-dev]

Any suggestions are welcome. CC @simonrozsival, @mattleibow, @manodasanW, @vitek-karas, @Sergio0694

Hi MS, any news on this ? My Windows Maui app is also having issues with AOT compilation on windows. Should I wait for windows maui to catch up (is someone working on these AOT issues) or is it recommended to switch to Windows SDK apps for full AOT. My understanding was that when Maui moved to Windows SDK 1.6 then AOT should work in Maui but it's not. Would like to stay in Maui but AOT is a must for me.