WinUI 3 is the next generation of Microsoft's Windows UI library. Scheduled for release in 2021, it succeeds the UWP XAML framework as Microsoft's actively-developed native UI platform.
Since WinUI 3 and UWP XAML are very similar in their API, Uno Platform offers compatibility with both. This article goes further into the differences and how they apply to Uno.
Tip
If you just want to add WinUI 2 controls to your Uno Platform project, check the guide here.
WinUI 3 differs in minor ways from UWP XAML in terms of API, and in more substantial ways in its technical comportment.
The chief difference between WinUI 3 and UWP XAML is the change of namespace. UWP XAML namespaces begin with 'Windows' - Windows.UI.Xaml, Windows.UI.Composition, and so on. WinUI 3 namespaces begin with 'Microsoft' - Microsoft.UI.Xaml, Microsoft.UI.Composition and so on. Aside from that change, the API surface is nearly identical. Some of the remaining differences are listed in our guide to upgrading to WinUI 3.
Below the surface, the differences are more substantial. The UWP XAML stack is part of the Windows OS. The WinUI 3 stack is decoupled from the OS. This means application developers can use the newest features without worrying that they might not be supported on the end user's system.
WinUI 3 is also decoupled from the application model. The UWP XAML stack is only compatible with the 'UWP model' in which the application runs in a secure sandbox. WinUI 3 is compatible both with the 'UWP model' and with the traditional 'Win32' or 'desktop' application model in which the application has largely-unrestricted access to the rest of the OS.
Uno Platform is only affected by the API change - the technical changes don't apply on non-Windows platforms.
When you create a new Uno Platform application, you can choose to create a WinUI 3-compatible application (using the WinUI 3 API, and building with WinUI 3 on the Windows head project) instead of a UWP XAML-compatible application using the dotnet new templates.
This is possible because we ship two sets of the Uno.UI binaries, one set that is compatible with UWP XAML, and a second set that is compatible with WinUI 3. The WinUI 3-compatible binaries are generated by an automated transformation step, so the runtime behavior is nearly identical for a given version number, and neither set lags behind the other in terms of releases.
The questions below should help guide you to the best choice when creating a new Uno Platform application. Note that WinUI 3 is nearing release and some of the guidance here may change or become outdated rather rapidly.
Because WinUI 3 is still in preview, compatible versions of 3rd-party libraries are not yet available in many cases. If you depend (or expect to depend) on these libraries, the UWP XAML API may be the way to go for now.
WinUI 3 applications using the Win32 application model can use .NET 5 and C# 9 right now, whereas UWP currently doesn't support .NET 5 and there's no firm date that it will be added.
Note that not all non-Windows platforms support .NET 5, see a full support matrix here.
If Windows is one of your target platforms, then the technical differences discussed above apply. Probably the key question is, can your application run in the sandboxed 'UWP model', or is it better served by the unrestricted 'Win32 model'?
Check the WinUI 3 roadmap for a list of features that won't be available in the initial supported release, like InkCanvas.