Add Detailed Porting Guide

[robloo]

I've started to do a more detailed look at porting a UWP/WinUI app over to Avalonia and think a detailed guide would be useful (several apply to WPF as well). Below I'll collect the things I've found so far in the hopes of adding a dedicated page to the docs eventually.

XAML

• Switch to xmlns="https://github.com/avaloniaui
• Add x:CompileBindings="True" where possible (it is supported in most cases now)
• Replace all ThemeResource usages with DynamicResource
• Remove any <ResourceDictionary.ThemeDictionaries> Light/Dark/HighContrast dictionaries. Avalonia does not conceptually support this yet and will use a different pattern when this functionality is added. For now, resource dictionaries for dark/light should be manually loaded.
• Remove unsupported properties from XAML
  • Remove any UpdateSourceTrigger usage which was common in WPF/WinUI TextBoxes. See https://github.com/AvaloniaUI/Avalonia/issues/3754
  • Spacing is missing in both Grid and StackPanel
  • Remove any Style property usage. This usually requires switching to the Theme property with a new ControlTheme or use style classes.
  • Remove BorderBrush, Background and BorderThickness property usage from Grid. Place the Grid inside a Border which has these properties like what was done in WPF. UWP/WinUI did this to flatten the visual tree for performance but it never made a lot of sense as Grid was just layout and should have no visual style.
  • Remove ComboBox.SelectionChangedTrigger="Committed" which isn't supported in Avalonia
  • More tricky, ComboBox doesn't have DisplayMemberPath, SelectedValue and SelectedValuePath: https://github.com/AvaloniaUI/Avalonia/issues/4718. This requires some changes to view models to work-around and possibly switching types. More recently DisplayMemberBinding was added to replace DisplayMemberPath: https://github.com/AvaloniaUI/Avalonia/pull/8922
• Switch from Visibility to IsVisible. This is one of the more involved changes and requires not only renames and property setter updates, but also converter and view model changes.
• Switch Style to ControlTheme in the cases of default control template styles
• Switch Style to using selectors and classes when not changing control templates
  • Replace any control usage not in Avalonia. Note that effort was made in the 11.0 release to close the control gap with WinUI and Avalonia now includes several controls such as SplitButton, ToggleSplitButton, DropDownButton, ColorPicker etc. out of the box.
  • For those controls still not in Avalonia (ContentDialog, etc.) It is best to use FluentAvalonia to add back most of the missing controls when porting from UWP/WinUI
  • FontIcon -> Fluent Avalonia's FontIcon
  • ListView -> ListBox
  • etc...
• Switch to new DataTemplateSelector pattern https://github.com/AvaloniaUI/Avalonia.Samples/tree/main/src/Avalonia.Samples/DataTemplates/IDataTemplateSample
• Any behaviors will require switching to using the Avalonia.Xaml.Behaviors package https://github.com/wieslawsoltes/AvaloniaBehaviors. This is largely compatible and was designed to follow UWP from the start.
• Any AcrylicBrush usage must be removed. Avalonia currently supports an experimental acrylic material but it is usable only on Border.Material property so is conceptually different. Note that the entire window can still simulate acrylic/mica using different methodology TransparencyLevelHint="AcrylicBlur".
• Avalonia doesn't support x:Uid='key' resource localization. For localized apps, this creates another very involved change. The recommended approach is to create a localization/translation markup extension and consume .resx files by the extension. See: https://github.com/AvaloniaUI/Avalonia/discussions/8741#discussioncomment-4009674
• [Also Code] Avalonia controls do not have any header or header template properties. Usage of these properties common in UWP/WinUI must be removed. In Avalonia, create a new HeaderedContentControl as required for this or just separate out the headers into TextBlocks. Avalonia, like WPF, is a cleaner design as it avoids duplicate properties and bloat in many controls.
• ListBox does not support grouping like ListView does in WinUI. This means Linq IGrouping cannot be used nor CollectionViewSource or ListView.GroupStyle. To work-around this custom ListBoxItems must be created with different data templates.

Code-Behind

• All occurrences of .ActualHeight and .ActualWidth must be changed to .Bounds.Height and .Bounds.Width
• Change all event handler signatures to use new event args types. These are sporadic and its best to follow IDE error information.
• Convert property types
  • UIElement to object? or IControl? for content properties
  • FrameworkElement to Control
  • Brush Background/BorderBrush to IBrush?
• All ItemsControls such as ListBox and ComboBox require a collection to be created and then set to the Items property. The Items property cannot be used directly like in WPF/UWP/WinUI which separates it from ItemsSource. When not using pure MVVM with these collections in view models this requires changing the code to build collections directly.
• Resource lookup has changed. Code such as (Brush)Application.Current.Resources["key"]; generally doesn't work as it won't search the full resources (https://github.com/AvaloniaUI/Avalonia/issues/6021). An extension method as described in the issue is generally the easiest fix but this still requires changing all usages in code.

Other

• Drag/Drop is heavily reworked coming from UWP/WinUI. However, Avalonia uses a pattern similar to WPF (but you must specially add handlers to the routed events as these are not exposed as CLR events).
• Tooltips also behave much more like WPF which requires changes coming over from UWP/WinUI.
• The most changed code is probably Visibility -> IsVisible. This shows up everywhere.
• Avalonia has a lot of non-mutable types such as brushes and colors that are mutable in WPF/UWP/WinUI. That requires changing code in some places.
• When porting over existing code Rider is almost mandatory. Visual Studio and the Avalonia plug-ins do not provide detailed enough error information to locate XAML issues in a reasonable way. Avalonia's name generator also is all-or-nothing so finding issues is very difficult in Visual Studio. However, Rider shows you right away any problems in your XAML code.
• Avalonia requires parameterless constructors in custom controls / views. That is not true in WinUI which can work with optional parameters (where all are optional).

Note: I might complete a base version of this for my own public docs repository. We'll see. Just collecting things here for now.

[robloo]

@maxkatz6 @grokys @kekekeks @danwalmsley Just FYI as it might be good to read through this before 11.0. Still a work-in-process but this list is made from looking at WinUI code in prep for a port.

The showstoppers for app migration WinUI -> Avalonia and most pain points (like CornerRadius, etc.) have been fixed. Only smaller things and differences are above.