WinUI 3 und das Windows App SDK im Überblick

Die Kladde läuft nach K2 im Browser. Dieser Kurs gibt ihr ein Windows-Programm: eine Desktop-Anwendung mit eigenem Fenster, Navigation, Tastaturbedienung und den Funktionen, die Anwenderinnen und Anwender von einem Windows-Programm erwarten. Das Werkzeug dafür heißt WinUI 3, und es gehört zum Windows App SDK. Diese Lektion klärt, was beides ist und was nicht, richtet Ihren Rechner ein, legt src/Kladde.Desktop aus einer Vorlage an und zeigt, wie ein WinUI-Projekt aufgebaut ist und wie schnell man darin eine Oberfläche ändern kann.

Der Kurs setzt K2 voraus: C# und async, die Web-API der Kladde mit ihrer Anmeldung über Entra ID und xUnit. Das wiederholt dieser Kurs nicht; wo er darauf aufbaut, steht ein Verweis. XAML und MVVM kennen Sie vielleicht aus dem Kurs W2 .NET MAUI: Der Kurs sagt, was gleich ist und was WinUI 3 anders macht, setzt W2 aber nicht voraus.

Stand der Prüfung. Dieser Kurs wurde auf einem Rechner geschrieben, auf dem das Windows App SDK, die WinUI-Vorlagen und die winapp CLI nicht eingerichtet sind. Jede Befehlszeile und jede Zeile XAML und C# in dieser Lektion stammt aus Referenz und Beispielen auf Microsoft Learn oder ist gegen sie gelesen. Sie wurde nicht gegen ein echtes WinUI-Projekt ausgeführt. Wo die Lektion beschreibt, was auf dem Bildschirm erscheint, beschreibt sie es nach Learn; sie gibt keine Ausgabe wieder, die gemessen wurde. Wo Learn etwas nicht sagt, steht das im Text („Learn nennt dazu nichts, prüfen Sie …“). Wenn Ihre Beobachtung von der Lektion abweicht, gilt Ihre Beobachtung, und Sie halten sie fest.

Was das Windows App SDK ist

Das Windows App SDK ist nach Learn die empfohlene Entwicklungsplattform für neue Windows-Desktop-Anwendungen. Es ist ein Satz von Programmierschnittstellen, der über NuGet kommt und unabhängig vom Betriebssystem ausgeliefert wird. Dadurch erreichen neue Funktionen Ihre Anwendung, ohne dass Windows selbst aktualisiert werden muss. Es läuft auf Windows 11 und auf Windows 10 ab Version 1809.

Learn nennt als Bestandteile:

Die Version bestimmen Sie über die Download-Seite zum Windows App SDK; sie ändert sich im Monatsrhythmus. Dieser Kurs nennt deshalb außer „Windows App SDK 2“ keine Versionsnummern. Es gibt drei Kanäle: Stable für die Produktion (der Standard in der Dokumentation), Preview und Experimental. Der Kurs bleibt bei Stable.

Was WinUI 3 ist

WinUI 3 ist nach Learn das empfohlene native Oberflächen-Rahmenwerk für neue Windows-Desktop-Anwendungen. Es arbeitet mit XAML, es gibt es für C# und C++, und es läuft auf x86, x64 und ARM. Teile der Windows-Oberfläche und PowerToys sind damit gebaut. WinUI 3 ist der Teil des Windows App SDK, der Fenster füllt; alles andere in der Tabelle oben (Lebenszyklus, Benachrichtigungen, Ressourcen) ist unabhängig davon verwendbar.

Dieser Satz ist der wichtigste der Lektion: Das Windows App SDK ist die Plattform, WinUI 3 ist ihre Oberfläche. Wer „WinUI“ sagt, meint im Alltag meist beides. Im Kurs steht „Windows App SDK“, wenn Fenster, Lebenszyklus oder Benachrichtigungen gemeint sind, und „WinUI“ oder „XAML“, wenn es um Steuerelemente und Seiten geht.

Wo WinUI 3 steht: WPF, Windows Forms, UWP, .NET MAUI

