CLI de Développement d'Applications Windows

Le CLI de Développement d'Applications Windows (winapp) est une interface de ligne de commande pour gérer les SDK Windows, l'empaquetage MSIX, générer l'identité d'application, les manifestes, les certificats, et utiliser les outils de compilation avec n'importe quel framework d'application. Il comble l'écart entre le développement multiplateforme et les capacités natives de Windows.

Quand Utiliser Cette Compétence

Utilisez cette compétence quand vous avez besoin de :

• Initialiser un projet d'application Windows avec configuration SDK, manifestes et certificats
• Créer des packages MSIX à partir de répertoires d'application
• Générer ou gérer des fichiers AppxManifest.xml
• Créer et installer des certificats de développement pour la signature
• Ajouter une identité de package pour déboguer les APIs Windows
• Signer des packages MSIX ou des exécutables
• Accéder aux outils de compilation du SDK Windows depuis n'importe quel framework
• Construire des applications Windows en utilisant des frameworks multiplateforme (Electron, Rust, Tauri, Qt)
• Configurer des pipelines CI/CD pour le déploiement d'applications Windows
• Accéder aux APIs Windows qui nécessitent une identité de package (notifications, Windows AI, intégration shell)
• Publier des applications sur le Microsoft Store via winapp store
• Créer des catalogues externes pour la gestion des actifs
• Configurer des projets .NET (csproj) avec le SDK Windows App via NuGet

Prérequis

• Windows 10 ou ultérieur
• CLI winapp installé via l'une de ces méthodes :
  • WinGet : winget install Microsoft.WinAppCli --source winget
  • NPM (pour Electron) : npm install @microsoft/winappcli --save-dev
  • GitHub Actions/Azure DevOps : Utilisez l'action setup-WinAppCli
  • Manuel : Téléchargez depuis GitHub Releases

Capacités Principales

1. Initialisation du Projet (winapp init)

Initialisez un répertoire avec les actifs requis (manifest, certificats, bibliothèques) pour construire une application Windows moderne. Supporte les modes d'installation SDK : stable, preview, experimental, ou none.

2. Empaquetage MSIX (winapp pack)

Créez des packages MSIX à partir de répertoires préparés avec signature optionnelle, génération de certificats, et empaquetage de déploiement autonome.

3. Identité de Package pour le Débogage (winapp create-debug-identity)

Ajoutez une identité de package temporaire aux exécutables pour déboguer les APIs Windows qui nécessitent une identité (notifications, Windows AI, intégration shell) sans empaquetage complet.

4. Gestion des Manifestes (winapp manifest)

Générez des fichiers AppxManifest.xml et mettez à jour les actifs image à partir d'images source, en créant automatiquement toutes les tailles et proportions requises. Supporte les placeholders de manifest pour du contenu dynamique et les noms qualifiés dans AppxManifest pour des définitions d'identité d'application flexibles.

5. Gestion des Certificats (winapp cert)

Générez des certificats de développement et installez-les dans le magasin local de la machine pour signer les packages.

6. Signature de Package (winapp sign)

Signez les packages MSIX et les exécutables avec des certificats PFX, avec support optionnel du serveur d'horodatage.

7. Accès aux Outils de Compilation du SDK (winapp tool)

Exécutez les outils de compilation du SDK Windows avec des chemins correctement configurés depuis n'importe quel framework ou système de compilation.

8. Intégration Microsoft Store (winapp store)

Exécutez les commandes du CLI Microsoft Store Developer directement depuis winapp, permettant la soumission au store, la validation de package, et les workflows de publication sans quitter le CLI.

9. Création de Catalogue Externe (winapp create-external-catalog)

Créez des catalogues externes pour rationaliser la gestion des actifs pour les développeurs, en séparant les données de catalogue du package principal.

Exemples d'Utilisation

Exemple 1 : Initialiser et Empaqueter une Application Windows

# Initialiser l'espace de travail avec les valeurs par défaut
winapp init
# Remarque : init ne génère plus automatiquement de certificat (v0.2.0+). Générez-en un explicitement :
winapp cert generate

