WinUI 3 and the Windows App SDK at a glance

After K2, the Kladde runs in the browser. This course gives it a Windows program: a desktop application with a window of its own, navigation, keyboard operation and the features that users expect from a Windows program. The tool for that is called WinUI 3, and it belongs to the Windows App SDK. This lesson clarifies what both are and what they are not, sets up your machine, creates src/Kladde.Desktop from a template, and shows how a WinUI project is built and how quickly you can change a user interface in it.

The course assumes K2: C# and async, the Kladde's web API with its sign-in through Entra ID, and xUnit. This course does not repeat that; where it builds on it, there is a reference. You may know XAML and MVVM from the course W2 .NET MAUI: this course says what is the same and what WinUI 3 does differently, but it does not assume W2.

State of the checks. This course was written on a machine on which the Windows App SDK, the WinUI templates and the winapp CLI are not set up. Every command line and every line of XAML and C# in this lesson comes from the reference and examples on Microsoft Learn or was read against them. It was not run against a real WinUI project. Where the lesson describes what appears on the screen, it describes it according to Learn; it does not reproduce any output that was measured. Where Learn does not say something, the text says so ("Learn says nothing about this, check ..."). If your observation differs from the lesson, your observation counts, and you write it down.

What the Windows App SDK is

According to Learn, the Windows App SDK is the recommended development platform for new Windows desktop applications. It is a set of programming interfaces that comes through NuGet and is shipped independently of the operating system. As a result, new features reach your application without Windows itself having to be updated. It runs on Windows 11 and on Windows 10 from version 1809.

Learn names these components:

You determine the version on the download page of the Windows App SDK; it changes every month. For that reason, this course names no version numbers apart from "Windows App SDK 2". There are three channels: Stable for production (the default in the documentation), Preview and Experimental. The course stays with Stable.

What WinUI 3 is

According to Learn, WinUI 3 is the recommended native user interface framework for new Windows desktop applications. It works with XAML, it exists for C# and C++, and it runs on x86, x64 and ARM. Parts of the Windows user interface and PowerToys are built with it. WinUI 3 is the part of the Windows App SDK that fills windows; everything else in the table above (lifecycle, notifications, resources) can be used independently of it.

This sentence is the most important one in the lesson: The Windows App SDK is the platform, WinUI 3 is its user interface. Whoever says "WinUI" usually means both in everyday talk. In this course, "Windows App SDK" is used when windows, lifecycle or notifications are meant, and "WinUI" or "XAML" when it is about controls and pages.

Where WinUI 3 stands: WPF, Windows Forms, UWP, .NET MAUI

Four neighbors come up in every discussion. Here is one paragraph on each, without any judgment on what you already have in production.

WPF and Windows Forms. Both remain valid for existing applications; whoever maintains such an application, moves it to .NET 10 or brings it to the web and to Azure will find that in the course "Modernization: WinForms/WPF to .NET 10, the web and Azure", not here. Learn names two bridges: first, the Windows App SDK can be built into existing WPF, Windows Forms and Win32 projects; the parts that have nothing to do with WinUI (application lifecycle, windowing, app notifications) can be used there. Second, WinUI XAML Islands bring WinUI controls into part of an existing application, for example as a new screen in a WPF program. Learn distinguishes them from the older "system XAML Islands", which host UWP controls and use other interfaces; the two must not be mixed. More on both is in the Modernization course and in the pages under "Further reading"; this course teaches neither WPF nor Windows Forms nor a migration.

UWP. The Windows App SDK does not support UWP applications. For programs that are UWP today, Learn names the path "Migrate from UWP to the Windows App SDK"; namespaces, project model and individual interfaces differ, many concepts remain. The course does not cover UWP any further.

.NET MAUI. MAUI is a cross-platform framework for mobile devices and desktop; on Windows it builds on WinUI 3. It pays off when the same user interface is supposed to run on Android, iOS, macOS and Windows (course W2 .NET MAUI). WinUI 3 runs only on Windows and talks to the Windows interfaces directly: whoever builds a program for Windows that feels like a Windows program is in the right place with WinUI 3. Both use XAML; what looks the same is not named the same (for example, pages, navigation and controls have different names), and lesson W5.1.2 goes into that.

