Ladění s využitím identity balíčku

Řada rozhraní API Windows (nabízená oznámení, úlohy na pozadí, sdílení cíle, spouštěcí úlohy, rozhraní API Windows AI) vyžaduje, aby vaše aplikace měla package identity. Během vývoje nechcete při každém testování sestavit úplný instalační program MSIX – winapp poskytuje dva příkazy, které vaší aplikaci poskytnou identitu aplikace za běhu.

Používáte Visual Studio s projektem balení? Pokud už pro zabalený projekt používáte Visual Studio, pravděpodobně pro ladění nepotřebujete winapp. Visual Studio už zpracovává registraci balíčku, identitu, aktivaci AUMID, přílohu ladicího programu a ladění aktivačního kódu – vše z F5. Nabízí také Ladicí → Další cíle ladění → Ladění nainstalovaného balíčku aplikace pro pokročilé scénáře. Následující pracovní postupy jsou nejužitečnější pro uživatele VS Code, terminálové pracovní postupy a architektury, které VS nativně nezabalí (Rust, Flutter, Tauri, Elektron, plain C++).

Dva přístupy: `winapp run` vs. `create-debug-identity`

	`winapp run`	`create-debug-identity`
Co se registruje	Balíček s úplným volným rozložením (celá složka)	Řídký balíček (single exe)
Jak se aplikace spouští	Spuštění aplikace winapp (aktivace AUMID nebo alias pro spuštění)	Spustíte exe sami (příkazový řádek, integrované vývojové prostředí atd.).
Simuluje instalaci MSIX	Ano – nejblíže produkčnímu chování	Ne – pouze řídká identita
Soubory zůstanou na místě	Zkopírováno do adresáře rozložení AppX	Ano – exe zůstane na původní cestě
Rozsah identity	Celý obsah složky (exe, knihovny DLL, datové soubory)	Jeden spustitelný soubor
Přátelský k ladění	Připojte se k PID po spuštění, nebo použijte `--no-launch` a spusťte pomocí aliasu.	Spusťte přímo z ladicího programu integrovaného vývojového prostředí – exe má identitu bez ohledu na okolnosti.
Podpora konzolových aplikací	`--with-alias` udržuje stdin/stdout v terminálu	Spustit exe přímo v terminálu
Nejlepší pro	Většina architektur (.NET, C++, Rust, Flutter, Tauri)	Elektron, aneb když potřebujete úplnou kontrolu ladicího programu IDE (F5)

Kdy použít co

Výchozí: `winapp run`

Používá se winapp run pro většinu vývojových pracovních postupů. Simuluje skutečnou instalaci MSIX – vaše aplikace získá stejnou identitu, možnosti a přidružení souborů, které by měla v produkčním prostředí.

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

Použít `create-debug-identity` když:

