Location>code7788 >text

AOT compiles Avalonia applications: StarBlog Publisher project practice and challenges

Popularity：268 ℃/2025-03-28 09:27:48

Preface

Recently I used Avalonia to develop an article publishing tool.StarBlog Publisher。

Avalonia is a cross-platform UI framework that can run on Windows, Linux, and macOS. Its features high performance, cross-platform and easy to use.

Avalonia has many advantages, such as high performance, cross-platform, and ease of use. However, it also has some disadvantages, such as a steep learning curve and a difficult document to find.

However, Avalonia is developed based on the .NetCore framework and finally packaged executable file. If framework-dependent release is selected, it is necessary to install the .NetCore runtime environment on the client, which is a huge burden for users. If you use self-contained to publish, the volume is relatively large.

And it is also easy to be decompiled, which is not allowed in some commercial software. (However, my project is open source, so there is no problem)

This article takes the StarBlog Publisher project as an example to record the pitfall process of publishing Avalonia applications using AOT.

The new version 1.1 has been released, welcome to download and try:/star-blog/starblog-publisher/releases

About AOT

Starting from .Net7, gradually supporting AOT releases is a very important feature. AOT releases can compile .Net applications into machine code that does not depend on runtime libraries, which is small in size and is not easily decompiled.

The principle of AOT release is to compile .Net applications into LLVM IR code, and then use the LLVM compiler to compile LLVM IR code into machine code. The LLVM compiler can compile LLVM IR code into machine code for different target platforms.

The current LTS version is .Net8, and the support for AOT has been improved. This time I will try to use AOT to release Avalonia applications.

PS: It is said that .Net9 provides a lot of optimizations and improvements to the AOT method, and I will try it next.

Problems that may occur with AOT

  • Compatibility Issue: AOT compilation may be incompatible with certain dependency libraries, especially those that rely on reflection, dynamic code generation, or JIT compilation. If you encounter problems, you may need to add more configurations in it.
  • Package size: AOT compilation generates larger executables (compared to framework-dependent mode), but starts faster.
  • Debugging Difficulty: Debugging an AOT compiled application may be more difficult.
  • Third-party library: Check whether the third-party library used in the project supports AOT compilation. For example, and is a preview version that may require special attention to its AOT compatibility.
  • Avalonia Specific Configuration: For Avalonia applications, it may be necessary to ensure that XAML-related type information is properly retained.

Modify project files

First, you need to add AOT-related configuration to the project file:

<Project Sdk="">
     <PropertyGroup>
         <OutputType>WinExe</OutputType>
         <TargetFramework>net8.0</TargetFramework>
         <Nullable>enable</Nullable>
         <BuiltInComInteropSupport>true</BuiltInComInteropSupport>
         <ApplicationManifest></ApplicationManifest>
         <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
        
         <!-- AOT related configuration -->
         <PublishAot>true</PublishAot>
         <TrimMode>full</TrimMode>
         <InvariantGlobalization>true</InvariantGlobalization>
         <IlcGenerateStackTraceData>false</IlcGenerateStackTraceData>
         <IlcOptimizationPreference>Size</IlcOptimizationPreference>
         <IlcFoldIdenticalMethodBodies>true</IlcFoldIdenticalMethodBodies>
        
         <JsonSerializerIsReflectionEnabledByDefault>true</JsonSerializerIsReflectionEnabledByDefault>
     </PropertyGroup>

     <!-- The rest remains unchanged -->
 </Project>

JSON serialization problem

JSON serialization is a common problem in AOT compilation environments because it usually depends on runtime reflection.

There are several places in this project that use JSON

One is application settings, the other is network request

Let’s talk about the conclusion first: Compared to AOT, if you want to use AOT, you should give priority to using the library.

Modify application settings Support AOT

If you have to use it, you need to modify it. Skip it directly if you use it.

using System;
 using;
 using;
 using;
 using;
 using ; // Add this namespace

 namespace ;

 // Add JsonSerializable feature to generate serialized code for AOT
 [JsonSerializable(typeof(AppSettings))]
 internal partial class AppSettingsContext: JsonSerializerContext
 {
 }

 public class AppSettings {
     private static readonly string ConfigPath = (
         (),
         "StarBlogPublisher",
         ""
     );

     // ... Existing code ...

     private static AppSettings Load() {
         try {
             if ((ConfigPath)) {
                 var json = (ConfigPath);
                 // Use AOT friendly serialization method
                 var settings = (json, );
                 return settings ?? new AppSettings();
             }
         }
         catch (Exception ex) {
             // If loading fails, return to default settings
             ($"Failed to load app settings. {ex}");
         }

         return new AppSettings();
     }

     public void Save() {
         try {
             var directory = (ConfigPath);
             if (!(directory)) {
                 (directory);
             }

             // Use AOT friendly serialization method
             var json = (this, , new JsonSerializerOptions {
                 WriteIndented = true
             });
             (ConfigPath, json);

             // Trigger configuration change event
             SettingsChanged?.Invoke(this, );
         }
         catch (Exception) {
             // todo handles the situation of saving failure
         }
     }
 }

explain

  1. Added[JsonSerializable]Features andJsonSerializerContextDerived classes, which is the key to supporting JSON serialization in .NET. This generates serialized code at compile time, rather than relying on runtime reflection.
  2. ModifiedLoad()andSave()Method, useAs type information, not relying on runtime type inference.
  3. This approach ensures that in an AOT environment, all required serialization code is generated at compile time without running-time reflection.

