XAML в Avalonia: ключові відмінності від WPF

У попередній статті ми детально розібрали XAML: namespace'и, ResourceDictionary, StaticResource та DynamicResource. Все це стосувалося WPF. Але якщо ви вже знаєте WPF XAML — ви знаєте 90% Avalonia XAML.

Залишилися 10%. Саме вони відрізняють файл MainWindow.xaml (WPF) від MainWindow.axaml (Avalonia). Ці відмінності невеликі, але якщо не знати про них — компілятор і IDE будуть лякати незрозумілими помилками на рівному місці.

Ця стаття — коротка шпаргалка: що змінилося, чому і як правильно.

Чому 90% залишається незмінним

Перш ніж перейти до відмінностей — важливо зафіксувати, що не змінюється:

Весь WPF XAML-синтаксис, що ви вивчали — валідний в Avalonia. Це не перебільшення, а факт архітектурного рішення команди Avalonia: зберегти максимальну сумісність з WPF на рівні розмітки.

Відмінність 1: .axaml замість .xaml

Перше, що помічаєш у структурі Avalonia-проєкту — всі файли розмітки мають розширення .axaml, а не .xaml.

WPF:       MainWindow.xaml  +  MainWindow.xaml.cs
Avalonia:  MainWindow.axaml +  MainWindow.axaml.cs

Чому саме .axaml

Причина суто практична — конфлікт інструментів у Visual Studio.

Коли у проєкті є файл з розширенням .xaml, Visual Studio автоматично відкриває його у WPF XAML Designer. Дизайнер намагається завантажити WPF-типи, не знаходить їх у Avalonia-збірці і падає з помилками. Це спричиняло масу плутанини у проєктах, де розробники використовували і WPF, і Avalonia.

Розширення .axaml (Avalonia XAML) не асоційоване з WPF Designer — Visual Studio відкриває його як звичайний текстовий XML-файл, а Avalonia Extension підключає власний previewer.

Технічне уточнення

.axaml — це конвенція, не технічна вимога. Avalonia чудово компілює і .xaml файли — синтаксис абсолютно однаковий. Але використання .axaml є офіційною рекомендацією команди Avalonia і це те, що генерують усі шаблони.

// .axaml.cs виглядає ідентично до .xaml.cs
public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent(); // Та сама магія, що в WPF
    }
}

Відмінність 2: Namespace URI

Найпомітніша відмінність у першому рядку XAML-файлу — різний URI у xmlns:

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="MyWpfApp.MainWindow"
        Title="WPF вікно">

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        x:Class="MyAvaloniaApp.MainWindow"
        Title="Avalonia вікно">

Що змінилося:

• xmlns (default namespace): WPF URI → Avalonia URI
• xmlns:x (XAML-директиви): незмінний — той самий http://schemas.microsoft.com/winfx/2006/xaml

Avalonia URI https://github.com/avaloniaui — так само просто ідентифікатор-рядок, як і WPF URI. Він теж не завантажує нічого з GitHub. Просто більш лаконічний і легко запам'ятовується.

Що маппує Avalonia URI

Аналогічно до WPF (де XmlnsDefinition реєструвала маппінг у сборці), в Avalonia збірки також реєструють маппінг своїх namespace'ів на https://github.com/avaloniaui:

// В Avalonia.Controls.dll (спрощено)
[assembly: XmlnsDefinition(
    "https://github.com/avaloniaui",
    "Avalonia.Controls")]

[assembly: XmlnsDefinition(
    "https://github.com/avaloniaui",
    "Avalonia.Media")]

[assembly: XmlnsDefinition(
    "https://github.com/avaloniaui",
    "Avalonia.Layout")]

// ... інші namespace'и

Тому <Button>, <TextBlock>, <Grid>, <StackPanel> — все це доступне без prefix'а, так само як у WPF.

Відмінність 3: using: замість clr-namespace:

У WPF для підключення власних класів ви писали:

xmlns:local="clr-namespace:MyApp"
xmlns:vm="clr-namespace:MyApp.ViewModels"
xmlns:ctrl="clr-namespace:MyApp.Controls"

