Foutopsporing met pakketidentiteit

Veel Windows API's (pushmeldingen, achtergrondtaken, doel delen, opstarttaken, Windows AI-API's) vereisen dat uw app package-identiteit heeft. Tijdens de ontwikkeling wilt u niet elke keer dat u test een volledig MSIX-installatieprogramma bouwen: winapp biedt twee opdrachten om uw app-identiteit snel te geven.

Gebruikt u Visual Studio met een verpakkingsproject? Als u al Visual Studio gebruikt voor uw verpakte project, hebt u waarschijnlijk geen winapp nodig voor foutopsporing. Visual Studio verwerkt al pakketregistratie, identiteit, AUMID-activering, foutopsporingsprogrammabijlage en foutopsporing van de activeringscode, allemaal van F5. Het biedt ook Debug → Andere foutopsporingsdoelen → Geïnstalleerd app-pakket debuggen voor geavanceerde scenario's. De onderstaande werkstromen zijn het handigst voor VS Code-gebruikers, terminalwerkstromen en frameworks die VS niet systeemeigen verpakt (Rust, Flutter, Tauri, Electron, plain C++).

Twee benaderingen: winapp run vs create-debug-identity

Wanneer te gebruiken welke

Standaardwaarde: winapp run

Gebruik winapp run dit voor de meeste ontwikkelwerkstromen. Het simuleert een echte MSIX-installatie: uw app krijgt dezelfde identiteit, mogelijkheden en bestandskoppelingen die deze in productie zou hebben.

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

Gebruik create-debug-identity wanneer:

• Uw exe staat los van uw build-uitvoer , bijvoorbeeld Electron-apps waarin electron.exe zich bevindt node_modules/
• U moet fouten opsporen in opstartcode en kan geen foutopsporingsprogramma snel genoeg koppelen nadat AUMID is gestart
• Met een aantal foutopsporingsprogramma's waar u auMID niet kunt starten en identiteit nodig hebt voor het gestarte proces, create-debug-identity registreert u de exe zodat deze identiteit heeft, ongeacht hoe het wordt gestart
• Je test specifiek het gedrag van sparse-pakketten (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

Scenario's voor foutopsporing

Scenario A: Gewoon uitvoeren met identiteit

De eenvoudigste werkstroom: bouwen, uitvoeren met identiteit, klaar.

winapp run .\build\Debug

Winapp registreert de map als een los indelingspakket en start de app. Api's die identiteit vereisen, werken onmiddellijk. Dit omvat het merendeel van de ontwikkelings- en testscenario's.

Voor console-apps die stdin/stdout nodig hebben in de huidige terminal, voegt u het volgende toe --with-alias:

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

Scenario B: Een foutopsporingsprogramma koppelen aan een actieve app

Start met winapp run, noteer de PID en voeg vervolgens het foutopsporingsprogramma van uw IDE toe.

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

Vervolgens in uw IDE:

• VS Code: Uitvoeren en Debuggen → selecteer de configuratie "Attach" (zie IDE-instelling hieronder)
• WinDbg: windbg -p 12345

Beperking: U mist alle code die wordt uitgevoerd voordat u deze bijvoegt. Gebruik Scenario D (create-debug-identity) voor opstartopsporing.

Scenario C: Identiteit registreren en vervolgens starten via AUMID of alias vanuit uw IDE

Gebruik --no-launch om het pakket te registreren en de app te starten via de AUMID (gerapporteerd door run) of uitvoeringsalias van uw IDE.

Stap 1: Registreer het pakket zonder het te starten:

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

Stap 2: Configureer uw IDE om te starten via de AUMID of de uitvoeringsalias (niet de exe rechtstreeks).

• Starten met AUMID: gebruik de opdracht start shell:AppsFolder\<AUMID>. winapp run voert de AUMID uit wanneer de app is geregistreerd.
• Starten met de alias: de alias moet worden gedefinieerd in uw manifest (Package.appxmanifest voorkeursoptie, appxmanifest.xml ook ondersteund).

Belangrijk: Het starten van de exe in de buildmap geeft deze geen identiteit. De app moet worden gestart via activatie van de AUMID of de uitvoeringsalias ervan. Dit is hoe losse indelingspakketten werken: identiteit is gekoppeld aan het activeringspad, niet aan het exe-bestand.

Scenario D: Starten vanuit uw IDE met identiteit (foutopsporing bij opstarten)

Dit is de beste methode voor het opsporen van fouten in opstartcode met volledig IDE-beheer . Het foutopsporingsprogramma van uw IDE bepaalt het proces vanaf de eerste instructie en de exe heeft identiteit, ongeacht hoe deze wordt gestart.

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

Start nu de exe op welke manier je maar wilt: vanuit de terminal, met F5 in VS Code, of vanuit een script. De exe heeft een identiteit omdat Windows een sparse-pakket rechtstreeks ernaar wijst.

Hoe het verschilt van winapp run: Met create-debug-identity, identiteit is gekoppeld aan de exe zelf (via Add-AppxPackage -ExternalLocation). Met winapp run is de identiteit gekoppeld aan het losse lay-outpakket, waardoor de app moet worden gestart via AUMID of een alias. Dit maakt create-debug-identity de betere keuze wanneer u uw IDE nodig hebt om de exe rechtstreeks te starten en fouten op te sporen.

Dit is ook de beste benadering voor Electron-apps waarbij het exe-pad verschilt van uw bronmap.

Scenario E: Debug-uitvoer en crashdiagnostiek vastleggen

Leg OutputDebugString inline berichten en uitzonderingen voor de eerste kans vast. Frameworkruis (WinUI, COM, DirectX interne traceringen) worden gefilterd vanuit de console, zodat alleen de foutopsporingsberichten van uw app worden weergegeven. Alles wordt nog steeds naar het logboekbestand geschreven voor volledig onderzoek.

Als de app vastloopt, wordt een minidump vastgelegd en automatisch geanalyseerd:

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

Bij crash bevat de uitvoer het uitzonderingstype, bericht en stacktracering met bronbestand en regelnummers (omgezet vanuit PDBs in de build-uitvoermap). Beheerde (.NET) crashes worden direct geanalyseerd zonder externe hulpprogramma's. Native (C++/WinRT) crashes tonen modulenamen en offsets; gebruik --symbols om PDB-symbolen te downloaden voor volledige functienamen:

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

Belangrijk: Hiermee wordt winapp als foutopsporingsprogramma gekoppeld. Windows staat slechts één foutopsporingsprogramma per proces toe, waardoor u Visual Studio, VS Code of WinDbg niet ook kunt koppelen.

IDE instellen

VS Code

De WinApp VS Code-extensie biedt een aangepast winapp foutopsporingstype waarmee uw app wordt gestart met pakketidentiteit en het foutopsporingsprogramma wordt gekoppeld, allemaal vanuit één F5-druk .

Foutopsporing met identiteit met één druk op F5

Voeg een winapp startconfiguratie toe aan .vscode/launch.json:

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

Wanneer u op F5 drukt:

1. Met de uitbreiding wordt in uw werkruimte gezocht naar uitvoermappen die .exe bestanden bevatten.
2. U selecteert de buildmap die u wilt uitvoeren (of stelt u inputFolder in om de prompt over te slaan).
3. Uw app wordt via winapp run gestart om het pakketidentiteit te verlenen.
4. Een kindersessie voor foutopsporing wordt gekoppeld aan het lopende proces met de door u opgegeven foutopsporingsprogramma.

Zodra het foutopsporingsprogramma is gekoppeld, krijgt u de volledige foutopsporingservaring in VS Code: stel onderbreekpunten in door te klikken op de kantlijn, stap regel voor regel (F10) door de code, stap in functies (F11), inspecteer variabelen in het deelvenster Variabelen, en evalueer expressies in de Foutopsporingsconsole. De app wordt uitgevoerd met pakketidentiteit overal, dus identiteitsafhankelijke API's gedragen zich precies zoals ze in productie zouden zijn.

Belangrijk: Het winapp foutopsporingstype bouwt uw project niet automatisch. Nadat u codewijzigingen hebt aangebracht, bouwt u het opnieuw op voordat u op F5 drukt.

Builds automatiseren met preLaunchTask

Om te voorkomen dat u vergeet het project opnieuw te bouwen, voegt u een preLaunchTask toe die uw project bouwt vóór elke foutopsporingssessie:

1. Definieer een build-taak in .vscode/tasks.json (bijvoorbeeld voor .NET):

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

2. Verwijs ernaar in uw launch.json:

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

Configuratie-eigenschappen

Ondersteunde foutopsporingsprogramma's

Voorbeeld voor een C++-project:

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

Opstart-debugging met Debug Identiteit aanmaken

Als u fouten wilt opsporen in opstartcode uit de eerste instructie, kan de F5-bijlagebenadering vroege code missen. Gebruik in plaats daarvan de opdracht WinApp: Foutopsporingsidentiteit maken vanuit het opdrachtpalet (Ctrl+Shift+P) om een sparse-pakket voor uw uitvoerbare bestand te registreren en vervolgens te starten met uw standaarddebugger:

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

Omdat create-debug-identity de identiteit wordt geregistreerd op de exe zelf, heeft de app een identiteit, ongeacht hoe deze wordt gestart, inclusief vanuit een standaard-VS Code-startconfiguratie.

Koppelen aan een lopend proces

Als je liever start vanuit de terminal met winapp run en dan koppelt, gebruik je een standaardkoppelingsconfiguratie:

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

Voor C++/Rust gebruikt u "type": "cppvsdbg" (MSVC) of "type": "lldb" (LLDB):

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

Opschonen

Wanneer u klaar bent met testen, voert u WinApp: Unregister Package vanuit de Command Palette uit om sideloaded ontwikkelingspakketten te verwijderen zonder VS Code te verlaten.