{"slug":"managedcode-avalonia","name":"avalonia","description":"Build 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, implement, and validate on the actual target platforms.","long_description":"---\nname: avalonia\ndescription: \"Build 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, implement, and validate on the actual target platforms.\"\ncompatibility: \"Requires a .NET SDK and Avalonia packages; desktop runtime validation requires the target OS and display environment.\"\n---\n\n# Avalonia\n\n## Workflow\n\n1. Inspect the SDK, target frameworks, Avalonia package versions, `.axaml` files, entrypoint, and supported OS/RIDs. Keep Avalonia packages on one compatible version. Use the [Avalonia 12 docs](https://docs.avaloniaui.net/docs/welcome) for 12 and the [Avalonia 11 docs](https://v11.docs.avaloniaui.net/) for 11; do not copy 12-only APIs into 11.\n2. Keep `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.\n3. Use typed compiled bindings and explicit binding modes. `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](references/bindings-and-controls.md) for templates, properties, resources, and command patterns.\n4. Use `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.\n5. Choose `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.\n6. Validate native integrations, dialogs, resources, shutdown, DPI, accessibility, and packaging on each supported platform. Read [references/platforms-and-publishing.md](references/platforms-and-publishing.md) before trimming or Native AOT. Read the [documentation map](references/official-docs-index.md) only for the selected topic.\n\n```mermaid\nflowchart LR\n Packages[Installed Avalonia major] --> Docs[Matching 11 or 12 documentation]\n Docs --> VM[View model and service]\n VM --> Bindings[Typed bindings and commands]\n Bindings --> UI[Views, templates, property system]\n UI --> Desktop[Desktop lifetime and UI dispatcher]\n Desktop --> Verify[Headless tests + native OS checks]\n Verify --> Publish[RID-specific publish and packaging]\n```\n\n## Install\n\nFor a new application, use the official templates rather than inventing project scaffolding:\n\n```bash\ndotnet new install Avalonia.Templates\ndotnet new avalonia.mvvm -o MyApp\ndotnet add MyApp/MyApp.csproj package CommunityToolkit.Mvvm\ndotnet run --project MyApp/MyApp.csproj\n```\n\nFor an existing project, select versions matching its target framework and installed Avalonia major:\n\n```bash\ndotnet add MyApp.csproj package Avalonia.Desktop --version \ndotnet add MyApp.csproj package Avalonia.Themes.Fluent --version \n```\n\n## Read: typed view-model bindings\n\nThe view model implements notifications through the toolkit. Wire the runtime context when constructing the view:\n\n```csharp\nusing CommunityToolkit.Mvvm.ComponentModel;\nusing CommunityToolkit.Mvvm.Input;\n\npublic partial class MainViewModel : ObservableObject\n{\n [ObservableProperty]\n private string name = \"Ada\";\n\n [ObservableProperty]\n private string greeting = \"Ready\";\n\n [RelayCommand]\n private void Greet() => Greeting = $\"Hello, {Name}\";\n}\n\n// In App.OnFrameworkInitializationCompleted, after checking desktop lifetime:\n// desktop.MainWindow = new MainWindow { DataContext = new MainViewModel() };\n```\n\nIn the view, replace `MyApp.ViewModels` with the actual namespace:\n\n```xml\n\n \n \n