WinUI 3 itself. For new Windows programs, it is the path that Learn recommends. What follows from that for your decision depends on whether the application is new, on which Windows versions it has to run, and on who maintains it later; the course gives no judgment.

What this course is not

• Not an introduction to C# or Entra ID. You bring both from K0 to K2.
• Not cross-platform. For that there is W2 .NET MAUI.
• No WPF, no Windows Forms, no migration (course Modernization).
• No game development and no C++/WinRT. C++ exists for WinUI 3 as well; the course stays with C#.
• No depth on the Windows AI interfaces. They are in the table; the course does not teach them.

Tools

For the first steps, Learn names two paths. Both are fine, and both lead to the same result, a project that you keep working on in your tool:

The winapp CLI does not install the .NET SDK; according to Learn, winapp new and winapp run stop with a message if it is missing. With WinGet:

winget install --id Microsoft.DotNet.SDK.10 --exact --source winget
winget install --id Microsoft.WinAppCli --exact --source winget

Then open a new terminal so that it finds the commands, and check the versions:

dotnet --version
winapp --version

Learn requires .NET SDK 10 or newer and winapp CLI 0.6 or newer. For Visual Studio, Learn shows a way to set up the required workloads and Developer Mode with a WinGet configuration file:

winget configure -f https://aka.ms/winui-config

Read the configuration before you run it: it changes your machine (Visual Studio workloads, Developer Mode). Learn links a description of the configuration for this. If you prefer to work by hand, install Visual Studio and choose the workload WinUI application development in the Visual Studio Installer.

In addition, independent of the path: the WinUI 3 Gallery. It shows every control with examples; you get it from the Microsoft Store or build it from the source on GitHub (repository microsoft/WinUI-Gallery). The example there is often the shortest way to find the XAML lines of a control.

Developer Mode

For both paths, Learn requires Windows Developer Mode: Windows needs it to register the app from your output. You turn it on in Settings (for the Windows 11 window, Learn names: System, For developers; the labels change between Windows versions). Turning it on requires administrator rights and can be blocked on company devices. If the deployment later reports that Developer Mode is off, this is the cause. What the mode changes on your machine is described by Learn on a page of its own about the security of the winapp CLI; read it if the machine does not belong to you alone.

Templates

For Visual Studio and for dotnet new, Learn names these C# project templates:

There are also item templates for an existing project: Blank Page, Blank Window, Content Dialog, Resource Dictionary, Resources File (.resw), Templated Control and User Control. On the command line, for example, dotnet new winui-page -n SettingsPage adds a page; dotnet new list winui lists all templates. The short names of the project templates in the table are the ones Learn names; if dotnet new list winui shows something different on your machine, the list on your machine counts.

The course starts with the empty template because you can name every file in it. The lessons W5.1.2 and W5.2.1 build the navigation skeleton and MVVM themselves, so that you know what is in the template if you do take it later after all.

Creating the project

With Visual Studio: Create a new project, search for WinUI, choose the C# template WinUI Blank App (Packaged), enter a name and location, press F5. The first time, a window about Developer Mode may appear; Learn mentions it as a note in the flow, and also that Visual Studio installs another package for it.

With the winapp CLI, from a folder where you keep your projects:

winapp new --name MyWinUIApp --template winui --use-defaults
cd MyWinUIApp
winapp run

According to Learn, winapp new creates the empty WinUI application and winapp run builds the project and starts it; no build and registration instruction of your own is needed. Learn shows the command for a folder named after the project (cd MyWinUIApp). Whether winapp new has an option for a target folder is not stated on the pages that were read: change into the folder where the project is supposed to be created first, and look after the command to see where it ended up.

Learn points out that the templates differ: in the current template of the CLI, MainPage.xaml contains an empty <Grid />; if this file is missing in your template, the content is in MainWindow.xaml. That is no small matter when you read examples: which of the two files your template has determines where the first content goes.

For the first change, Learn shows this content in the page (or in the window):

