Vorstellung des ersten WinUI-C++-Programms

In der vorherigen Lektion haben wir die Installation von WinUI C++ abgeschlossen und unser erstes funktionsfähiges Programm erstellt. In dieser Lektion analysieren wir die Struktur dieses ersten WinUI-C++-Projekts.

Im Folgenden erklären wir die Aufgabe jeder Datei und jedes Verzeichnisses.

Analyse des Projektverzeichnisses

Lösungsname

Ganz oben steht „Solution ‚App3’“ – das ist der Name der Lösung, hier also App3. Beim Erstellen eines Projekts können Sie einen individuellen Lösungsnamen festlegen, standardmäßig wird derselbe Name wie das Projekt verwendet.

Auf dem Screenshot ist das erste Eingabefeld der Projektname, das letzte der Lösungsname. Standardmäßig sind beide identisch, Sie können aber unterschiedliche Namen vergeben.

Eine Lösung kann mehrere Projekte enthalten; hier liegt nur ein verpacktes Desktop-Projekt App3 (Desktop) vor.

1. References (Verweise)

Dieser Ordner speichert Verweise auf projektabhängige SDKs, das Windows App SDK, die WinRT-Laufzeit und über NuGet installierte Komponenten:

Alle Abhängigkeiten wie Windows SDK, WinUI-3-Steuerelementbibliothek, C++/WinRT-Headerbibliotheken sowie Microsoft.UI.Xaml werden hier verwaltet;
Eine manuelle Bearbeitung ist nicht erforderlich, Visual Studio aktualisiert diese Einträge automatisch bei der Verwaltung von NuGet-Paketen.

2. External Dependencies (Externe Abhängigkeiten)

Dieser Ordner scannt automatisch Systemheader, SDK-Header und Header von Drittanbieterbibliotheken:

Windows.h, die Header aus dem winrt/-Verzeichnis sowie untergeordnete Header von Microsoft.UI.Xaml;
Der Ordner ist schreibgeschützt, er dient nur zur Ansicht extern eingebundener Codes und kann nicht manuell bearbeitet werden. Er enthält üblicherweise Bibliotheken, die mit Visual Studio installiert werden.

Dateien externer Abhängigkeiten (Ausschnitt)

Doppelklicken Sie eine beliebige Datei zum Öffnen – Sie sehen, dass sie sich im Installationsverzeichnis von Visual Studio befindet. Fahren Sie mit der Maus über den Dateinamen oben im Editor, um den vollständigen Pfad anzuzeigen.

3. Assets-Ressourcenordner (App-Symbole / Startbildschirm)

Dieser Ordner enthält alle Bildressourcen für den Microsoft Store, Systemdialoge, den Start-Splashscreen und den Sperrbildschirm, die für das Verpacken und Veröffentlichen im Microsoft Store benötigt werden:

Warum existieren diese Dateien? Weil wir bei der Projekterstellung eine vorverpackte Projektvorlage gewählt haben. Unter Verpacken versteht man das Kompilieren zu einer MSIX-Datei für den Microsoft Store. Wo liegt der Unterschied zwischen verpacktem und unverpacktem Projekt? Ein unverpacktes Projekt erzeugt eine eigenständige EXE-Datei, die direkt per Doppelklick ausgeführt werden kann – so funktionieren viele ältere Projekte. Beim verpackten Verfahren werden alle EXE-, DLL- und Ressourcendateien in eine einzige Installationsdatei gebündelt, die Benutzer nur doppelklicken müssen, um die App zu installieren. Wir haben diese verpackte Variante gewählt, da wir die Anwendung später im Microsoft Store veröffentlichen wollen.

Der obige Screenshot zeigt die gewählte Projektvorlage. Aus der Beschreibung geht hervor, dass sie zum Erstellen von MSIX-Dateien für die Veröffentlichung im Microsoft Store gedacht ist. Der Store erfordert zahlreiche Symbole und Grafiken, weshalb diese Ressourcen bereits im Projekt enthalten sind. Es ist auch möglich, ein unverpacktes Projekt zu erstellen, das nur eine EXE zur direkten Ausgabe generiert – darauf gehen wir später ein.

