Dokumentace a využití rozhraní příkazového řádku

Dokončování prostředí

Povolte dokončování tabulátoru pro příkazy, možnosti a hodnoty. Pokyny k nastavení najdete v průvodci dokončováním prostředí .

# Quick setup for PowerShell (permanent — add to profile)
winapp complete --setup powershell >> $PROFILE

# Or try it in the current session only
winapp complete --setup powershell | Out-String | Invoke-Expression

inicializace

Inicializace adresáře pomocí sady Windows SDK, Windows App SDK a požadovaných prostředků pro moderní vývoj pro Windows

winapp init [base-directory] [options]

argumenty :

• base-directory – Základní/kořenový adresář pro aplikaci nebo pracovní prostor (výchozí: aktuální adresář)

Možnosti:

• --config-dir <path> - Konfigurace pro čtení a ukládání adresáře (výchozí: aktuální adresář)
• --setup-sdks – Režim instalace sady SDK: stabilní (výchozí), Preview, experimentální nebo none (přeskočení instalace sady SDK)
• --ignore-config, --no-config – Nepoužívejte konfigurační soubor pro správu verzí
• --no-gitignore – Neaktualizovat soubor .gitignore
• --use-defaults, --no-prompt – Nevybídejte výzvu a použijte výchozí nastavení všech výzev.
• --config-only - Zpracování pouze operací konfiguračního souboru, přeskočení instalace balíčku

Co to dělá:

• Vytvoří winapp.yaml konfigurační soubor (pouze v případech, kdy jsou spravované balíčky SDK, přeskočeno --setup-sdks nonepomocí )
• Stáhne balíčky Windows SDK a Windows App SDK.
• Generuje hlavičky a binární soubory C++/WinRT.
• Vytvoří Package.appxmanifest.
• Nastaví nástroje sestavení a povolí vývojářský režim.
• Aktualizuje soubor .gitignore, aby se vygenerované soubory vyloučily.
• Ukládá sdílené soubory v adresáři globální mezipaměti.

Automatická detekce projektů .NET:

Když se v cílovém adresáři nachází soubor .csproj, init používá zjednodušený tok specifický pro .NET:

• Ověří a aktualizuje TargetFramework na TFM kompatibilní s Windows (např. net10.0-windows10.0.26100.0).
• Přidá Microsoft.WindowsAppSDK a Microsoft.Windows.SDK.BuildTools jako položky NuGet PackageReference přímo v .csproj
• Generuje Package.appxmanifest, prostředky a vývojový certifikát.
• Nevytváří ani nestahuje projekce jazyka C++ (pro balíčky NuGet použijte winapp.yaml).

Příklady:

# Initialize current directory
winapp init

# Initialize with experimental packages
winapp init --setup-sdks experimental

# Initialize specific directory without prompts
winapp init ./my-project --use-defaults

# Initialize a .NET project (auto-detected from .csproj)
cd my-dotnet-app
winapp init

Tip: Instalace sad SDK po počáteční instalaci

Pokud jste spustili init--setup-sdks none (nebo přeskočili instalaci sady SDK) a později budete potřebovat sady SDK:

# Re-run init to install SDKs - preserves existing files (manifest, etc.)
winapp init --use-defaults --setup-sdks stable

Použijte --setup-sdks preview nebo --setup-sdks experimental pro verze Preview nebo experimentální sady SDK.

obnovení

Obnovte balíčky a znovu vygenerujte soubory na základě stávající winapp.yaml konfigurace.

winapp restore [options]

Možnosti:

• --config-dir <path> – Adresář obsahující winapp.yaml (výchozí: aktuální adresář)

Co to dělá:

• Přečte existující winapp.yaml konfiguraci.
• Stahuje/aktualizuje balíčky SDK na zadané verze
• Znovu vygeneruje hlavičky a binární soubory C++/WinRT.
• Ukládá sdílené soubory v adresáři globální mezipaměti.

Příklady:

# Restore from winapp.yaml in current directory
winapp restore

aktualizace

Aktualizujte balíčky na nejnovější verze a aktualizujte konfigurační soubor.

winapp update [options]

Možnosti:

• --setup-sdks <stable|preview|experimental|none> – Režim instalace sady SDK: stable (výchozí), preview, experimentalnebo none (přeskočit instalaci sady SDK)

Co to dělá:

• Přečte existující winapp.yaml konfiguraci v aktuálním adresáři.
• Aktualizuje všechny balíčky na nejnovější dostupné verze.
• Aktualizuje soubor winapp.yaml s novými čísly verzí.
• Znovu vygeneruje hlavičky a binární soubory C++/WinRT.

Příklady:

# Update packages to latest versions
winapp update

# Update including experimental packages
winapp update --setup-sdks experimental

