Présentation du premier programme WinUI en C++

Au cours précédent, nous avons terminé l’installation de WinUI C++ et créé notre premier programme fonctionnel. Dans cette leçon, nous allons analyser la structure de ce premier projet WinUI C++.

Nous détaillons ci-dessous le rôle de chaque fichier et dossier.

Analyse de l’arborescence du projet

Nom de la solution

La ligne tout en haut « Solution ‘App3’ » correspond au nom de la solution, ici App3. Vous pouvez définir un nom personnalisé lors de la création du projet ; par défaut, il reprend le nom du projet.

Sur la capture, le premier champ correspond au nom du projet, le dernier au nom de la solution. Ils sont identiques par défaut mais vous pouvez leur attribuer des noms différents.

Une solution peut regrouper plusieurs projets ; ici, nous n’avons qu’un seul projet empaqueté pour bureau : App3 (Desktop).

1. References (Références)

Ce dossier stocke les références vers les SDK dépendants, le Windows App SDK, le runtime WinRT et les composants installés via NuGet :

• Il gère toutes les dépendances : Windows SDK, bibliothèque de contrôles WinUI 3, fichiers d’en-tête C++/WinRT, Microsoft.UI.Xaml, etc. ;
• Aucune modification manuelle n’est nécessaire : Visual Studio met à jour ces références automatiquement lors de la gestion des paquets NuGet.

2. External Dependencies (Dépendances externes)

Ce dossier liste automatiquement les fichiers d’en-tête système, les en-têtes des SDK et ceux des bibliothèques tierces :

• Windows.h, les en-têtes du dossier winrt/, les en-têtes bas niveau de Microsoft.UI.Xaml ;
• Il est en lecture seule : il permet de consulter le code externe mais ne peut pas être édité manuellement. Il regroupe généralement les bibliothèques fournies avec Visual Studio.

Double-cliquez sur n’importe quel fichier pour l’ouvrir : vous verrez qu’il est stocké dans le dossier d’installation de Visual Studio. Passez la souris sur le nom du fichier en haut de l’éditeur pour afficher son chemin complet.

3. Dossier Assets (Ressources : icônes et écran de lancement)

Il contient toutes les images utilisées pour le Microsoft Store, les fenêtres système, l’écran de démarrage et l’écran de verrouillage, nécessaires à l’empaquetage et la publication sur le Microsoft Store :

Pourquoi ces fichiers existent-ils ? Parce que nous avons choisi un modèle de projet empaqueté lors de la création. L’empaquetage consiste à compiler l’application au format MSIX, destiné au Microsoft Store. Quelle est la différence entre projet empaqueté et non empaqueté ? Un projet non empaqueté génère un simple fichier exe exécutable directement. La plupart des anciens projets fonctionnent ainsi : compilez, double-cliquez sur l’exe pour lancer l’app. À l’inverse, l’empaquetage regroupe tous les exe, dll et ressources dans un seul fichier installable par double-clic. Nous avons choisi ce modèle car nous souhaitons publier notre application sur le Microsoft Store.

L’image ci-dessus montre le modèle sélectionné. Sa description indique qu’il génère un fichier MSIX pour publication sur le Microsoft Store. La boutique requiert de nombreuses icônes et visuels, c’est pourquoi ils sont intégrés au projet. Il est possible de créer un projet non empaqueté qui produit un exe directement, nous aborderons ce point plus tard.

Rôle de chaque image

app.manifest

Manifeste d’application Windows traditionnel (compatible Win32) :

• Définit les autorisations de l’application, les versions Windows compatibles, la gestion DPI, les droits administrateur et le comportement de mise à l’échelle des fenêtres ;
• Il se distingue du Package.appxmanifest des UWP : les projets de bureau empaquetés possèdent les deux manifestes simultanément.

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

Classe racine globale, point d’entrée de l’application (correspond à winrt::App3::App)

1. App.xaml : dictionnaire de ressources XAML global. Il regroupe styles, modèles de contrôles, couleurs, polices et ressources de thème partagés par toutes les pages du projet.
2. App.xaml.h : fichier d’en-tête généré automatiquement par C++/WinRT, déclare la classe App et ses fonctions de cycle de vie : OnLaunched, OnActivated, etc.
3. App.xaml.cpp : implémentation de la logique du cycle de vie de l’application
   • OnLaunched : exécuté au lancement du programme, instancie et affiche la fenêtre MainWindow ;
   • Gestion de l’activation, de la suspension, du changement de thème et capture des exceptions ;
   • Toute logique d’initialisation globale (polices, bases de données, services singletons) s’écrit ici.

