Application WinUI

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

Flux requis

1. Classifie la tâche comme environnement/setup, amorçage de nouvelle app, design, implémentation, révision ou dépannage.
2. Si la tâche porte sur la préparation d'une machine pour WinUI, l'audit de la disponibilité, ou la création d'une toute nouvelle app, commence par le flux setup-and-scaffold intégré dans cette compétence avant tout travail plus large de design, implémentation ou dépannage :
   • Choisis le nom de l'app quand la demande concerne une nouvelle app.
   • Utilise le nom exact que l'utilisateur a fourni s'il s'agit déjà d'un nom de dossier sûr.
   • Si l'utilisateur n'a pas donné de nom, dérive un nom court en PascalCase à partir de la demande et indique ce que tu as choisi.
   • Crée le projet dans l'espace de travail actuel de l'utilisateur sauf s'il a demandé un autre emplacement.
   • N'utilise pas --force sauf si l'utilisateur l'a explicitement demandé pour écraser les fichiers existants.
   • Exécute la configuration WinGet intégrée à partir du répertoire de la compétence afin que le chemin relatif reste exactement config.yaml :

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

• Traite la configuration comme étant destinée à activer Developer Mode, 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.
• Évalue le résultat de la configuration avant de continuer. Continue en cas de succès. En cas d'échec, inspecte la sortie au lieu de deviner. Si le modèle winui est déjà disponible et la chaîne d'outils utilisable, note l'échec partiel et continue. Si des prérequis manquent encore, arrête-toi et rapporte clairement le bloqueur.
• Vérifie que le modèle est disponible avant l'échafaudage :

dotnet new list winui

• Pour les demandes d'environnement diagnostiques uniquement, explique que l'amorçage intégré peut modifier la machine et obtiens une confirmation avant de l'exécuter. Si l'utilisateur refuse les changements, utilise les conseils de vérification manuelle dans references/foundation-environment-audit-and-remediation.md et résume la disponibilité sous present, missing, uncertain, et recommended optional tools.
• Pour une toute nouvelle app, échafaude avec dotnet new winui -o <name>. Ajoute les options de modèle uniquement si 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'invente pas de drapeaux non supportés. Si l'utilisateur demande un comportement packagé, passe --unpackaged false. Sinon, conserve la valeur par défaut du modèle.
• Vérifie un nouvel échafaudage en confirmant que le fichier projet attendu existe et en exécutant dotnet build contre le .csproj généré.
• Lance une app nouvellement échafaudée via le chemin correct pour son modèle de packaging réel et confirme qu'il y a une vraie fenêtre de niveau supérieur au lieu de te fier uniquement au code de sortie du processus de lancement.