pack

Vytvořte balíčky MSIX z připravených adresářů aplikací. Vyžaduje, aby se soubor manifestu (Package.appxmanifest upřednostňovaný, appxmanifest.xml podporovaný) vyskytoval v cílovém adresáři, v aktuálním adresáři nebo předal s --manifest možností. (spuštění init nebo manifest generate vytvoření manifestu)

winapp pack <input-folder> [options]

argumenty :

• input-folder - Adresář obsahující soubory aplikace k zabalení

Možnosti:

• --output <filename> – Název výstupního souboru MSIX (výchozí nastavení: <name>_<version>_<arch>.msixnávrat zpět <name>_<version>.msixna , <name>_<arch>.msixnebo <name>.msix pokud nelze určit verzi/arch)
• --name <name> – Název balíčku (výchozí hodnota: z manifestu)
• --manifest <path> - Cesta k souboru manifestu (Package.appxmanifest upřednostňovaný, appxmanifest.xml také podporovaný; výchozí: auto-detect)
• --cert <path> – Cesta k podpisovým certifikátům (umožňuje automatické podepisování)
• --cert-password <password> - Heslo certifikátu (výchozí: "heslo")
• --generate-cert – Vygenerování nového vývojového certifikátu
• --install-cert – Instalace certifikátu do počítače
• --publisher <name> – název Publisher pro generování certifikátů
• --self-contained – modul runtime Windows App SDK sady prostředků
• --skip-pri - Přeskočit generování souborů PRI
• --executable <path> - Cesta ke spustitelnému souboru vzhledem ke vstupní složce (také --exe). Slouží k vyřešení $targetnametoken$ zástupných symbolů v manifestu.

Co to dělá:

• Ověřuje a zpracovává soubory Package.appxmanifest.
• $placeholder$ Řeší tokeny v manifestu (viz zástupné symboly manifestu níže).
• Zajišťuje správné rámcové závislosti.
• Aktualizace paralelních manifestů s registracemi
• Automaticky zjistí komponenty WinRT třetích stran a zaregistruje jejich aktivační třídy (viz níže zjišťování komponent WinRT ).
• Zpracovává samostatné nasazení WinAppSDK.
• Podepíše balíček, pokud je zadaný certifikát.

Zjišťování komponent WinRT

Při balení winapp pack automaticky prohledá balíčky NuGet definované v komponentách winapp.yaml WinRT nebo *.csproj jiných výrobců (např. Win2D). Analyzuje .winmd soubory, aby extrahovali aktivovatelné názvy tříd a vyhledali jejich implementace knihovny DLL. Zjištěné položky jsou registrovány takto:

• Závislé na rozhraní (výchozí): Aktivační třídy jsou přidány jako <InProcessServer> položky v Package.appxmanifest
• Samostatné (--self-contained): Aktivační třídy jsou vloženy do souběžných manifestů (SxS) v rámci spustitelného souboru.

Rozlišení zástupného symbolu během balení:

Pokud manifest obsahuje $targetnametoken$ v atributu Executable :

1. Pokud --executable je zadána (cesta vzhledem ke vstupní složce), zástupný symbol se nahradí zadanou hodnotou.
2. winapp pack Jinak prohledá kořenový adresář vstupní složky pro .exe soubory – pokud je nalezena přesně jedna, použije se automaticky.
3. Pokud se najde nula nebo více .exe souborů, zobrazí se chyba s výzvou k zadání. --executable

Příklady:

# Package directory with auto-detected manifest
winapp pack ./dist

# Package with custom output name and certificate
winapp pack ./dist --output MyApp.msix --cert ./cert.pfx

# Package with generated and installed certificate and self-contained WinAppSDK runtime
winapp pack ./dist --generate-cert --install-cert --self-contained

# Package with explicit executable (resolves $targetnametoken$ in manifest)
winapp pack ./dist --executable MyApp.exe

create-debug-identity

Vytvořte identitu aplikace pro ladění pomocí řídkého balení. Exe zůstane v původním umístění – Windows k němu přidruží identitu prostřednictvím Add-AppxPackage -ExternalLocation.

Kdy použít tento vs winapp run: Použijte create-debug-identity , když je exe oddělený od kódu vaší aplikace (např. Elektron aplikace, kde electron.exe je node_modules) nebo při konkrétně testování řídké chování balíčku. Pro většinu architektur, kde exe je ve výstupní složce sestavení, použijte winapp run místo toho – zaregistruje úplný volný balíček rozložení a spustí aplikaci. Úplné porovnání najdete v průvodci laděním .

winapp create-debug-identity [entrypoint] [options]

argumenty :

• entrypoint – Cesta ke spustitelnému souboru (.exe) nebo skriptu, který potřebuje identitu

