Application WinUI

Utilisez cette compétence pour les travaux WinUI 3 et Windows App SDK nécessitant des conseils de configuration ancrés, un amorçage d'application, des décisions UX Windows modernes, ou des modèles d'implémentation concrets.

Flux Obligatoire

1. Classifiez la tâche comme environnement/configuration, amorçage de nouvelle application, conception, implémentation, examen ou dépannage.
2. Si la tâche concerne la préparation d'une machine pour WinUI, l'audit de disponibilité, ou la création d'une toute nouvelle application, commencez par le flux de configuration et d'échafaudage inclus dans cette compétence avant tout travail plus large de conception, implémentation ou dépannage :
   • Choisissez le nom de l'application quand la demande porte sur une nouvelle application.
   • Utilisez le nom exact que l'utilisateur a fourni quand il s'agit déjà d'un nom de dossier sûr.
   • Si l'utilisateur n'a pas donné de nom, dérivez un nom court en PascalCase de la demande et déclarez ce que vous avez choisi.
   • Créez le projet dans l'espace de travail actuel de l'utilisateur à moins qu'il n'ait demandé un autre emplacement.
   • N'utilisez pas --force à moins que l'utilisateur n'ait explicitement demandé de remplacer les fichiers existants.
   • Exécutez la configuration WinGet incluse à partir du répertoire de compétence pour que le chemin relatif reste exactement config.yaml :

winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity

• Traitez la configuration comme destinée à activer le Mode Développeur, installer ou mettre à jour Visual Studio Community 2026, et installer les composants C# Managed Desktop, Universal et Windows App SDK nécessaires au développement WinUI.
• Évaluez le résultat de la configuration avant de continuer. Continuez en cas de succès. En cas d'échec, inspectez la sortie au lieu de deviner. Si le modèle winui est déjà disponible et la chaîne d'outils utilisable, notez l'échec partiel et continuez. Si des prérequis manquent toujours, arrêtez et signalez clairement le blocage.
• Vérifiez que le modèle est disponible avant l'échafaudage :

dotnet new list winui

• Pour les demandes de diagnostic uniquement d'environnement, expliquez que l'amorçage inclus peut modifier la machine et obtenez une confirmation avant de l'exécuter. Si l'utilisateur refuse les modifications, utilisez les conseils de vérification manuelle dans references/foundation-environment-audit-and-remediation.md et résumez la disponibilité en present, missing, uncertain et recommended optional tools.
• Pour une toute nouvelle application, échafaudez avec dotnet new winui -o <name>. Ajoutez les options de modèle uniquement quand l'utilisateur les a demandées. Options supportées : -f|--framework net10.0|net9.0|net8.0, -slnx|--use-slnx, -cpm|--central-pkg-mgmt, -mvvm|--use-mvvm, -imt|--include-mvvm-toolkit, -un|--unpackaged, -nsf|--no-solution-file, --force. N'inventez pas de drapeaux non supportés. Si l'utilisateur demande un comportement empaqueté, passez --unpackaged false. Sinon conservez le défaut du modèle.
• Vérifiez un nouvel échafaudage en confirmant que le fichier projet attendu existe et en exécutant dotnet build contre le .csproj généré.
• Lancez une application nouvellement échafaudée à travers le chemin correct pour son modèle d'empaquetage réel et confirmez qu'il y a une véritable fenêtre de haut niveau au lieu de vous fier uniquement au code de sortie du processus de lancement.

