Felsökning med paketidentitet

Många Windows API:er (push-meddelanden, bakgrundsuppgifter, delningsmål, startuppgifter Windows AI-API:er) kräver att appen har paketidentitet. Under utvecklingen vill du inte skapa ett fullständigt MSIX-installationsprogram varje gång du testar – winapp tillhandahåller två kommandon för att ge din appidentitet i farten.

Använder du Visual Studio med ett paketeringsprojekt? Om du redan använder Visual Studio för ditt paketerade projekt behöver du förmodligen inte winapp för felsökning. Visual Studio hanterar redan paketregistrering, identitet, AUMID-aktivering, felsökning av bifogade filer och felsökning av aktiveringskod – allt från F5. Den erbjuder även felsökning → Andra felsökningsmål → Felsöka installerat apppaket för avancerade scenarier. Arbetsflödena nedan är mest användbara för VS Code-användare, terminalbaserade arbetsflöden och ramverk som VS inte paketera internt (Rust, Flutter, Tauri, Electron, plain C++).

Två metoder: `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
Vad den registrerar	Fullständigt löst layoutpaket (hela mappen)	Sparse-paket (en ensam exe-fil)
Så startar appen	Startad av winapp (aktivering via AUMID eller körningsalias)	Du startar exe själv (kommandorad, IDE osv.)
Simulerar MSIX-installation	Ja – närmast produktionsbeteende	Nej – endast gles identitet
Filer finns kvar	Kopierades till en AppX-layoutkatalog	Ja – exe stannar kvar på sin ursprungliga sökväg
Identitetsomfång	Hela mappinnehållet (exe, DLL:er, tillgångar)	Självständig körbar fil
Felsökningsvänlig	Koppla till PID efter start eller använd `--no-launch` sedan starta via alias	Starta direkt från IDE:s felsökningsprogram – exe har identitet oavsett
Stöd för konsolapp	`--with-alias` håller stdin/stdout i terminalen	Kör exe direkt i terminalen
Bäst för	De flesta ramverk (.NET, C++, Rust, Flutter, Tauri)	Elektron, eller när du behöver fullständig IDE-felsökningskontroll (F5)

När du ska använda vilken

Standardvärde: `winapp run`

Använd winapp run för de flesta utvecklingsarbetsflöden. Den simulerar en riktig MSIX-installation – din app får samma identitet, funktioner och filassociationer som den skulle ha i produktion.

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

Använd `create-debug-identity` när:

Din exe är skild från din byggoutput – t.ex. Electron-appar där electron.exe finns i node_modules/
Du måste felsöka startkod och kan inte ansluta ett felsökningsprogram tillräckligt snabbt efter AUMID-start
Med vissa felsökningsprogram där du inte kan starta med AUMID och behöver identitet i den startade processen – create-debug-identity registrerar exe så att det har identitet oavsett hur det startas
Du testar glesa paketbeteende specifikt (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

Felsökningsscenarier

Scenario A: Kör bara med identitet

Det enklaste arbetsflödet – skapa, köra med identitet, klar.

winapp run .\build\Debug

Winapp registrerar mappen som ett löst layoutpaket och startar appen. API:er som kräver identitet fungerar omedelbart. Detta omfattar de flesta utvecklings- och testscenarier.

För konsolappar som behöver stdin/stdout i den aktuella terminalen lägger du till --with-alias:

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

Scenario B: Koppla ett felsökningsprogram till en app som körs

Starta med winapp run, notera PID:t och bifoga sedan IDE:s felsökningsprogram.

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

Sedan använd i din IDE:

VS Code: Kör och felsök → välj "Anslut"-konfiguration (se IDE-konfigurationen nedan)
WinDbg: windbg -p 12345

Begränsning: Du missar all kod som körs innan du kopplar. För felsökning av start använder du Scenario D (create-debug-identity).

Scenario C: Registrera identitet och starta sedan via AUMID eller alias från din IDE

Använd --no-launch för att registrera paketet och starta sedan appen via dess AUMID (rapporteras av ) eller runfrån din IDE.

Steg 1: Registrera paketet utan att starta:

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

Steg 2: Konfigurera din IDE att starta via AUMID eller körningsaliaset (inte exe direkt).

Starta med AUMID: Använd kommandot start shell:AppsFolder\<AUMID>. winapp run matar ut AUMID när appen är registrerad.
Startar med aliaset: Aliaset måste definieras i manifestet (Package.appxmanifest rekommenderas, appxmanifest.xml stöds också).

Viktigt: Att bara starta exe-filen i byggmappen ger den inte identitet. Appen måste startas via AUMID-aktivering eller dess körningsalias. Så här fungerar lösa layoutpaket – identiteten är kopplad till aktiveringssökvägen, inte till exe-filen.

Scenario D: Starta från din IDE med identitet (startfelsökning)

Det här är den bästa metoden för att felsöka startkod med fullständig IDE-kontroll – din IDE-felsökare styr processen från den allra första instruktionen och exe har identitet oavsett hur den startas.

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

Starta nu exe hur du vill – från terminalen, från VS CodeS F5, från ett skript. Exe har identitet eftersom Windows registrerat ett sparse-paket som pekar direkt på det.

Hur det skiljer sig från winapp run: Med create-debug-identityär identiteten kopplad till själva exe (via Add-AppxPackage -ExternalLocation). Med winapp runär identiteten kopplad till det lösa layoutpaketet – appen måste startas via AUMID eller ett alias. Detta gör create-debug-identity det bättre valet när du behöver din IDE för att starta och felsöka exe direkt.

Det här är också den bästa metoden för Electron-appar där exe-sökvägen skiljer sig från källkatalogen.

Scenario E: Fånga felsökningsutdata och kraschdiagnostik

Samla in OutputDebugString meddelanden och förstahandsundantag inlinje. Ramverksbrus (WinUI, COM, interna DirectX-spårningar) filtreras från konsolen så att endast appens felsökningsmeddelanden visas. Allt skrivs fortfarande till loggfilen för fullständig undersökning.

Om appen kraschar fångas en minidump in och analyseras automatiskt:

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

Vid en krasch inkluderar utdata undantagstypen, meddelandet och stackspårningen med källfils- och radnummer (som har lösats från PDB-filer i din byggutdata-mapp). Hanterade (.NET) krascher analyseras omedelbart utan externa verktyg. Interna krascher (C++/WinRT) visar modulnamn och förskjutningar. Lägg till --symbols för att ladda ned PDB-symboler för fullständiga funktionsnamn.

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

Viktigt: Detta bifogar winapp som felsökningsprogram. Windows tillåter bara ett felsökningsprogram per process, så du kan inte heller koppla Visual Studio, VS Code eller WinDbg.

IDE-konfiguration

VS Code

WinApp VS Code-tillägget ger en anpassad winapp felsökningstyp som startar din app med paketidentitet och kopplar felsökningsprogrammet – allt från en enda F5-press.

Felsökning med en tryckning på F5 med identitet

Lägg till en winapp startkonfiguration i .vscode/launch.json:

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

När du trycker på F5:

Tillägget söker igenom din arbetsyta efter build-output-kataloger som innehåller .exe filer.
Du väljer den byggmapp som ska köras (eller ange inputFolder för att hoppa över kommandotolken).
Appen startas via winapp run för att ge den paketidentitet.
En barnfelsökningssession ansluter till den körande processen med hjälp av den debugger du angav.

När felsökningsprogrammet har bifogats får du fullständig VS Code-felsökning – ange brytpunkter genom att klicka på rännstenen, gå igenom kod rad för rad (F10), gå in i funktioner (F11), inspektera variabler i fönstret Variabler och utvärdera uttryck i felsökningskonsolen. Appen körs med paketidentitet genomgående, så identitetsberoende API:er beter sig exakt som i produktion.

Viktigt: Felsökningstypen winapp skapar inte projektet automatiskt. När du har gjort kodändringar återskapar du innan du trycker på F5.

Automatisera byggen med `preLaunchTask`

För att undvika att glömma att återskapa lägger du till en preLaunchTask som skapar projektet före varje felsökningssession:

Definiera en byggaktivitet i .vscode/tasks.json (till exempel för .NET):

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

Referera till den i din launch.json:

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

Konfigurationsegenskaper

Property	Type	Standardinställning	Description
`inputFolder`	string		Sökväg till mappen för kompileringsutdata som innehåller din apps binärfiler (t.ex. `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Om den inte har angetts uppmanas du att välja en mapp.
`manifest`	string		Sökväg till en AppX-manifestfil (t.ex. `AppxManifest.xml`, `Package.appxmanifest`, eller `appxmanifest.xml`). Om den inte har angetts detekterar CLI automatiskt från indatamappen eller den aktuella katalogen.
`debuggerType`	string	`coreclr`	Underliggande felsökningsprogram som ska användas (`coreclr`, `cppvsdbg`eller `node`).
`workingDirectory`	string	arbetsyta mapp	Arbetskatalog för applikationen.
`args`	string		Kommandoradsargument som ska skickas till programmet.
`outputAppxDirectory`	string		Utdatakatalog för paketet med lös layout. Som standard är en `AppX` mapp placerad i indatamappen.
`port`	nummer	`9229`	(`node` endast) Den port som används för Node.js `--inspect` lyssnaren och anslutningsanslutningen. Åsidosätt när standardporten redan används.