Ouvrez le fichier cpp, vous y trouverez ce code :

    void App::OnLaunched([[maybe_unused]] LaunchActivatedEventArgs const& e)
    {
        window = make();
        window.Activate();
    }

À partir d’ici, le programme passe à MainWindow. App est uniquement le point d’entrée, il ne crée pas de fenêtre. C’est MainWindow qui instancie la fenêtre visible, les contrôles et les boîtes de dialogue.

5. Ensemble MainWindow.xaml (fenêtre principale)

Fenêtre principale par défaut du programme, fenêtre racine visible de l’application de bureau, fenêtre de plus haut niveau.

1. MainWindow.xaml : mise en page de la fenêtre : boutons, zones de texte, contrôles de navigation, conteneur Frame pour les pages sont définis ici ;
2. MainWindow.idl : Fichier de définition d’interface IDL (cœur de C++/WinRT). Définit propriétés, méthodes et événements exposés par la fenêtre, utilisé pour le binding XAML, les appels inter-composants et la génération de métadonnées de type. Toute modification régénère automatiquement les fichiers colle .h/.cpp.
3. MainWindow.xaml.h : fichier d’en-tête de classe généré à partir de l’IDL et du XAML, contient les déclarations des membres de contrôles, constructeurs et gestionnaires d’événements.
4. MainWindow.xaml.cpp : logique métier de la fenêtre : gestion des clics de boutons, liaisons de données, navigation entre pages, interactions des contrôles.

Voici le contenu de MainWindow.xaml, fichier qui définit les contrôles et la mise en page :

<?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>

6. module.g.cpp

Fichier généré automatiquement pour le module global C++/WinRT (interdit toute modification manuelle)

• Génère le code d’enregistrement des types WinRT à partir de tous les fichiers .idl ;
• Fournit le point d’entrée de l’espace de noms winrt::App3::implementation, permettant au système de reconnaître les contrôles XAML et classes de fenêtre personnalisées ;
• Tout ajout ou suppression de fichier IDL déclenche une régénération automatique par Visual Studio.

7. Package.appxmanifest (Manifeste de paquet MSIX, fichier essentiel)

Fichier de configuration pour empaqueter une application de bureau au format MSIX. Double-cliquez dessus pour l’ouvrir dans l’éditeur visuel :

• Nom de l’application, version, éditeur, icônes, point de lancement ;
• Déclaration des autorisations système (accès fichiers, caméra, réseau, tâches en arrière-plan) ;
• Association des protocoles d’ouverture de fichiers, protocoles URL et extensions ;
• Configuration des informations de publication sur la boutique, raccourcis bureau, associations de fichiers. Différence avec app.manifest : celui-ci est le manifeste dédié au Microsoft Store et aux paquets MSIX, spécifique aux UWP et applications de bureau empaquetées.

On y configure par exemple les informations liées au Microsoft Store : version, nom du paquet, éditeur, etc. Ces données sont à récupérer sur le portail développeur du Microsoft Store.

8. packages.config

Fichier de configuration des paquets NuGet : enregistre la version de tous les paquets NuGet installés sur le projet, par exemple :

• Bibliothèques Microsoft.Windows.SDK.NET, Windows App SDK, C++/WinRT, WinUI 3 ;
• Lors d’un travail collaboratif ou sur un autre ordinateur, Visual Studio utilise ce fichier pour restaurer automatiquement toutes les dépendances.

9. pch.h/pch.cpp (En-têtes précompilés, accélération de la compilation C++)

pch = Precompiled Header (en-tête précompilé)

1. pch.h : regroupe tous les en-têtes communs du projet (winrt/Windows.*, Microsoft.UI.Xaml.*, bibliothèques standard). Chaque fichier cpp commence par #include "pch.h" ;
2. pch.cpp : fichier source de compilation des en-têtes précompilés. Son rôle : réduire massivement le temps de compilation en évitant de charger les mêmes en-têtes système dans chaque fichier.

Tous les includes communs sont regroupés dans ce fichier : les autres sources n’ont qu’à l’inclure, ce qui réduit le volume de code et accélère la compilation.

10. readme.txt

Document de livraison fourni par le modèle Visual Studio, il explique les bases de la compilation, l’empaquetage et le débogage des projets WinUI 3 en C++.

Les deux manifestes souvent confondus

1. app.manifest → Manifeste processus Win32 traditionnel (fenêtres, compatibilité système, autorisations)
2. Package.appxmanifest → Manifeste de paquet MSIX (boutique, installation, déclaration des fonctionnalités système)

Flux d’exécution global du projet

1. Lancement du programme → exécution de App::OnLaunched(App.xaml.cpp)
2. Création de l’instance MainWindow et activation de l’affichage : window = make(); window
   Previous: Installer WinUI en C++ et créer votre premier projet