WinUI for WPF developers

Notes I'm making while learning WinUI. They should be useful for WPF developers, who are starting their first WinUI project.

Work in progress!

• WinUI for WPF developers
  • 1.1. Some useful links on start
  • 1.2. Common errors
  • 1.3. x:Bind
    • 1.3.1. Main differences between Bind and x:Bind
    • 1.3.2. x:Bind in depth
    • 1.3.4. Example application
  • 1.4. ResourceDictionary
  • 1.5. Visibility and x:Load
  • 1.6. Styles

1.1. Some useful links on the start

• Windows App SDK download

• Windows Template Studio - a sophisticated wizard for creating new WinUI projects

• WinUI 3 Gallery - a demo app, that shows all WinUI 3 controls with Xaml examples and links to documentation. Also some Microsoft docs can open an example in this application, if you have it installed

• WinUI 2 Gallery - also useful, because some Microsoft docs, for older controls, link to WinUI 2 Gallery app

• Windows Community Toolkit sample app - a demo app for Windows Community Toolkit

• Windows Composition Samples - a collection of samples demonstrating how to build WinUI applications with advanced effects and animations, according to Fluent Design on github

• ResourceDictionary with Code-behind Visual Studio Item Template - see ResourceDictionary section

1.2. Common errors

• In case of this compilations error:_Microsoft.ui.xaml.dll is unable to load_ compilation - edit the project file, and add: <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>

• XamlCompiler error WMC0615: Type 'TemplateBinding' used after '{' must be a Markup Extension. Error code 0x80004005. - this is a parser error - template binding can only be used in ControlTemplates

1.3. x:Bind

1.3.1. Main differences between Bind and x:Bind

• x:Mode is by default OneTime! (An exception: x:DefaultBindMode)

• Child controls don't inherit DataContext property, you need to set DataContext explicitly in Xaml if you want to use it.

• x:Binding default source is not the DataContext but the code-behind

• Binding is not supported in styles. There is a workaround, but it's not a generic solution.

• Binding in ResourceDictionary - see: ResourceDictionary section

• RelativeSource Mode="FindAncestor" is not supported, a workaround is on this blog post

• Check UWP vs WPF document. It seems still relevant for WinUI.

1.3.2. x:Bind in depth

• Dictionary item binding is possible. Example: <TextBlock Text="{x:Bind Players['John Smith']}" />. This works for types that implement IDictionary<string, T> only.

• Attached Properies. Example: <TextBlock Text="{x:Bind Button22.(Grid.Row)}"/>

• Pathless casting - {x:Bind MethodName((namespace:TypeOfThis))} is a valid way to perform what is conceptually equivalent to {x:Bind MethodName(this)}.

• Casting. In short: C# style casting is needed (because x:Bind is strongly typed) and possible, in C# manner. Example, see: casting tab

• Event binding - commands are not needed to handle events in view model! Example

• Function binding - functions can have multiple arguments, so they may not only replace converters but also multibinding. Supported function argument types.

• Extension methods are supported in function binding too! Example.

• BindBack - Specifies a function to use for the reverse direction of a two-way binding. Example - BindBack tab

• Template binding - the TemplateBinding markup extension has many limitations. It doesn't allow for converters or binding mode, and it doesn't provide any error feedback in case of a mis-typed target property name. This means that the view will simply fail to load. Use Binding RelativeSource={RelativeSource Mode=TemplatedParent}, Path=<property> instead. Example - Template binding tab.

1.3.4. Example application

A simple app presenting a few usages of x:Bind which are not obvious for WPF devs is in src folder of this repo

1.4. ResourceDictionary

To have x:Bind working in a ResourceDictionary it is required to have code-behind. Here is a useful ResourceDictionary with Code-behind Visual Studio extension.

1.5. Visibility and x:Load

In contrast to WPF, setting the Visibility property of a UI element to Collapsed does not unload it; it simply prevents it from being displayed, making it equivalent to Visibility.Hidden in WPF. This can result in performance problems, especially when using Collapsed in item templates for lists, etc. To effectively unload a portion of the visual tree, use the x:Load attribute. Note that x:DeferLoadStrategy, which does a similar job, is now obsolete and should not be used.

1.6. Styles

Binding is style setters is not supported (except for TemplateBinding), as well as BasedOn with default styles.

Binding in style workaround - it requires to write some code for every dependency property you'd like to use, so it's not a generic solution.