Vier Nachbarn tauchen in jeder Diskussion auf. Hier steht zu jedem ein Absatz, ohne Wertung dessen, was Sie schon im Betrieb haben.

WPF und Windows Forms. Beide bleiben für vorhandene Anwendungen gültig; wer eine solche Anwendung pflegt, auf .NET 10 hebt oder ins Web und nach Azure bringt, findet das im Kurs „Modernisierung: WinForms/WPF nach .NET 10, Web und Azure“, nicht hier. Zwei Brücken nennt Learn: Erstens kann das Windows App SDK in vorhandene WPF-, Windows-Forms- und Win32-Projekte eingebaut werden; die Teile, die nichts mit WinUI zu tun haben (Anwendungslebenszyklus, Fenster, App-Benachrichtigungen), lassen sich dort verwenden. Zweitens bringen WinUI XAML Islands WinUI-Steuerelemente in einen Teil einer vorhandenen Anwendung, etwa als neuer Bildschirm in einem WPF-Programm. Learn grenzt sie von den älteren „system XAML Islands“ ab, die UWP-Steuerelemente hosten und andere Schnittstellen benutzen; die beiden dürfen nicht vermischt werden. Mehr zu beidem steht im Kurs Modernisierung und in den Seiten unter „Weiterlesen“; dieser Kurs lehrt weder WPF noch Windows Forms noch eine Migration.

UWP. Das Windows App SDK unterstützt UWP-Anwendungen nicht. Für Programme, die heute UWP sind, nennt Learn den Weg „Migrate from UWP to the Windows App SDK“; Namensräume, Projektmodell und einzelne Schnittstellen unterscheiden sich, viele Konzepte bleiben. Der Kurs behandelt UWP nicht weiter.

.NET MAUI. MAUI ist ein plattformübergreifendes Rahmenwerk für Mobilgeräte und Desktop; unter Windows baut es auf WinUI 3 auf. Es lohnt sich, wenn dieselbe Oberfläche auf Android, iOS, macOS und Windows laufen soll (Kurs W2 .NET MAUI). WinUI 3 läuft nur unter Windows und spricht dafür die Windows-Schnittstellen unmittelbar an: Wer ein Programm für Windows baut, das sich wie ein Windows-Programm anfühlt, ist bei WinUI 3 richtig. Beide benutzen XAML; was gleich aussieht, ist nicht gleich benannt (zum Beispiel heißen Seiten, Navigation und Steuerelemente anders), und die Lektion W5.1.2 geht darauf ein.

WinUI 3 selbst. Für neue Windows-Programme ist es der Weg, den Learn empfiehlt. Was daraus für Ihre Entscheidung folgt, hängt davon ab, ob die Anwendung neu ist, auf welche Windows-Versionen sie muss und wer sie später pflegt; der Kurs gibt keine Wertung vor.

Was dieser Kurs nicht ist

• Keine Einführung in C# oder Entra ID. Beides bringen Sie aus K0 bis K2 mit.
• Keine Plattformübergreifung. Dafür gibt es W2 .NET MAUI.
• Kein WPF, kein Windows Forms, keine Migration (Kurs Modernisierung).
• Keine Spieleentwicklung und kein C++/WinRT. C++ gibt es bei WinUI 3 auch; der Kurs bleibt bei C#.
• Keine Tiefe zu den Windows-KI-Schnittstellen. Sie stehen in der Tabelle; der Kurs lehrt sie nicht.

Werkzeuge

Learn nennt für die ersten Schritte zwei Wege. Beide sind in Ordnung, und beide führen zum selben Ergebnis, einem Projekt, das Sie in Ihrem Werkzeug weiter bearbeiten:

Die winapp CLI installiert das .NET SDK nicht, winapp new und winapp run brechen nach Learn mit einem Hinweis ab, wenn es fehlt. Mit WinGet:

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

Öffnen Sie danach ein neues Terminal, damit es die Befehle findet, und prüfen Sie die Versionen:

dotnet --version
winapp --version

