avalonia-wpf-migration
Use when migrating a WPF application to Avalonia, mapping WPF concepts to Avalonia equivalents, or understanding differences between WPF and Avalonia APIs.
SKILL.mdskills/avalonia/avalonia-wpf-migration/SKILL.md
GitHubAvalonia WPF Migration
Overview
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
| WPF | Avalonia | Notes |
|---|---|---|
.xaml |
.axaml |
Extension differs |
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" |
xmlns="https://github.com/avaloniaui" |
Root namespace |
DependencyProperty |
StyledProperty / DirectProperty |
See property system |
FrameworkElement |
Control |
Base for custom controls |
UserControl (base) |
UserControl |
Same name, similar API |
Control (for lookless) |
TemplatedControl |
Different base class |
Style with TargetType |
ControlTheme with TargetType |
Styling lookless controls |
Style with Triggers |
Style with nested styles + pseudoclasses |
No Triggers in Avalonia |
DataTrigger |
Binding + pseudoclass / Classes binding |
Pattern change |
ResourceDictionary Source= |
ResourceInclude Source="avares://..." |
URI scheme differs |
pack://application:,,,/ |
avares://AssemblyName/ |
Asset URI scheme |
Window.ShowDialog() |
window.ShowDialog(owner) |
Requires owner parameter |
MessageBox.Show() |
No built-in — use dialog or notification | API removed |
Dispatcher.Invoke() |
Dispatcher.UIThread.InvokeAsync() |
Async-first |
BindingOperations.ClearBinding() |
control.ClearValue(prop) |
Slightly different |
x:Static |
x:Static |
Same |
TemplateBinding |
TemplateBinding |
Same |
RelativeSource Self |
{Binding $self.Property} |
Different syntax |
RelativeSource AncestorType |
{Binding $parent[TypeName].Property} |
Different syntax |
EventTrigger + Storyboard |
Animation in styles |
Different animation system |
BitmapImage + Uri |
Bitmap + AssetLoader |
Different image loading |
IValueConverter |
IValueConverter |
Same interface |
IMultiValueConverter |
IMultiValueConverter |
Same interface |
ObservableCollection<T> |
ObservableCollection<T> |
Same |
ICommand |
ICommand |
Same |
CollectionViewSource |
DataGridCollectionView |
Different class |
Frame + NavigationService |
ContentControl + ViewModel swap | MVVM pattern preferred |
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 */ });
What Works Without Changes
INotifyPropertyChangedimplementationsICommandimplementationsObservableCollection<T>usageIValueConverterimplementations- Data binding patterns (with namespace/syntax adjustments)
- Most MVVM framework code (ReactiveUI, CommunityToolkit.Mvvm)
ItemsControl,ListBox,DataGrid(similar APIs)- 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 - Using
FrameworkElementas base class — useControl Style TargetTypewithoutx:Keyfor ControlThemes — template not applied