Débogage avec l’identité de package

De nombreuses API Windows (notifications Push, tâches en arrière-plan, cible de partage, tâches de démarrage, Windows API IA) nécessitent que votre application dispose d’une identité package. Pendant le développement, vous ne souhaitez pas créer un programme d’installation MSIX complet chaque fois que vous testez : winapp fournit deux commandes pour donner à votre application l’identité de votre application à la volée.

Utilisation de Visual Studio avec un projet d’empaquetage ? Si vous utilisez déjà Visual Studio pour votre projet empaqueté, vous n'avez probablement pas besoin de winapp pour le débogage. Visual Studio gère déjà l'enregistrement du package, l'identité, l'activation AUMID, l'attachement du débogueur et le débogage du code d'activation, le tout depuis F5. Il offre également Déboguer → Autres cibles de débogage → Déboguer le package d’application installé pour les scénarios avancés. Les flux de travail ci-dessous sont les plus utiles pour les utilisateurs de VS Code, les workflows basés sur les terminaux et les frameworks que VS ne package pas en mode natif (Rust, Flutter, Tauri, Electron, plain C++).

Deux approches : `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
Ce qu'il enregistre	Package de disposition libre complet (dossier entier)	Package éparse (single exe)
Lancement de l’application	Lancé par winapp (activation AUMID ou alias d’exécution)	Vous lancez l’exe vous-même (ligne de commande, IDE, etc.)
Simule l’installation de MSIX	Oui : plus proche du comportement de production	Non — Identité éparse uniquement
Les fichiers restent en place	Copié dans un répertoire de mise en page AppX	Oui — exe reste à son chemin d’origine
Étendue de l’identité	Contenu complet du dossier (exe, DLL, ressources)	Exécutable unique
Débogueur facile à utiliser	Attacher au PID après le lancement, ou utiliser `--no-launch` puis lancer via un alias	Lancez directement à partir du débogueur de votre IDE : l’exe conserve son identité dans tous les cas.
Prise en charge des applications console	`--with-alias` maintient stdin/stdout dans le terminal	Exécuter exe directement dans le terminal
Idéal pour	La plupart des frameworks (.NET, C++, Rust, Flutter, Tauri)	Electron, ou lorsque vous devez exercer un contrôle complet du débogueur IDE (F5)

Quand utiliser lequel

Valeur par défaut : `winapp run`

Utilisez winapp run dans la plupart des flux de travail de développement. Il simule une véritable installation MSIX : votre application obtient les mêmes identités, fonctionnalités et associations de fichiers qu’elle aurait en production.

# Build your app, then:
winapp run .\build\output

Utilisez `create-debug-identity` quand :

Votre exe est séparé de votre sortie de build — par exemple, dans les applications Electron où electron.exe se trouve dans node_modules/
Vous devez déboguer le code de démarrage et ne pouvez pas attacher suffisamment rapidement un débogueur après le lancement d’AUMID
Avec certains débogueurs où vous ne pouvez pas lancer avec AUMID et que vous avez besoin d'une identité pour le processus lancé, create-debug-identity enregistre l'exe afin qu'il dispose d'une identité, peu importe comment il est lancé.
Vous testez spécifiquement le comportement du package sparse (AllowExternalContent, TrustedLaunch)

# Register identity for an exe, then launch it however you want:
winapp create-debug-identity .\bin\Debug\myapp.exe
.\bin\Debug\myapp.exe   # or F5 in your IDE

Scénarios de débogage

Scénario A : Exécutez uniquement avec l'identité

Flux de travail le plus simple : générer, exécuter avec l’identité, terminé.

winapp run .\build\Debug

Winapp inscrit le dossier en tant que package de disposition libre et lance l’application. Les API nécessitant une identité fonctionnent immédiatement. Cela couvre la majorité des scénarios de développement et de test.

Pour les applications console qui ont besoin de stdin/stdout dans le terminal actuel, ajoutez --with-alias:

winapp run .\build\Debug --with-alias

Scénario B : Attacher un débogueur à une application en cours d’exécution

Lancez avec winapp run, notez le PID, puis attachez le débogueur de votre IDE.

winapp run .\build\Debug
# Output: Process ID: 12345

Ensuite, dans votre IDE :

VS Code : Exécuter et déboguer → sélectionner la configuration « Attacher » (voir configuration de l’IDE ci-dessous)
WinDbg : windbg -p 12345

Limitation: Vous manquerez tout code qui s’exécute avant d’attacher. Pour le débogage de démarrage, utilisez le scénario D (create-debug-identity).

Scénario C : Inscrire l’identité, puis lancer via AUMID ou alias à partir de votre IDE

Utilisez --no-launch pour inscrire le package, puis lancez l'application via son AUMID (signalé par run) ou son alias d'exécution à partir de votre IDE.

Étape 1 : Inscrivez le package sans lancer :

winapp run .\build\Debug --no-launch

Étape 2 : Configurez votre IDE pour lancer via l’AUMID ou l’alias d’exécution (pas directement l’exe).

Lancement avec AUMID : Utilisez la commande start shell:AppsFolder\<AUMID>. winapp run affiche l’AUMID lorsque l’application est enregistrée.
Lancement avec l’alias : l’alias doit être défini dans votre manifeste (Package.appxmanifest préféré, appxmanifest.xml également pris en charge).

Important: Le simple lancement de l’exe dans le dossier de build ne lui donnera pas d’identité. L’application doit être démarrée via l’activation AUMID ou son alias d’exécution. C’est ainsi que fonctionnent les packages de disposition libre : l’identité est liée au chemin d’activation, et non au fichier exe.

Scénario D : Lancer à partir de votre IDE avec l’identité (débogage de démarrage)

Il s’agit de la meilleure approche pour le débogage du code de démarrage avec un contrôle IDE complet : le débogueur de votre IDE contrôle le processus à partir de la première instruction, et l’exe a une identité quelle que soit la façon dont elle est lancée.

winapp create-debug-identity .\build\Debug\myapp.exe

Lancez maintenant l’exe comme vous le souhaitez , à partir du terminal, à partir du F5 de VS Code, à partir d’un script. L’exe a une identité car Windows a enregistré un package sparse pointant directement dessus.

Comment il diffère de winapp run: Avec create-debug-identity, l’identité est liée à l’exe lui-même (via Add-AppxPackage -ExternalLocation). Avec winapp run, l’identité est associée au package de mise en page souple : l’application doit être lancée par AUMID ou un alias. Cela rend create-debug-identity le meilleur choix lorsque vous avez besoin de votre IDE pour lancer et déboguer l’exe directement.

Il s’agit également de la meilleure approche pour les applications Electron où le chemin d’accès exe diffère de votre répertoire source.

Scénario E : Capturer la sortie du débogage et les diagnostics de panne

Capturez les OutputDebugString messages et les exceptions de première chance directement. Le bruit de l’infrastructure (WinUI, COM, les traces internes de DirectX) est filtré depuis la console afin que seuls les messages de débogage de votre application apparaissent. Tout est systématiquement écrit dans le fichier journal pour une analyse complète.

Si l’application se bloque, un minidump est capturé et analysé automatiquement :

winapp run .\build\Debug --debug-output

En cas de plantage, le résultat inclut le type d’exception, le message et le traçage de pile avec le fichier source et les numéros de ligne (résolus à partir de fichiers PDB dans votre 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 de module et les décalages ; ajoutez --symbols pour télécharger les symboles PDB et obtenir les noms complets des fonctions.

winapp run .\build\Debug --debug-output --symbols

Important: Cela attache winapp en tant que débogueur. Windows autorise uniquement un débogueur par processus. Vous ne pouvez donc pas également attacher Visual Studio, VS Code ou WinDbg.

Configuration de l’IDE

VS Code

L’extension VS Code WinApp fournit un type de débogage personnaliséwinapp qui lance votre application avec l’identité du package et attache le débogueur , tous à partir d’une seule pression F5.

Appuyez sur la touche F5 pour un débogage d'une seule frappe avec l'identité

Ajoutez une winapp configuration de lancement à .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "winapp",
            "request": "launch",
            "name": "WinApp: Launch and Attach"
        }
    ]
}

Lorsque vous appuyez sur F5 :

L’extension analyse votre espace de travail pour rechercher des répertoires de sortie de build contenant des .exe fichiers.
Vous sélectionnez le dossier de build à exécuter (ou définissez inputFolder pour ignorer l’invite).
Il lance votre application via winapp run pour lui donner une identité de package.
Une session de débogage enfant s’attache au processus en cours d’exécution à l’aide du débogueur que vous avez spécifié.

Une fois que le débogueur s'attache, vous bénéficiez de l’interface de débogage complète de VS Code : définissez des points d’arrêt en cliquant sur la marge, exécutez le code ligne par ligne (F10), entrez dans les fonctions (F11), inspectez les variables dans le volet Variables et évaluez les expressions dans la Console de débogage. L’application s’exécute avec une identité de package dans l’ensemble, de sorte que les API dépendantes de l’identité se comportent exactement comme elles le feraient en production.

Important: Le winapp type de débogage ne génère pas automatiquement votre projet. Après avoir apporté des modifications de code, régénérez avant d’appuyer sur F5.

Automatiser les builds avec `preLaunchTask`

Pour éviter d'oublier de reconstruire, ajoutez un preLaunchTask permettant de reconstruire votre projet avant chaque session de débogage :

Définissez une tâche de génération dans .vscode/tasks.json (par exemple, pour .NET) :

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": ["build", "${workspaceFolder}"],
            "problemMatcher": "$msCompile"
        }
    ]
}

Référencez-le dans votre launch.json:

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch and Attach",
    "preLaunchTask": "build"
}

Propriétés de configuration

Propriété	Catégorie	Default	Description
`inputFolder`	string		Chemin d’accès au dossier de sortie de build contenant vos fichiers binaires d’application (par exemple). `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621` Si ce n’est pas le cas, vous êtes invité à sélectionner un dossier.
`manifest`	string		Chemin d’accès à un fichier manifeste AppX (par exemple, `AppxManifest.xml`, `Package.appxmanifest`ou `appxmanifest.xml`). S’il n’est pas défini, l’interface CLI détecte automatiquement à partir du dossier d’entrée ou du répertoire actif.
`debuggerType`	string	`coreclr`	Débogueur sous-jacent à utiliser (`coreclr`, `cppvsdbg`ou `node`).
`workingDirectory`	string	répertoire d’espace de travail	Répertoire de travail de l’application.
`args`	string		Arguments de ligne de commande à passer à l’application.
`outputAppxDirectory`	string		Répertoire de sortie pour le package de disposition libre. La valeur par défaut est un `AppX` dossier à l’intérieur du dossier d’entrée.
`port`	Numéro	`9229`	(`node` uniquement) Port utilisé pour l’écouteur Node.js `--inspect` et la connexion d’attachement. Remplacez lorsque le port par défaut est déjà utilisé.

Débogueurs pris en charge

`debuggerType`	Langue	Extension requise
`coreclr` (valeur par défaut)	C# / .NET	Kit de développement C#
`cppvsdbg`	C / C++	C/C++
`node`	Node.js / Electron	Intégré

Exemple de projet C++ :

{
    "type": "winapp",
    "request": "launch",
    "name": "WinApp: Launch C++ App",
    "debuggerType": "cppvsdbg"
}

Débogage de démarrage avec Create Debug Identity

Si vous devez déboguer le code de démarrage à partir de la première instruction, la méthode d’attache avec F5 risque de manquer les premières instructions du code. Utilisez plutôt la commande WinApp : Create Debug Identity à partir de la palette de commandes (Ctrl+Shift+P) pour inscrire un package éparse pour votre exécutable, puis lancez-la avec votre débogueur standard :

{
    "name": "Launch (with identity)",
    "type": "coreclr",
    "request": "launch",
    "program": "${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621/myapp.exe"
}

Étant donné create-debug-identity qu’elle inscrit l’identité sur l’exe lui-même, l’application a une identité quelle que soit la façon dont elle est lancée, y compris à partir d’une configuration de lancement VS Code standard.

Attacher à un processus en cours d’exécution

Si vous préférez lancer à partir du terminal winapp run et ensuite vous connecter, utilisez une configuration d’attachement standard :

{
    "name": "Attach to Process",
    "type": "coreclr",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Pour C++/Rust, utilisez "type": "cppvsdbg" (MSVC) ou "type": "lldb" (LLDB) :

{
    "name": "Attach (C++)",
    "type": "cppvsdbg",
    "request": "attach",
    "processId": "${command:pickProcess}"
}

Nettoyage

Lorsque vous avez terminé les tests, exécutez WinApp : Désinscrire le package à partir de la palette de commandes pour supprimer les packages de développement chargés en parallèle sans quitter VS Code.

Commentaires

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

Last updated on 2026-05-12