xamarin-macios/docs/nativeaot.md

NativeAOT

We've added experimental support for using NativeAOT when publishing iOS, tvOS, Mac Catalyst and macOS apps in .NET 8.

NativeAOT may produce smaller and/or faster apps - or it may not. It's very important to test and profile to determine the results of enabling NativeAOT.

Our initial testing shows significant improvements both in size (up to 50% smaller) and startup (up to 50% faster). For more information about performance see .NET 8 Performance Improvements in .NET MAUI.

However, it is important to point out that NativeAOT requires trimming whole applications (using <MtouchLink>Full</MtouchLink>, which is enabled by default) and is much more restrictive and aggressive in removing code which is not AOT compatible. As a result, if the applications is using some AOT incompatible constructs (e.g. dynamically referencing code for which a dependency cannot be statically determined), NativeAOT compiler might remove them during build time, which can result in crashes at runtime. To warn users about when this can happen, trimming and AOT warnings are produced and they should not be neglected. Instead, all such warnings should be addressed, code adapted accordingly, and the application must be tested and profiled in this configuration. Only then it is safe to assume that the application is compatible with NativeAOT and should not cause any unexpected behaviour.

Finally, there could be cases when fixing mentioned trimming and AOT warnings is not possible, i.e. warnings coming from referenced frameworks or third-party libraries. In such cases, <MtouchLink>SdkOnly</MtouchLink> can be specified on the project level and could help as a workaround. This affects the application size, but even in this mode NativeAOT tends to produce up to 28% smaller applications compared to Mono showing a great potential of this new experimental feature.

How to enable NativeAOT?

NativeAOT is enabled by setting the PublishAot property to true in the project file:

<PropertyGroup>
	<PublishAot>true</PublishAot>
</PropertyGroup>

Notes

NativeAOT is only used when publishing (dotnet publish). In particular dotnet build -t:Publish is not equivalent to dotnet publish, only dotnet publish will enable NativeAOT.

Unsupported workaround: set the _IsPublishing property to true to make dotnet build think it's dotnet publish:

<PropertyGroup>
	<PublishAot>true</PublishAot>
	<_IsPublishing>true</_IsPublishing>
</PropertyGroup>

This can be useful to install and run apps with NativeAOT from the IDE, because it's not possible to use dotnet publish when running from the IDE.

Compatibility and limitations

There are no known issues specific to our platforms with NativeAOT; but the limitations are exactly the same as for other supported platforms.

Nevertheless, we would like to point out a few features that are not available with NativeAOT, that are with Mono, when targeting Apple platforms:

• NativeAOT does not support managed debugging.

• There's no interpreter when using NativeAOT, and as such the UseInterpreter and MtouchInterpreter properties have no effect.

• NativeAOT requires trimming, and MAUI isn't trimmer-safe, and thus unfortunately MAUI projects don't typically work with NativeAOT (we hope to rectify this situation for .NET 9).