Hibakeresés Csomagidentitás használatával

Számos Windows API-nak (leküldéses értesítések, háttérfeladatok, megosztási cél, indítási feladatok, Windows AI API-k) az alkalmazásnak package identitással kell rendelkeznie. A fejlesztés során nem szeretne teljes MSIX-telepítőt létrehozni minden teszteléskor – a Winapp két parancsot biztosít az alkalmazás identitásának menet közbeni átadásához.

A Visual Studio-t használja egy csomagolási projektben? Ha már használja a Visual Studio a csomagolt projekthez, valószínűleg nem kell winappot használnia a hibakereséshez. Visual Studio már kezeli a csomagregisztrációt, az identitást, az AUMID-aktiválást, a hibakereső mellékletet és az aktiválási kód hibakeresését – mindezt az F5-ből. Emellett hibakeresési → egyéb hibakeresési célokat is kínál, → a telepített alkalmazáscsomag hibakeresését speciális forgatókönyvekhez. Az alábbi munkafolyamatok leginkább a VS Code-felhasználók, terminálalapú munkafolyamatok és keretrendszerek számára hasznosak, amelyeket a VS natív módon nem csomagol (Rust, Flutter, Tauri, Electron, plain C++).

Két megközelítés: `winapp run` vs `create-debug-identity`

	`winapp run`	`create-debug-identity`
Amit regisztrál	Teljes laza elrendezési csomag (teljes mappa)	Ritka csomag (egyetlen exe)
Az alkalmazás indítása	Winapp által indított (AUMID aktiválási vagy végrehajtási alias)	Az exe-t saját maga indíthatja el (parancssor, IDE stb.)
MSIX telepítés szimulálása	Igen – az éles működéshez legközelebbi	Nem – csak ritka identitás
A fájlok a helyén maradnak	Átmásolva egy AppX-elrendezési könyvtárba	Igen – az exe az eredeti elérési úton marad
Identitás hatóköre	Teljes mappatartalom (exe, DLL-ek, objektumok)	Egyetlen végrehajtható fájl
Hibakereső-kompatibilis	Indítsa el a PID-hez való csatlakozást az indítás után, vagy használja `--no-launch`, majd indítson el az alias segítségével.	Közvetlenül az IDE hibakeresőjéből indítható – az exe identitással rendelkezik, függetlenül attól, hogy
Konzolalkalmazások támogatása	`--with-alias` stdin/stdout marad a terminálban	Exe futtatása közvetlenül a terminálban
Legjobb	A legtöbb keretrendszer (.NET, C++, Rust, Flutter, Tauri)	Elektron, vagy ha teljes IDE hibakeresési vezérlésre van szükséged (F5)

Mikor érdemes az egyiket vagy a másikat használni

Alapértelmezett: `winapp run`

A legtöbb fejlesztési munkafolyamathoz használható winapp run . Valós MSIX-telepítést szimulál – az alkalmazás ugyanazokat az identitásokat, képességeket és fájltársításokat kapja, mint az éles környezetben.

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

Használja a `create-debug-identity`-t, amikor:

Az exe különáll az építési kimenettől – például az Electron-alkalmazásokban, ahol electron.exe a node_modules/
Hibakeresést kell végeznie az indítási kódon , és az AUMID elindítása után nem lehet elég gyorsan csatolni a hibakeresőt
Néhány hibakeresőnél, ahol nem lehet AUMID-del indítani, és az elindított folyamatnak szüksége van azonosításra – create-debug-identity regisztrálja az exe-t, hogy az mindig rendelkezzen azonosítással, függetlenül az indítás módjától.
A ritka csomagok viselkedését kifejezetten teszteli (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

Hibakeresési forgatókönyvek

Forgatókönyv A: Csak az identitás használata

A legegyszerűbb munkafolyamat – létrehozás, futtatás identitással, kész.

winapp run .\build\Debug

A Winapp laza elrendezésű csomagként regisztrálja a mappát, és elindítja az alkalmazást. Az identitást igénylő API-k azonnal működnek. Ez a fejlesztési és tesztelési forgatókönyvek többségére vonatkozik.

Azon konzolalkalmazások esetében, amelyeknek stdin/stdout-ra van szükségük az aktuális terminálban, adja hozzá a következőt --with-alias:

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

B. forgatókönyv: Hibakereső csatolása futó alkalmazáshoz

Indítsa el a következővel winapp run: jegyezze fel a PID-t, majd csatolja az IDE hibakeresőjét.

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

Ezután az IDE-ben:

VS Code: A futtatás és hibakeresés → válassza a "Csatlakozás" konfigurációt (lásd alább az IDE beállítása)
WinDbg: windbg -p 12345

Korlátozás: Lemarad minden kódról, amely a csatolás előtt fut le. Az indítási hibakereséshez használja a D forgatókönyvet (create-debug-identity).

C. forgatókönyv: Identitás regisztrálása, majd indítás az AUMID-en vagy aliason keresztül az IDE-ből

Használja a --no-launch parancsot a csomag regisztrálásához, majd IDE-jéből indítsa el az alkalmazást az AUMID segítségével (amit a run jelent), vagy az végrehajtási álnevet használva.

1. lépés: Regisztrálja a csomagot indítás nélkül:

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

2. lépés: Konfigurálja az IDE-t úgy, hogy az AUMID vagy a végrehajtási alias (nem közvetlenül az exe) használatával induljon el.

Indítás az AUMID azonosítóval: Használja a parancsot start shell:AppsFolder\<AUMID>. winapp run az alkalmazás regisztrálásakor az AUMID-t adja ki.
Indítás az aliassal: Az aliast meg kell határozni a jegyzékben (Package.appxmanifest előnyben részesített, appxmanifest.xml szintén támogatott).

Fontos: Ha egyszerűen elindítja az exe-t a buildmappában , az nem adja meg az identitást. Az alkalmazást az AUMID aktiválásával vagy végrehajtási aliasával kell elindítani. Így működnek a laza elrendezési csomagok – az identitás az aktiválási útvonalhoz van kötve, nem az exe fájlhoz.

D. forgatókönyv: Indítás az IDE-ből identitással (indítási hibakeresés)

Ez a legjobb módszer az indítási kód teljes IDE-vezérléssel történő hibakereséséhez – az IDE hibakeresője az első utasításból vezérli a folyamatot, az exe pedig az indítás módjától függetlenül rendelkezik identitással.

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

Most indítsa el az exe-t tetszőleges módon – a terminálról, a VS Code F5-éből, egy szkriptből. Az exe identitással rendelkezik, mert a Windows regisztrált egy sparse csomagot, amely közvetlenül rá mutat.

Miben különbözik a következőtől winapp run: Az create-debug-identity identitás magához az futtatható fájlhoz kötődik (Add-AppxPackage -ExternalLocation révén). Az winapp runidentitás a laza elrendezési csomaghoz van kötve – az alkalmazást az AUMID-ben vagy egy aliason keresztül kell elindítani. Ez jobb create-debug-identity választás, ha az IDE-nek szüksége van az exe közvetlen elindítására és hibakeresésére.

Ez az Electron-alkalmazások esetében is ez a legjobb módszer, ahol az exe elérési útja eltér a forráskönyvtártól.

E. forgatókönyv: A hibakeresési napló és a rendszerösszeomlási diagnosztika rögzítése

Üzenetek és első esélyű kivételek rögzítése OutputDebugString beágyazottan. A keretrendszer zaja (WinUI, COM, DirectX belső nyomkövetések) a konzolról szűrve jelenik meg, így csak az alkalmazás hibakeresési üzenetei jelennek meg. A teljes vizsgálathoz minden a naplófájlba van írva.

Ha az alkalmazás összeomlik, a rendszer automatikusan rögzíti és elemzi a minidumpot:

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

Összeomláskor a kimenet magában foglalja a kivétel típusát, az üzenetet és a veremkivonatot a forrásfájllal és sorszámokkal (a build kimeneti mappájában lévő PDB-fájlokból feloldva). A felügyelt (.NET) összeomlásokat a rendszer azonnal elemzi külső eszközök nélkül. A natív (C++/WinRT) összeomlások a modulneveket és az eltolásokat jelenítik meg; adjon hozzá --symbols a teljes függvénynevekhez tartozó PDB-szimbólumok letöltéséhez.

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

Fontos: Ez a winappot csatolja hibakeresőként. Windows csak egy hibakeresőt engedélyez folyamatonként, ezért nem csatolhat Visual Studio, VS Code vagy WinDbg eszközt is.

WinUI stowed exception osztályozása

A legtöbb WinUI-összeomlás egy XAML-eseménykezelőn belül kezdődik, és félretett kivételként (0xC000027B) jelentkezik, amelyet később a dispatcher újra dob, így a normál verem már nem a valódi okra mutat. Amikor az összeomlott alkalmazás betöltötte a Microsoft.UI.Xaml.dll elemet, a winapp automatikusan lefuttat egy kiegészítő triage-ellenőrzést, amely dekódolja az eltárolt kivételt és a natív XAML-diszpécserláncot (Microsoft.UI.Xaml → CXcpDispatcher → CoreMessagingXP → CLR-gazda). Az eredmény hozzá lesz fűzve a hibakeresési naplóhoz. Nincs szükség kapcsolóra – a rendszer automatikusan engedélyezi a WinUI-dumpokhoz. Adja hozzá a(z) --symbols elemet a teljesen feloldott függvénynevekhez a diszpécselési láncban.

Ennek működéséhez a winapp rögzíti az összeomlási memóriaképet a leállást okozó eltárolt kivétel rekordjával együtt (és annak paramétereivel, amelyek az eltárolt kivételek tömbjére mutatnak), miközben megőrzi az első esélyű kivételhez tartozó szálkontextust, így a szokásos felügyelt elemzés továbbra is helyreállítja az eredeti felhasználói veremkeretet és a triage-fázis meg tudja találni az eltárolt kivételt.

Ez a szakasz a DbgEnget a WinUI csapat WinDbg JavaScript-bővítményével futtatja. A natív hibakereső motor (dbgeng.dll és társai) a NuGetből származik, a JsProvider.dll pedig — a JavaScript-parancsfuttató gazdagép, amely nem érhető el a NuGeten — az első használatkor közvetlenül a hivatalos WinDbg-letöltésből töltődik le (csak a szükséges néhány száz kilobájtnyi adatot olvassa be, nem pedig a teljes csomagot). Mivel a JsProvider.dll buildjének meg kell egyeznie a motor buildjével — az eltérő buildű szolgáltató betöltése indításkor összeomlasztja a hibakeresőt —, ezért ahhoz a konkrét WinDbg-csomaghoz van rögzítve, amelynek buildje megegyezik a NuGet-motoréval (nem pedig a folyamatosan frissülő „current” kiadáséhoz), és a beszerzés után összevetik a két buildet: eltérés esetén azt elutasítják, a triage-ot pedig egyértelmű indoklással kihagyják ahelyett, hogy a rendszer csendben összeomlana. A hibakeresőcsomagok verzióhoz vannak kötve, és mielőtt bármely natív DLL-jüket kinyernék és betöltenék, egy beépített SHA-512 tartalomhash alapján ellenőrzik őket (a bővítményt pedig egy rögzített hash ellenőrzik); JsProvider.dll emellett érvényes Microsoft Authenticode-aláírással is kell rendelkeznie, amelyet a tanúsítványlánc teljes visszavonás-ellenőrzésével vizsgálnak (ha a visszavonási adatok offline nem érhetők el, akkor csak az aláírás ellenőrzésére térnek vissza, de a visszavont tanúsítványt minden esetben elutasítják). A letöltéseket ideiglenes fájlba rendezik, ellenőrzik, majd atomi módon közzéteszik a gyorsítótárban, így az egyidejű futtatás soha nem figyel meg részben írt vagy nem ellenőrzött DLL-t. Minden futtatáskor újra ellenőrzik a gyorsítótárazott binárisokat (az JsProvider.dll aláírást és annak egyezését az engine buildjével, valamint azt, hogy a motor DLL-jei érvényes PE-képet alkotnak-e), így a csonkolt vagy inkonzisztenssé vált gyorsítótár hiba helyett újrabeszerzéssel önhelyreállítást végez, ahelyett hogy minden futtatáskor meghiúsulna. Ez összességében azt jelenti, hogy egy tükörszerverről származó vagy kompromittált forrás nem csempészhet be módosított binárisokat — bármilyen hiba esetén a rendszer inkább kihagyja a triázst, mintsem nem ellenőrzött kódot töltsön be. Minden a winapp globális könyvtárában kerül gyorsítótárazásra, így a későbbi futtatások offline is működnek. Ha a környezet letiltja ezeket a letöltéseket, telepítse az Windows hibakeresési eszközeit (a Windows SDK-n keresztül), vagy állítsa a WINAPP_DBGTOOLS_DIR környezeti változót egy olyan hibakereső könyvtárra, amely már tartalmaz dbgeng.dll ésJsProvider.dll. Ha WINAPP_DBGTOOLS_DIR be van állítva, mérvadó – csak az adott könyvtárat tekinti meg –, ezért ha nem teljes, akkor a napló az adott hiányzó összetevőt (dbgeng.dll és/vagy JsProvider.dll) adja meg ahelyett, hogy egy már beállított változót állít be. Ha a triage sikeres, a konzol egy egysoros eredményt jelenít meg (az eltárolt kivétel hibakódját/üzenetét); ha a bináris fájlok nem szerezhetők meg, a rendszer kihagyja a triage-fázist (a szabványos felügyelt/natív elemzés továbbra is lefut), a konzol ezt jelzi, a napló pedig elmagyarázza, miért.

A triage pass egy rövid életű gyermekfolyamatban fut. Erre azért van szükség, mert a winapp főfolyamata a memóriakép rögzítése és elemzése során betölti a rendszer dbghelp.dll összetevőjét, és a modern motor dbgeng.dll nem tud hozzákapcsolódni ehhez a régebbi, már memóriában lévő példányhoz — egy új folyamat tiszta betöltőállapotot biztosít a motor számára. A stowed-exception struktúrák dekódolásához operációsrendszer-szimbólumokra (combase.dll) is szükség van, amelyek --symbols a Microsoft nyilvános szimbólumkiszolgálóról tölthetők le; azon buildeken, amelyek szimbólumait nem teszik közzé ott, a triage pass továbbra is azonosítja a beszúrt kivételt, de nem tudja teljes mértékben kibontani.

IDE beállítása

VS Code

A WinApp VS Code bővítmény egy egyéni winapp hibakeresési típust biztosít, amely csomagidentitással indítja el az alkalmazást, és csatolja a hibakeresőt – mindezt egyetlen F5 billentyűvel. Telepítse a Visual Studio Marketplace-ről; a forrás- és problémakövető élőben a microsoft/WinAppVSCE-adattárban.

Egynyomásos F5-hibakeresés identitással

winapp Indítási konfiguráció hozzáadása a(z) .vscode/launch.json-hez:

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

Az F5 billentyű lenyomásakor:

A bővítmény fájlokat tartalmazó .exe buildkimeneti könyvtárakat keres a munkaterületen.
Válassza ki a futtatni kívánt buildmappát (vagy állítsa be inputFolder a parancssor kihagyásához).
Elindítja az alkalmazást winapp run a csomag identitásának átadása érdekében.
A gyermek hibakeresési munkamenet a megadott hibakeresővel csatlakozik a futó folyamathoz.

Miután a hibakereső csatlakozik, megkapja a teljes VS Code hibakeresési élményt – töréspontokat állíthat be a margóra kattintva, sorról sorra léphet, beléphet a függvényekbe, változók vizsgálata a F10 panelen, és kifejezések kiértékelése a F11-on. Az alkalmazás teljes egészében csomagidentitással fut, így az identitásfüggő API-k pontosan ugyanúgy viselkednek, mint az éles környezetben.

Fontos: A winapp hibakeresési típus nem hozza létre automatikusan a projektet. A kódmódosítások elvégzése után az F5 billentyű lenyomása előtt végezze el az újraépítést.

Felépítések automatizálása a `preLaunchTask`

Annak érdekében, hogy ne feledkezzen meg az újraépítésről, adjon hozzá egy preLaunchTask olyan fájlt, amely minden hibakeresési munkamenet előtt létrehozza a projektet:

Buildelési feladat definiálása .vscode/tasks.json (például .NET):

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

Hivatkozzon rá a következőben launch.json:

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

Konfigurációs tulajdonságok

Ingatlan	Típus	Alapértelmezett	Description
`inputFolder`	karakterlánc		Az alkalmazás bináris fájljait tartalmazó build kimeneti mappájának elérési útja (pl. `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`). Ha nincs beállítva, a rendszer kérni fogja, hogy válasszon ki egy mappát.
`manifest`	karakterlánc		Egy AppX-jegyzékfájl elérési útja (pl. `AppxManifest.xml`, , `Package.appxmanifest`vagy `appxmanifest.xml`). Ha nincs beállítva, a parancssori felület automatikusan észleli a bemeneti mappát vagy az aktuális könyvtárat.
`debuggerType`	karakterlánc	`coreclr`	Használandó mögöttes hibakereső (`coreclr`, `cppvsdbg`, vagy `node`).
`workingDirectory`	karakterlánc	munkaterület mappája	Az alkalmazás munkakönyvtára.
`args`	karakterlánc		Az alkalmazásnak továbbítandó parancssori argumentumok.
`outputAppxDirectory`	karakterlánc		A laza elrendezésű csomag kimeneti könyvtára. `AppX` mappává állítja be alapértelmezetten a bemeneti mappán belül.
`port`	szám	`9229`	(`node` kizárólag) A Node.js `--inspect` figyelőhöz és a csatolási kapcsolathoz használt port. Bírálja felül, ha az alapértelmezett port már használatban van.

Támogatott hibakeresők

`debuggerType`	Nyelv	Kötelező bővítmény
`coreclr` (alapértelmezett)	C# / .NET	C# fejlesztői készlet
`cppvsdbg`	C / C++	C/C++
`node`	Node.js/ Elektron	Beépítve

Példa egy C++ projektre:

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

Hibakeresés indítása hibakeresési identitás létrehozásával

Ha az első utasításból kell hibakeresést végeznie az indítási kódban, előfordulhat, hogy az F5 csatolási megközelítése kihagyja a korai kódot. Ehelyett használja a WinApp: Create Debug Identity parancsot a parancskatalógusból (Ctrl+Shift+P) egy ritka csomag regisztrálásához a végrehajtható fájlhoz, majd indítsa el a standard hibakeresővel:

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

Mivel create-debug-identity magát az exe-t regisztrálja, az alkalmazás identitással rendelkezik, függetlenül attól, hogy hogyan indult el – beleértve egy szabványos VS Code indítási konfigurációt is.

Csatlakozz egy futó folyamathoz

Ha inkább a terminálról indít winapp run, majd csatlakozzon, használjon egy szabványos csatolási beállítást.

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

C++/Rust esetén használja "type": "cppvsdbg" az (MSVC) vagy "type": "lldb" a (LLDB) elemet:

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

Tisztítás

Ha végzett a teszteléssel, futtassa a WinApp: Csomag regisztrációjának törlése parancsot a parancs palettából, hogy a VS Code bezárása nélkül eltávolítsa az oldalról betöltött fejlesztési csomagokat.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-07-24