В Avalonia є скорочений еквівалентний синтаксис через using::

xmlns:local="using:MyApp"
xmlns:vm="using:MyApp.ViewModels"
xmlns:ctrl="using:MyApp.Controls"

Обидва синтаксиси підтримуються в Avalonia. Але using: є рекомендованим — він коротший і більш читабельний. Всі шаблони Avalonia генерують саме using:.

Для класів з іншої збірки формат такий самий, як і в WPF — потрібен assembly=:

<!-- WPF -->
xmlns:ext="clr-namespace:SomeLib.Extensions;assembly=SomeLib"

<!-- Avalonia (також працює clr-namespace, але using: скорочує запис) -->
xmlns:ext="using:SomeLib.Extensions;assembly=SomeLib"

Відмінність 4: Ресурси та ThemeResource

Механізм ресурсів у Avalonia — той самий що й у WPF: ResourceDictionary, x:Key, StaticResource, DynamicResource, MergedDictionaries. Всі ці концепції переносяться без змін.

Але Avalonia додає один новий Markup Extension — ThemeResource.

Що таке ThemeResource

ThemeResource — це спеціалізований аналог DynamicResource, який розуміє Avalonia-теми (Light / Dark / HighContrast). Він шукає ресурс у активній темі застосунку, а не тільки у звичайних ResourceDictionary.

<!-- Ресурс реагує на перемикання теми Light/Dark -->
<TextBlock Foreground="{ThemeResource SystemControlForegroundBaseHighBrush}"/>

<!-- DynamicResource — шукає у ResourceDictionary ланцюжку -->
<TextBlock Foreground="{DynamicResource MyCustomBrush}"/>

<!-- StaticResource — одноразовий пошук при ініціалізації -->
<Button Background="{StaticResource PrimaryBrush}"/>

ThemeResource особливо важливий при використанні Avalonia Fluent Theme: всі системні кольори теми (фон вікна, колір тексту, колір акценту) задані через ThemeResource. Якщо ви хочете, щоб ваш кастомний контрол "підхоплював" активну тему автоматично — використовуйте ThemeResource для системних кольорів.

Ресурси: що залишається незмінним

<!-- Це 100% однаково у WPF і Avalonia -->
<Window.Resources>
    <SolidColorBrush x:Key="MyBrush" Color="#2563eb"/>
    <sys:String x:Key="MyString">Привіт</sys:String>
</Window.Resources>

<!-- StaticResource та DynamicResource — без змін -->
<Button Background="{StaticResource MyBrush}"/>
<TextBlock Foreground="{DynamicResource MyBrush}"/>

<!-- MergedDictionaries — без змін -->
<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="avares://MyApp/Resources/Colors.axaml"/>
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

Одна деталь: у Avalonia для embedded-ресурсів (файлів, вбудованих у збірку) шлях починається з avares:// протоколу замість звичайного відносного шляху:

<!-- WPF: відносний шлях -->
<ResourceDictionary Source="Resources/Colors.xaml"/>

<!-- Avalonia: avares:// протокол для embedded-ресурсів -->
<ResourceDictionary Source="avares://MyAvaloniaApp/Resources/Colors.axaml"/>

Де MyAvaloniaApp — назва збірки (Assembly Name з .csproj). Це трохи детальніше, але дозволяє точно адресувати ресурси з різних збірок.

Avalonia Previewer: живий перегляд без WPF Designer

У WPF є вбудований XAML Designer у Visual Studio — панель, що показує вікно поруч з кодом. Він часто "ламається", вимагає перезапуску і підтримує лише Windows.

Avalonia пішла іншим шляхом: Avalonia Previewer — окремий процес, що рендерить .axaml через власний движок Avalonia і показує результат у боковій панелі IDE.

Як запустити Previewer

Чому Previewer кращий за WPF Designer

Avalonia Previewer рендерить той самий Skia-рушій, що й реальний застосунок — тому те, що ви бачите у preview, точно відповідає результату при запуску.

Повна порівняльна таблиця: WPF XAML vs Avalonia XAML

Ось side-by-side порівняння 15 ключових конструкцій:

Практичні завдання