WinUI is a user interface layer that contains modern controls and styles for building Windows apps, both Desktop and UWP. As the native UI layer in Windows, it embodies Fluent Design, giving each Windows app the polished feel that users expect.

WinUI 3 is the latest version of the WinUI framework, shipping later this year. It dramatically expands WinUI into a full UX framework, making WinUI available for all types of Windows apps – from Win32 to UWP – for use as the UI layer. When ready, every Windows app will be able to take advantage of its modern controls that work regardless of the Windows version that they are running on.

Released today, WinUI 3 Preview 4 is a stability preview release that includes critical bug fixes and other general improvements for the framework.

Capabilities introduced in Preview 4

  • Parity with WinUI 2.5 (includes InfoBar control, new features in ProgressRing and NavigationView, and bug fixes)
  • Custom titlebar capabilities: new Window.ExtendsContentIntoTitleBar and Window.SetTitleBar APIs that allow developers to create custom title bars in Desktop apps.
  • VirtualSurfaceImageSource support

New features and capabilities introduced in past WinUI 3 Previews

The following features and capabilities were introduced in WinUI 3 Preview 1-3 and continue to be supported in WinUI 3 Preview 4.

  • Ability to create Desktop apps with WinUI, including .NET 5 for Win32 apps
  • RadialGradientBrush
  • TabView updates
  • Dark theme updates
  • Improvements and updates to WebView2
    • Support for High DPI
    • Support for window resizing and moving
    • Updated to target more recent version of Edge
    • No longer necessary to reference a WebView2-specific Nuget package
  • SwapChainPanel
  • MRT Core Support
    • This makes apps faster and lighter on startup and provides quicker resource lookup.
  • ARM64 Support
  • Drag and drop inside and outside of apps
  • RenderTargetBitmap (currently only XAML content – no SwapChainPanel content)
  • Custom cursor support
  • Off-thread input
  • Improvements to our tooling/developer experience:
    • Live Visual Tree, Hot Reload, Live Property Explorer and similar tools
    • Intellisense for WinUI 3
  • Improvements required for open source migration

For more information on both the benefits of WinUI 3 and the WinUI roadmap, see the Windows UI Library Roadmap on GitHub.

List of bugs fixed in Preview 4

Below is a list of user-facing bugs that the team has fixed since Preview 3. There has also been a lot of work going on surrounding stabilization and improving our testing.

  • This release has taken on a new version of CS/WinRT and the Windows SDK, which fixed the following bugs:
    • Crash when binding to a URI property using {Binding}
    • C#/WinRT Marshal functions not interoperating correctly with .NET 5
  • WinUI 3 crash when running on Windows Insider Builds
    • Thanks to multiple community contributors for reporting this bug on GitHub!
  • WebView2 doesn’t apply host app’s Language/locale to CoreWebView2Environment
  • Windows Community Toolkit DataGrid control crashes app on start/when scrollbars appear
    • Thanks to multiple community contributors for reporting this bug on GitHub!
  • Page rendering gets into a bad state when display mode changes
  • Crash when using Language ComboBox in CalendarView
  • WinUI 3 Desktop: Can’t tab out of WebView2
  • WinUI 3 Desktop: TreeView with derived TreeViewNodes crashes
  • WinUI 3 Desktop: Unable to Enter Text into TextBox inside ContentDialog
  • WinUI 3 Desktop: ALT and F6 don’t work
  • Old removed SwapChainPanel renders on top of new SwapChain
  • WinUI 3 Desktop: Cannot scroll with trackpad
  • Crash when using NavigationView control with multiple windows on the same thread
  • Accessibility Issue: Show focus rect on WinUI desktop app launch
  • Access violation while scrolling in DataGrid
  • WinUI 3 Desktop: Tab cycling does not work
  • Drag and Drop on GridView fails in desktop application with WinUI Xaml Islands
  • Accessibility issue: Unable to scroll with PageUp/PageDown keys on WinUI 3 Desktop
  • WebView2 has wrong viewport size
  • WebView2 crash on click after opening MenuFlyout
  • WinUI 3 Desktop: Attempting to bring down DropDownButton or SplitButton’s flyout causes app crash
  • WebView2: Double right click on mouse causes a crash
  • Clicking on a ToggleSplitButton causes the application to crash
  • WinUI 3 Desktop: Empty DesktopWindowXamlSource window visible on task bar
  • WinUI 3 Desktop: DataGrid not displaying
  • WinUI 3 Desktop: Unable to drop files onto Grid
  • WinUI 3 Desktop: ItemsRepeater crash in WinUI 3 Preview 2
  • AccessViolationException thrown when updating bindings
  • WinUI 3 Desktop: app crashes on scroll NavigationView
  • ItemsControl does not get updated while dynamically adding or removing items in its ItemsSource collection.
  • Compile error C2760 in App.xaml.g.h if C++ Conformance Mode enabled

Limitations and known issues

The Preview 4 release is simply a preview with bugs, limitations, and other issues with the scenarios around Desktop apps are especially new.

The following items are some of the known issues with WinUI 3 Preview 4.

