avaloniaBuild and debug Avalonia 11/12 .NET applications with XAML, compiled bindings, MVVM, custom controls, desktop lifetimes, and platform publishing. USE FOR: Avalonia projects, bindings, commands, themes, UI dispatch, trimming, or Native AOT. DO NOT USE FOR: WPF, WinUI, MAUI, Uno, or Avalonia XPF compatibility work. INVOKES: inspect installed versions, impleme…
Independent GitHub snapshot · Automated classification · Original documentation governs
.axaml files, entrypoint, and supported OS/RIDs. Keep Avalonia packages on one compatible version. Use the Avalonia 12 docs for 12 and the Avalonia 11 docs for 11; do not copy 12-only APIs into 11.Program.BuildAvaloniaApp, App.axaml, views, view models, and domain/services separate. Desktop hosts use StartWithClassicDesktopLifetime and create MainWindow in OnFrameworkInitializationCompleted; single-view targets require their own lifetime. The previewer can have no application lifetime.x:DataType describes the binding type; it does not set the runtime DataContext. Avalonia 12 enables compiled bindings by default; explicitly enable them on 11. Read references/bindings-and-controls.md for templates, properties, resources, and command patterns.CommunityToolkit.Mvvm for observable state and commands when appropriate. Prefer cancellable asynchronous service operations, surface errors, and marshal background updates to the UI dispatcher. Keep services independent of controls.StyledProperty for styleable/animatable values and DirectProperty for backed state without style precedence. Use DataTemplate to display data and ControlTemplate/ControlTheme to change a control's visual structure. Use UserControl for application composition, TemplatedControl for reusable skinnable controls, and custom rendering only when needed.flowchart LR
Packages[Installed Avalonia major] --> Docs[Matching 11 or 12 documentation]
Docs --> VM[View model and service]
VM --> Bindings[Typed bindings and commands]
Bindings --> UI[Views, templates, property system]
UI --> Desktop[Desktop lifetime and UI dispatcher]
Desktop --> Verify[Headless tests + native OS checks]
Verify --> Publish[RID-specific publish and packaging]
For a new application, use the official templates rather than inventing project scaffolding:
dotnet new install Avalonia.Templates
dotnet new avalonia.mvvm -o MyApp
dotnet add MyApp/MyApp.csproj package CommunityToolkit.Mvvm
dotnet run --project MyApp/MyApp.csproj
For an existing project, select versions matching its target framework and installed Avalonia major:
dotnet add MyApp.csproj package Avalonia.Desktop --version <compatible-version>
dotnet add MyApp.csproj package Avalonia.Themes.Fluent --version <compatible-version>
The view model implements notifications through the toolkit. Wire the runtime context when constructing the view:
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
public partial class MainViewModel : ObservableObject
{
[ObservableProperty]
private string name = "Ada";
[ObservableProperty]
private string greeting = "Ready";
[RelayCommand]
private void Greet() => Greeting = quot;Hello, {Name}";
}
// In App.OnFrameworkInitializationCompleted, after checking desktop lifetime:
// desktop.MainWindow = new MainWindow { DataContext = new MainViewModel() };
In the view, replace MyApp.ViewModels with the actual namespace:
<Window xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:vm="using:MyApp.ViewModels"
x:Class="MyApp.MainWindow"
x:DataType="vm:MainViewModel" x:CompileBindings="True">
<StackPanel Spacing="8" Margin="16">
<TextBox Text="{Binding Name, Mode=TwoWay}" />
<Button Content="Greet" Command="{Binding GreetCommand}" />
<TextBlock Text="{Binding Greeting}" />
</StackPanel>
</Window>
using Avalonia;
using Avalonia.Controls.Primitives;
public class StatusBadge : TemplatedControl
{
public static readonly StyledProperty<string> TextProperty =
AvaloniaProperty.Register<StatusBadge, string>(nameof(Text), "Ready");
public string Text
{
get => GetValue(TextProperty);
set => SetValue(TextProperty, value);
}
}
Define the visual tree in a control theme; keep CLR accessors limited to GetValue/SetValue, because styles and bindings can bypass them. Use property-change hooks for behavior and SetCurrentValue when changing a value without replacing its existing binding.
<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault> explicitly for consistent 11/12 behavior. Use ReflectionBinding only for a justified dynamic path; review trimming risk.Dispatcher.UIThread.InvokeAsync when completion matters, Post for a queued notification, and CheckAccess when deciding whether to marshal. Update bound collections on the UI thread; avoid .Result/.Wait() there.ShutdownMode and owner for ShowDialog<T>(owner). Inject a dialog service into view models instead of constructing windows there.avares:// resources differ from WPF. Do not transplant WPF styles or assume platform behavior is identical.dotnet build <solution> -c Release and the repository's focused tests; verify that typed binding paths compile and commands update observable state.Avalonia.Headless.XUnit or Avalonia.Headless.NUnit for dispatcher-aware control tests. Keep unrelated tests parallel; constrain only a concrete destructive collision domain.