Documentation et utilisation de l’interface CLI

Achèvement de l’interpréteur de commande

Activez la saisie semi-automatique de tabulation pour les commandes, les options et les valeurs. Consultez le guide de saisie semi-automatique de Shell pour obtenir des instructions de configuration.

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

Init

Initialisez un répertoire avec le Kit de développement logiciel (SDK) Windows, SDK d'application Windows et les ressources requises pour le développement Windows moderne.

winapp init [base-directory] [options]

Arguments :

base-directory - Répertoire de base/racine de l’application/espace de travail (par défaut : répertoire actif)

Options :

--config-dir <path> - Répertoire pour lire/stocker la configuration (par défaut : répertoire actif)
--setup-sdks - Mode d’installation du Kit de développement logiciel (SDK) : « stable » (valeur par défaut), « préversion », « expérimental » ou « none » (ignorer l’installation du SDK)
--ignore-config, - --no-config N’utilisez pas de fichier de configuration pour la gestion des versions
--no-gitignore - Ne mettez pas à jour le fichier .gitignore
--use-defaults, - --no-prompt Ne pas inviter et utiliser la valeur par défaut de toutes les invites
--config-only - Gérer uniquement les opérations de fichier de configuration, ignorer l’installation du package

Résultat :

Crée un winapp.yaml fichier de configuration (uniquement lorsque les packages du Kit de développement logiciel (SDK) sont gérés ; ignorés avec --setup-sdks none)
Télécharge les packages du Kit de développement logiciel (SDK) et de SDK d'application Windows
Génère des en-têtes C++/WinRT et des fichiers binaires
Crée Package.appxmanifest
Configure les outils de génération et active le mode développeur
Met à jour .gitignore pour exclure les fichiers générés
Stocke les fichiers partageables dans le répertoire global du cache

Détection automatique de projet .NET :

Lorsqu’un fichier .csproj se trouve dans le répertoire cible, init utilise un flux simplifié spécifique aux .NET :

Valide et met à jour le TargetFramework sur un TFM compatible avec Windows (par exemple, net10.0-windows10.0.26100.0)
Ajoute Microsoft.WindowsAppSDK et Microsoft.Windows.SDK.BuildTools en tant qu’entrées NuGet PackageReference directement dans le .csproj
Génère Package.appxmanifest, des ressources, et un certificat de développement
Ne crée pas ou ne télécharge winapp.yaml de projections C++ (utilisation dotnet restore pour les packages NuGet)

Exemples :

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

Conseil : Installer des kits SDK après l’installation initiale

