Windows UI Library 3 Preview 3 (November 2020)

Windows UI Library (WinUI) 3 is a native user experience (UX) framework for both Windows Desktop and UWP apps.

WinUI 3 Preview 3 brings both new and improved functionality, along with significant bug fixes.

See Preview 3 limitations and known issues.

Important

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.

We will continue shipping preview releases of WinUI 3 into 2021, followed by the first official release.

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

Install WinUI 3 Preview 3

WinUI 3 Preview 3 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 3, follow these steps.

Note

You can also clone and build the WinUI 3 Preview 3 version of the XAML Controls Gallery.

  1. Ensure that your development computer has Windows 10, version 1803 (build 17134), or newer installed.

  2. Install Visual Studio 2019, version 16.9 Preview

    You must include the following workloads when installing Visual Studio:

    • .NET Desktop Development (this also installs .NET 5)
    • Universal Windows Platform development

    To build C++ apps, you must also include the following workloads:

    • Desktop development with C++
    • The C++ (v142) Universal Windows Platform tools optional component for the Universal Windows Platform workload (see "Installation Details" under the "Universal Windows Platform development" section, on the right pane)
  3. Make sure your system has a NuGet package source enabled for nuget.org. For more information, see Common NuGet configurations.Windows Community Toolkit

  4. Download and install the WinUI 3 Preview 3 VSIX package. This adds both the WinUI 3 project templates and the NuGet package containing the WinUI 3 libraries to Visual Studio 2019.

    For instructions on how to add the VSIX package to Visual Studio, see Finding and Using Visual Studio Extensions.

WebView2

If you're using the WebView2 control in your app, please install the Dev Channel version of the Microsoft Edge Browser from Microsoft Edge Insider Channels. Make sure to uninstall any existing instances of Microsoft Edge Beta, Microsoft Edge Dev, and Microsoft Edge WebView2 Runtime.

Windows Community Toolkit

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

Create WinUI projects

After installing the WinUI 3 Preview 3 VSIX package, you're ready to create a new project using one of the WinUI project templates in Visual Studio. To access the WinUI project templates in the Create a new project dialog, filter the language to C++ or C#, the platform to Windows, and the project type to WinUI. Alternatively, you can search for WinUI and select one of the available C# or C++ templates.

WinUI project templates

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

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.

With this release, we've also added WinUI 3 API reference documentation for all WinRT APIs ported to WinUI 3.

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

Project templates for WinUI 3

You can use these WinUI project templates to create apps.

Template Language Description
Blank App, Packaged (WinUI in Desktop) C# and C++ Creates a desktop .NET 5 (C#) or native Win32 (C++) app with a WinUI-based user interface. The generated project includes a basic window that derives from the Microsoft.UI.Xaml.Window class in the WinUI library that you can use to start building your UI. For more information about this project type, see Get started with WinUI 3 for desktop apps.

The solution also includes a Windows Application Packaging Project that is configured to build the app into an MSIX package. This provides a modern deployment experience, the ability to integrate with Windows 10 features via package extensions, and much more.
Blank App (WinUI in UWP) C# and C++ Creates a UWP app that with a WinUI-based user interface. The generated project includes a basic page that derives from the Microsoft.UI.Xaml.Controls.Page class in the WinUI library that you can use to start building your UI. For more information about this project type, see Get started with WinUI 3 for UWP apps.

You can use these WinUI project templates to build components that can be loaded and used by a WinUI-based app.

Template Language Description
Class Library (WinUI in Desktop) C# only Creates a .NET 5 managed class library (DLL) in C# that can be used by other .NET 5 desktop apps with a WinUI-based user interface.
Class Library (WinUI in UWP) C# only Creates a managed class library (DLL) in C# that can be used by other UWP apps with a WinUI-based user interface.
Windows Runtime Component (WinUI) C++ Creates a Windows Runtime component written in C++/WinRT that can be consumed by any UWP or Desktop app with a WinUI-based user interface, regardless of the programming language in which the app is written.
Windows Runtime Component (UWP) C# Creates a Windows Runtime component written in C# that can be consumed by any UWP app with a WinUI-based user interface, regardless of the programming language in which the app is written.

Item templates for WinUI 3

The following item templates are available for use in a WinUI project. To access these WinUI item templates, right-click the project node in Solution Explorer, select Add -> New item, and click WinUI in the Add New Item dialog.

WinUI item templates