Možnosti:

• --manifest <path> – Cesta k souboru manifestu aplikace nebo Package.appxmanifestappxmanifest.xml (výchozí nastavení: automatické rozpoznání Package.appxmanifest nebo appxmanifest.xml v aktuálním adresáři)
• --no-install – Po vytvoření balíček neinstalujte.
• --keep-identity – Ponechte as-isidentity manifestu bez připojení .debug k názvu balíčku a ID aplikace.

Co to dělá:

• Upraví souběžný manifest spustitelného souboru.
• Zaregistruje balíček s řídkou strukturou pro digitální identitu.
• Umožňuje ladění rozhraní API vyžadujících identitu.

Příklady:

# Add identity to executable using local manifest
winapp create-debug-identity ./bin/MyApp.exe

# Add identity with custom manifest location
winapp create-debug-identity ./dist/app.exe --manifest ./custom-manifest.xml

# Create identity for hosted app script
winapp create-debug-identity app.py

manifest

Generování a správa souborů Package.appxmanifest

generování manifestu

Vygenerujte Package.appxmanifest ze šablon.

winapp manifest generate [directory] [options]

argumenty :

• directory - Adresář pro generování manifestu (výchozí: aktuální adresář)

Možnosti:

• --package-name <name> – Název balíčku (výchozí: název složky)
• --publisher-name <name> – Publisher CN (výchozí hodnota: CN=<current user>)
• --version <version> – Verze (výchozí hodnota: 1.0.0.0)
• --description <text> - Popis (výchozí hodnota: Moje aplikace)
• --entrypoint <path> – Spustitelný soubor vstupního bodu nebo skript
• --template <type> - Typ šablony: packaged (výchozí) nebo sparse
• --logo-path <path> - Cesta k souboru obrázku loga
• --if-exists <Error|Overwrite|Skip> - Chování, pokud soubor manifestu již existuje v cílové cestě (výchozí: Error)

Šablony:

• packaged – Manifest balené aplikace úrovně Standard
• sparse – Manifest aplikace využívající řídké nebo externí umístění balení

Zástupné symboly manifestu

Vygenerované manifesty používají $placeholder$ tokeny (ohraničené znakem dolaru), které se automaticky vyřeší během balení.

To se řídí stejnou konvencí používanou Visual Studio šablonami projektů, takže manifesty jsou přenositelné napříč nástroji.

Způsob řešení zástupných symbolů:

• winapp pack — Při balení $targetnametoken$ se přeloží pomocí --executable možnosti nebo automatického rozpoznání jediné .exe složky ve vstupní složce. Pokud se najde více (nebo nula) .exe souborů a --executable není zadáno, zobrazí se chyba.
• winapp create-debug-identity — Pokud je zadaný argument vstupního bodu, $targetnametoken$ je z něj vyřešen. Bez vstupního bodu musí být zástupný symbol spustitelného souboru již vyřešen v manifestu.
• winapp manifest generate --executable — Pokud --executable je k dispozici, metadata manifestu (verze, popis) a ikony se extrahují ze spustitelného souboru, ale vygenerovaný manifest se stále používá $targetnametoken$.exe; tento zástupný symbol se přeloží později (např. winapp pack nebo winapp create-debug-identity).

PS: Udržování $targetnametoken$ v manifestu vrácení se změnami zabraňuje pevnému kódování spustitelných názvů a funguje s sestaveními winapp pack i Visual Studio.

Příklady:

# Generate standard manifest interactively
winapp manifest generate

# Generate with all options specified
winapp manifest generate ./src --package-name MyApp --publisher-name "CN=My Company" --if-exists overwrite

alias doplňku manifestu

Přidejte alias spuštění (uap5:AppExecutionAlias) do Package.appxmanifest. To umožňuje spuštění zabalené aplikace z příkazového řádku zadáním názvu aliasu.

winapp manifest add-alias [options]

Možnosti:

• --name <alias> - Název aliasu (např. myapp.exe). Výchozí hodnota: Odvozeno z atributu Executable v manifestu.
• --manifest <path> - Cesta k Package.appxmanifest (výchozí: prohledávat aktuální adresář)
• --app-id <id> – ID aplikace pro přidání aliasu (výchozí: první prvek aplikace)

Co to dělá:

• Přečte manifest a odvodí alias z atributu Executable (zachová zástupné symboly jako $targetnametoken$.exe).
• uap5 Přidá deklaraci oboru názvů, pokud ještě není k dispozici.
• <Extensions> Přidá blok s <uap5:AppExecutionAlias> uvnitř cílového elementu aplikace.
• Pokud už alias existuje, nahlásí ho a úspěšně se ukončí.

Příklady:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifest aktualizace-aktiv

