跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

avalonia

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.

managedcode · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add managedcode/dotnet-skills --skill 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." compatibility: "Requires a .NET SDK and Avalonia packages; desktop runtime validation requires the target OS and display environment."

Avalonia

Workflow

  1. 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 for 12 and the Avalonia 11 docs for 11; do not copy 12-only APIs into 11.
  2. 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.
  3. 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 for templates, properties, resources, and command patterns.
  4. 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.
  5. 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.
  6. Validate native integrations, dialogs, resources, shutdown, DPI, accessibility, and packaging on each supported platform. Read references/platforms-and-publishing.md before trimming or Native AOT. Read the documentation map only for the selected topic.
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]

Install

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>

Read: typed view-model bindings

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 = $"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>

Write: a styleable custom-control property

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.

Options and constraints

  • Set <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault> explicitly for consistent 11/12 behavior. Use ReflectionBinding only for a justified dynamic path; review trimming risk.
  • Use 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.
  • Choose an intentional ShutdownMode and owner for `ShowD
阅读完整来源 ↗