Template Language Description
Blank Page (WinUI) C# and C++ Adds a XAML file and code file that defines a new page derived from the Microsoft.UI.Xaml.Controls.Page class in the WinUI library.
Blank Window (WinUI in Desktop) C# and C++ Adds a XAML file and code file that defines a new window derived from the Microsoft.UI.Xaml.Window class in the WinUI library.
Custom Control (WinUI) C# and C++ Adds a code file for creating a templated control with a default style. The templated control is derived from the Microsoft.UI.Xaml.Controls.Control class in the WinUI library.

For a walkthrough that demonstrates how to use this item template, see Templated XAML controls for UWP and WinUI 3 apps with C++/WinRT and Templated XAML controls for UWP and WinUI 3 apps with C#. For more information about templated controls, see Custom XAML Controls.
Resource Dictionary (WinUI) C# and C++ Adds an empty, keyed collection of XAML resources. For more information, see ResourceDictionary and XAML resource references.
Resources File (WinUI) C# and C++ Adds a file for storing string and conditional resources for your app. You can use this item to help localize your app. For more info, see Localize strings in your UI and app package manifest.
User Control (WinUI) C# and C++ Adds a XAML file and code file for creating a user control that derives from the Microsoft.UI.Xaml.Controls.UserControl class in the WinUI library. Typically, a user control encapsulates related existing controls and provide its own logic.

For more information about user controls, see Custom XAML Controls.

Visual Studio Support

In order to take advantage of the latest tooling features added into WinUI 3 Preview 3 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. The table below shows the compatibility of future versions with WinUI 3 Preview 3:

VS Version WinUI 3 Preview 3
16.8 RTM No
16.9 Previews Yes
16.9 RTM No
16.10 Previews Yes

New features and capabilities in Preview 3

  • ARM64 Support
  • Drag and drop inside and outside of apps
  • RenderTargetBitmap (currently only XAML content - no SwapChainPanel content)
  • Improvements to our tooling/developer experience:
    • Live Visual Tree, Hot Reload, Live Property Explorer and similar tools
    • Intellisense now working for WinUI 3
  • MRT Core Support
    • This makes apps faster and lighter on startup and provides quicker resource lookup.
  • Custom cursor support
  • Off-thread input
  • Performance improvements since Preview 2
  • Multiple windows in Desktop apps - improved support since Preview 2

New features and capabilities introduced in past WinUI 3 Previews

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

  • 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
  • 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.

Provide feedback and suggestions

We welcome your feedback in the WinUI GitHub repo.

What's coming next?

Take a look at our detailed feature roadmap to see when specific features will be brought into WinUI 3.

Preview 3 limitations and known issues

The Preview 3 release is just that, a preview. The scenarios around Desktop apps are especially new. Please expect bugs, limitations, and other issues.

The following items are some of the known issues with WinUI 3 Preview 3. If you find an issue that isn't listed below, please let us know by contributing to an existing issue or filing a new issue through the WinUI GitHub repo.

Platform and OS support

WinUI 3 Preview 3 is compatible with PCs running the Windows 10 April 2018 Update (version 1803 - build 17134) and newer.

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.

  • If you’re using a WebView2 in your app but it is not rendering or loading, you may be running an incompatible version of the Edge browser. Download the Dev channel of Microsoft Edge and be sure to uninstall any existing instances of Microsoft Edge Beta, Microsoft Edge Dev, and Microsoft Edge WebView2 Runtime.

  • Marshal functions should not be used in .NET 5 WinUI apps as they do not interoperate correctly with C#/WinRT. For more details, see this page.

  • If you experience a crash setting a URI property, for example using a {Binding} in Xaml markup, you can work around it by using {x:Bind}, or by using a preview version of C#/WinRT. To do this, add the following lines to your .csproj file:

    <ItemGroup>
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" 
                          RuntimeFrameworkVersion="10.0.18362.11-preview" />
      <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" 
                          TargetingPackVersion="10.0.18362.11-preview" />
    </ItemGroup>
    
  • 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.

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

WinUI 3 Preview 3 XAML Controls Gallery app
Example of the WinUI 3 Preview 3 XAML Controls Gallery app

To download the sample, clone the winui3preview branch using the following command:

git clone --single-branch --branch winui3preview https://github.com/microsoft/Xaml-Controls-Gallery.git

After cloning, ensure that you switch to the winui3preview branch in your local Git environment:

git checkout winui3preview