Vygenerujte všechny požadované soubory MSIX z jednoho zdrojového obrazu.

winapp manifest update-assets <image-path> [options]

argumenty :

• image-path - Cesta ke zdrojovému souboru obrázku (PNG, JPG, SVG, ICO, GIF, BMP atd.)

Možnosti:

• --manifest <path> – Cesta k souboru Package.appxmanifest (výchozí: prohledávat aktuální adresář)
• --light-image <path> - Cesta k samostatnému zdrojovému obrázku pro světlé varianty motivu

Description:

Vezme jednu zdrojovou image a vygeneruje komplexní sadu prostředků image MSIX na základě odkazů na prostředky manifestu:

Pro každý prostředek odkazovaný v manifestu:

• 5 variant škálování – základ (bez přípony), .scale-125, .scale-150, , .scale-200.scale-400

Ikona aplikace (Square44x44Logo / AppList, 44×44 base):

• 14 lícených cílových variant — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14 neplatifikovaných cílových variant – .targetsize-{size}_altform-unplated

Additionally:

• app.ico – soubor ICO s více rozlišením (16, 24, 32, 48, 256) pro integraci prostředí. Pokud se existující .ico soubor nachází v adresáři prostředků (např. AppIcon.ico ze šablony projektu), nahradí se místo vytvoření duplicitního souboru.

Pomocí --light-image:

• Světlý motiv cílí na varianty – .targetsize-{size}_altform-lightunplated (ikona aplikace)
• Světlé varianty měřítka motivu – .scale-{factor}_altform-colorful_theme-light (dlaždice, logo obchodu)

Podpora SVG: Soubory SVG jsou plně podporované jako zdrojové image. Jsou vykresleny jako vektory přímo v každé cílové velikosti, což vytváří výsledky perfektních pixelů ve všech rozlišeních.

Příkaz škáluje obrázky úměrně při zachování poměru stran a v případě potřeby je zacentruje s průhlednými pozadími. Prostředky se ukládají do Assets adresáře vzhledem k umístění manifestu.

Příklady:

# Generate assets with auto-detected manifest
winapp manifest update-assets mylogo.png

# Use an SVG source for best quality at all sizes
winapp manifest update-assets mylogo.svg

# Specify manifest location explicitly
winapp manifest update-assets mylogo.png --manifest ./dist/Package.appxmanifest

# Generate light theme variants from a separate image
winapp manifest update-assets mylogo.png --light-image mylogo-light.png

# Use the same image for both (generates all MRT light theme qualifiers)
winapp manifest update-assets mylogo.png --light-image mylogo.png

# With verbose output
winapp manifest update-assets mylogo.png --verbose

provozovat

Vytvořte volný balíček rozložení z výstupní složky sestavení, zaregistrujte ho v Windows pomocí rozhraní API Windows.Management.Deployment.PackageManager a spusťte aplikaci – simuluje úplnou instalaci MSIX pro ladění. Vrátí ID procesu pro přílohu ladicího programu.

This je upřednostňovaným příkazem pro ladění s identitou balíčku pro většinu architektur (.NET, C++, Rust, Flutter, Tauri). Na rozdíl od create-debug-identity toho, který registruje řídký balíček pro jeden exe, winapp run zaregistruje celou složku jako volný balíček rozložení, stejně jako skutečná instalace MSIX. Běžné pracovní postupy ladění najdete v průvodci laděním .

winapp run <input-folder> [options]

argumenty :

• input-folder – Adresář obsahující aplikaci ke spuštění (povinné)

Možnosti:

• --manifest <path> - Cesta k Package.appxmanifest (výchozí: autodetekce ze vstupní složky nebo aktuálního adresáře)
• --output-appx-directory <path> - Výstupní adresář pro volný balíček rozložení (výchozí: AppX uvnitř adresáře vstupní složky)
• --args <string> – Argumenty příkazového řádku, které se předávají aplikaci. Případně použijte -- argumenty následované argumenty, abyste se vyhnuli escapingu (např winapp run . -- --flag value. ).
• --no-launch – Vytvořte pouze identitu ladění a zaregistrujte balíček bez spuštění aplikace.
• --with-alias – Spusťte aplikaci pomocí svého aliasu spuštění místo aktivace AUMID. Aplikace běží v aktuálním terminálu s zděděným stdin/stdout/stderr. uap5:ExecutionAlias Vyžaduje v manifestu (použijte winapp manifest add-alias ho k přidání). Nelze kombinovat s --no-launch. Nelze kombinovat s --json.
• --debug-output - Zachyťte OutputDebugString zprávy a výjimky první šance ze spuštěné aplikace. Šum rozhraní (WinUI, COM, DirectX) je filtrován z výstupu konzoly; celý soubor protokolu zachytí všechno. Pokud dojde k chybovému ukončení aplikace, automaticky zachytí minidump a analyzuje ho, aby zobrazil typ výjimky, zprávu a trasování zásobníku se zdrojovým souborem:řádkovými čísly (vyřešenými z souborů PDB ve výstupní složce sestavení). Spravované (.NET) se analyzují okamžitě bez externích nástrojů. V nativních chybových ukončeních (C++/WinRT) se zobrazují názvy modulů a posuny. Současně se k procesu může připojit jenom jeden ladicí program, takže ostatní ladicí programy (Visual Studio, VS Code) se nedají používat současně. Místo toho použijte --no-launch , pokud potřebujete připojit jiný ladicí program. Nelze kombinovat s --no-launch. Nelze kombinovat s --json.
• --symbols – Stáhněte si symboly PDB ze serveru symbolů Microsoft pro bohatší nativní analýzu chybových ukončení s vyřešenými názvy funkcí. Používá se pouze s --debug-output. Pokud se vynechá a dojde k nativnímu chybovému ukončení, výstup navrhne přidání tohoto příznaku. Nejprve spusťte symboly stahování a místně je ukládá do mezipaměti; následující spuštění používají mezipaměť.
• --unregister-on-exit - Zrušení registrace vývojového balíčku po ukončení aplikace. Odebere pouze balíčky zaregistrované ve vývojovém režimu. Nelze kombinovat s --no-launch.
• --detach - Spusťte aplikaci a vraťte se okamžitě, aniž byste čekali na jeho ukončení. Užitečné pro CI/automatizaci, kde potřebujete po spuštění pracovat s aplikací. Vytiskne PID do stdoutu (nebo ve formátu JSON pomocí --json). Nelze kombinovat s --no-launch, --debug-output, --with-aliasnebo --unregister-on-exit.
• --clean – Před opětovným nasazením odeberte data aplikace existujícího balíčku (LocalState, settings atd.). Ve výchozím nastavení se data aplikací zachovají napříč opětovným nasazením.
• --json – Formátovat výstup jako JSON pro programovou spotřebu (např. CI/automation). Užitečné při --detach zachycení PID. Nelze kombinovat s --with-alias nebo --debug-output.

Trvalost dat aplikace:

Ve výchozím nastavení winapp run zachová data vaší aplikace (LocalState, RoamingStateSettings, atd.) při opětovném nasazení. Pokud vaše aplikace zapisuje data do ApplicationData.Current.LocalFolder kontextu balíčku nebo Environment.GetFolderPath(SpecialFolder.LocalApplicationData) v rámci balíčku, přežijí se napříč winapp run vyvoláním.

Použijte --clean , když potřebujete nové spuštění (např. k resetování poškozeného stavu nebo testování chování při prvním spuštění).

Co to dělá:

• Vyhledá nebo vygeneruje Package.appxmanifest.
• Vytvoří a zaregistruje identitu ladění pomocí volného balíčku rozložení.
• Vypočítá ID modelu uživatele aplikace (AUMID).
• Spustí aplikaci pomocí registrované identity (pokud --no-launch není zadána).
• Vytiskne ID procesu (PID) pro přílohu ladicího programu.

Příklady:

# Register debug identity and launch app from build output
winapp run ./bin/Debug

# Launch with custom manifest and arguments
winapp run ./dist --manifest ./out/Package.appxmanifest --args "--my-flag value"

# Pass arguments after -- to avoid escaping (equivalent to --args)
winapp run ./bin/Debug -- --my-flag value

# Specify output directory for loose layout package
winapp run ./bin/Release --output-appx-directory ./AppXDebug

# Register identity without launching
winapp run ./bin/Debug --no-launch

# Launch via execution alias (console apps run in current terminal)
winapp run ./bin/Debug --with-alias

# Launch and capture OutputDebugString messages and crash diagnostics
winapp run ./bin/Debug --debug-output

# Download native symbols for richer crash analysis (C++/WinRT crashes)
winapp run ./bin/Debug --debug-output --symbols

# Combine with execution alias to debug console apps inline
winapp run ./bin/Debug --with-alias --debug-output

# Run and automatically clean up registration on exit
winapp run ./bin/Debug --with-alias --unregister-on-exit

# Launch and detach immediately (useful for CI/automation)
winapp run ./bin/Debug --detach

# Detach with JSON output (returns PID for scripting)
winapp run ./bin/Debug --detach --json

# Wipe application data (LocalState, settings) and start fresh
winapp run ./bin/Debug --clean

Vlastnosti NÁSTROJE MSBuild (balíček NuGet):