Learn verlangt .NET SDK 10 oder neuer und winapp CLI 0.6 oder neuer. Für Visual Studio zeigt Learn einen Weg, die benötigten Arbeitslasten und den Entwicklermodus mit einer WinGet-Konfigurationsdatei einzurichten:

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

Lesen Sie die Konfiguration vorher, bevor Sie sie ausführen: Sie verändert Ihren Rechner (Visual-Studio-Arbeitslasten, Entwicklermodus). Learn verlinkt dafür eine Beschreibung der Konfiguration. Wer lieber von Hand arbeitet, installiert Visual Studio und wählt im Visual Studio Installer die Arbeitslast WinUI application development.

Dazu kommt, unabhängig vom Weg: Die WinUI 3 Gallery. Sie zeigt jedes Steuerelement mit Beispielen, Sie bekommen sie im Microsoft Store oder bauen sie aus dem Quelltext auf GitHub (Repository microsoft/WinUI-Gallery). Das Beispiel dort ist oft der kürzeste Weg, um die XAML-Zeilen eines Steuerelements zu finden.

Der Entwicklermodus

Learn verlangt für beide Wege den Entwicklermodus von Windows: Windows braucht ihn, um die App aus Ihrer Ausgabe zu registrieren. Sie schalten ihn in den Einstellungen ein (Learn nennt für das Windows-11-Fenster: System, Für Entwickler; die Bezeichnungen ändern sich zwischen Windows-Versionen). Das Einschalten verlangt Administratorrechte und kann auf Geräten einer Firma gesperrt sein. Meldet die Bereitstellung später, der Entwicklermodus sei ausgeschaltet, ist das die Ursache. Was der Modus an Ihrem Rechner ändert, beschreibt Learn auf einer eigenen Seite zur Sicherheit der winapp CLI; lesen Sie sie, wenn der Rechner nicht Ihnen allein gehört.

Vorlagen

Learn nennt für Visual Studio und für dotnet new diese Projektvorlagen für C#:

Dazu gibt es Elementvorlagen für ein vorhandenes Projekt: Blank Page, Blank Window, Content Dialog, Resource Dictionary, Resources File (.resw), Templated Control und User Control. Auf der Kommandozeile fügt zum Beispiel dotnet new winui-page -n SettingsPage eine Seite hinzu; dotnet new list winui listet alle Vorlagen. Die Kurznamen der Projektvorlagen in der Tabelle sind die, die Learn nennt; wenn dotnet new list winui bei Ihnen etwas anderes zeigt, gilt die Liste Ihres Rechners.

Der Kurs beginnt mit der leeren Vorlage, weil man an ihr jede Datei benennen kann. Navigationsgerüst und MVVM bauen die Lektionen W5.1.2 und W5.2.1 selbst, damit Sie wissen, was in der Vorlage steht, wenn Sie sie später doch einmal nehmen.

Das Projekt anlegen

Mit Visual Studio: Create a new project, nach WinUI suchen, die C#-Vorlage WinUI Blank App (Packaged) wählen, Namen und Ort eingeben, F5 drücken. Beim ersten Mal kann ein Fenster mit dem Entwicklermodus erscheinen; Learn nennt es als Hinweis im Ablauf, ebenso, dass Visual Studio dafür ein weiteres Paket installiert.

Mit der winapp CLI, aus einem Ordner, in dem Sie Ihre Projekte halten:

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

winapp new legt nach Learn die leere WinUI-Anwendung an, winapp run baut das Projekt und startet es; eine eigene Bau- und Registrierungsanweisung ist nicht nötig. Learn zeigt den Befehl für einen Ordner mit dem Namen des Projekts (cd MyWinUIApp). Ob winapp new eine Option für einen Zielordner hat, steht auf den gelesenen Seiten nicht: Wechseln Sie vorher in den Ordner, in dem das Projekt entstehen soll, und schauen Sie nach dem Befehl, wo es gelandet ist.

Learn weist darauf hin, dass sich die Vorlagen unterscheiden: In der aktuellen Vorlage der CLI enthält MainPage.xaml ein leeres <Grid />; fehlt diese Datei in Ihrer Vorlage, steht der Inhalt in MainWindow.xaml. Das ist keine Kleinigkeit, wenn Sie Beispiele lesen: Welche der beiden Dateien Ihre Vorlage hat, bestimmt, wo der erste Inhalt steht.