In addition, you need to make sure that AOT compiled JSON source generator is enabled in the project file:

<PropertyGroup>
     <!-- Other attributes -->
     <JsonSerializerIsReflectionEnabledByDefault>false</JsonSerializerIsReflectionEnabledByDefault>
 </PropertyGroup>

These modifications will ensure that the AppSettings class can correctly perform JSON serialization and deserialization in the AOT compilation environment.

Refit's JSON serialization problem in AOT mode

In AOT mode, the JSON processing of the Refit library can also be used

The library is installed first, and additional configuration is required to handle type information.

Add type pre-registration

You need to create a new class to pre-register the types used in all API interfaces:

using;
 using;
 using;
 using;

 namespace ;

 /// <summary>
 /// Compile the type used by pre-register Refit for AOT
 /// </summary>
 public static class RefitTypeRegistration
 {
     /// <summary>
     /// Call this method when the application starts to ensure that all types are pre-registered
     /// </summary>
     public static void RegisterTypes()
     {
         // Register commonly used response types
          = () => new JsonSerializerSettings
         {
             TypeNameHandling = ,
             // Add a custom converter if needed
             Converters = new List<JsonConverter>
             {
                 // Custom converters can be added
             }
         };

         // Warm-up types - Make sure these types are included when AOT compiled
         var types = new[]
         {
             typeof(ApiResponse<>),
             typeof(ApiResponse<List<Category>>),
             typeof(ApiResponse<List<WordCloud>>),
             // Add other API response types
             typeof(List<Category>),
             typeof(Category),
             typeof(WordCloud),
             // Add all model types
         };

         // Trigger type loading
         foreach (var type in types)
         {
             var _ = ;
         }
     }
 }

Modify the ApiService class

Modify the ApiService class to ensure that the type is registered at initialization:

using Refit;
 using;
 using System;
 using;
 using;
 using;

 namespace ;

 public class ApiService {
     private static ApiService? _instance;

     public static ApiService Instance {
         get {
             _instance ??= new ApiService();
             return _instance;
         }
     }

     private readonly RefitSettings _refitSettings;

     private ApiService() {
         // Make sure the type is registered
         ();
        
         // Configure Refit settings
         _refitSettings = new RefitSettings(new NewtonsoftJsonContentSerializer(
             new JsonSerializerSettings
             {
                 TypeNameHandling = ,
                 // Disable reflection optimization, which is important in AOT environment
                 TypeNameAssemblyFormatHandling =
             }
         ));
     }

     // ... The rest of the code remains the same ...
 }

Initialize type registration

Make sure to call type registration when the application starts:

public override void OnFrameworkInitializationCompleted()
 {
     // Make sure Refit type is registered
     ();
    
     // Other initialization codes...
    
     ();
 }

Adding AOT compatibility configuration

Since AOT compilation has limitations on reflection and dynamic code generation, you need to add a file to specify the type that needs to be retained:

<Directives xmlns="/netfx/2013/01/metadata">
     <Application>
         <!-- Add assemblies and types that need to be preserved in AOT -->
         <Assembly Name="StarBlogPublisher" Dynamic="Required All" />
         <Assembly Name="" Dynamic="Required All" />
         <Assembly Name="Avalonia" Dynamic="Required All" />

         <!-- Refit related assembly -->
         <Assembly Name="Refit" Dynamic="Required All" />
         <Assembly Name="" Dynamic="Required All" />

         <!-- Add API interface and model type -->
         <Assembly Name="StarBlogPublisher">
             <Type Name="" Dynamic="Required All" />
             <Type Name="" Dynamic="Required All" />
             <Type Name="" Dynamic="Required All" />
         </Assembly>
        
         <Assembly Name="">
             <Type Name="`1" Dynamic="Required All" />
         </Assembly>
     </Application>
 </Directives>

Then refer to this file in the project file:

<ItemGroup>
    <RdXmlFile Include="" />
</ItemGroup>

release

Use the following command to publish an AOT version of the application:

dotnet publish -c Release -r win-x64 -p:PublishAot=true

For other platforms, the corresponding RID can be replaced:

  • Windows: win-x64
  • macOS: osx-x64
  • Linux: linux-x64

summary

AOT release is an important feature of the .Net platform. It can compile applications into machine code that does not depend on runtime, which not only reduces the size of the release package, but also increases the startup speed and increases the difficulty of decompilation.

There are still some pitfalls in publishing Avalonia applications using AOT. : JSON serialization issues, type registration issues, and AOT compatibility issues. In response to these problems, the following solutions can be solved:

  1. In terms of JSON serialization, libraries with better support for AOT are preferred, and the correctness of serialization is ensured through type pre-registration.
  2. For functions that require reflection, explicitly declaring the types that need to be retained through files, solving the type cropping problem during AOT compilation.
  3. In terms of project configuration, performance and package size are balanced by reasonably setting AOT-related compilation options.

Although there are still some restrictions on AOT release, such as relatively difficult debugging and some third-party libraries may be incompatible, with the development of the .Net platform (especially the version after .Net9), AOT's support will become more and more complete. AOT release is an option worth considering for Avalonia applications that require high performance, small size, decompile protection.

<Previous Next>