Při použití balíčku NuGet Microsoft.Windows.SDK.BuildTools.WinAppdotnet run automaticky vyvolá winapp run. Následující vlastnosti nástroje MSBuild lze nastavit v .csproj řízení chování:

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Zrušit registraci

Zrušení registrace zkušebního vývojového balíčku Odebere pouze balíčky zaregistrované ve vývojovém režimu (např. prostřednictvím winapp run nebo create-debug-identity). Balíčky nainstalované v úložišti nebo nainstalované MSIX se nikdy neodeberou.

winapp unregister [options]

Možnosti:

• --manifest <path> – Cesta k Package.appxmanifest (výchozí: autodetekce z aktuálního adresáře)
• --force - Přeskočte kontrolu adresáře umístění instalace a zrušte registraci i v případě, že byl balíček zaregistrován z jiného stromu projektu.
• --json – Formátování výstupu ve formátu JSON

Co to dělá:

• Přečte název balíčku z manifestu.
• Vyhledá jak balíčky, {name}.debug tak {name} balíčky (varianta ladění je vytvořená pomocí create-debug-identity)
• Ověřuje, jestli byl každý balíček zaregistrovaný ve vývojovém režimu (IsDevelopmentMode == true).
• Ověří umístění instalace balíčku v aktuálním adresářovém stromu (pokud --force)
• Zrušení registrace odpovídajících balíčků

Příklady:

# Unregister from current directory (auto-detects manifest)
winapp unregister

# Unregister with explicit manifest
winapp unregister --manifest ./Package.appxmanifest

# Force unregister even if registered from a different project tree
winapp unregister --force

# JSON output for scripting
winapp unregister --json

cert

Generování, kontrola a instalace vývojových certifikátů

Generování certifikátu

Generování vývojových certifikátů pro podepisování balíčků

winapp cert generate [options]

Možnosti:

• --manifest <Package.appxmanifest> – Extrahování informací o vydavateli z Package.appxmanifest
• --publisher <name> – název Publisher certifikátu
• --output <path> – Výstupní cesta k souboru certifikátu (podporuje absolutní a relativní cesty)
• --password <password> - Heslo certifikátu (výchozí: "heslo")
• --valid-days <valid-days> – Počet dnů platnosti certifikátu (výchozí hodnota: 365)
• --install – Nainstalujte certifikát do úložiště místního počítače po generování.
• --if-exists <Error|Overwrite|Skip> – Nastavení chování, pokud soubor certifikátu již existuje (výchozí: Chyba)
• --export-cer - Exportujte .cer soubor (pouze veřejný klíč) vedle .pfxsouboru . Užitečné pro distribuci veřejného certifikátu samostatně pro instalaci důvěryhodnosti.
• --json – Formátovat výstup jako JSON pro programovou spotřebu. Chyby se vrátí také jako JSON ({"error": "..."}).

Informace o certifikátu

Zobrazí podrobnosti certifikátu ze souboru PFX. Užitečné pro ověření, že certifikát odpovídá vašemu manifestu před podepsáním.

winapp cert info <cert-path> [options]

argumenty :

• cert-path – Cesta k souboru certifikátu (PFX)

Možnosti:

• --password <password> - Heslo pro soubor PFX (výchozí: "heslo")
• --json – Formátování výstupu ve formátu JSON

Instalace certifikátu

Nainstalujte certifikát do úložiště certifikátů počítače.

winapp cert install <cert-path> [options]

argumenty :

• cert-path – Cesta k souboru certifikátu k instalaci

Příklady:

# Generate certificate for specific publisher
winapp cert generate --publisher "CN=My Company" --output ./mycert.pfx

# Generate certificate and export public key .cer file
winapp cert generate --publisher "CN=My Company" --export-cer

# Generate certificate with JSON output (for scripting)
winapp cert generate --publisher "CN=My Company" --json

# View certificate details
winapp cert info ./mycert.pfx

# View certificate details as JSON
winapp cert info ./mycert.pfx --json

# Install certificate to machine
winapp cert install ./mycert.pfx

znak

Podepište balíčky MSIX a spustitelné soubory pomocí certifikátů.

winapp sign <file-path> [options]

argumenty :

• file-path – Cesta k balíčku MSIX nebo spustitelnému souboru pro podepsání

Možnosti:

• --cert <path> - Cesta k podpisovým certifikátům
• --cert-password <password> - Heslo certifikátu (výchozí: "heslo")

Příklady:

# Sign MSIX package
winapp sign MyApp.msix --cert ./mycert.pfx

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

create-external-catalog

CodeIntegrityExternal.cat Vygenerujte soubor katalogu obsahující hodnoty hash spustitelných souborů ze zadaných adresářů. Tento katalog se používá s příznakem TrustedLaunch v manifestech balíčku MSIX (AllowExternalContent), aby bylo možné provádět externí soubory, které nejsou zahrnuty v samotném balíčku.