Für die erste Änderung zeigt Learn diesen Inhalt in der Seite (oder im Fenster):

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

Hat die Seite schon Steuerelemente, fügen Sie nur das TextBlock in die vorhandene Fläche ein und lassen Namen und Ereignis-Handler stehen. Ersetzen Sie nicht die umgebende Page, das Window und nicht den Rahmen und die Titelleiste in MainWindow.xaml. Speichern Sie, starten Sie neu (winapp run oder F5). Das Fenster zeigt nach Learn den Text.

Wenn nichts erscheint, nennt Learn diese Prüfungen:

Kladde.Desktop

Für die Kladde legen Sie das Projekt später an derselben Stelle an wie die Projekte aus K2. Die Aufteilung gilt für den ganzen Kurs:

Der Grund für die Trennung steht bei Learn im Abschnitt zum Testen: Code, der Microsoft.UI.Xaml-Typen braucht, läuft nur auf dem UI-Thread einer XAML-Anwendung. Learn empfiehlt, Code in eine Bibliothek auszulagern, die Anwendung und Test beide referenzieren. W5.2.1 setzt das um; bis dahin gibt es nur das Anwendungsprojekt.

Wie ein WinUI-Projekt aufgebaut ist

Learn beschreibt die Dateien, mit denen Sie am meisten zu tun haben (Lernprogramm „Project setup“ der WinUI-Notes-Anleitung):

Zu jeder XAML-Datei gehört eine Code-Behind-Datei. In ihr deklariert die XAML-Datei die Klasse mit dem Attribut x:Class, und beide sind Teile derselben partial class. Die XAML-Datei beschreibt die Oberfläche, die Code-Behind-Datei reagiert auf Ereignisse und verändert die Objekte, die in XAML angelegt wurden. Learn nennt als Merkmale, die beweisen, dass ein Projekt WinUI 3 und kein UWP-, WPF- oder MAUI-Projekt ist:

1. Die Projektdatei enthält <UseWinUI>true</UseWinUI>.
2. Sie verweist auf das Paket Microsoft.WindowsAppSDK.
3. Der XAML-Code und der C#-Code benutzen Typen aus Microsoft.UI.Xaml.
4. Package.appxmanifest liefert die Paketidentität.
5. Das Zielframework enthält Windows; Learn nennt als Beispiel net10.0-windows10.0.26100.0.

Prüfen Sie das an Ihrem Projekt. Ihr Zielframework kann sich von dem Beispiel unterscheiden, je nachdem, was Ihre Vorlage setzt.

Die Namensräume sind für Leute mit WPF- oder UWP-Erfahrung die häufigste Stolperstelle: WinUI 3 benutzt Microsoft.UI.Xaml und Microsoft.UI.Xaml.Controls, nicht Windows.UI.Xaml. Learn zeigt es in einem Lernprogramm zur Arbeit mit einem KI-Assistenten: Dort steht ein Beispiel mit using Windows.UI.Xaml.Controls; und der Hinweis, dass das der UWP-Namensraum und für WinUI 3 falsch ist; richtig ist Microsoft.UI.Xaml.Controls (und dem Dialog dort fehlt zusätzlich die XamlRoot, dazu in W5.1.2 mehr). Ein Blick auf die using-Zeilen ist die schnellste Prüfung eines fremden Codebeispiels, ob von einem Assistenten, aus einem Forum oder aus einem alten Artikel.

Wie die Anwendung startet

App.xaml.cs ist der Einstieg. Die Klasse App leitet von Application ab, und ihre Methode OnLaunched läuft, wenn die Anwendung gestartet wird. Dort entsteht das Fenster. Learn zeigt in der Referenz zur Klasse Page ein Beispiel, das das Zusammenspiel zeigt, wenn eine Anwendung ein Frame in das Fenster setzt und zu einer Seite navigiert:

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();
}

