跳到主要内容

Native AOT Deployment

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 several advantages specifically relevant to 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:

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

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

ViewModels and Dependency Injection

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

Publishing Avalonia Native AOT Applications

Windows

dotnet publish -r win-x64 -c Release

Linux

dotnet publish -r linux-x64 -c Release

macOS

Intel based macOS

dotnet publish -r osx-x64 -c Release

Apple silicon based macOS

dotnet publish -r osx-arm64 -c Release
提示

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

Troubleshooting Common Issues

For ViewModels or services using reflection:

<ItemGroup>
<TrimmerRootDescriptor Include="TrimmerRoots.xml" />
</ItemGroup>

Create a TrimmerRoots.xml:

<linker>
<assembly fullname="YourApplication">
<type fullname="YourApplication.ViewModels*" preserve="all"/>
</assembly>
</linker>

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, please refer to Platform/architecture restrictions.

Additional Resources