Podobá se tomu, jak signtool.exe se vytvoří AppxMetadata\CodeIntegrity.cat při podepisování balíčku MSIX, ale vygeneruje externí katalog pro použití s řídkým nebo externím umístěním.

winapp create-external-catalog <input-folder> [options]

argumenty :

• input-folder – Jeden nebo více adresářů obsahujících spustitelné soubory ke zpracování. Oddělte více adresářů středníky (např. "dir1;dir2")

Možnosti:

• --recursive, -r – Zahrnutí souborů z podadresářů
• --use-page-hashes - Zahrnout hodnoty hash stránek při generování katalogu (vytvoří větší katalog s daty hash jednotlivých stránek)
• --compute-flat-hashes - Při generování katalogu zahrňte hodnoty hash plochých souborů.
• --if-exists <Error|Overwrite|Skip> - Chování, pokud výstupní soubor již existuje (výchozí: Error)
• --output, -o – Cesta k souboru výstupního katalogu. Pokud není zadaný, CodeIntegrityExternal.cat vytvoří se v aktuálním adresáři. Pokud je zadaný adresář, připojí se výchozí název souboru.

Co to dělá:

• Prohledá zadané adresáře pro spustitelné soubory (binární soubory PE s oddíly kódu).
• Vygeneruje soubor definice katalogu (CDF) s hodnotami hash všech nalezených spustitelných souborů.
• Používá rozhraní API Windows CryptoCAT k vytvoření souboru katalogu .cat.
• Nespustitelné soubory (např .txt. bez .dll oddílů kódu) se automaticky přeskočí.

Příklady:

# Generate catalog for all executables in a directory
winapp create-external-catalog ./bin

# Include files in subdirectories
winapp create-external-catalog ./bin --recursive

# Specify a custom output path
winapp create-external-catalog ./bin --output ./dist/CodeIntegrityExternal.cat

# Overwrite existing catalog
winapp create-external-catalog ./bin --if-exists Overwrite

# Skip generation if catalog already exists
winapp create-external-catalog ./bin --if-exists Skip

# Include page hashes (for stricter code integrity validation)
winapp create-external-catalog ./bin --use-page-hashes

# Process multiple directories
winapp create-external-catalog "./bin;./lib" --recursive

# Combine multiple options
winapp create-external-catalog ./bin --recursive --use-page-hashes --compute-flat-hashes --output ./dist/CodeIntegrityExternal.cat --if-exists Overwrite

Kdy použít:

Tento příkaz použijte při vytváření řídkého balíčku MSIX, který k ověření externích spustitelných souborů používá TrustedLaunch. Typický pracovní postup je:

1. winapp manifest generate --template sparse — Vytvoření řídké manifestu pomocí AllowExternalContent
2. winapp create-external-catalog ./bin — Generování katalogu integrity kódu pro spustitelné soubory vaší aplikace
3. winapp pack — Zabalte manifest, prostředky a katalog do MSIX.

nástroj

Přistupujte k nástrojům sady Windows SDK přímo. Používá nástroje dostupné v Microsoft.Windows. SDK. BuildTools

winapp tool <tool-name> [tool-arguments]

Dostupné nástroje:

• makeappx – Vytváření a manipulace s balíčky aplikací
• signtool - Podepisovat soubory a ověřovat podpisy
• mt - Nástroj manifestu pro souběžná sestavení
• A další nástroje sady Windows SDK z Microsoft.Windows. SDK. BuildTools

Příklady:

# Use signtool to verify signature
winapp tool signtool verify /pa MyApp.msix

uložit

Spusťte příkaz rozhraní příkazového řádku pro vývojáře v Microsoft Storu. Tento příkaz stáhne rozhraní příkazového řádku pro vývojáře Microsoft Store, pokud ještě není staženo. Přečtěte si další informace o rozhraní příkazového řádku pro vývojáře Microsoft Store.

winapp store [args...]

argumenty :

• args... – Argumenty, které se mají předat přímo do rozhraní příkazového msstore řádku. Dostupné příkazy a možnosti najdete v dokumentaci k rozhraní příkazového řádku MSStore .

Co to dělá:

• Zajišťuje, že se rozhraní příkazového řádku pro vývojáře Microsoft Store (msstore) stáhne a zpřístupní ve vašem systému.
• Přepošla všechny argumenty do rozhraní příkazového msstore řádku.
• Spustí příkaz zobrazující výstup přímo v terminálu.

Příklady:

# List all apps in your Microsoft Partner Center account
winapp store app list

# Publish a package to the Microsoft Store
winapp store publish ./myapp.msix --appId <your-app-id>

get-winapp-path

