WinUI

Prepare to develop with WinUI 3

Page update date :
Page creation date :

Operating environment

Windows
  • Windows 11
Visual Studio
  • Visual Studio 2022 Version 17.9.3
.NET
  • .NET 6
  • (.NET 8)
WinUI
  • WinUI 3
Windows App SDK
  • 1.4.230913002

Prerequisites

In some cases, lower versions may also work.

Windows
  • Windows 10
  • Windows 11
Visual Studio
  • Visual Studio 2022 version 17.9.3 or later
.NET
  • .NET 6
  • (.NET 8)
Windows App SDK
  • 1.4.230913002 or later

Install Visual Studio and set up WinUI

WinUI 3 development projects can be added with the Visual Studio installation. This section provides a simplified description of the Visual Studio installation process. For detailed instructions, please refer to the following Tips.

Launch the Visual Studio 2022 installer from the internet or media. It supports Community, Professional, or higher editions.

In the workload selection, select . NET Desktop Development.

「. NET Desktop Development and check Windows App SDK C# Templates from the Installation Details on the right.

Now just start the installation. There are other screens, but I won't explain them until they create a project.

Once the installation is complete, create a new project.

There is a in the search item in the winui upper right, so when you select it, the WinUI 3 project template will be displayed, so select any template and create a project.

You can now develop applications using WinUI 3.

If you see "Targeting a version of .NET that is not installed"

As of Visual Studio 2022 version 17.9.1 , .NET for WinUI 3 targets .NET 6. If you don't select any additional runtimes in Visual Studio 2022, only the .NET 8 runtime will be installed, and you may see a warning like the one below.

If you're concerned, you can install the .NET 6 runtime or just dismiss the warning. You don't need to install the .NET 6 runtime to debug.

If you want to add a WinUI 3 development environment later

If you install Visual Studio first, you can add a WinUI 3 development environment later.

Start Visual Studio and select Tools > Get Tools and Features from the menu.

The same screen as when you installed Visual Studio will be displayed, so you can use the . Make sure ".NET Desktop Development" is checked, and check "Windows App SDK C# Template" from "Installation Details" on the right.

Enable developer mode

WinUI applications run in a security-enhanced environment unlike other desktop applications. Therefore, it cannot be run as it is. When you try to run it, you will see a dialog like the one below and you will be prompted to enable "Developer Mode". If you click the link, the setting screen will be displayed, so please enable "Developer Mode".

Even if you are not using Visual Studio, you can also enable or disable "Developer Mode" from the settings screen. Select "Settings" from the Start menu.

From the System menu, select For Developers.

There is a toggle for "For developers", so set it to "On". A note will be displayed, so select "Yes" to enable it.

If you want to change to .NET 8

If you create a project with this template, it will default to .NET 6. Even if I change the target framework to .NET 8 from the project properties, the build still shows errors and warnings. However, around 03/13/2024, the Windows App SDK will be updated to officially support .NET 8.

However, the template is still in .NET 6, so you'll need to work on .NET 8 once you've created the project. There may be a possibility that it will be supported in future version upgrades.

First, create a project, and then use NuGet to update the Windows App SDK-related versions.

Unless otherwise, everything is up to date. Microsoft.WindowsAppSDK must be at least 1.5.XXXX.

Change the target framework to .NET 8 from the project properties.

Even if you build in this state, an error will be displayed because the project settings are outdated.

Open the project file as code.

RuntimeIdentifiersSince there is a parameter, remove the character of 10 as follows Win10 .

Before Modification

<RuntimeIdentifiers>win10-x86;win10-x64;win10-arm64</RuntimeIdentifiers>

↓

After the fix

<RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>

It also rewrites the program's publishing settings. Open each .pubxml file in the Properties > PublishProfiles folder.

Similarly RuntimeIdentifier , remove the character of 10 in the Win10 parameter of .

After that, rebuild and verify that there are no errors or warnings. .pubxml (There will be a warning in the file, but you don't have to worry about it because it's a different syntax from this issue.) )

However, for some reason, the WinUI class library continues to warn even if you do the same thing as above. For the time being, you can run it, so let's wait until this is fixed.