# Construire votre application (spécifique au framework)
# ...

# Créer un package MSIX signé
winapp pack ./build-output --generate-cert --output MyApp.msix

Exemple 2 : Déboguer avec Identité de Package

# Ajouter une identité de débogage à l'exécutable pour tester les APIs Windows
winapp create-debug-identity ./bin/MyApp.exe

# Exécuter votre application - elle a maintenant une identité de package
./bin/MyApp.exe

Exemple 3 : Configuration du Pipeline CI/CD

# Exemple GitHub Actions
- name: Setup winapp CLI
  uses: microsoft/setup-WinAppCli@v1

- name: Initialize and Package
  run: |
    winapp init --no-prompt
    winapp pack ./build-output --output MyApp.msix

Exemple 4 : Intégration d'Application Electron

# Installer via npm
npm install @microsoft/winappcli --save-dev

# Initialiser et ajouter une identité de débogage pour Electron
npx winapp init
npx winapp node add-electron-debug-identity

# Empaqueter pour la distribution
npx winapp pack ./out --output MyElectronApp.msix

Recommandations

1. Exécutez winapp init en premier - Initialisez toujours votre projet avant d'utiliser d'autres commandes pour assurer la configuration SDK et manifest. Remarque : à partir de v0.2.0, winapp init ne génère plus de certificat de développement automatiquement. Exécutez winapp cert generate explicitement quand vous avez besoin de signer avec un certificat de développement.
2. Réexécutez create-debug-identity après les modifications de manifest - L'identité de package doit être recréée chaque fois que AppxManifest.xml est modifié.
3. Utilisez --no-prompt pour CI/CD - Prévient les invites interactives dans les pipelines automatisés en utilisant les valeurs par défaut.
4. Utilisez winapp restore pour les projets partagés - Recrée l'état exact de l'environnement défini dans winapp.yaml sur les machines.
5. Générez les actifs à partir d'une seule image - Utilisez winapp manifest update-assets avec un logo pour générer toutes les tailles d'icônes requises.

Modèles Communs

Modèle : Initialiser un Nouveau Projet

cd my-project
winapp init
# Crée : AppxManifest.xml, configuration SDK, winapp.yaml
# Remarque : les projets .NET (csproj) ignorent winapp.yaml et configurent les packages NuGet directement dans le .csproj

# Générer explicitement un certificat de signature de développement (plus fait par init)
winapp cert generate

Modèle : Empaqueter avec un Certificat Existant

winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix

Modèle : Déploiement Autonome

# Inclure le runtime du SDK Windows App avec le package
winapp pack ./my-app --self-contained --generate-cert

Modèle : Mettre à Jour les Versions de Package

# Mettre à jour vers les derniers SDKs stables
winapp update

# Ou mettre à jour vers les SDKs preview
winapp update --setup-sdks preview

Limitations

• Windows 10 ou ultérieur requis (CLI Windows uniquement)
• Le débogage d'identité de package nécessite de réexécuter create-debug-identity après toute modification de manifest
• Le déploiement autonome augmente la taille du package en incluant le runtime du SDK Windows App
• Les certificats de développement sont pour les tests uniquement ; la production nécessite des certificats de confiance
• Certaines APIs Windows nécessitent des déclarations de capacité spécifiques dans le manifest
• winapp init ne génère plus de certificat automatiquement (v0.2.0+) ; exécutez winapp cert generate explicitement
• Les projets .NET (csproj) ignorent winapp.yaml ; les packages SDK sont configurés directement dans le fichier projet
• Le CLI winapp utilise le cache global NuGet pour les packages (pas %userprofile%/.winapp/packages)
• Le CLI winapp est en préversion publique et sujet à changement

APIs Windows Activées par l'Identité de Package

L'identité de package déverrouille l'accès à des APIs Windows puissantes :

Dépannage

Références

• Dépôt GitHub
• Documentation CLI Complète
• Guide Projet .NET
• Exemples d'Applications
• SDK Windows App
• Aperçu de l'Empaquetage MSIX
• Aperçu de l'Identité de Package