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.

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

VS Code

Rozšíření WinApp VS Code nabízí speciální winapp typ ladění, který spustí vaši aplikaci s identitou balíčku a připojí ladicí program – to vše jediným stiskem F5.

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-05-12