Developer tools

  • Only C# and C++/WinRT apps are supported
  • Desktop apps support .NET 5 and C# 9, and must be packaged in an MSIX app
  • UWP apps support .NET Native and C# 7.3
  • Developer tools and Intellisense may not work properly in Visual Studio version 16.8.
  • No XAML Designer support
  • New C++/CX apps are not supported, however, your existing apps will continue to function (please move to C++/WinRT as soon as possible)
  • Support for multiple windows in Desktop apps is in progress, but not yet complete and stable.
    • Please file a bug on our repo if you find new issues or regressions with multi-window behavior.
  • Unpackaged desktop deployment is not supported
  • When running a Desktop app using F5, make sure that you are running the packaging project. Hitting F5 on the app project will run an unpackaged app, which WinUI 3 does not yet support.

Missing Platform Features

  • Xbox support
  • HoloLens support
  • Windowed popups
    • More specifically, the ShouldConstrainToRootBounds property always acts as if it’s set to true, regardless of the property value.
  • Inking support
  • Acrylic
  • MediaElement and MediaPlayerElement
  • MapControl
  • RenderTargetBitmap for SwapChainPanel and non-XAML content
  • SwapChainPanel does not support transparency
  • Global Reveal uses fallback behavior, a solid brush
  • XAML Islands is not supported in this release
  • 3rd party ecosystem libraries will not fully function
  • IMEs do not work

Known issues

  • Alt+F4 does not close Desktop app windows.
  • Due to changes with CoreWindow, the following WinRT APIs may no longer work with Desktop apps as expected:

    For more information on using WinRT APIs in your WinUI 3 Desktop app, see Windows Runtime APIs available to desktop apps.

  • Windows.UI.ViewManagement.UISettings.ColorValuesChanged Event is no longer supported in Desktop apps. This may cause issues if you are using it to detect changes in Windows themes.
  • This release includes some experimental APIs. These have not been thoroughly tested by the team and may have unknown issues. Please file a bug on our repo if you encounter any issues.
  • Previously, to get a CompositionCapabilities instance you would call CompositionCapabilites.GetForCurrentView(). However, the capabilities returned from this call were not dependent on the view. To address and reflect this, we’ve deleted the GetForCurrentView() static in this release, so now you can create a CompositionCapabilties object directly.
  • For C# UWP apps:The WinUI 3 framework is a set of WinRT components which can be used from C++ (using C++/WinRT) or C#. When using C#, there are two versions of .NET, depending on the app model: when using WinUI 3 in a UWP app you’re using .NET Native; when using in a Desktop app you’re using .NET 5 (and C#/WinRT).When using C# for a WinUI 3 app in UWP, there are a few API namespace differences compared to C# in a WinUI 3 Desktop app or a C# WinUI 2 app: some types are in a Microsoft namespace rather than a System namespace. For example, rather than the INotifyPropertyChanged interface being in the System.ComponentModel namespace, it’s in the Microsoft.UI.Xaml.Data namespace.This applies to:
    • INotifyPropertyChanged (and related types)
    • INotifyCollectionChanged
    • ICommand

    The System namespace versions still exist, but cannot be used with WinUI 3. This means that ObservableCollection doesn’t work as-is in WinUI 3 C# UWP apps. For a workaround, see the CollectionsInterop sample in the XAML Controls Gallery sample.

What’s coming next?

Developers can take a look at Microsoft’s detailed feature roadmap to see when specific features will be brought into WinUI 3.

Install WinUI 3 Preview 4

WinUI 3 Preview 4 includes Visual Studio project templates to help get started building apps with a WinUI-based user interface, and a NuGet package that contains the WinUI libraries. To install WinUI 3 Preview 4, follow these steps.

Windows Community Toolkit

If you’re using the Windows Community Toolkit, download the latest version.

Aside from the limitations and known issues, building an app using the WinUI projects is similar to building a UWP app with XAML and WinUI 2.x. Therefore, most of the guidance documentation for UWP apps and the Windows.UI WinRT namespaces in the Windows SDK is applicable.

For more information about getting started with the WinUI project templates, see the following articles:

An API reference documentation for this release is coming soon but in the meantime, developers can look at the WinUI 3 API reference documentation for Preview 3.

If you created a project using WinUI 3 Preview 3, you can upgrade your project to use Preview 4. See the WinUI GitHub repository for detailed instructions.

In order to take advantage of the latest tooling features added into WinUI 3 Preview 4 like Hot Reload, Live Visual Tree, and Live Property Explorer, you must use the latest preview version of Visual Studio with the latest WinUI 3 preview and be sure to enable WinUI tooling in Visual Studio Preview Features, as described in the instructions here.

See the WinUI 3 Preview 4 branch of the XAML Controls Gallery for a sample app that includes all WinUI 3 Preview 4 controls and features.


Example of the WinUI 3 Preview 4 XAML Controls Gallery app

This WinUI 3 preview release is intended for early evaluation and to gather feedback from the developer community. It should NOT be used for production apps. Microsoft will continue shipping preview releases of WinUI 3 into 2021, followed by the first official, supported release in March 2021.

Please use the WinUI GitHub repo to provide feedback and log suggestions and issues.

Comments