Aufgabe jeder Bilddatei

Datei	Aufgabe
LockScreenLogo.scale-200.png	App-Symbol auf dem Sperrbildschirm (200 % hoher DPI-Skalierung)
SplashScreen.scale-200.png	Splashscreen beim Programmstart
Square44x44Logo… mehrere Bilder	Kleines Startmenü-Symbol, Taskleisten-Symbol, Alt+Tab-Fenstervorschau
Square150x150Logo.scale-200.png	Mittelgroßes Kachelsymbol im Startmenü
StoreLogo.png	Großes App-Symbol zur Anzeige im Microsoft Store
Wide310x150Logo.scale-200.png	Breite Kachel im Startmenü

app.manifest

Traditionelles Windows-Anwendungsmanifest (Win32-kompatibel):

Legt App-Berechtigungen, kompatible Windows-Versionen, DPI-Erkennung, Administratorrechte und das Skalierverhalten von Fenstern fest;
Es unterscheidet sich vom UWP-eigenen Package.appxmanifest – bei verpackten Desktop-Projekten liegen beide Manifeste parallel vor.

4. App.xaml / App.xaml.h / App.xaml.cpp

Globale Wurzelklasse und Einstiegspunkt der Anwendung (entspricht winrt::App3::App)

App.xaml: Globales XAML-Ressourcenwörterbuch. Globale Stile, Steuerelementvorlagen, Farben, Schriftarten und Themenressourcen, die von allen Seiten im Projekt gemeinsam genutzt werden.
App.xaml.h: Automatisch von C++/WinRT generierte Headerdatei mit der Deklaration der Klasse App, inklusive Lebenszyklusfunktionen wie OnLaunched und OnActivated.
App.xaml.cpp: Implementierung der App-Lebenszykluslogik:
- OnLaunched: Wird beim Start des Programms ausgeführt, erstellt und aktiviert das Fenster MainWindow;
- Verarbeitet Fensteraktivierung, Aussetzung, Themenwechsel und Ausnahmebehandlung;
- Hier werden alle globalen Initialisierungslogiken (Schriftarten, Datenbanken, Singleton-Dienste) abgelegt.

Öffnen Sie die CPP-Datei, dann sehen Sie folgenden Code:

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make<MainWindow>();
        window.Activate();
    }Code-Sprache: C++ (cpp)

An dieser Stelle wechselt das Programm zu MainWindow. App ist nur der Einstiegspunkt und erstellt keine Fenster – MainWindow ist die eigentliche Instanz für sichtbare Fenster, Steuerelemente und Dialoge.

5. Gesamtset MainWindow.xaml (Hauptfenster)

Standard-Hauptfenster des Programms, oberste sichtbare Wurzelfenster der Desktop-Anwendung.

MainWindow.xaml: Fensterlayout. Hier werden Schaltflächen, Textfelder, Navigationssteuerelemente und der Frame zur Aufnahme von Seiten definiert;
MainWindow.idl: IDL-Schnittstellendefinitionsdatei (Kern von C++/WinRT). Definiert vom Fenster freigegebene Eigenschaften, Methoden und Ereignisse für XAML-Bindung, komponentenübergreifende Aufrufe und Typmetadaten. Bei Änderungen werden automatisch passende .h/.cpp-Bindecodes generiert.
MainWindow.xaml.h: Aus IDL und XAML automatisch generierte Klassenheader mit Deklarationen von Steuerelementmitgliedern, Konstruktoren und Ereignishandlern.
MainWindow.xaml.cpp: Fenster-Geschäftslogik: Code für Schaltflächenklicks, Datenbindung, Seitenwechsel und Steuerelementinteraktionen.

Folgend der Inhalt von MainWindow.xaml, der alle Steuerelemente und das Layout festlegt:

<?xml version="1.0" encoding="utf-8"?>
<Window
    x:Class="App3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:App3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"
    Title="App3">

    <Grid>

    </Grid>
</Window>
Code-Sprache: HTML, XML (xml)

6. module.g.cpp

Automatisch generierte globale Moduldatei für C++/WinRT (manuelle Änderungen verboten)

