Skip to content

Commit 86fa341

Browse files
MikeCodesDotNETMikeCodesDotNET
committed
added native aot info
1 parent d695f7e commit 86fa341

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎docs/deployment/native-aot.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
id: native-aot
3+
title: Native AOT Deployment
4+
---
5+
6+
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.
7+
8+
## Benefits for Avalonia Applications
9+
10+
Native AOT compilation provides several advantages specifically relevant to Avalonia applications:
11+
12+
- Faster application startup time, particularly beneficial for desktop applications
13+
- Reduced memory footprint for resource-constrained environments
14+
- Self-contained deployment without requiring .NET runtime installation
15+
- Improved security through reduced attack surface (no JIT compilation)
16+
- Smaller distribution size when combined with trimming
17+
18+
## Setting Up Native AOT for Avalonia
19+
20+
### 1. Project Configuration
21+
22+
Add the following to your csproj file:
23+
24+
```xml
25+
<PropertyGroup>
26+
<PublishAot>true</PublishAot>
27+
<!-- Recommended Avalonia trimming settings for Native AOT -->
28+
<BuiltInComInteropSupport>false</BuiltInComInteropSupport>
29+
<TrimMode>link</TrimMode>
30+
</PropertyGroup>
31+
```
32+
33+
### 2. Trimming Configuration
34+
35+
Native AOT requires trimming. Add these trim settings specific to Avalonia:
36+
37+
```xml
38+
<ItemGroup>
39+
<!-- Preserve Avalonia types for reflection -->
40+
<TrimmerRootAssembly Include="Avalonia.Themes.Fluent" />
41+
<TrimmerRootAssembly Include="Avalonia.Themes.Default" />
42+
</ItemGroup>
43+
```
44+
45+
## Avalonia-Specific Considerations
46+
47+
### XAML Loading
48+
When using Native AOT, XAML is compiled into the application at build time. Ensure you:
49+
- Use `x:CompileBindings="True"` in your XAML files
50+
- Avoid dynamic XAML loading at runtime
51+
- Use static resource references instead of dynamic resources where possible
52+
53+
### Assets and Resources
54+
- Bundle all assets as embedded resources
55+
- Use `AvaloniaResource` build action for your assets
56+
- Avoid dynamic asset loading from external sources
57+
58+
### ViewModels and Dependency Injection
59+
- Register your ViewModels at startup
60+
- Use compile-time DI configuration
61+
- Avoid reflection-based service location
62+
63+
## Publishing Avalonia Native AOT Applications
64+
65+
### Windows
66+
```bash
67+
dotnet publish -r win-x64 -c Release
68+
```
69+
70+
### Linux
71+
```bash
72+
dotnet publish -r linux-x64 -c Release
73+
```
74+
75+
### macOS
76+
Intel based macOS
77+
```bash
78+
dotnet publish -r osx-x64 -c Release
79+
```
80+
Apple silicon based macOS
81+
```bash
82+
dotnet publish -r osx-arm64 -c Release
83+
```
84+
85+
:::tip
86+
You can then use Apple's [lipo tool](https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary) to combine both Intel and Apple Silicon binaries, enabling you to ship Universal binaries.
87+
:::
88+
89+
## Troubleshooting Common Issues
90+
91+
### 1. Missing XAML Controls
92+
If controls are missing at runtime:
93+
```xml
94+
<ItemGroup>
95+
<!-- Add specific Avalonia controls you're using -->
96+
<TrimmerRootAssembly Include="Avalonia.Controls" />
97+
</ItemGroup>
98+
```
99+
100+
### 2. Reflection-Related Errors
101+
For ViewModels or services using reflection:
102+
```xml
103+
<ItemGroup>
104+
<TrimmerRootDescriptor Include="TrimmerRoots.xml" />
105+
</ItemGroup>
106+
```
107+
108+
Create a `TrimmerRoots.xml`:
109+
```xml
110+
<linker>
111+
<assembly fullname="YourApplication">
112+
<type fullname="YourApplication.ViewModels*" preserve="all"/>
113+
</assembly>
114+
</linker>
115+
```
116+
117+
## Known Limitations
118+
119+
When using Native AOT with Avalonia, be aware of these limitations:
120+
- Dynamic control creation must be configured in trimmer settings
121+
- Some third-party Avalonia controls may not be AOT-compatible
122+
- Platform-specific features need explicit configuration
123+
- Live preview in design-time tools may be limited
124+
125+
## Platform Support
126+
127+
| Platform | Status |
128+
|----------|--------|
129+
| Windows x64 | ✅ Supported |
130+
| Windows Arm64 | ✅ Supported |
131+
| Linux x64 | ✅ Supported | |
132+
| Linux Arm64 | ✅ Supported |
133+
| macOS x64 | ✅ Supported | |
134+
| macOS Arm64 | ✅ Supported |
135+
| Browser | ❌ Not Supported |
136+
137+
## Best Practices
138+
139+
1. **Application Structure**
140+
- Use MVVM pattern consistently
141+
- Minimize reflection usage
142+
- Prefer compile-time configuration
143+
144+
2. **Resource Management**
145+
- Use static resources when possible
146+
- Bundle all required assets
147+
- Implement proper cleanup in IDisposable
148+
149+
3. **Performance Optimization**
150+
- Enable binding compilation
151+
- Use compiled bindings
152+
- Implement proper virtualization for large collections
153+
154+
## Additional Resources
155+
156+
- [Avalonia Sample Applications with Native AOT](https://github.com/AvaloniaUI/Avalonia.Samples)

‎sidebars.js

+1
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,7 @@ const sidebars = {
537537
'items': [
538538
'deployment/macOS',
539539
'deployment/debian-ubuntu',
540+
'deployment/native-aot',
540541
],
541542
},
542543
{

0 commit comments

Comments
 (0)