3. Lisez references/_sections.md, puis chargez uniquement les fichiers de référence qui correspondent à la tâche.
4. Rendez le modèle d'empaquetage explicite avant de créer ou de refactoriser l'application. Privilégiez l'empaqueté pour les flux de travail de produit de type Store et les flux de déploiement/F5 de Visual Studio. Privilégiez l'non-empaqueté quand l'utilisateur s'attend à des boucles de génération et d'exécution répétables en ligne de commande ou à des lancements .exe directs après chaque modification.
5. Quand la tâche est un échec opaque du compilateur XAML comme MSB3073 ou XamlCompiler.exe, lisez references/foundation-template-first-recovery.md et simplifiez en retournant au modèle dotnet new winui actuel pour le modèle d'empaquetage choisi avant d'inventer une structure de récupération personnalisée.
6. Pour tout travail qui crée ou modifie une application WinUI, faites un ensemble d'éditions complet mais minimal, puis générez et exécutez l'application avant de répondre à l'utilisateur. Faites cela par défaut même quand l'utilisateur n'a pas explicitement demandé de vérification. Si une instance d'application en exécution verrouille la sortie alors que d'autres travaux restent, arrêtez-la, regénérez, relancez et continuez la vérification. Quand le travail est complet et que la vérification du lancement réussit, laissez l'instance d'application final vérifiée en exécution pour l'utilisateur à moins qu'il n'ait explicitement demandé le contraire.
7. Traitez la vérification du lancement comme incomplète jusqu'à ce que l'application affiche des signaux de succès objectifs comme une fenêtre de haut niveau réactive, un titre de fenêtre attendu, ou un autre comportement de démarrage clair. Un processus généré seul n'est pas suffisant.
8. Privilégiez Microsoft Learn pour les exigences, les attentes d'API et les conseils de plateforme.
9. Privilégiez WinUI Gallery pour l'utilisation concrète des contrôles, la composition shell et les détails de conception.
10. Privilégiez WindowsAppSDK-Samples pour les API au niveau du scénario comme le fenêtrage, le cycle de vie, les notifications, le déploiement et les contrôles personnalisés.
11. Développez vers les conseils WinUI et Fluent en premier. Traitez les shells WinUI natifs, les contrôles, les interactions et le chrome de contrôle comme le chemin d'implémentation par défaut.
12. Pour les surfaces de commande groupées comme les actions de document, la mise en forme d'éditeur, les bascules de vue, ou les barres d'outils au niveau de la page, privilégiez une CommandBar native ou une autre surface de commande standard WinUI avant de construire une ligne personnalisée avec Grid, StackPanel, Border, ou des regroupements de boutons ad hoc.
13. N'inventez pas de contrôles spécifiques à l'application, de bibliothèques de composants sur mesure, ou de chrome personnalisé pour remplacer le comportement standard de WinUI à moins que l'utilisateur n'ait explicitement demandé cette personnalisation, que le système de conception du produit existant ne l'exige déjà, ou qu'une lacune de plateforme vérifiée ne laisse aucune option native propre.
14. Quand la personnalisation est nécessaire, composez, modélez ou restylisez d'abord les contrôles WinUI intégrés et les ressources système avant d'ajouter des dépendances CommunityToolkit ou de créer un nouveau contrôle personnalisé.
15. Utilisez CommunityToolkit uniquement quand les contrôles WinUI intégrés ou les aides ne couvrent pas proprement le besoin.
16. Supportez le mode clair et sombre par défaut. Traitez la sortie de thème unique comme une exception qui nécessite une demande utilisateur explicite ou une contrainte de produit existante.
17. Utilisez les ressources conscientes du thème, les pinceaux système et les crochets de stylisation WinUI au lieu de couleurs codées en dur claires uniquement ou sombres uniquement lors de la création ou révision de l'UI.
18. Rendez la propriété de défilement explicite pour les dispositions de collection. Quand une page défile déjà verticalement, ne supposez pas qu'une GridView imbriquée ou une autre collection propriétaire du défilement affichera correctement une barre de posters horizontale.
19. N'ajoutez pas de wrappers Border supplémentaires autour de sections, de listes ou de cartes à moins que la bordure n'effectue un travail distinct que le contrôle contenu ou la surface parent ne fournisse déjà. Évitez les compositions « double-carte » où une Border de section enveloppe des éléments enfants qui s'affichent déjà sous forme de cartes.
20. Traitez la réactivité comme un problème shell-plus-page, pas seulement un problème de redimensionnement de contrôle. Planifiez un comportement explicite de largeur large, moyenne et téléphone pour la navigation, le remplissage, la densité de contenu et les régions pied/outils, et simplifiez ou masquez l'UI non essentielle au fur et à mesure que la largeur diminue.

Routes Courantes

Règles d'Environnement

• Ne devinez pas si la machine est prête pour le développement WinUI. Vérifiez-la.
• Utilisez le flux de configuration et d'échafaudage inclus dans cette compétence pour la configuration fraîche, la correction et l'échafaudage du premier projet au lieu de déléguer à une autre compétence.
• Traitez config.yaml dans le répertoire de cette compétence comme la source de vérité d'amorçage incluse.
• Traitez les signaux d'environnement incertains comme incertains, pas comme succès.
• Si la tâche est un audit uniquement et l'utilisateur refuse les modifications de machine, utilisez les conseils de vérification manuelle dans references/foundation-environment-audit-and-remediation.md et gardez les signaux incertains explicites au lieu d'impliquer le succès.
• Si config.yaml est manquant, dites-le clairement et revenez au flux officiel Microsoft au lieu de prétendre que le chemin inclus existe.
• Gardez la disponibilité de l'environnement, le choix d'empaquetage et la vérification du démarrage de l'application comme des contrôles distincts. Passer l'un ne prouve pas les autres.
• Échouez fermé sur les résultats de lancement ambigus. Si l'application ne s'est pas clairement ouverte, continuez le débogage.
• Après la création ou l'édition d'une application WinUI, ne vous arrêtez pas à une génération réussie. Lancez l'application, confirmez le comportement de démarrage objectif, et laissez l'instance d'application final vérifié en exécution avant de rendre le contrôle à l'utilisateur à moins qu'il ne vous dise explicitement de ne pas l'exécuter.

Règles de Référence

• Gardez C# comme chemin principal. Mentionnez C++ ou C++/WinRT uniquement quand la différence est matérielle.
• Préservez les conventions d'une base de code existante au lieu de forcer une structure d'exemple générique sur elle.
• Traitez les conseils de conception WinUI et les contrôles natifs comme la ligne de base. Ne dérivez pas vers des systèmes de composants sur mesure ou des remplaçants spécifiques à l'application pour les contrôles standard à moins que l'utilisateur n'en demande explicitement ou que la base de code existante n'en dépende déjà.
• Supportez le mode clair et sombre par défaut pour le travail de l'UI d'application à moins que l'utilisateur n'explicitement demande un résultat de thème unique ou que le produit en impose un.
• Privilégiez les contrôles WinUI intégrés et les crochets de stylisation système avant d'ajouter des dépendances CommunityToolkit, des contrôles personnalisés ou des systèmes de surface spécifiques à l'application.
• Placez les conseils détaillés de contrôle, thématisation, shell, défilement, réactivité, empaquetage et récupération dans les fichiers de référence correspondants au lieu de dupliquer ces règles ici.