Si vous avez exécuté init avec --setup-sdks none (ou ignoré l’installation du Kit de développement logiciel (SDK) et que vous avez besoin ultérieurement des kits SDK :

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init --use-defaults --setup-sdks stable

Utilisez --setup-sdks preview ou --setup-sdks experimental pour les versions préliminaires/expérimentales du Kit de développement logiciel (SDK) expérimental.

restore

Restaurez des packages et régénérez les fichiers en fonction de la configuration existante winapp.yaml .

winapp restore [options]

Options :

--config-dir <path> - Répertoire contenant winapp.yaml (valeur par défaut : répertoire actif)

Résultat :

Lit la configuration existante winapp.yaml
Téléchargements/mises à jour des packages sdk vers des versions spécifiées
Régénère les en-têtes C++/WinRT et les fichiers binaires
Stocke les fichiers partageables dans le répertoire global du cache

Note

Pour les projets .NET initialisés avec winapp init, il n’existe aucun winapp.yaml. Utilisez dotnet restore pour restaurer des packages NuGet.

Exemples :

# Restore from winapp.yaml in current directory
winapp restore

update

Mettez à jour les packages vers leurs dernières versions et mettez à jour le fichier de configuration.

winapp update [options]

Options :

--setup-sdks <stable|preview|experimental|none>- Mode d’installation du Kit de développement logiciel (SDK) : stable (par défaut), previewou experimentalnone (ignorer l’installation du Kit de développement logiciel (SDK)

Résultat :

Lit la configuration existante winapp.yaml dans le répertoire actif
Met à jour tous les packages vers leurs dernières versions disponibles
Met à jour le fichier avec les winapp.yaml nouveaux numéros de version
Régénère les en-têtes C++/WinRT et les fichiers binaires

Exemples :

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Créez des packages MSIX à partir de répertoires d’applications préparés. Nécessite un fichier manifeste (Package.appxmanifest préféré, appxmanifest.xml également pris en charge) à présenter dans le répertoire cible, dans le répertoire actif ou passé avec l’option --manifest . (exécuter init ou manifest generate créer un manifeste)

winapp pack <input-folder> [options]

Arguments :

input-folder - Répertoire contenant les fichiers d’application à empaqueter

Options :

--output <filename> - Nom de fichier MSIX de sortie (par défaut : <name>_<version>_<arch>.msix, revenir à <name>_<version>.msix, <name>_<arch>.msixou <name>.msix lorsque la version/arch ne peut pas être déterminée)
--name <name> - Nom du package (valeur par défaut : à partir du manifeste)
--manifest <path> - Chemin d’accès au fichier manifeste (Package.appxmanifest préféré, appxmanifest.xml également pris en charge ; par défaut : détection automatique)
--cert <path> - Chemin d’accès au certificat de signature (active la signature automatique)
--cert-password <password> - Mot de passe du certificat (par défaut : « mot de passe »)
--generate-cert - Générer un nouveau certificat de développement
--install-cert - Installer un certificat sur l’ordinateur
--publisher <name> - nom Publisher pour la génération de certificats
--self-contained - Runtime SDK d'application Windows groupé
--skip-pri - Ignorer la génération de fichiers PRI
--executable <path> - Chemin d’accès à l’exécutable par rapport au dossier d’entrée (également --exe). Permet de résoudre les espaces réservés $targetnametoken$ dans le manifeste.

Résultat :

Valide et traite les fichiers Package.appxmanifest
Résout les jetons $placeholder$ dans le manifeste (voir espaces réservés du manifeste ci-dessous)
Garantit les dépendances d’infrastructure appropriées
Met à jour des manifestes parallèles avec des enregistrements
Découvre automatiquement les composants WinRT tiers et inscrit leurs classes activables (voir découverte de composants WinRT ci-dessous)
Gère le déploiement WinAppSDK autonome
Signe le paquet si le certificat est fourni

Découverte de composants WinRT

Lors de l’empaquetage, winapp pack analyse automatiquement les packages NuGet définis dans les winapp.yaml*.csproj composants WinRT tiers (par exemple, Win2D). Il analyse les .winmd fichiers pour extraire les noms de classes activables et localiser leurs DLL d’implémentation. Les entrées découvertes sont inscrites comme suit :

Dépendant de l’infrastructure (par défaut) : les classes pouvant être activées sont ajoutées en tant qu’entrées <InProcessServer> dans le Package.appxmanifest
Autonome (--self-contained) : les classes activables sont incorporées dans des manifestes côte à côte (SxS) au sein de l’exécutable

Résolution d’espace réservé pendant l’empaquetage :

Si le manifeste contient $targetnametoken$ dans l’attribut Executable :

Si --executable elle est fournie (chemin d’accès relatif au dossier d’entrée), l’espace réservé est remplacé par la valeur spécifiée.
Dans le cas contraire, winapp pack analyse la racine du dossier d’entrée pour les .exe fichiers : si exactement un fichier est trouvé, il est utilisé automatiquement
Si zéro ou plusieurs .exe fichiers sont trouvés, une erreur s’affiche pour vous demander de spécifier --executable

Exemples :

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

create-debug-identity

Créez une identité d’application pour le débogage à l’aide d’un empaquetage partiellement alloué. L’exe reste dans son emplacement d’origine : Windows associe l’identité à celle-ci via Add-AppxPackage -ExternalLocation.

Quand utiliser ce fichier vs winapp run: utilisez create-debug-identity quand l’exe est distinct de votre code d’application (par exemple, applications Electron où electron.exe se trouve) node_modulesou lorsque vous testez spécifiquement le comportement du package éparse. Pour la plupart des frameworks où l’exe se trouve dans votre dossier de sortie de build, utilisez winapp run plutôt : il inscrit un package de disposition libre complet et lance l’application. Consultez le Guide de débogage pour obtenir une comparaison complète.

winapp create-debug-identity [entrypoint] [options]

Arguments :

entrypoint - Chemin d’accès à l’exécutable (.exe) ou script qui a besoin d’une identité

Options :

--manifest <path> - Chemin d’accès au fichier manifeste de l’application, soit Package.appxmanifestappxmanifest.xml (par défaut : détection Package.appxmanifest automatique ou appxmanifest.xml dans le répertoire actif)
--no-install - N’installez pas le package après la création
--keep-identity - Conservez l’identité du manifeste as-is, sans ajouter .debug le nom du package et l’ID d’application

Résultat :

Modifie le manifeste parallèle de l'exécutable
Enregistre le package clairsemé pour l'identité
Active le débogage des API nécessitant des identités

Exemples :

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

manifeste

Générez et gérez des fichiers Package.appxmanifest.

générer un manifeste

Générez Package.appxmanifest à partir de modèles.

winapp manifest generate [directory] [options]

Arguments :

directory - Répertoire dans lequel générer le manifeste (par défaut : répertoire actif)

Options :

--package-name <name> - Nom du package (par défaut : nom du dossier)
--publisher-name <name> - Publisher CN (par défaut : CN=<current user>)
--version <version> - Version (par défaut : « 1.0.0.0 »)
--description <text> - Description (valeur par défaut : « Mon application »)
--entrypoint <path> - Exécutable ou script du point d’entrée
--template <type> - Type de modèle : packaged (par défaut) ou sparse
--logo-path <path> - Chemin d’accès au fichier image de logo
--if-exists <Error|Overwrite|Skip> - Comportement lorsque le fichier manifeste existe déjà au niveau du chemin d’accès cible (par défaut : Error)

Modèles:

packaged - Manifeste d’application empaqueté standard
sparse - Manifest de l'application utilisant un empaquetage d'emplacements disséminés/externes

Espaces réservés de manifeste

Les manifestes générés utilisent des jetons $placeholder$ (délimités par un signe dollar) qui sont résolus automatiquement au moment de l’empaquetage :

Espace réservé	Résolu à	Exemple
$targetnametoken$	Nom exécutable sans extension	`Executable="$targetnametoken$.exe"` → `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Toujours résolu automatiquement

Cela suit la même convention utilisée par Visual Studio modèles de projet, de sorte que les manifestes sont portables entre les outils.

Comment les espaces réservés sont gérés :

winapp pack — Pendant l’empaquetage, $targetnametoken$ est résolu à l’aide de l’option --executable ou en détectant automatiquement le single .exe dans le dossier d’entrée. Si plusieurs fichiers (ou zéro) .exe sont trouvés et --executable ne sont pas spécifiés, une erreur s’affiche.
winapp create-debug-identity — Lorsqu’un argument de point d’entrée est fourni, $targetnametoken$ il est résolu à partir de celui-ci. Sans point d’entrée, l’espace réservé exécutable doit déjà être résolu dans le manifeste.
winapp manifest generate --executable — Lorsqu’elles --executable sont fournies, les métadonnées du manifeste (version, description) et les icônes sont extraites de l’exécutable, mais le manifeste généré utilise $targetnametoken$.exetoujours ; cet espace réservé est résolu ultérieurement (par exemple winapp pack , ou winapp create-debug-identity).

PS : Conserver $targetnametoken$ dans votre manifeste archivé évite les noms exécutables codés en dur et fonctionne avec les builds winapp pack et Visual Studio.

Exemples :

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

manifest add-alias

Ajoutez un alias d’exécution (uap5:AppExecutionAlias) à un Package.appxmanifest. Cela permet de lancer l’application empaquetée à partir de la ligne de commande en tapant le nom de l’alias.

winapp manifest add-alias [options]

Options :

--name <alias> - Nom d’alias (par exemple myapp.exe). Valeur par défaut : déduit de l’attribut Executable dans le manifeste.
--manifest <path> - Chemin d’accès à Package.appxmanifest (par défaut : rechercher dans le répertoire actif)
--app-id <id> - ID d’application pour ajouter l’alias à (par défaut : premier élément Application)

Résultat :

Lit le manifeste et déduit l’alias de l’attribut Executable (préservation des espaces réservés comme $targetnametoken$.exe)
Ajoute la déclaration d’espace de noms s’il n’est uap5 pas déjà présent
Ajoute un <Extensions> bloc avec <uap5:AppExecutionAlias> l’élément Application cible
Si l’alias existe déjà, le signale et se ferme correctement

Exemples :

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifeste mettre à jour les assets

Générez toutes les ressources d’image MSIX requises à partir d’une seule image source.

winapp manifest update-assets <image-path> [options]

Arguments :

image-path - Chemin d’accès au fichier image source (PNG, JPG, SVG, ICO, GIF, BMP, etc.)

Options :

--manifest <path> - Chemin d’accès au fichier Package.appxmanifest (par défaut : rechercher dans le répertoire actif)
--light-image <path> - Chemin d’une image source distincte pour les variantes de thème clair

Description:

Prend une image source unique et génère un ensemble complet de ressources d’image MSIX en fonction des références d’éléments multimédias du manifeste :

Pour chaque ressource référencée dans le manifeste :

5 variantes d’échelle — base (pas de suffixe), .scale-125, .scale-150, .scale-200, .scale-400

Pour l’icône d’application (Square44x44Logo / AppList, 44×44 base) :

14 cibles platesize de variantes — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
14 cibles nonplatéesizent des variantes — .targetsize-{size}_altform-unplated

De plus:

app.ico — Fichier ICO à résolution multiple (16, 24, 32, 48, 256) pour l’intégration de l’interpréteur de commandes. Si un fichier existant .ico se trouve dans le répertoire des ressources (par exemple, AppIcon.ico à partir d’un modèle de projet), il est remplacé sur place plutôt que de créer un doublon

Avec --light-image :

Thème clair cible les variantes — .targetsize-{size}_altform-lightunplated (icône d’application)
Variantes d’échelle de thème clair — .scale-{factor}_altform-colorful_theme-light (vignettes, logo de magasin)

Prise en charge SVG : Les fichiers SVG sont entièrement pris en charge en tant qu’images sources. Ils sont rendus en tant que vecteurs directement à chaque taille cible, produisant des résultats parfaits en pixels à toutes les résolutions.

La commande met à l’échelle les images proportionnellement tout en conservant les proportions, en les centreant avec des arrière-plans transparents si nécessaire. Les ressources sont enregistrées dans le répertoire Assets par rapport à l’emplacement du manifeste.

Exemples :

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

Courir

Créez un package de disposition libre à partir d’un dossier de sortie de build, inscrivez-le auprès de Windows à l’aide de l’API Windows.Management.Deployment.PackageManager et lancez l’application , en simulant une installation MSIX complète pour le débogage. Retourne l’ID de processus pour la pièce jointe du débogueur.

Cette commande est la commande préférée pour le débogage avec l’identité de package pour la plupart des frameworks (.NET, C++, Rust, Flutter, Tauri). Contrairement create-debug-identity à ce qui enregistre un package partiellement alloué pour un seul exe, winapp run inscrit l’intégralité du dossier en tant que package de disposition libre, tout comme une véritable installation MSIX. Consultez le Guide de débogage pour les flux de travail de débogage courants.

winapp run <input-folder> [options]

Arguments :

input-folder - Répertoire contenant l’application à exécuter (obligatoire)

Options :

--manifest <path> - Chemin d’accès à Package.appxmanifest (par défaut : détection automatique à partir du dossier d’entrée ou du répertoire actif)
--output-appx-directory <path> - Répertoire de sortie pour le package de disposition libre (valeur par défaut : AppX à l’intérieur du répertoire du dossier d’entrée)
--args <string> - Arguments de ligne de commande à passer à l’application. Vous pouvez également utiliser -- suivi d’arguments pour éviter l’échappement (par exemple). winapp run . -- --flag value
--no-launch - Créez uniquement l’identité de débogage et inscrivez le package sans lancer l’application.
--with-alias - Lancez l’application à l’aide de son alias d’exécution au lieu de l’activation AUMID. L’application s’exécute dans le terminal actuel avec stdin/stdout/stdout/stderr hérité. Nécessite un uap5:ExecutionAlias dans le manifeste (utiliser winapp manifest add-alias pour en ajouter un). Impossible de combiner avec --no-launch. Impossible de combiner avec --json.
--debug-output - Capturez les OutputDebugString messages et les exceptions de première chance de l’application lancée. Le bruit de l’infrastructure (WinUI, COM, DirectX) est filtré à partir de la sortie de la console ; le fichier journal complet capture tout. Si l’application se bloque, capture automatiquement un minidump et l’analyse pour afficher le type d’exception, le message et la trace de pile avec des numéros de ligne de fichier source (résolus à partir de fichiers PDB dans le dossier de sortie de build). Les incidents managés (.NET) sont analysés instantanément sans outils externes. Les blocages natifs (C++/WinRT) affichent les noms et les décalages des modules. Un seul débogueur peut s’attacher à un processus à la fois, de sorte que d’autres débogueurs (Visual Studio, VS Code) ne peuvent pas être utilisés simultanément. Utilisez --no-launch plutôt si vous devez attacher un autre débogueur. Impossible de combiner avec --no-launch. Impossible de combiner avec --json.
--symbols - Téléchargez des symboles PDB à partir de Microsoft Serveur de symboles pour une analyse de plantage native plus riche avec des noms de fonction résolus. Utilisé uniquement avec --debug-output. S’il est omis et qu’un incident natif se produit, la sortie suggère d’ajouter cet indicateur. La première exécution télécharge les symboles et les met en cache localement ; les exécutions suivantes utilisent le cache.
--unregister-on-exit - Annulez l’inscription du package de développement après la fermeture de l’application. Supprime uniquement les packages inscrits en mode de développement. Impossible de combiner avec --no-launch.
--detach - Lancez l’application et revenez immédiatement sans attendre qu’elle se termine. Utile pour l’automatisation/ci où vous devez interagir avec l’application après le lancement. Imprime le PID sur stdout (ou au format JSON avec --json). Impossible de combiner avec --no-launch, , --debug-output--with-aliasou --unregister-on-exit.
--clean - Supprimez les données d’application du package existant (LocalState, paramètres, etc.) avant le nouveau déploiement. Par défaut, les données d’application sont conservées entre les redéploiements.
--json - Mettre en forme la sortie au format JSON pour la consommation par programmation (par exemple, CI/automation). Utile pour --detach capturer le PID. Impossible de combiner avec --with-alias ou --debug-output.

Persistance des données d’application :

Par défaut, winapp run conserve les données de votre application (LocalState, RoamingState, Settingsetc.) lors du redéploiement. Si votre application écrit des données dans ApplicationData.Current.LocalFolder ou Environment.GetFolderPath(SpecialFolder.LocalApplicationData) dans le contexte du package, ces données survivent entre winapp run les appels.

Utilisez --clean quand vous avez besoin d’un nouveau démarrage (par exemple, pour réinitialiser l’état endommagé ou tester le comportement de première exécution).

Résultat :

Recherche ou génère package.appxmanifest
Crée et inscrit une identité de débogage à l’aide d’un package de disposition libre
Calcule l’ID de modèle utilisateur d’application (AUMID)
Lance l’application à l’aide de l’identité inscrite (sauf --no-launch indication contraire)
Imprime l’ID de processus (PID) pour la pièce jointe du débogueur

Exemples :

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Propriétés MSBuild (package NuGet) :

Lorsque vous utilisez le package NuGet Microsoft.Windows.SDK.BuildTools.WinApp, dotnet run appelle automatiquement winapp run. Les propriétés MSBuild suivantes peuvent être définies dans votre .csproj pour contrôler le comportement :

Propriété	Default	Description
`EnableWinAppRunSupport`	`true`	Activer/désactiver la fonctionnalité de prise en charge de l’exécution
`WinAppLaunchArgs`	(vide)	Arguments à transmettre à l’application lors du lancement
`WinAppRunUseExecutionAlias`	`false`	Lancer via un alias d’exécution au lieu de l’activation AUMID
`WinAppRunNoLaunch`	`false`	Inscrire uniquement l’identité sans lancer
`WinAppRunDebugOutput`	`false`	Capturez des `OutputDebugString` messages et des exceptions de première chance. Un seul débogueur peut s’attacher à la fois (empêche VS/VS Code). Utilisez `WinAppRunNoLaunch` plutôt pour attacher un autre débogueur.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Unregister

Annulez l’inscription d’un package de développement chargé de manière indépendante. Supprime uniquement les packages inscrits en mode de développement (par exemple, via winapp run ou create-debug-identity). Les packages installés dans le Magasin ou MSIX ne sont jamais supprimés.

winapp unregister [options]

Options :

--manifest <path> - Chemin d’accès à Package.appxmanifest (par défaut : détection automatique à partir du répertoire actif)
--force - Ignorez la vérification du répertoire d’emplacement d’installation et annulez l’inscription même si le package a été inscrit à partir d’une autre arborescence de projet
--json - Mettre en forme la sortie en tant que JSON

Résultat :

Lit le nom du package à partir du manifeste
Recherche les deux {name} et {name}.debug les packages (la variante de débogage est créée par create-debug-identity)
Vérifie que chaque package a été inscrit en mode de développement (IsDevelopmentMode == true)
Vérifie que l’emplacement d’installation du package se trouve sous l’arborescence du répertoire actif (sauf si --force)
Désinscrit les packages correspondants

Exemples :

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# JSON output for scripting
winapp unregister --json

cert

Générez, inspectez et installez des certificats de développement.

Générer un certificat

Générez des certificats de développement pour la signature de paquet.

winapp cert generate [options]

Options :

--manifest <Package.appxmanifest> - Extraire des informations de l’éditeur à partir de Package.appxmanifest
--publisher <name> - nom Publisher du certificat
--output <path> - Chemin d’accès au fichier de certificat de sortie (prend en charge les chemins absolus et relatifs)
--password <password> - Mot de passe du certificat (par défaut : « mot de passe »)
--valid-days <valid-days> - Nombre de jours pendant lesquels le certificat est valide (valeur par défaut : 365)
--install - Installer le certificat dans le magasin d’ordinateurs local après la génération
--if-exists <Error|Overwrite|Skip> - Définir le comportement si le fichier de certificat existe déjà (valeur par défaut : Erreur)
--export-cer - Exportez un .cer fichier (clé publique uniquement) en même temps que le .pfxfichier . Utile pour distribuer le certificat public séparément pour l’installation d’approbation.
--json - Mettre en forme la sortie au format JSON pour la consommation par programmation. Les erreurs sont également retournées en tant que JSON ({"error": "..."}).

Informations sur le certificat

Afficher les détails du certificat à partir d’un fichier PFX. Utile pour vérifier qu’un certificat correspond à votre manifeste avant la signature.

winapp cert info <cert-path> [options]

Arguments :

cert-path - Chemin d’accès au fichier de certificat (PFX)

Options :

--password <password> - Mot de passe pour le fichier PFX (par défaut : « mot de passe »)
--json - Mettre en forme la sortie en tant que JSON

Installation du certificat

Installez le certificat dans le magasin de certificats de l’ordinateur.

winapp cert install <cert-path> [options]

Arguments :

cert-path - Chemin d’accès au fichier de certificat à installer

Exemples :

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

Signe

Signer des packages MSIX et des exécutables avec des certificats.

winapp sign <file-path> [options]

Arguments :

file-path - Chemin d’accès au package MSIX ou exécutable à signer

Options :

--cert <path> - Chemin d’accès au certificat de signature
--cert-password <password> - Mot de passe du certificat (par défaut : « mot de passe »)

Exemples :

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

create-external-catalog

Générez un CodeIntegrityExternal.cat fichier catalogue contenant des hachages de fichiers exécutables à partir de répertoires spécifiés. Ce catalogue est utilisé avec l’indicateur TrustedLaunch dans les manifestes de package partiellement alloués MSIX (AllowExternalContent) pour autoriser l’exécution de fichiers externes non inclus dans le package lui-même.

Cela est similaire à la façon de signtool.exe créer AppxMetadata\CodeIntegrity.cat lors de la signature d’un package MSIX, mais génère un catalogue externe à utiliser avec l’empaquetage d’emplacement éparse/externe.

winapp create-external-catalog <input-folder> [options]

Arguments :

input-folder - Un ou plusieurs répertoires contenant des fichiers exécutables à traiter. Séparer plusieurs répertoires avec des points-virgules (par exemple, "dir1;dir2")

Options :

--recursive, - -r Inclure des fichiers à partir de sous-répertoires
--use-page-hashes - Inclure des hachages de page lors de la génération du catalogue (produit un catalogue plus grand avec des données de hachage par page)
--compute-flat-hashes - Inclure des hachages de fichiers plats lors de la génération du catalogue
--if-exists <Error|Overwrite|Skip> - Comportement lorsque le fichier de sortie existe déjà (valeur par défaut : Error)
--output, -o - Chemin d’accès du fichier catalogue de sortie. S’il n’est pas spécifié, CodeIntegrityExternal.cat est créé dans le répertoire actif. Si un répertoire est spécifié, le nom de fichier par défaut est ajouté.

Résultat :

Analyse les répertoires spécifiés pour les fichiers exécutables (fichiers binaires PE avec sections de code)
Génère un fichier de définition de catalogue (CDF) avec des hachages de tous les exécutables trouvés
Utilise Windows API CryptoCAT pour produire le fichier catalogue .cat
Les fichiers non exécutables (par exemple, .txt.dll sans sections de code) sont automatiquement ignorés

Exemples :

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Quand utiliser :

Utilisez cette commande lors de la création d’un package MSIX partiellement alloué qui utilise TrustedLaunch pour vérifier les exécutables externes. Le flux de travail classique est le suivant :

winapp manifest generate --template sparse — Créer un manifeste partiellement alloué avec AllowExternalContent
winapp create-external-catalog ./bin — Générer le catalogue d’intégrité du code pour les exécutables de votre application
winapp pack — Empaqueter le manifeste, les ressources et le catalogue dans un fichier MSIX

Outil

Accédez directement aux outils du Kit de Développement Logiciel (SDK) Windows. Utilise les outils disponibles dans Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Outils disponibles :

makeappx - Créer et manipuler des packages d’application
signtool - Signer des fichiers et vérifier les signatures
mt - Outil manifeste pour les assemblages côte-à-côte
Et d’autres outils Windows SDK de Microsoft.Windows. SDK. BuildTools

Exemples :

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

store

Exécutez une commande CLI développeur du Microsoft Store. Cette commande télécharge l’interface CLI Microsoft Store développeur si elle n’est pas déjà téléchargée. En savoir plus sur l’interface CLI Microsoft Store Developer CLI.

winapp store [args...]

Arguments :

args... : arguments à passer directement à l’interface msstore CLI. Consultez la documentation de l’interface CLI MSStore pour connaître les commandes et options disponibles.

Résultat :

Vérifie que l’interface CLI Microsoft Store Développeur (msstore) est téléchargée et disponible sur votre système.
Transfère tous les arguments à l’interface msstore CLI.
Exécute la commande montrant la sortie directement dans votre terminal.

Exemples :

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Obtenir les chemins d’accès aux composants du Kit de développement logiciel (SDK) Windows installés.

winapp get-winapp-path [options]

Ce qu’il retourne :

Chemins d’accès au répertoire de l’espace .winapp de travail
Répertoires d’installation de package
Emplacements d’en-tête générés

node create-addon

(Disponible uniquement dans le package NPM) Générer des modèles de complément C++ ou C# natifs avec Windows SDK et l’intégration SDK d'application Windows.

npx winapp node create-addon [options]

Options :

--name <name> - Nom du module complémentaire (valeur par défaut : « nativeWindowsAddon »)
--template - Sélectionnez le type de module complémentaire. Les options sont cs ou cpp (par défaut : cpp)
--verbose - Activer la sortie détaillée

Résultat :

Crée un répertoire d'extension avec des fichiers de modèle
Génère binding.gyp et addon.cc avec des exemples de sdk Windows
Installe les dépendances npm requises (nan, node-addon-api, node-gyp)
Ajoute un script de génération à package.json

Exemples :

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

node add-electron-debug-identity

(Disponible dans le package NPM uniquement) Ajoutez l’identité d’application au processus de développement Electron à l’aide d’un empaquetage partiellement alloué. Nécessite un Package.appxmanifest (créez-en un avec winapp init ou winapp manifest generate si vous n’en avez pas).

Important

Il existe un problème connu lié à l’empaquetage d’applications Electron éparses qui provoquent le blocage de l’application au démarrage ou non au rendu du contenu web. Le problème a été résolu dans Windows, mais il n’a pas encore été propagé aux appareils Windows externes. Si vous voyez ce problème après l’appel add-electron-debug-identity, vous pouvez désactiver le bac à sable dans votre application Electron à des fins de débogage avec l’indicateur --no-sandbox . Ce problème n’affecte pas l’empaquetage MSIX complet.

Pour supprimer l'identité de débogage d'Electron, utilisez winapp node clear-electron-debug-identity.

npx winapp node add-electron-debug-identity [options]

Options :

Choix	Description
`--manifest <path>`	Chemin d’accès à Package.appxmanifest personnalisé (par défaut : Package.appxmanifest dans le répertoire actif)
`--no-install`	N'installez pas ou ne modifiez pas les dépendances ; ne configurez que l'identité de débogage d'Electron
`--keep-identity`	Conservez l’identité du manifeste as-is, sans ajouter `.debug` le nom du package et l’ID d’application
`--verbose`	Activer la sortie détaillée

Résultat :

Inscrit l’identité de débogage pour electron.exe processus
Permet de tester les API nécessitant des identités dans le développement Electron
Utilise package.appxmanifest existant pour la configuration des identités

Exemples :

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node effacer-Électron-débogage-identité

(Disponible dans le package NPM uniquement) Supprimez l’identité du package du processus de débogage Electron en restaurant le electron.exe d’origine de la sauvegarde.

npx winapp node clear-electron-debug-identity [options]

Options :

Choix	Description
`--verbose`	Activer la sortie détaillée

Résultat :

Restaure electron.exe à partir de la sauvegarde créée par add-electron-debug-identity
Supprime les fichiers de sauvegarde après la restauration
Retourne Electron à son état d’origine sans identité de package

Exemples :

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Options globales

Toutes les commandes prennent en charge ces options globales :

--verbose, -v - Activer la sortie détaillée pour la journalisation détaillée
--quiet, - -q Supprimer les messages de progression
--help, -h - Afficher l’aide de la commande

Répertoire global du cache

Winapp crée un répertoire pour mettre en cache des fichiers qui peuvent être partagés entre plusieurs projets.

Par défaut, winapp crée un répertoire dans $UserProfile/.winapp le répertoire global du cache.

Pour utiliser un autre emplacement, définissez la variable d’environnement WINAPP_CLI_CACHE_DIRECTORY .

En cmd :

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Dans PowerShell et pwsh :

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Winapp crée automatiquement ce répertoire lorsque vous exécutez des commandes telles que init ou restore.

ui

Inspectez et interagissez avec les interfaces utilisateur d’application Windows en cours d’exécution à l’aide de UI Automation (UIA).

winapp ui [command] [options]

Commandes:

status - Se connecter à l’application et afficher les informations
inspect - Arborescence des éléments View
search - Rechercher des éléments par sélecteur
get-property - Lire les propriétés de l’élément
get-text / get-value - Lire la valeur/le texte à partir de l’élément (TextPattern, ValuePattern ou Name)
screenshot - Capturer la fenêtre/l’élément en png (boîtes de dialogue capture automatiquement séparément)
invoke - Activer l’élément (cliquez, basculez, développez)
click - Cliquer sur un élément via la simulation de souris (pour les contrôles qui ne prennent pas en charge l’appel)
set-value - Définir la valeur sur l’élément modifiable (texte, nombre)
focus - Déplacer le focus clavier
scroll-into-view - Élément Scroll visible
wait-for - Attendre l’état de l’élément
list-windows - Répertorier toutes les fenêtres d’une application
get-focused - Signaler l’élément actuellement axé

Options :

-a, --app <app> - Application cible (nom, titre ou PID)
-w, --window <hwnd> - Fenêtre cible par HWND (stable)

Pour obtenir une documentation complète, consultez docs/ui-automation.md.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-12

Documentation et utilisation de l’interface CLI

Achèvement de l’interpréteur de commande

Init

restore

update

pack

Découverte de composants WinRT

create-debug-identity

manifeste

générer un manifeste

Espaces réservés de manifeste

manifest add-alias

manifeste mettre à jour les assets

Courir

Unregister

cert

Générer un certificat

Informations sur le certificat

Installation du certificat

Signe

create-external-catalog

Outil

store

get-winapp-path

node create-addon

node add-electron-debug-identity

node effacer-Électron-débogage-identité

Options globales

Répertoire global du cache

ui

Commentaires

Ressources supplémentaires