Create your first WinUI 3 project

In this topic we'll see how to use Visual Studio to create a new project for a C# .NET or C++ app that has a Windows UI Library (WinUI) 3 user interface (UI). We'll also take a look at some of the code in the resulting project, what it does, and how it works.

Links to full installation details are in the steps below. We recommend the Windows App SDK version 1.0 Stable, but you can choose any version from any of the Windows App SDK release channels. From that topic, you can follow the links to the release notes for each channel. Be sure to check any limitations and known issues in the release notes, since those might affect the results of following along with these steps.

Important

If you're working on a UWP app, refer to Migrate from UWP to the Windows App SDK.

Key concepts

  • MSIX-packaging. This is the process of packaging an app using MSIX technology (see What is MSIX?). MSIX is a package format that gives your users an easy way to install, uninstall, and update your app using a modern UI. MSIX-packaging also gives your app a package identity, which is needed for certain Windows features (for example, custom context menu extensions).
  • Sparse-packaging. This is a way to opt out of MSIX-packaging, so that your app is unrestricted in terms of the kind of app it is, the APIs it can call, and its access to the Registry and file system. And with sparse-packaging, your app still has package identity, so you can use the Windows features mentioned above. An app that's sparse-packaged is typically installed and updated using .exe or .msi files; and uses a custom installer, ClickOnce, or xcopy deployment.
  • No packaging. Another way to opt out of MSIX-packaging, for the reasons given above. But an app that isn't packaged doesn't have package identity. An app that's not packaged is typically installed and updated using .exe or .msi files; and uses a custom installer, ClickOnce, or xcopy deployment.

MSIX-packaged: Create a new project for an MSIX-packaged C# or C++ WinUI 3 desktop app

  1. To set up your development computer, see Install tools for the Windows App SDK.

  2. In Visual Studio, select File > New > Project.

  3. In the New Project dialog's drop-down filters, select C#/C++, Windows, and WinUI, respectively.

  4. Select the Blank App, Packaged (WinUI 3 in Desktop) project template, and click Next. That template creates a desktop app with a WinUI 3-based user interface. The generated project is configured with the package manifest and other support needed to build the app into an MSIX package (see What is MSIX?). For more information about this project template, see Package your app using single-project MSIX.

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

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

  6. The project that Visual Studio generates contains your app's code. The App.xaml file and code-behind file(s) define an Application-derived class that represents your running app. The MainWindow.xaml file and code-behind file(s) define a MainWindow class that represents the main window displayed by your app. Those classes derive from types in the Microsoft.UI.Xaml namespace provided by WinUI 3.

    The project also includes the package manifest for building the app into an MSIX package.

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

  7. To add a new item to your app, right-click the 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 WinUI 3 templates in Visual Studio.

    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 on your development computer to confirm that the app runs without errors.

