Avalonia WPF Migration

Overview

Target: Avalonia 12.x (12.1.x recommended); 11.x notes are labeled (11.x); see avalonia-versions. Avalonia 12 requires net8.0+ (net10.0 recommended) — .NET Framework and netstandard2.0 targets are not supported, so retarget WPF apps on .NET Framework to modern .NET first (Avalonia 11.3 is the last line supporting them).

Avalonia's API is intentionally WPF-like. Most XAML, binding, and MVVM patterns transfer directly. Key differences: styling system, ControlTemplates → ControlThemes, no Triggers, .axaml extension, namespace differences.

Quick Mapping Table

Styles: No Triggers

WPF:

<!-- WPF - DOES NOT WORK in Avalonia -->
<Style TargetType="Button">
    <Style.Triggers>
        <Trigger Property="IsMouseOver" Value="True">
            <Setter Property="Background" Value="Red"/>
        </Trigger>
    </Style.Triggers>
</Style>

Avalonia:

<Style Selector="Button:pointerover">
    <Setter Property="Background" Value="Red"/>
</Style>

ControlTemplate → ControlTheme

WPF:

<Style TargetType="Button">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="Button">
                ...
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</Style>

Avalonia:

<ControlTheme TargetType="Button" x:Key="{x:Type Button}">
    <Setter Property="Template">
        <ControlTemplate>
            ...
        </ControlTemplate>
    </Setter>
</ControlTheme>

RelativeSource Binding

<!-- WPF -->
<TextBlock Text="{Binding RelativeSource={RelativeSource AncestorType=Window}, Path=Title}"/>

<!-- Avalonia -->
<TextBlock Text="{Binding $parent[Window].Title}"/>
<TextBlock Text="{Binding $self.Tag}"/>
<TextBlock Text="{Binding $parent.Tag}"/>

Asset URIs

<!-- WPF -->
<Image Source="pack://application:,,,/Assets/logo.png"/>

<!-- Avalonia -->
<Image Source="avares://MyApp/Assets/logo.png"/>

Dialogs

// WPF
MessageBox.Show("Hello");
var dialog = new OpenFileDialog();
dialog.ShowDialog();

// Avalonia
// Use StorageProvider for file dialogs (see avalonia-services skill)
// Use WindowNotificationManager for notifications
// For message dialogs: use a community library like MessageBox.Avalonia
// or implement a simple dialog Window
var result = await new ConfirmDialog("Are you sure?").ShowDialog<bool>(owner);

Dispatcher

// WPF
Dispatcher.Invoke(() => { /* UI update */ });

// Avalonia
await Dispatcher.UIThread.InvokeAsync(() => { /* UI update */ });
// or
Dispatcher.UIThread.Post(() => { /* fire-and-forget */ });

Bindings (12.0+)

Compiled bindings are the default: WPF-style {Binding Name} needs x:DataType on the root/DataTemplate, otherwise it fails to compile. Quick path for ported XAML: add x:DataType, or use {ReflectionBinding Name}, or set <AvaloniaUseCompiledBindingsByDefault>false</AvaloniaUseCompiledBindingsByDefault>. Data-annotation validation is opt-in.

MVVM Frameworks

• ReactiveUI: package ReactiveUI.Avalonia (12.x); Avalonia.ReactiveUI does not exist for 12.
• CommunityToolkit.Mvvm: unchanged.
• WPF SystemDecorations/WindowStyle-like tweaks → Window.WindowDecorations (12.0+).

What Works Without Changes

• INotifyPropertyChanged implementations
• ICommand implementations
• ObservableCollection<T> usage
• IValueConverter implementations
• Data binding patterns (with namespace/syntax adjustments)
• Most MVVM framework code (ReactiveUI, CommunityToolkit.Mvvm)
• ItemsControl, ListBox (similar APIs); DataGrid needs the Avalonia.Controls.DataGrid package
• Grid, StackPanel, DockPanel layouts (same attached properties)

Common Mistakes

• Using WPF Trigger syntax — silently ignored or compile error
• Using pack:// URIs — assets not found
• Calling MessageBox.Show() — doesn't exist
• Targeting net48 / netstandard2.0 with Avalonia 12 — unsupported
• {Binding} without x:DataType in 12 — compile error
• Using FrameworkElement as base class — use Control
• Style TargetType without x:Key for ControlThemes — template not applied