Felsökningsprogram som stöds

`debuggerType`	Language	Obligatorisk förlängning
`coreclr` (standardinställning)	C# /.NET	C# Utvecklingspaket
`cppvsdbg`	C/C++	C/C++
`node`	Node.js/Electron	Inbyggd

Exempel för ett C++-projekt:

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

Startfelsökning med Skapa felsökningsidentitet

Om du behöver felsöka startkod från den allra första instruktionen kan metoden F5-bifoga missa tidig kod. Använd i stället kommandot WinApp: Create Debug Identity från kommandopaletten (Ctrl+Shift+P) för att registrera ett glest paket för den körbara filen och starta det sedan med standardfelsökaren:

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

Eftersom create-debug-identity registrerar identiteten på själva exe:n har appen identitet oavsett hur den startas , inklusive från en standardkonfiguration för VS Code-start.

Koppla till en process som körs

Om du föredrar att starta med winapp run från terminalen och sedan ansluta använder du en standardanslutningskonfiguration:

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

För C++/Rust använder du "type": "cppvsdbg" (MSVC) eller "type": "lldb" (LLDB):

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

Rensning

När du är klar med testningen kör du WinApp: Avregistrera paket från kommandopaletten för att ta bort separat inlästa utvecklingspaket utan att behöva lämna VS Code.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-05-12