Das ist ein Beispiel für ein Muster, nicht der Inhalt Ihrer Vorlage: Learn nennt auf den gelesenen Seiten nicht, was OnLaunched in der Vorlage winui genau enthält. Öffnen Sie App.xaml.cs in Ihrem Projekt und lesen Sie. Die Muster aus dem Beispiel sind die Bausteine, die Sie in den Vorlagen wiederfinden werden: Ein Fenster ist ein Microsoft.UI.Xaml.Window, es wird erzeugt und mit Activate() sichtbar gemacht, ein Frame ist ein Behälter für Seiten (Frame.Navigate(typeof(...))), eine Seite ist eine Page. In W5.1.2 setzen Sie ein Frame mit einer Seitennavigation ein.

Ein Hinweis zum Begriff Fenster: Window aus WinUI ist nach Learn eine Abstraktion über die niedrigeren Fensterarten (bei UWP CoreWindow, bei Win32 das Fensterhandle). Dass Window keine Eigenschaft XamlRoot hat, das Element in ihm aber schon, ist die Ursache für den Dialog-Fehler in W5.1.2.

Gepackt und ungepackt

Die WinUI-Vorlagen bauen nach Learn standardmäßig ein MSIX-Paket: Die Anwendung hat eine Paketidentität, das Manifest Package.appxmanifest, und Windows installiert sie als Paket. Gepackt ist die empfohlene Voreinstellung. Daraus folgt für Visual Studio: Starten Sie mit dem Startprofil MsixPackage, nicht mit dem Profil, das die .exe direkt aufruft. Der Paketierungsschritt installiert die benötigten Laufzeitteile.

Ungepackt heißt: kein MSIX, keine Paketidentität. Es gibt zwei Wege, die Laufzeit des Windows App SDK mitzubringen:

• Abhängig vom Framework: Die Laufzeit muss auf dem Rechner installiert sein, der Installer der Anwendung kümmert sich darum. Fehlt sie, meldet Windows beim Start den Fehler „Unable to load DLL 'Microsoft.ui.xaml.dll'“. Das ist die häufigste Ursache dieser Meldung nach Learn: eine ungepackte Anwendung auf einem Rechner ohne die passende Laufzeit.
• Selbstenthaltend: Die Anwendung bringt die Abhängigkeiten des Windows App SDK mit.

Was dazwischen liegt (Einstellungen in der Projektdatei, Verteilungswege, Folgen für Updates und Dateizuordnungen), ist der Stoff von W5.3.2. Für den Anfang genügt der Unterschied: gepackt ist der Weg der Vorlage, und die Übungen laufen gepackt.

XAML Hot Reload und die Werkzeuge zur Laufzeit

Der Grund, warum die Arbeit an einer Oberfläche angenehm sein kann: Sie ändern XAML, während die Anwendung läuft, und sehen die Änderung, ohne neu zu starten. Für WinUI 3 hat Visual Studio dazu vier Werkzeuge, die zusammen funktionieren:

Die Voraussetzungen und Grenzen, nach Learn:

• XAML Hot Reload braucht den Debugger. Starten Sie mit F5; Strg+F5 (ohne Debugging) schaltet Hot Reload, Live Visual Tree und Live Property Explorer ab. Die laufende Anwendung zeigt eine kleine Werkzeugleiste, die bestätigt, dass Hot Reload verfügbar ist. Fehlt sie, prüfen Sie unter Tools, Options, Debugging, XAML Hot Reload, ob die Option eingeschaltet ist.
• Hot Reload schafft die gewöhnlichen Änderungen: Elemente hinzufügen, entfernen oder umordnen, Eigenschaftswerte ändern (Farben, Abstände, Text, Größen), Stile und Ressourcen ergänzen oder ändern, den Inhalt von Datenvorlagen ändern.
• Einen Neustart verlangen nach Learn neue Klassen, neue Ereignis-Handler im Code-Behind, Änderungen am x:Class, gelegentlich Änderungen an den zusammengeführten Wörterbüchern in App.xaml und x:Bind-Ausdrücke, die auf neue Eigenschaften zeigen. Wenn Hot Reload eine Änderung nicht anwenden kann, zeigt die Werkzeugleiste eine Meldung.
• Der Designer (die Registerkarte „Design“ mit Ziehen und Ablegen) unterstützt WinUI-3-Projekte nach Learn derzeit nicht. Eine XAML-Datei, die nur den XML-Editor zeigt, ist also nicht defekt. Dafür gibt es die Werkzeuge der Tabelle. Learn empfiehlt außerdem das Fenster XAML Binding Failures (Debug, Windows), um Fehler in Bindungen zu finden.
• Die winapp CLI hat diese Werkzeuge nicht; sie baut und startet (winapp run). Wenn Sie mit ihr arbeiten, ändern Sie XAML, speichern und starten neu.