Získejte cesty k nainstalovaným komponentám sady Windows SDK.

winapp get-winapp-path [options]

Co vrátí:

• Cesty k .winapp adresáři pracovního prostoru
• Instalační adresáře balíčků
• Generovaná umístění hlaviček

node create-addon

(k dispozici pouze v balíčku NPM) Generování nativních šablon doplňků C++ nebo C# se sadou Windows SDK a integrací Windows App SDK.

npx winapp node create-addon [options]

Možnosti:

• --name <name> – Název doplňku (výchozí hodnota: nativeWindowsAddon)
• --template - Vyberte typ doplňku. Možnosti jsou cs nebo cpp (výchozí: cpp)
• --verbose – Povolení podrobného výstupu

Co to dělá:

• Vytvoří adresář doplňků se soubory šablon.
• Generuje binding.gyp a addon.cc s příklady sady Windows SDK.
• Nainstaluje požadované závislosti npm (nan, node-addon-api, node-gyp).
• Přidá skript sestavení do package.json

Příklady:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

node add-elektron-debug-identity

(K dispozici pouze v balíčku NPM) Přidání identity aplikace do vývojového procesu Elektron pomocí zhuštěné balení Vyžaduje Package.appxmanifest (vytvořte ho nebo winapp initwinapp manifest generate pokud ho nemáte).

npx winapp node add-electron-debug-identity [options]

Možnosti:

Co to dělá:

• Zaregistruje identitu ladění pro proces electron.exe.
• Umožňuje testování rozhraní API vyžadujících identitu ve vývoji elektronů.
• Používá existující Package.appxmanifest pro konfiguraci identity.

Příklady:

# Add identity to Electron development process
npx winapp node add-electron-debug-identity

# Use a custom manifest file
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node clear-elektron-debug-identity

(K dispozici pouze v balíčku NPM) Odeberte identitu balíčku z procesu ladění Elektron obnovením původního electron.exe ze zálohy.

npx winapp node clear-electron-debug-identity [options]

Možnosti:

Co to dělá:

• Obnoví electron.exe ze zálohy vytvořené pomocí add-electron-debug-identity
• Odebere záložní soubory po obnovení.
• Vrátí elektron do původního stavu bez identity balíčku.

Příklady:

# Remove identity from Electron development process
npx winapp node clear-electron-debug-identity

Globální možnosti

Všechny příkazy podporují tyto globální možnosti:

• --verbose, -v – Povolení podrobného výstupu pro podrobné protokolování
• --quiet, -q – Potlačení zpráv o průběhu
• --help, -h – Zobrazit nápovědu k příkazu

Adresář globální mezipaměti

Winapp vytvoří adresář pro ukládání souborů do mezipaměti, které se dají sdílet mezi více projekty.

Ve výchozím nastavení winapp vytvoří adresář $UserProfile/.winapp jako globální adresář mezipaměti.

Pokud chcete použít jiné umístění, nastavte proměnnou WINAPP_CLI_CACHE_DIRECTORY prostředí.

V cmd:

REM Set a custom location for winapp's global cache
set WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

V PowerShellu a pwsh:

# Set a custom location for winapp's global cache
$env:WINAPP_CLI_CACHE_DIRECTORY=d:\temp\.winapp

Winapp vytvoří tento adresář automaticky, když spustíte příkazy jako init nebo restore.

Ui

Kontrola a interakce se spuštěnými uživatelskými rozhraními aplikace Windows pomocí model UI Automation (UIA).

winapp ui [command] [options]

Příkazy:

• status – Připojení k aplikaci a zobrazení informací
• inspect – Strom prvků zobrazení
• search - Najít prvky podle selektoru
• get-property – Čtení vlastností elementu
• get-text / get-value – Čtení hodnoty a textu z elementu (TextPattern, ValuePattern nebo Name)
• screenshot – Zachytávání okna nebo elementu ve formátu PNG (automaticky zachytává dialogy samostatně)
• invoke - Aktivovat prvek (kliknutí, přepínač, rozbalení)
• click - Klikněte na prvek prostřednictvím simulace myši (pro ovládací prvky, které nepodporují vyvolání)
• set-value - Nastavit hodnotu u upravitelného prvku (text, číslo)
• focus - Přesunutí fokusu klávesnice
• scroll-into-view – Viditelný prvek posuvníku
• wait-for – Čekání na stav elementu
• list-windows – Vypsat všechna okna pro aplikaci
• get-focused – Sestava aktuálně prioritního prvku

Možnosti:

• -a, --app <app> – Cílová aplikace (název, název nebo PID)
• -w, --window <hwnd> - Cílové okno podle HWND (stabilní)

Úplnou dokumentaci najdete v dokumentaci/ui-automation.md.