3. Lis references/_sections.md, puis charge uniquement les fichiers de référence qui correspondent à la tâche.
4. Rends le modèle de packaging explicite avant de créer ou refactoriser l'app. Défaut packagé pour les workflows de produit de type Store et les flux de déploiement/F5 de Visual Studio. Défaut unpackagé quand l'utilisateur s'attend à des boucles CLI build-and-run répétables ou des lancements .exe directs après chaque changement.
5. Quand la tâche est un échec opaque du compilateur XAML comme MSB3073 ou XamlCompiler.exe, lis references/foundation-template-first-recovery.md et simplifie en revenant vers l'échafaudage dotnet new winui actuel pour le modèle de packaging choisi avant d'inventer une structure de récupération personnalisée.
6. Pour tout travail qui crée ou modifie une app WinUI, fais un ensemble de modifications complet mais minimaliste, puis construis l'app et lance-la avant de répondre à l'utilisateur. Fais cela par défaut même quand l'utilisateur n'a pas explicitement demandé la vérification. Si une instance d'app en cours d'exécution verrouille la sortie tandis que d'autres travaux restent, arrête-la, reconstruit, relance et continue la vérification. Quand le travail est terminé et que la vérification de lancement réussit, laisse l'instance d'app finale vérifiée en cours d'exécution pour l'utilisateur sauf s'il t'a explicitement demandé de ne pas le faire.
7. Traite la vérification de lancement comme incomplète jusqu'à ce que l'app montre des signaux de succès objectifs tels qu'une fenêtre de niveau supérieur réactive, le titre de fenêtre attendu, ou autre comportement de démarrage clair. Un processus généré par lui-même n'est pas suffisant.
8. Privilégie Microsoft Learn pour les exigences, les attentes d'API et les conseils de plateforme.
9. Privilégie WinUI Gallery pour l'utilisation concrète des contrôles, la composition de shell et les détails de design.
10. Privilégie WindowsAppSDK-Samples pour les API au niveau des scénarios telles que le windowing, le cycle de vie, les notifications, le déploiement et les contrôles personnalisés.
11. Construis vers la guidance WinUI et Fluent en premier. Traite les shells, contrôles, interactions et chrome de contrôle natifs WinUI comme le chemin d'implémentation par défaut.
12. Pour les surfaces de commande groupées telles que les actions de document, le formatage d'éditeur, les bascules de vue, ou les barres d'outils au niveau de la page, favorise un CommandBar natif ou une autre surface de commande stock WinUI avant de construire une ligne personnalisée avec Grid, StackPanel, Border, ou des groupements de boutons ad hoc.
13. N'invente pas de contrôles spécifiques à l'app, de bibliothèques de composants bespoke, ou de chrome personnalisé pour remplacer le comportement stock WinUI sauf si l'utilisateur demande explicitement cette personnalisation, le système de design de produit existant l'exige déjà, ou un gap de plateforme vérifié laisse aucune option native propre.
14. Quand la personnalisation est nécessaire, compose d'abord, modèle ou restyse 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. Utilise CommunityToolkit uniquement quand les contrôles WinUI intégrés ou les assistants ne couvrent pas le besoin proprement.
16. Supporte le mode clair et sombre par défaut. Traite la sortie à thème unique comme une exception qui requiert une demande utilisateur explicite ou une contrainte de produit existante.
17. Utilise les ressources conscientes du thème, les pinceaux système et les crochets de style WinUI au lieu de couleurs codées en dur claires uniquement ou sombres uniquement quand tu construis ou révises l'UI.
18. Rends la propriété du défilement explicite pour les mises en page de collection. Quand une page défile déjà verticalement, n'assume pas qu'un GridView imbriqué ou une autre collection possédant le défilement rendra toujours correctement un rail d'affiche horizontal.
19. N'ajoute pas d'enveloppes Border supplémentaires autour de sections, listes ou cartes sauf si la bordure effectue un travail distinct que le contrôle contenu ou la surface parent ne fournit pas déjà. Évite les compositions "double-carte" où une Border de section enveloppe les éléments enfants qui se rendent déjà sous forme de cartes.
20. Traite la réactivité comme un problème shell-plus-page, pas seulement un problème de redimensionnement de contrôle. Planifie un comportement explicite de largeur large, moyenne et téléphone pour la navigation, le remplissage, la densité de contenu et les régions de pied de page/outil, et simplifie ou masque l'UI non essentielle quand la largeur diminue.

Routes courantes

Règles d'environnement

• Ne devinez pas si la machine est prête pour le développement WinUI. Vérifie-le.
• Utilise le flux setup-and-scaffold intégré dans cette compétence pour la configuration initiale, la correction et l'échafaudage du premier projet au lieu de déléguer à une autre compétence.
• Traite config.yaml dans le répertoire de cette compétence comme la source de vérité du bootstrap intégré.
• Traite les signaux d'environnement incertains comme incertains, pas comme un succès.
• Si la tâche est un audit uniquement et l'utilisateur refuse les changements de machine, utilise les conseils de vérification manuelle dans references/foundation-environment-audit-and-remediation.md et garde les signaux incertains explicites au lieu d'impliquer le succès.
• Si config.yaml manque, dis-le clairement et reviens au workflow officiel de Microsoft au lieu de prétendre que le chemin intégré existe.
• Garde la disponibilité d'environnement, le choix de packaging et la vérification de démarrage d'application comme des vérifications séparées. Passer l'une ne prouve pas les autres.
• Échoue fermé sur des résultats de lancement ambigus. Si l'app ne s'est pas clairement ouverte, continue le débogage.
• Après avoir créé ou modifié une app WinUI, ne t'arrête pas à une construction réussie. Lance l'app, confirme le comportement de démarrage objectif et laisse l'instance d'app finale vérifiée en cours d'exécution avant de rendre le contrôle à l'utilisateur sauf s'il dit explicitement de ne pas la lancer.

Règles de référence

• Garde C# comme chemin principal. Mentionne C++ ou C++/WinRT uniquement quand la différence est matérielle.
• Préserve les conventions d'une base de code existante au lieu de forcer une structure d'exemple générique sur elle.
• Traite la guidance de design WinUI et les contrôles natifs comme la base de référence. Ne dérive pas vers des systèmes de composants bespoke ou des remplacements d'app spécifiques pour les contrôles standard sauf si l'utilisateur demande explicitement ou la base de code existante en dépend déjà.
• Supporte le mode clair et sombre par défaut pour le travail de l'UI de l'app sauf si l'utilisateur demande explicitement un résultat à thème unique ou le produit en impose déjà un.
• Favorise les contrôles WinUI intégrés et les crochets de style système avant d'ajouter des dépendances CommunityToolkit, des contrôles personnalisés ou des systèmes de surface spécifiques à l'app.
• Mets les conseils détaillés sur les contrôles, le thématique, le shell, le défilement, la réactivité, le packaging et la récupération dans les fichiers de référence correspondants au lieu de dupliquer ces règles ici.