Váš exe je oddělený od výstupu sestavení – například ty aplikace Electron, kde electron.exe se nachází v node_modules/
Potřebujete ladit spouštěcí kód a po spuštění AUMID nemůžete připojit ladicí program dostatečně rychle.
cs-CZ: S některými ladicími programy, kde nelze spustit s AUMID a je nutná identita na spuštěný proces — create-debug-identity zaregistruje EXE, takže má identitu bez ohledu na to, jak je spuštěno.
Testujete konkrétně chování řídkých balíčků (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énáře ladění

Scénář A: Pouze spusťte s identitou

Nejjednodušší pracovní postup – sestavení, spuštění s identitou, hotovo.

winapp run .\build\Debug

Winapp zaregistruje složku jako volný balíček rozložení a spustí aplikaci. Rozhraní API vyžadující identitu fungují okamžitě. Týká se to většiny vývojových a testovacích scénářů.

Pro konzolové aplikace , které potřebují stdin/stdout v aktuálním terminálu, přidejte --with-alias:

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

Scénář B: Připojení ladicího programu ke spuštěné aplikaci

Spusťte s winapp run, zaznamenejte PID a poté připojte ladicí program IDE.

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

Pak v integrovaném vývojovém prostředí (IDE):

VS Code: Spustit a ladit → vyberte konfiguraci "Attach" (vizte nastavení IDE níže).
WinDbg: windbg -p 12345

Omezení: Před připojením zmeškáte veškerý kód, který se spustí. Pro ladění po spuštění použijte scénář D (create-debug-identity).

Scénář C: Registrace identity a následné spuštění prostřednictvím AUMID nebo aliasu z integrovaného vývojového prostředí

K registraci balíčku použijte --no-launch, poté spusťte aplikaci prostřednictvím svého AUMID (uvedeného run) nebo aliasu spuštění z vašeho integrovaného vývojového prostředí (IDE).

Krok 1: Zaregistrujte balíček bez spuštění:

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

Krok 2: Nakonfigurujte integrované vývojové prostředí (IDE) tak, aby se spustilo prostřednictvím AUMID nebo aliasu spuštění (ne přímo exe).

Spuštění pomocí AUMID: Použijte příkaz start shell:AppsFolder\<AUMID>. winapp run vypíše AUMID při registraci aplikace.
Spuštění pomocí aliasu: Alias musí být definován v manifestu (Package.appxmanifest upřednostňovaný, appxmanifest.xml také podporovaný).

Důležité: Jednoduše spuštění exe ve složce sestavení nedává identitu. Aplikace se musí spustit prostřednictvím aktivace AUMID nebo aliasu spuštění. Takto fungují volné balíčky rozložení – identita je svázaná s cestou aktivace, nikoli s exe souborem.

Scénář D: Spuštění z integrovaného vývojového prostředí s identitou (ladění při spuštění)

Toto je nejlepší přístup pro ladění spouštěcího kódu s úplným řízením IDE – ladicí program integrovaného vývojového prostředí řídí proces od první instrukce a exe má identitu bez ohledu na to, jak je spuštěna.

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

Nyní spusťte exe libovolným způsobem – z terminálu, z VS Code, pomocí F5, nebo ze skriptu. Exe má identitu, protože Windows zaregistrovala balíček sparse ukazující přímo na něj.

Jak se liší od winapp run: S create-debug-identity, identita je svázána se samotným exe (prostřednictvím Add-AppxPackage -ExternalLocation). Když použijete winapp run, identita je svázaná s neutrálním rozložením balíčku – aplikace se musí spustit prostřednictvím AUMID nebo aliasu. To dělá z create-debug-identity lepší volbu, když potřebujete, aby vaše integrované vývojové prostředí (IDE) přímo spustilo a ladilo spustitelný soubor (exe).

Toto je také nejlepší přístup pro aplikace Electron , kde se cesta exe liší od vašeho zdrojového adresáře.

Scénář E: Zachycení výstupu ladění a diagnostiky chybových ukončení

Zachyťte OutputDebugString zprávy a výjimky prvního záchytu přímo v kódu. Šum rozhraní (WinUI, COM, interní trasování DirectX) se filtruje z konzoly, takže se zobrazí jenom ladicí zprávy vaší aplikace. Všechno je stále zapsáno do souboru protokolu pro úplné šetření.

Pokud dojde k chybovému ukončení aplikace, minidump se zachytí a automaticky analyzuje:

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

Při pádu výstup obsahuje typ výjimky, zprávu a trasování zásobníku se zdrojovým souborem a čísly řádků (získané ze souborů PDB ve výstupní složce sestavení). Spravované havárie (.NET) se analyzují okamžitě bez externích nástrojů. U nativních pádů (C++/WinRT) se zobrazují názvy modulů a offsety; přidáním --symbols stáhněte symboly PDB pro úplné názvy funkcí:

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

Důležité: Tím se připojí winapp jako ladicí program. Windows umožňuje pouze jeden ladicí program na proces, takže proto nelze připojit Visual Studio, VS Code ani WinDbg.

Analýza odložených výjimek ve WinUI

Většina pádů WinUI začíná v obsluze události XAML a projeví se jako odložená výjimka (0xC000027B), která je později znovu vyvolána dispečerem, takže běžný zásobník volání už neukazuje na skutečnou příčinu. Když se načetla havarovaná aplikace Microsoft.UI.Xaml.dll, winapp automaticky spustí dodatečnou analýzu, která dekóduje odloženou výjimku a nativní dispečerský řetězec XAML (Microsoft.UI.Xaml → CXcpDispatcher → CoreMessagingXP → hostitel CLR). Výsledek se připojí k protokolu ladění. Není potřeba žádný příznak – pro výpisy WinUI se automaticky povoluje. Přidejte --symbols pro plně vyhodnocené názvy funkcí v řetězci dispatchování.

Aby tato funkce fungovala, winapp zachytí výpis stavu systému pomocí záznamu ukončující zaseknuté výjimky (a jeho parametrů, které ukazují na pole s pevnými výjimkami) a zachová kontext vlákna první šance, takže standardní spravovaná analýza stále obnoví původní rámec uživatele a průchozí třídění může najít stowed exception.

Tato fáze obsahuje DbgEng s rozšířením WinDbg JavaScript od týmu WinUI. Ladicí modul pochází z NuGetu; JsProvider.dll (hostitel JavaScriptu, který není publikován na NuGetu) se při prvním použití stáhne z oficiální distribuce WinDbg. Obojí má pevně danou verzi a je ověřeno před načtením – pomocí hashů obsahu SHA-512 a kontroly podpisu Microsoft Authenticode u JsProvider.dll – a jakékoli selhání ověření vede k přeskočení třídění namísto načtení neověřeného kódu. Všechno se ukládá do mezipaměti pod globálním adresářem winapp, takže pozdější spuštění jsou offline.

Pokud vaše prostředí blokuje stahování, nainstalujte buď nástroje ladění pro Windows (prostřednictvím sady Windows SDK), nebo nastavte WINAPP_DBGTOOLS_DIR adresář ladicího programu, který obsahuje dbgeng.dll a JsProvider.dll. Je-li nastavena hodnota WINAPP_DBGTOOLS_DIR, je směrodatná — použije se pouze tento adresář — a pokud je neúplný, v protokolu je uvedena chybějící komponenta.

Když je triage úspěšná, konzole zobrazí jednořádkový výsledek (chybový kód/zprávu uložené výjimky). Když to nelze spustit, konzola to oznámí, protokol vysvětlí proč a standardní spravovaná/nativní analýza se i tak spustí.

Fáze triáže probíhá v krátkodobém podřízeném procesu, protože hlavní proces aplikace winapp už načetl systém dbghelp.dll a moderní dbgeng.dll se vedle něj nemůže navázat. Dekódování struktur odložených výjimek také vyžaduje symboly operačního systému (combase.dll), které --symbols stahuje z veřejného serveru symbolů společnosti Microsoft; u buildů, jejichž symboly tam nejsou zveřejněny, analýza stále identifikuje odloženou výjimku, ale nemůže ji plně rozvinout.

Nastavení integrovaného vývojového prostředí (IDE

VS Code

Rozšíření WinApp VS Code poskytuje vlastní winapp typ ladění, který spustí vaši aplikaci s identitou balíčku a připojí ladicí program — to vše jediným stisknutím F5. Nainstalujte ho z Visual Studio Marketplace; jeho zdrojový kód a přehled nahlášených problémů najdete v repozitáři microsoft/WinAppVSCE.

Ladění F5 jedním stisknutím klávesy F5 s identitou

winapp Přidejte konfiguraci spuštění do.vscode/launch.json:

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

Když stisknete klávesu F5:

Rozšíření zkontroluje váš pracovní prostor pro výstupní adresáře sestavení obsahující .exe soubory.
Vyberte složku sestavení, kterou chcete spustit (nebo nastavte inputFolder, abyste přeskočili výzvu).
Aplikaci se spustí prostřednictvím winapp run, aby jí poskytl identitu balíčku.
Podřízená ladicí relace se připojí k spuštěnému procesu použitím zadaného ladicího programu.

Jakmile se ladicí program připojí, získáte kompletní prostředí ladění VS Code – nastavíte zarážky kliknutím na okraj, krokujte kódem po řádku (F10), krokujte do funkcí (F11), zkontrolujte proměnné v podokně Proměnné a vyhodnoťte výrazy v Konzole ladění. Aplikace běží s identitou balíčku v celém prostředí, takže rozhraní API závislá na identitě se chovají přesně tak, jak by to bylo v produkčním prostředí.

Důležité: Typ ladění winappnevytvoří váš projekt automaticky. Po provedení změn kódu znovu sestavte před stisknutím klávesy F5.

Automatizujte sestavení pomocí `preLaunchTask`

Abyste nezapomněli na opětovné sestavení, přidejte preLaunchTask, který sestaví váš projekt před každou ladicí relací:

Definujte úlohu sestavení v .vscode/tasks.json (například pro .NET):

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

Odkazujte na ni v :launch.json

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

Vlastnosti konfigurace

Vlastnictví	Typ	Výchozí	Description
`inputFolder`	řetězec		Cesta k výstupní složce sestavení obsahující binární soubory aplikace (např `${workspaceFolder}/bin/Debug/net8.0-windows10.0.22621`. ). Pokud není nastavená, zobrazí se výzva k výběru složky.
`manifest`	řetězec		Cesta k souboru manifestu AppX (např `AppxManifest.xml`. , `Package.appxmanifest`, nebo `appxmanifest.xml`). Pokud není nastavené, rozhraní příkazového řádku automaticky rozpozná ze vstupní složky nebo aktuálního adresáře.
`debuggerType`	řetězec	`coreclr`	Základní ladicí program, který se má použít (`coreclr`, `cppvsdbg`nebo `node`).
`workingDirectory`	řetězec	složka pracovního prostoru	Pracovní adresář pro aplikaci
`args`	řetězec		Argumenty příkazového řádku, které se předávají aplikaci.
`outputAppxDirectory`	řetězec		Výstupní adresář balíčku s volným uspořádáním Výchozí je složka `AppX` uvnitř vstupní složky.
`port`	Číslo	`9229`	(`node` pouze) Port použitý pro naslouchací port Node.js `--inspect` a navázání připojení. Předčíst, pokud je výchozí port již používán.

Podporované ladicí programy

`debuggerType`	Jazyk	Požadované rozšíření
`coreclr` (výchozí)	C# / .NET	C# Dev Kit
`cppvsdbg`	C / C++	C/C++
`node`	Node.js / Elektron	Integrovaný

Příklad projektu C++:

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

Ladění při spuštění s použitím funkce Create Debug Identity

Pokud potřebujete ladit úvodní kód od první instrukce, metoda ladění pomocí F5 může vynechat kód na začátku. Místo toho použijte příkaz WinApp: Vytvoření identity ladění z palety příkazů (Ctrl+Shift+P) k registraci řídkého balíčku pro váš spustitelný soubor a pak ho spusťte pomocí standardního ladicího programu:

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

Vzhledem k tomu, že create-debug-identity registruje identitu na samotném souboru exe, má aplikace identitu bez ohledu na to, jak je spuštěna — včetně případů, kdy je spuštěna pomocí standardní konfigurace spuštění ve VS Code.

Připojení ke spuštěnému procesu

Pokud chcete spustit z winapp run terminálu a pak připojit, použijte standardní konfiguraci připojení:

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

Pro C++/Rust použijte "type": "cppvsdbg" (MSVC) nebo "type": "lldb" (LLDB):

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

Vyčištění

Po dokončení testování spusťte WinApp: Zrušit registraci balíčku z Příkazové palety, abyste odstranili vývojové balíčky nahrané sideloadingem, aniž byste opustili VS Code.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-08-19