Learn schlägt eine Spielwiese-Seite vor: eine eigene Seite, deren einziger Zweck es ist, Steuerelemente, Stile und Layouts auszuprobieren. Sie lässt sich während der Entwicklung über einen Menüeintrag erreichen, der nur in Debug-Builds erscheint (#if DEBUG). Das ist ein guter Ort für alles, was Sie in W5.1.2 ausprobieren, bevor es in eine echte Seite kommt.

Die Kladde: ein Windows-Programm neben der Webanwendung

Mit dieser Lektion hat die Kladde ein neues Projekt: src/Kladde.Desktop, eine gepackte WinUI-Anwendung, die ein leeres Fenster zeigt. Die Projekte aus K2 (Kladde.Core, Kladde.Data, Kladde.Web und die übrigen) ändern Sie nicht. Das Programm wird die Web-API der Kladde nutzen, ab W5.2.2; die Regeln der Kladde bleiben dort, wo sie sind. In W5.1.2 bauen Sie die ersten eigenen Seiten: Termine und Kontakte, in einer NavigationView, noch mit festen Beispieldaten im Code und ohne MVVM, weil MVVM erst in W5.2.1 an der Reihe ist. Bis dahin steht Logik im Code-Behind, und die Lektion sagt es jedes Mal, damit Sie es später aufräumen können.

Was Sie jetzt können

• Sie erklären, was das Windows App SDK und WinUI 3 sind, und wie sich beide zu WPF, Windows Forms, UWP und .NET MAUI verhalten, und Sie wissen, wo vorhandene WPF- und Windows-Forms-Programme behandelt werden.
• Sie richten .NET 10 SDK, Visual Studio mit der Arbeitslast für WinUI oder die winapp CLI und den Entwicklermodus ein.
• Sie legen eine WinUI-Vorlage an, starten sie und ordnen App.xaml, MainWindow.xaml, Package.appxmanifest und die Projektdatei ihrem Zweck zu.
• Sie unterscheiden gepackt und ungepackt und erkennen den Fehler, der auftritt, wenn die Laufzeit fehlt.
• Sie nutzen XAML Hot Reload, Live Visual Tree und die WinUI 3 Gallery mit ihren Grenzen und haben Kladde.Desktop angelegt.

Weiterlesen

• Windows App SDK: Bestandteile und Nutzen.
• Build your first WinUI app: Werkzeuge, Vorlage, erste Änderung, Fehlersuche.
• Windows App Development Frequently Asked Questions: bestehende Anwendungen, UWP, Visual Studio und andere Editoren.
• WinUI templates in Visual Studio: Projekt- und Elementvorlagen.
• Using WinApp CLI with WinUI: erstellen, starten, Fehler suchen, paketieren von der Kommandozeile.
• WinUI 3: das Rahmenwerk, die Gallery, der Weg zur API-Referenz.
• Use the Windows App SDK in an existing project: das SDK in WPF, Windows Forms und Win32 verwenden.
• Host WinUI controls with XAML Islands: WinUI-Steuerelemente in vorhandenen Anwendungen.
• XAML runtime design tools for WinUI 3: Hot Reload, Live Visual Tree, Spielwiese-Seite.
• Project setup: die Dateien eines WinUI-Projekts.
• Migrate from UWP to the Windows App SDK: für Programme, die heute UWP sind.