Get started with WinUI 3 for desktop apps

WinUI 3 - Project Reunion 0.5 includes project templates that enable you to create managed C#/.NET 5 and native C++/Win32 desktop apps with an entirely WinUI-based user interface. When you create apps using these project templates, the entire user interface of your application is implemented using windows, controls, and other UI types provided by WinUI 3. For a complete list of the project templates, see Project templates for WinUI 3.

WinUI 3 ships as a part of the Project Reunion package. For more on Project Reunion, see Build desktop Windows apps with Project Reunion 0.5 (March 2021).

Prerequisites

To use the WinUI 3 for desktop project templates described in this article, configure your development computer and install the Project Reunion 0.5 Visual Studio extension. For details, see Set up your development environment.

Create a WinUI 3 desktop app for C# and .NET 5

  1. In Visual Studio 2019, select File -> New -> Project.

  2. In the project drop-down filters, select C#, Windows, and WinUI, respectively.

  3. Select the Blank App, Packaged (WinUI 3 in Desktop) project type and click Next.

    Screenshot of Create a new project wizard with the Blank App Packaged (Win UI in Desktop) option highlighted.

  4. Enter a project name, choose any other options as desired, and click Create.

  5. In the following dialog box, set the Target version to Windows 10, version 2004 (build 19041) and Minimum version to Windows 10, version 1809 (build 17763) and then click OK.

    Target and Min Version

  6. At this point, Visual Studio generates two projects:

    • Project name (Desktop): This project contains your app's code. The App.xaml file and App.xaml.cs code-behind file define an Application class that represents your app instance. The MainWindow.xaml file and MainWindow.xaml.cs code-behind file define a MainWindow class that represents the main window displayed by your app. These classes derive from types in the Microsoft.UI.Xaml namespace provided by WinUI.

      Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Main Windows X A M L dot C S file.

    • Project name (Package): This is 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. This project contains the package manifest for your app, and it is the startup project for your solution by default.

      Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Package app x manifest file.

  7. To add a new item to your app project, right-click the Project name (Desktop) project node in Solution Explorer and select Add -> New Item. In the Add New Item dialog box, select the WinUI tab, choose the item you want to add, and then click Add. For more details about the available items, see Item templates for WinUI 3.

    Screenshot of the Add New Item dialog box with the Installed > Visual C sharp Items > Win U I selected and the Blank Page option highlighted.

  8. Build and run your solution to confirm that the app runs without errors.

Create a WinUI 3 desktop app for C++/Win32

  1. In Visual Studio 2019, select File -> New -> Project.

  2. In the project drop-down filters, select C++, Windows, and WinUI.

  3. Select the Blank App, Packaged (WinUI 3 in Desktop) project type and click Next.

    Another screenshot of Create a new project wizard with the Blank App Packaged (Win U I in Desktop) option highlighted.

  4. Enter a project name, choose any other options as desired, and click Create.

  5. In the following dialog box, set the Target version to Windows 10, version 20004 (build 19041) and Minimum version to Windows 10, version 1809 (build 17763) and then click OK.

    Target and Min Version

  6. At this point, Visual Studio generates two projects:

    • Project name (Desktop): This project contains your app's code. The App.xaml and various App code files define an Application class that represents your app instance, and the MainWindow.xaml and various MainWindow code files define a MainWindow class that represents the main window displayed by your app. These classes derive from types in the Microsoft.UI.Xaml namespace provided by WinUI.

      Screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Main Windows X A M L file.

    • Project name (Package): This is 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. This project contains the package manifest for your app, and it is the startup project for your solution by default.

      Another screenshot of Visual Studio showing the Solution Explorer pane and the contents of the Package app x manifest file.

  7. To add a new item to your app project, right-click the Project name (Desktop) project node in Solution Explorer and select Add -> New Item. In the Add New Item dialog box, select the WinUI tab, choose the item you want to add, and then click Add. For more details about the available items, see Item templates for WinUI 3.

    New Item

  8. Build and run your solution to confirm that the app runs without errors.

    Note

    Only the packaged project will launch, so make sure that one is set as the Startup Project.

Localizing your WinUI desktop app

To support multiple languages in a WinUI desktop app, and ensure proper localization of your packaged project, add the appropriate resources to the project (see App resources and the Resource Management System) and declare each supported language in the package.appxmanifest file of your project. When you build the project, the specified languages are added to the generated app manifest (AppxManifest.xml) and the corresponding resources are used.

  1. Open the .wapproj's package.appxmanifest in a text editor and locate the following section:

    <Resources>
        <Resource Language="x-generate"/>
    </Resources>
    
  2. Replace the <Resource Language="x-generate"> with <Resource /> elements for each of your supported languages. For example, the following markup specifies that "en-US" and "es-ES" localized resources are available:

    <Resources>
        <Resource Language="en-US"/>
        <Resource Language="es-ES"/>
    </Resources>
    

Known issues and limitations

See the Limitations and known issues section of Windows UI Library 3 - Project Reunion 0.5.

Windows UI Library 3 - Project Reunion 0.5