Generiert WinRT-Typregistrierungscode anhand aller .idl-Dateien;
Bietet den Namensraum-Einstiegspunkt winrt::App3::implementation, damit das System benutzerdefinierte XAML-Steuerelemente und Fensterklassen erkennt;
Nach Hinzufügen oder Löschen von IDL-Dateien regeneriert Visual Studio diese Datei automatisch.

7. Package.appxmanifest (MSIX-Verpackungsmanifest, zentrale Datei)

Konfigurationsdatei zum Verpacken von Desktop-Apps zu MSIX-Installationspaketen. Doppelklicken Sie sie, um den visuellen Editor zu öffnen:

App-Name, Version, Herausgeber, Symbole und Startpunkt;
Deklaration von Systemberechtigungen (Dateizugriff, Kamera, Netzwerk, Hintergrundaufgaben);
Zuordnung von Dateiöffnungsprotokollen, URL-Protokollen und Erweiterungen;
Konfiguration von Store-Veröffentlichungsdaten, Desktop-Verknüpfungen und Dateizuordnungen. Abgrenzung zu app.manifest: Dies ist das spezielle Manifest für Microsoft Store / MSIX-Pakete, nur für UWP und verpackte Desktop-Apps.

Hier werden beispielsweise alle Microsoft Store-relevanten Einstellungen wie Version, Paketname und Herausgeber hinterlegt – diese Daten müssen Sie im Entwicklerportal des Microsoft Store abrufen.

8. packages.config

Konfigurationsdatei für NuGet-Pakete: Speichert die Version aller im Projekt installierten NuGet-Pakete, zum Beispiel:

Bibliotheken Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3;
Bei Teamarbeit oder Gerätewechsel nutzt Visual Studio diese Datei, um alle Abhängigkeitspakete automatisch wiederherzustellen.

9. pch.h/pch.cpp (Vorkompilierte Header, Beschleunigung der C++-Kompilierung)

pch = Precompiled Header (vorkompilierter Header)

pch.h: Bündelt alle global genutzten Header (winrt/Windows.*, Microsoft.UI.Xaml.*, Standardbibliotheken). Jede CPP-Datei beginnt mit der Zeile #include "pch.h";
pch.cpp: Quelldatei zur Kompilierung des vorkompilierten Headers. Vorteil: Die Kompilierzeit sinkt stark, da nicht jede Datei einzeln hunderte Systemheader laden muss.

Alle wiederverwendbaren Includes werden zentral hier abgelegt. Andere Quelldateien binden nur diese eine Datei ein, das spart Code und beschleunigt den Build-Vorgang.

10. readme.txt

Dokument im Lieferumfang der Visual Studio-Vorlage mit grundlegenden Hinweisen zum Kompilieren, Verpacken und Debuggen von WinUI-3-C++-Projekten.

Zwei leicht verwechselte Manifest-Dateien

app.manifest → Traditionelles Win32-Prozessmanifest (Fensterverhalten, Systemkompatibilität, Berechtigungen)
Package.appxmanifest → MSIX-App-Paketmanifest (Store-Veröffentlichung, Installation, Systemfunktionsdeklarationen)

Gesamter Ausführungsablauf des Programms

Programmstart → Ausführung von App::OnLaunched(App.xaml.cpp)
Erstellen einer MainWindow-Instanz und Aktivieren der Anzeige: window = make(); window.Activate();
MainWindow.xaml rendert die Benutzeroberfläche, die CPP-Datei verarbeitet alle Benutzerinteraktionen
Beim Verpacken zum Installer wird Package.appxmanifest eingelesen, um das Paket zu generieren; alle Symbole aus dem Assets-Ordner werden ins Paket eingebettet

Das war die vollständige Erklärung zur Verzeichnisstruktur und dem Ablauf des einfachsten leeren Projekts. In der nächsten Lektion fügen wir eine Schaltfläche zum Fenster hinzu, die bei Klick eine Zahl hochzählt – damit verstehen wir die Arbeitsweise des WinUI-C++-Frameworks.

Previous: WinUI mit C++ installieren und erstes Projekt erstellen