Skip to main content

Native AOT

Native AOT (Ahead-of-Time) compilation allows you to publish your Avalonia applications as self-contained executables with native performance characteristics. This guide covers Avalonia-specific considerations and setup for Native AOT deployment.

Benefits for Avalonia applications​

Native AOT compilation provides the following advantages for Avalonia applications:

  • Faster application startup time, particularly beneficial for desktop applications
  • Reduced memory footprint for resource-constrained environments
  • Self-contained deployment without requiring .NET runtime installation
  • Improved security through reduced attack surface (no JIT compilation)
  • Smaller distribution size when combined with trimming

Setting up Native AOT for Avalonia​

Project configuration​

Add the following to your .csproj file(s).

<PropertyGroup>
    <!-- Only needed for the main executable project -->
    <PublishAot>true</PublishAot>

    <!-- Add to all projects/libraries in use, to ensure AOT compatibility -->
    <IsAotCompatible>true</IsAotCompatible>

    <!-- Necessary before Avalonia 12.0, was used for accessiblity APIs -->
    <BuiltInComInteropSupport>false</BuiltInComInteropSupport>
</PropertyGroup>

For information, please see Native AOT deployment on the .NET documentation site.

Avalonia-specific considerations​

XAML loading​

When using Native AOT, XAML is compiled into the application at build time. Ensure you:

  • Use x:CompileBindings="True" in your XAML files
  • Avoid dynamic XAML loading at runtime
  • Use static resource references instead of dynamic resources where possible

Assets and resources​

  • Bundle all assets as embedded resources
  • Use AvaloniaResource build action for your assets
  • Avoid dynamic asset loading from external sources

View models and dependency injection​

  • Register your view models at startup
  • Use compile-time DI configuration
  • Avoid reflection-based service location

Publishing Avalonia Native AOT applications​

To publish your app, run dotnet publish in the command line:

dotnet publish -r <runtime> -c Release

As an example, dotnet publish -r osx-arm64 -c Release would publish the app for Apple Silicon devices.

For more information, please see Native AOT deployment and dotnet publish on the .NET documentation site.

tip

You can then use Apple's lipo tool to combine both Intel and Apple Silicon binaries, enabling you to ship Universal binaries.

Add a trimmer root descriptor to your .csproj file.

.csproj
<ItemGroup>
    <ProjectReference Include="..\YourAssembly\YourAssembly.csproj" />
    <TrimmerRootAssembly Include="YourAssembly" />
</ItemGroup>

For information, please see Trimming on the .NET documentation site.

Known limitations​

When using Native AOT with Avalonia, be aware of these limitations:

  • Dynamic control creation must be configured in trimmer settings
  • Some third-party Avalonia controls may not be AOT-compatible
  • Platform-specific features need explicit configuration
  • Live preview in design-time tools may be limited

Platform support​

For platform support, refer to Platform/architecture restrictions.

Avalonia XPF​

If you are using Avalonia XPF, Native AOT is also supported. See XPF: Native AOT for XPF-specific setup and usage.

See also​

On this page