Debuggen mit Paketidentität

Viele Windows APIs (Pushbenachrichtigungen, Hintergrundaufgaben, Zielfreigabe, Startaufgaben, Windows AI-APIs) erfordern, dass Ihre App package Identity hat. Während der Entwicklung möchten Sie nicht jedes Mal, wenn Sie testen, ein vollständiges MSIX-Installationsprogramm erstellen – winapp stellt zwei Befehle bereit, um die Identität Ihrer Anwendung direkt zu vergeben.

Verwenden sie Visual Studio mit einem Verpackungsprojekt? Wenn Sie bereits Visual Studio für Ihr verpacktes Projekt verwenden, benötigen Sie wahrscheinlich keine Winapp für das Debuggen. Visual Studio behandelt bereits die Paketregistrierung, Identität, AUMID-Aktivierung, Anbindung des Debuggers und Debugging des Aktivierungscodes — alles durch Drücken von F5. Es bietet außerdem Debug → Weitere Debugziele → Debug Installiertes App-Paket, um erweiterte Szenarien zu debuggen. Die folgenden Workflows sind am nützlichsten für VS Code-Benutzer, terminalbasierte Workflows und Frameworks, die VS nicht nativ verpacken (Rust, Flutter, Tauri, Electron, plain C++).

Zwei Ansätze: winapp run vs. create-debug-identity

Wann man was verwenden sollte

Standardwert: winapp run

Verwenden Sie winapp run für die meisten Entwicklungsworkflows. Sie simuliert eine echte MSIX-Installation – Ihre App erhält die gleiche Identität, Funktionen und Dateizuordnungen, die sie in der Produktion haben würden.

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

Verwenden Sie create-debug-identity in folgenden Fällen:

• Ihre exe ist von Ihrem Build-Ergebnis getrennt – z. B. Electron-Apps, wo electron.exe in node_modules/ lebt
• Sie müssen Startcode debuggen und können einen Debugger nach dem Start von AUMID nicht schnell genug anfügen.
• Bei einigen Debuggern, bei denen Sie mit AUMID nicht starten können und Identität für den gestarteten Prozess benötigen – create-debug-identity registriert die exe so, dass sie eine Identität hat, unabhängig davon, wie sie gestartet wird
• Sie testen das Verhalten sparsamer Pakete (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

Debuggingszenarien

Szenario A: Einfach mit Identität ausführen

Der einfachste Workflow – Erstellen, Ausführen mit Identität, fertig.

winapp run .\build\Debug

Winapp registriert den Ordner als loses Layoutpaket und startet die App. Identitätserfordernis erfordernde APIs funktionieren sofort. Dies deckt die meisten Entwicklungs- und Testszenarien ab.

Fügen Sie Folgendes für Konsolen-Apps, die stdin/stdout im aktuellen Terminal benötigen, hinzu --with-alias.

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

Szenario B: Anfügen eines Debuggers an eine ausgeführte App

Starten Sie mit winapp run, notieren Sie sich die PID, und fügen Sie dann den Debugger Ihrer IDE an.

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

Dann in Ihrer IDE:

• VS-Code: Ausführen und Debuggen → "Anfügen"-Konfiguration auswählen (siehe IDE-Setup unten)
• WinDbg: windbg -p 12345

Einschränkung: Sie verpassen Code, der ausgeführt wird, bevor Sie anhängen. Verwenden Sie für das Startdebugging Szenario D (create-debug-identity).

Szenario C: Registrieren der Identität und Starten über AUMID oder Alias aus Ihrer IDE

Verwenden Sie --no-launch, um das Paket zu registrieren, und starten Sie anschließend die App entweder über die AUMID (gemeldet von run) oder den Ausführungsalias aus Ihrer IDE.

Schritt 1: Registrieren Sie das Paket, ohne das Paket zu starten:

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

Schritt 2: Konfigurieren Sie Ihre IDE so, dass sie über die AUMID oder den Ausführungsalias (nicht die exe direkt) gestartet wird.

• Starten mit AUMID: Verwenden Sie den Befehl start shell:AppsFolder\<AUMID>. winapp run gibt die AUMID aus, wenn die App registriert ist.
• Starten mit dem Alias: Der Alias muss in Ihrem Manifest definiert werden (Package.appxmanifest bevorzugt, appxmanifest.xml auch unterstützt).

Wichtig: Beim Starten der EXE im Buildordner wird ihr keine Identität zugewiesen. Die App muss über die AUMID-Aktivierung oder den Ausführungsalias gestartet werden. So funktionieren lose Layoutpakete - Identität ist an den Aktivierungspfad gebunden, nicht an die EXE-Datei.

Szenario D: Starten von Ihrer IDE mit Benutzeridentität (Startvorgangs-Debugging)

Dies ist der beste Ansatz für das Debuggen von Startcode mit vollständiger IDE-Steuerung – der Debugger Ihrer IDE steuert den Prozess bereits ab der ersten Anweisung, und die EXE behält ihre Identität, unabhängig davon, wie sie gestartet wird.

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

Starten Sie nun die EXE-Datei auf beliebige Weise: vom Terminal, mit F5 in VS Code, aus einem Skript. Die Exe besitzt eine Identität, weil Windows ein sparse-Paket registriert, das direkt auf sie zeigt.

Wie es sich von winapp run unterscheidet: Mit create-debug-identity ist die Identität an die Exe selbst gebunden (über Add-AppxPackage -ExternalLocation). Mit winapp run" ist die Identität an das lose Layoutpaket gebunden – die App muss über AUMID oder einen Alias gestartet werden. Dies macht create-debug-identity die bessere Wahl, wenn Sie Ihre IDE benötigen, um die EXE direkt zu starten und zu debuggen.

Dies ist auch der beste Ansatz für Electron-Apps , bei denen sich der Exe-Pfad von Ihrem Quellverzeichnis unterscheidet.

Szenario E: Erfassen der Debugausgabe und Absturzdiagnose

Erfassen Sie OutputDebugString Nachrichten und Erstaußnahmen direkt im Code. Framework-Rauschen (WinUI, interne COM- und DirectX-Ablaufverfolgungen) werden in der Konsole gefiltert, sodass nur die Debugmeldungen Ihrer App angezeigt werden. Alles wird weiterhin in die Protokolldatei geschrieben, um eine umfassende Analyse durchzuführen.

Wenn die App abstürzt, wird ein Minidump erfasst und automatisch analysiert:

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

Beim Absturz enthält die Ausgabe den Ausnahmetyp, die Fehlermeldung und die Stapelverfolgung mit Quelldatei und Zeilennummern (bestimmt aus PDBs im Buildausgabeordner). Verwaltete (.NET) Abstürze werden sofort ohne externe Tools analysiert. Abstürze nativer (C++/WinRT)-Anwendungen zeigen Modulnamen und Offsets an; fügen Sie --symbols hinzu, um PDB-Symbole für vollständige Funktionsnamen herunterzuladen.

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

Wichtig: Dadurch wird winapp als Debugger angefügt. Windows erlaubt nur einen Debugger pro Prozess, sodass Sie Visual Studio, VS Code oder WinDbg nicht gleichzeitig anhängen können.

IDE Setup

VS Code

Die WinApp VS Code-Erweiterung stellt einen benutzerdefinierten winapp Debugtyp bereit, der Ihre App mit Paketidentität startet und den Debugger anfügt – alles aus einem einzelnen F5-Drücken .

Einmaliges F5-Debugging mit Identität

Hinzufügen einer winapp Startkonfiguration zu .vscode/launch.json:

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

Wenn Sie F5 drücken:

1. Die Erweiterung scannt Ihren Arbeitsbereich auf Verzeichnisse für Build-Ausgaben, die .exe-Dateien enthalten.
2. Sie wählen den Buildordner aus, der ausgeführt werden soll, (oder setzen inputFolder, um die Eingabeaufforderung zu überspringen).
3. Es startet Ihre App über winapp run, um ihr Paketidentität zu verleihen.
4. Eine untergeordnete Debugsitzung wird mit dem von Ihnen angegebenen Debugger an den ausgeführten Prozess angefügt.

Sobald der Debugger angefügt ist, erhalten Sie die vollständige VS Code-Debugging-Oberfläche – legen Sie Haltepunkte fest, indem Sie auf den Rand klicken, Schritt für Schritt durch den Code (F10), in Funktionen eintreten (F11), Variablen im Variablenbereich inspizieren und Ausdrücke in der Debugkonsole auswerten. Die App wird während der gesamten Ausführung mit Paketidentität ausgeführt, sodass sich identitätsabhängige APIs genau wie in der Produktion verhalten.

Wichtig: Der winapp Debugtyp erstellt Ihr Projekt nicht automatisch. Bevor Sie F5 drücken, kompilieren Sie bitte den Code nach den vorgenommenen Änderungen neu.

Automatisiere Builds mit preLaunchTask

Um zu vermeiden, dass das Projekt nicht neu erstellt wird, fügen Sie eine preLaunchTask Aufgabe hinzu, die Ihr Projekt vor jeder Debug-Sitzung erstellt.

1. Definieren Sie eine Buildaufgabe in .vscode/tasks.json (z. B. für .NET):

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

2. Verweisen Sie in Ihrem launch.json auf dies:

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

Konfigurationseigenschaften

Unterstützte Debugger

Beispiel für ein C++-Projekt:

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

Startup-Debugging mit Erstellung einer Debug-Identität

Wenn Sie Startcode ab der ersten Anweisung debuggen müssen, kann der Ansatz zum Anfügen mit F5 möglicherweise früh ausgeführten Code übersehen. Verwenden Sie stattdessen den Befehl WinApp: Create Debug Identity aus der Befehlspalette (Ctrl+Shift+P), um ein Sparse Package für Ihre ausführbare Datei zu registrieren, und starten Sie es dann mit Ihrem Standard-Debugger.

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

Da create-debug-identity die Identität direkt auf der EXE selbst registriert, besitzt die App eine Identität, unabhängig davon, wie sie gestartet wird, einschließlich aus einer Standard-VS-Code-Startkonfiguration.

Anfügen an einen ausgeführten Prozess

Wenn Sie lieber mit winapp run aus dem Terminal starten und dann anhängen möchten, verwenden Sie eine Standard-Verbindungskonfiguration.

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

Verwenden Sie "type": "cppvsdbg" für C++/Rust (MSVC) oder "type": "lldb" (LLDB):

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

Wird bereinigt

Wenn Sie mit dem Testen fertig sind, führen Sie WinApp: Paket abmelden aus der Befehlspalette aus, um sideloaded Entwicklungspakete zu entfernen, ohne VS Code zu verlassen.