<Grid>
    <TextBlock
        Text="Hello, WinUI!"
        HorizontalAlignment="Center"
        VerticalAlignment="Center" />
</Grid>

If the page already has controls, add only the TextBlock into the existing area and leave names and event handlers in place. Do not replace the surrounding Page, the Window, or the frame and title bar in MainWindow.xaml. Save, restart (winapp run or F5). According to Learn, the window shows the text.

If nothing appears, Learn names these checks:

Kladde.Desktop

For the Kladde, you create the project later in the same place as the projects from K2. The division applies to the whole course:

The reason for the separation is in the testing section of Learn: code that needs Microsoft.UI.Xaml types runs only on the UI thread of a XAML application. Learn recommends moving code into a library that application and test both reference. W5.2.1 puts that into practice; until then there is only the application project.

How a WinUI project is built

Learn describes the files you deal with most (tutorial "Project setup" of the WinUI Notes walkthrough):

Every XAML file has a code-behind file. In it, the XAML file declares the class with the attribute x:Class, and both are parts of the same partial class. The XAML file describes the user interface, the code-behind file reacts to events and changes the objects that were created in XAML. Learn names these characteristics that prove a project is WinUI 3 and not a UWP, WPF or MAUI project:

1. The project file contains <UseWinUI>true</UseWinUI>.
2. It references the package Microsoft.WindowsAppSDK.
3. The XAML code and the C# code use types from Microsoft.UI.Xaml.
4. Package.appxmanifest provides the package identity.
5. The target framework contains Windows; Learn names net10.0-windows10.0.26100.0 as an example.

Check this in your project. Your target framework may differ from the example, depending on what your template sets.

The namespaces are the most common stumbling block for people with WPF or UWP experience: WinUI 3 uses Microsoft.UI.Xaml and Microsoft.UI.Xaml.Controls, not Windows.UI.Xaml. Learn shows it in a tutorial on working with an AI assistant: there is an example with using Windows.UI.Xaml.Controls; and the note that this is the UWP namespace and wrong for WinUI 3; the right one is Microsoft.UI.Xaml.Controls (and the dialog there additionally lacks the XamlRoot, more on that in W5.1.2). A glance at the using lines is the fastest check of someone else's code example, whether from an assistant, from a forum or from an old article.

How the application starts

App.xaml.cs is the entry point. The class App derives from Application, and its method OnLaunched runs when the application is started. The window is created there. In the reference for the class Page, Learn shows an example of how the pieces work together when an application puts a Frame into the window and navigates to a page:

protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    m_window = new MainWindow();

    // Create a Frame to act as the navigation context.
    Frame rootFrame = new Frame();

    rootFrame.NavigationFailed += OnNavigationFailed;

    // Place the frame in the current Window
    m_window.Content = rootFrame;

    rootFrame.Navigate(typeof(MainPage), args.Arguments);

    m_window.Activate();
}

This is an example of a pattern, not the content of your template: on the pages that were read, Learn does not say what exactly OnLaunched contains in the winui template. Open App.xaml.cs in your project and read it. The patterns from the example are the building blocks you will find again in the templates: a window is a Microsoft.UI.Xaml.Window, it is created and made visible with Activate(), a Frame is a container for pages (Frame.Navigate(typeof(...))), a page is a Page. In W5.1.2 you use a Frame with page navigation.

A note on the term window: according to Learn, Window from WinUI is an abstraction over the lower-level kinds of windows (CoreWindow in UWP, the window handle in Win32). The fact that Window has no XamlRoot property, while the element inside it does, is the cause of the dialog error in W5.1.2.

Packaged and unpackaged

According to Learn, the WinUI templates build an MSIX package by default: the application has a package identity, the manifest Package.appxmanifest, and Windows installs it as a package. Packaged is the recommended default. For Visual Studio it follows: start with the launch profile MsixPackage, not with the profile that calls the .exe directly. The packaging step installs the required runtime parts.

Unpackaged means: no MSIX, no package identity. There are two ways to bring the Windows App SDK runtime along:

• Framework-dependent: the runtime has to be installed on the machine, and the application's installer takes care of that. If it is missing, Windows reports at startup the error "Unable to load DLL 'Microsoft.ui.xaml.dll'". According to Learn, this is the most common cause of that message: an unpackaged application on a machine without the matching runtime.
• Self-contained: the application brings the Windows App SDK dependencies with it.

What lies in between (settings in the project file, distribution paths, consequences for updates and file associations) is the subject of W5.3.2. For the start, the difference is enough: packaged is the template's path, and the exercises run packaged.

XAML Hot Reload and the runtime tools

The reason why working on a user interface can be pleasant: you change XAML while the application is running, and you see the change without restarting. For WinUI 3, Visual Studio has four tools for this that work together:

The prerequisites and limits, according to Learn:

• XAML Hot Reload needs the debugger. Start with F5; Ctrl+F5 (without debugging) turns off Hot Reload, the Live Visual Tree and the Live Property Explorer. The running application shows a small toolbar that confirms Hot Reload is available. If it is missing, check under Tools, Options, Debugging, XAML Hot Reload whether the option is turned on.
• Hot Reload handles the usual changes: adding, removing or reordering elements, changing property values (colors, spacing, text, sizes), adding or changing styles and resources, changing the content of data templates.
• According to Learn, these require a restart: new classes, new event handlers in the code-behind, changes to the x:Class, occasionally changes to the merged dictionaries in App.xaml, and x:Bind expressions that point to new properties. If Hot Reload cannot apply a change, the toolbar shows a message.
• According to Learn, the designer (the "Design" tab with drag and drop) does not currently support WinUI 3 projects. A XAML file that shows only the XML editor is therefore not broken. The tools in the table exist for that. Learn also recommends the XAML Binding Failures window (Debug, Windows) for finding errors in bindings.
• The winapp CLI does not have these tools; it builds and runs (winapp run). If you work with it, you change XAML, save and restart.

Learn suggests a playground page: a page of its own whose only purpose is to try out controls, styles and layouts. During development it can be reached through a menu item that appears only in debug builds (#if DEBUG). It is a good place for everything you try in W5.1.2 before it goes into a real page.

The Kladde: a Windows program next to the web application

With this lesson the Kladde has a new project: src/Kladde.Desktop, a packaged WinUI application that shows an empty window. You do not change the projects from K2 (Kladde.Core, Kladde.Data, Kladde.Web and the others). The program will use the Kladde's web API, from W5.2.2; the Kladde's rules stay where they are. In W5.1.2 you build the first pages of your own: appointments and contacts, in a NavigationView, still with fixed sample data in the code and without MVVM, because MVVM comes up only in W5.2.1. Until then, logic sits in the code-behind, and the lesson says so each time, so that you can tidy it up later.

What you can do now

• You explain what the Windows App SDK and WinUI 3 are, and how both relate to WPF, Windows Forms, UWP and .NET MAUI, and you know where existing WPF and Windows Forms programs are covered.
• You set up the .NET 10 SDK, Visual Studio with the WinUI workload or the winapp CLI, and Developer Mode.
• You create a WinUI template, run it, and assign App.xaml, MainWindow.xaml, Package.appxmanifest and the project file to their purposes.
• You tell packaged from unpackaged and recognize the error that occurs when the runtime is missing.
• You use XAML Hot Reload, the Live Visual Tree and the WinUI 3 Gallery with their limits, and you have created Kladde.Desktop.

Further reading

• Windows App SDK: components and benefits.
• Build your first WinUI app: tools, template, first change, troubleshooting.
• Windows App Development Frequently Asked Questions: existing applications, UWP, Visual Studio and other editors.
• WinUI templates in Visual Studio: project and item templates.
• Using WinApp CLI with WinUI: create, run, troubleshoot, package from the command line.
• WinUI 3: the framework, the Gallery, the way to the API reference.
• Use the Windows App SDK in an existing project: using the SDK in WPF, Windows Forms and Win32.
• Host WinUI controls with XAML Islands: WinUI controls in existing applications.
• XAML runtime design tools for WinUI 3: Hot Reload, Live Visual Tree, playground page.
• Project setup: the files of a WinUI project.
• Migrate from UWP to the Windows App SDK: for programs that are UWP today.