avalonia-app-development

Use when setting up Avalonia app structure, resource dictionaries, application lifetimes, startup configuration, cross-platform project setup, or App.axaml configuration.

SKILL.md

GitHub

Avalonia App Development

Overview

Avalonia app entry: Program.cs builds and runs an AppBuilder. App.axaml + App.axaml.cs is the root. Platform lifetime determines how the app runs (Desktop vs Single-view for mobile/WASM).

Program.cs

using Avalonia;
using Avalonia.ReactiveUI; // or remove if not using ReactiveUI

class Program
{
    [STAThread]
    public static void Main(string[] args) => BuildAvaloniaApp()
        .StartWithClassicDesktopLifetime(args);

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .WithInterFont()
            .LogToTrace();
            // .UseReactiveUI() // add if using ReactiveUI
}

App.axaml

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyApp.App"
             RequestedThemeVariant="Default">
    <Application.DataTemplates>
        <local:ViewLocator/>
    </Application.DataTemplates>
    <Application.Styles>
        <FluentTheme/>
    </Application.Styles>
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceInclude Source="avares://MyApp/Assets/Colors.axaml"/>
            </ResourceDictionary.MergedDictionaries>
            <SolidColorBrush x:Key="AccentBrush" Color="#FF5722"/>
        </ResourceDictionary>
    </Application.Resources>
</Application>

App.axaml.cs

public partial class App : Application
{
    public override void Initialize() => AvaloniaXamlLoader.Load(this);

    public override void OnFrameworkInitializationCompleted()
    {
        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
        {
            desktop.MainWindow = new MainWindow
            {
                DataContext = new MainViewModel()
            };
        }
        else if (ApplicationLifetime is ISingleViewApplicationLifetime singleView)
        {
            singleView.MainView = new MainView
            {
                DataContext = new MainViewModel()
            };
        }
        base.OnFrameworkInitializationCompleted();
    }
}

Application Lifetimes

Lifetime Interface Platforms
Classic Desktop IClassicDesktopStyleApplicationLifetime Windows, macOS, Linux
Single View ISingleViewApplicationLifetime iOS, Android, WASM
Lifetime-less None Headless testing

Resource Dictionaries

<!-- Colors.axaml (standalone resource dictionary) -->
<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Color x:Key="PrimaryColor">#FF5722</Color>
    <SolidColorBrush x:Key="PrimaryBrush" Color="{StaticResource PrimaryColor}"/>
    <sys:Double x:Key="DefaultCornerRadius" xmlns:sys="clr-namespace:System;assembly=mscorlib">8</sys:Double>
</ResourceDictionary>

Include with:

<ResourceInclude Source="avares://MyApp/Assets/Colors.axaml"/>

StaticResource vs DynamicResource

StaticResource DynamicResource
Resolved Once at load time On every access
Runtime changes No Yes
Theme variants No Yes (required)
Performance Faster Slightly slower

Use DynamicResource for anything theme-variant-aware. Use StaticResource for constants that never change.

Assets

<!-- In .csproj -->
<ItemGroup>
    <AvaloniaResource Include="Assets/**"/>
</ItemGroup>

Access: avares://MyApp/Assets/logo.png

Cross-Platform Project Structure

MyApp/
  MyApp.csproj           — Desktop (Windows/macOS/Linux)
  Program.cs
  App.axaml + .cs
  Views/
  ViewModels/
  Assets/
MyApp.Mobile/            — Optional: iOS/Android
  MyApp.Mobile.csproj
MyApp.Browser/           — Optional: WASM
  MyApp.Browser.csproj
MyApp.Core/              — Shared ViewModels/Models
  MyApp.Core.csproj

Community Libraries & Tooling

Dependency Injection / Hosting

Library NuGet Purpose
Lemon.Hosting.Avaloniaui Lemon.Hosting.Avaloniaui .NET Generic Host integration for Avalonia
Prism.Avalonia Prism.Avalonia IoC, modules, regions, navigation
AvaloniaInside.Shell GitHub: AvaloniaInside/Shell Shell navigation + side menu for mobile/desktop

Hot Reload / Dev Tools

Tool NuGet / Repo Purpose
HotAvalonia HotAvalonia Hot reload for AXAML without restart
Live.Avalonia GitHub: worldbeater/Live.Avalonia Live reloading for development
Avant Garde GitHub: kuiperzone/AvantGarde Standalone cross-platform XAML previewer
DevTools for Avalonia devtools.nlnet.net Enhanced runtime inspector and debugger

Localization

Library NuGet Purpose
Echoes GitHub: Voyonic-Systems/Echoes Simple type-safe translations/i18n

Misc

  • ShowMeTheXaml.Avalonia — display corresponding XAML at runtime for demos/docs (ShowMeTheXaml.Avalonia)
  • Verify.Avalonia — extends Verify for Avalonia headless UI snapshot testing (Verify.Avalonia)
  • Sortable.Avalonia — animated drag-drop sort behavior attachments (sortable-avalonia)
  • AsyncImageLoader.Avalonia — async image loading from web for Image controls (AsyncImageLoader.Avalonia)

Common Mistakes

  • Using StartWithClassicDesktopLifetime for mobile/WASM (must use ISingleViewApplicationLifetime)
  • AvaloniaXamlLoader.Load(this) missing in Initialize() — styles and resources not loaded
  • Using StaticResource for ThemeVariant-sensitive resources — dark mode won't update
  • Asset path casing mismatch on Linux (Assets/Logo.png vs assets/logo.png)