Non-MSIX-packaged: Create a new project for a non-MSIX-packaged C# or C++ WinUI 3 desktop app

  1. To set up your development computer, see Install tools for the Windows App SDK.

  2. Download the latest installer for the Windows App SDK from Downloads for the Windows App SDK. This will install the runtime package dependencies required to run and deploy a non-MSIX-packaged app on the target device (see Windows App SDK deployment guide for unpackaged apps).

  3. C++. Install the Microsoft Visual C++ Redistributable (VCRedist) appropriate for the architecture of the target device.

    • The latest version of the VCRedist is compatible with the latest Visual Studio generally-available (GA) release (that is, not preview), as well as all versions of Visual Studio that can be used to build Windows App SDK binaries.
    • Insider builds of Visual Studio might have installed a later version of the VCRedist, and running the public version will then fail with this error (which you can ignore): Error 0x80070666: Cannot install a product when a newer version is installed.

    Note

    If you don't have the VCRedist installed on the target device, then dynamic links to c:\windows\system32\vcruntime140.dll fail. That failure can manifest to end users in various ways.

  4. In Visual Studio, select File > New > Project.

  5. In the New Project dialog's drop-down filters, select C#/C++, Windows, and WinUI, respectively.

  6. You need to start with an MSIX-packaged project in order to use XAML diagnostics. So select the Blank App, Packaged (WinUI 3 in Desktop) project template, and click Next. .

  7. Add the following property to your project file—either your .csproj (C#) or .vcxproj (C++) file:

    <WindowsPackageType>None</WindowsPackageType>
    

    Visual Studio 2019 - C# Project file with WindowsPackageType set to None highlighted

  8. C++. In your C++ project (.vcxproj) file, set the AppxPackage property to false:

     <AppxPackage>false</AppxPackage>
    
  9. C#. To start a C# app from Visual Studio (either Debugging or Without Debugging), select the Unpackaged launch profile from the Start drop-down. If the Package profile is selected, then you'll see a deployment error in Visual Studio. This step isn't necessary if you start the application (.exe) from the command line or from Windows File Explorer.

    Visual Studio - Start drop-down with C# application unpackaged launch profile highlighted

  10. Build and run.

The bootstrapper API

Setting the <WindowsPackageType>None</WindowsPackageType> project property causes the auto-initializer to locate and load a version of the Windows App SDK version that's most appropriate for your app.

If you have advanced needs (such as custom error handling, or to load a specific version of the Windows App SDK), then you can instead call the bootstrapper API explicitly. For more info, see Use the Windows App SDK runtime for non-MSIX-packaged apps, and Tutorial—Use the bootstrapper API in a non-MSIX-packaged app that uses the Windows App SDK.

For more info about the bootstrapper, see Deployment architecture and overview for framework-dependent apps.

A look at the code in the project template

In this walkthough, we used the Blank App, Packaged (WinUI 3 in Desktop) project template, which creates a desktop app with a WinUI 3-based user interface. Let's take a look at some of the code that comes with that template, and what it does. For more info on available WinUI 3 project and item templates, see WinUI 3 templates in Visual Studio.

The app's entry point

When the Windows operating system (OS) runs an app, the OS begins execution in the app's entry point. That entry point takes the form of a Main (or wWinMain for C++/WinRT) function. Ordinarily, a new project configures that function to be auto-generated by the Visual Studio build process. And it's hidden by default, so you don't need to be concerned with it. But if you are curious for more info, then see Single-instancing in Main or wWinMain.

The App class

The app as a whole is represented by a class that's typically called simply App. That class is defined in App.xaml and in its code-behind file(s) (App.xaml.cs, or App.xaml.h and .cpp). App is derived from the WinUI 3 Microsoft.UI.Xaml.Application class.

The generated code in the entry point creates an instance of App, and sets it running.

In the constructor of App, you'll see the InitializeComponent method being called. That method essentially parses the contents of App.xaml, which is XAML markup. And that's important because App.xaml contains merged resources that need to be resolved and loaded into a dictionary for the running app to use.

Another interesting method of App is OnLaunched. In there we create and activate a new instance of the MainWindow class (which we'll look at next).

The MainWindow class

The main window displayed by the app is of course represented by the MainWindow class. That class is defined in MainWindow.xaml and in its code-behind file(s) (MainWindow.xaml.cs, or MainWindow.xaml.h and .cpp). MainWindow is derived from the WinUI 3 Microsoft.UI.Xaml.Window class.

The constructor of MainWindow calls its own InitializeComponent method. Again, its job is to turn the XAML markup inside MainWindow.xaml into a graph of user interface (UI) objects.

In MainWindow.xaml you'll see the basic layout of MainWindow. At the layout root is a dynamic panel called a Microsoft.UI.Xaml.Controls.StackPanel. For more info about layout panels, see Layout panels.

Inside that StackPanel is a Microsoft.UI.Xaml.Controls.Button. And that Button uses the markup Click="myButton_Click" to declaratively hook up an event handler method for the Click event.

That method is named myButton_Click, and you can find the implementation of that method in MainWindow.xaml.cs, or in MainWindow.xaml.cpp. In it, the content of the button is changed from the default "Click Me" to "Clicked".

C++. If you created a C++ project, then you'll also see a MainWindow.idl file. For more info, see the C++/WinRT documentation. XAML controls; bind to a C++/WinRT property is a good place to start learning about the purpose and usage of .idl files.

Next steps

To continue your development journey with the Windows App SDK, see Develop Windows desktop apps.