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
  • --exe <path> – Cesta ke spustitelnému souboru aplikace. Vyžaduje --sparse. Vygeneruje pouze řídký manifest identity pro exe místo úplného nastavení balíčku nebo sady SDK.
  • --sparse - Vygenerujte manifest řídké identity (appxmanifest.xml) pro existující desktopový exe. Přeskočí instalaci sady SDK nebo balíčku. Používejte s --exe.
  • --name <name> - Přepsat název balíčku (pouze řídký; výchozí: odvozeno z exe)
  • --publisher <CN> - Přepsat CN vydavatele (pouze zhuštěné; výchozí: odvozeno z názvu společnosti exe)
  • --output-dir <path> - Adresář pro zápis řídké manifestu a Assets/ (pouze řídký; výchozí: sparse/ složka v aktuálním adresáři)
  • --force - Přepište existující appxmanifest.xml v cílovém adresáři (pouze řídké). Bez něj se inicializaci nepodaří nahradit stávající manifest nebo prostředky.
  • --add-js-bindings (pouze npm) – Přidejte winapp.jsBindings do package.json a vygenerujte vazby JS/TypeScript bez výzvy (nekompatibilní s --setup-sdks none)

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.
  • Generuje vazby JS pro rozhraní API Windows App SDK, pokud je tato možnost povolená (pouze npm).

Automatická detekce projektů:

Při init spuštění bez argumentu adresáře provede první hledání aktuálního stromu adresáře a vyhledá kompatibilní projekty (až 10). Podporované typy projektů:

  • Tauri – tauri.conf.json našel jednu úroveň pod adresářem.
  • Elektron — package.json se electron závislostmi nebo devDependencies
  • Flutter – pubspec.yaml v kořenovém adresáři projektu
  • .NET – .csproj v kořenovém adresáři projektu
  • Rust – Cargo.toml v kořenovém adresáři projektu
  • C++ – CMakeLists.txt v kořenovém adresáři projektu

Hledání přeskočí běžně ignorované adresáře (node_modules, bin, obj, .git atd.). Pokud je nalezen kompatibilní projekt, podadresáře pod ním nejsou prohledána.

  • Pokud je zadaný argument adresáře (např. winapp init . nebo winapp init path/to/project), vyhledávání se přeskočí a init zkontroluje pouze tento adresář pro kompatibilní projekt.
  • Pokud --use-defaults je (nebo --no-prompt) nastavena bez argumentu adresáře, init přeskočí vyhledávání a inicializuje aktuální adresář neinteraktivně, upozornění nejprve, pokud tam není zjištěn žádný známý typ projektu (např. winapp init --use-defaults)
  • V neinteraktivních prostředích (piped stdin, CI, přesměrovaný vstup) init automaticky používá --use-defaults chování a vygeneruje upozornění: Non-interactive environment detected. Using default values.
  • Pokud je aktuální adresář kompatibilním projektem, init okamžitě pokračuje
  • Pokud se přesně jeden projekt najde jinde, zobrazí se výzva k potvrzení.
  • Pokud se najde více projektů, můžete vybrat, který z nich se má inicializovat – aktuální adresář je vždy k dispozici jako záložní možnost.
  • Pokud se nenašly žádné projekty, zobrazí se upozornění a zobrazí se dotaz, jestli chcete přesto pokračovat.
  • Pokud hledání dosáhne limitu 10 projektů, upozornění navrhne zadání argumentu adresáře.

Automatický tok projektu .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).

Režim řídké identity (--exe + --sparse):

Vygeneruje manifest balíčku jen pro řídký balíček identity pro existující spustitelný soubor plochy – první krok pracovního postupu řídkých balíčků. Na rozdíl od úplného init toku se tím přeskočí všechna instalace sady SDK/balíčku (řídké balíčky identit nemají žádné závislosti sady SDK) a vygeneruje pouze manifest a zástupné prostředky.

  • Odvodí název balíčku, vydavatele, popis a verzi z exe prostřednictvím FileVersionInfo (přepsání pomocí --name, --publishernebo interaktivně)
  • Zapisuje appxmanifest.xml (s názvem exe nahrazeným do Executable) a Assets/ složku do sparse/ složky v aktuálním adresáři (nebo --output-dir)
  • Používá --use-defaults/--no-prompt se k přeskočení interaktivních výzev k přepsání (popisné pro CI).
  • --exe bez --sparse chyby

Prostředky jsou externí. Řídké .msix je pouze identita: vygenerované jsou vyřešeny Assets/ z instalačního adresáře aplikace (umístění externího obsahu) za běhu, nikoli z balíčku ..msix Nasaďte je společně s vaší aplikací.

Další kroky po winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> sestavení identity .msix, pak winapp embed-identity <exe>. Úplný návod najdete v průvodci řídkým balením .

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

# Generate a sparse identity manifest for an existing exe (no SDK install)
winapp init --exe ./bin/Release/net8.0-windows/MyApp.exe --sparse --use-defaults

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.

Nové…

Vytvořte novou aplikaci WinUI z oficiální šablony Windows App SDKdotnet new. Interaktivní ve výchozím nastavení; automaticky používá výchozí hodnoty v neinteraktivních prostředích.

winapp new [options]

Možnosti:

  • -t, --template <short-name>- Krátký název šablony (např. winui, winui-navviewwinui-mvvm, winui-lib, , ). winui-unittest Ověřeno proti nainstalované sadě za běhu; Spuštěním příkazu winapp new --list zobrazíte vše. Výchozí hodnota: winui (prázdná aplikace).
  • -n, --name <name> - Název nové aplikace nebo projektu (výchozí hodnota: odvozená od --output, else WinUIApp)
  • -o, --output <path> - Adresář pro vytvoření aplikace v (výchozí: ./<name>)
  • --use-defaults, --no-prompt – Nevybídejte výzvu; používejte výchozí hodnoty (prázdná šablona, název od --output/--namea ponechejte nainstalovanou sadu šablon namísto aktualizace).
  • --force – Generování uživatelského rozhraní i v případě, že výstupní adresář již obsahuje soubory
  • --template-version <latest|installed|version> - Verze sady šablon WinUI: latest nainstaluje nejnovější publikovanou sadu, installed zachová, co už je staženo (bez sítě), nebo připne explicitní verzi, například 1.2.3. Výchozí nastavení: Nainstalujte nejnovější, pokud není k dispozici žádný balíček, jinak se zobrazí výzva k aktualizaci zastaralého balíčku (ponechte as-is pod --use-defaults).
  • --list – Vypsat dostupné šablony WinUI a ukončit (nejprve nainstaluje nejnovější balíček, pokud není nainstalován žádný)
  • --json – Formátování výstupu ve formátu JSON

Šablony:

Seznam šablon je přečtený živě z nainstalované sady, takže vždy odráží verzi, kterou máte – spuštěním zobrazíte winapp new --list aktuální sadu. Běžné šablony:

Krátký název Description
winui Minimální prázdná aplikace WinUI 3 (balení MSIX)
winui-navview Úvodní aplikace NavigationView
winui-tabview Úvodní aplikace TabView
winui-mvvm Aplikace MVVM (CommunityToolkit.Mvvm)
winui-lib Knihovna tříd WinUI 3
winui-unittest Zabalená aplikace MSTest; testy se spustí při spuštění

Kanonický krátký název každé šablony je prvním seznamem aliasů dotnet new . Všechny uvedené aliasy (např. winui3, wasdk-single) jsou také přijímány. Při spuštění uvnitř existujícího projektu dotnet new WinUI se také zobrazí šablony položek (např. prázdná stránka), které winapp new se přidají do aktuálního projektu, a ne do nového projektu.

Správa verzí sady šablon:

winapp new už nepřipne konkrétní verzi sady šablon. Pokud není nainstalována žádná sada, nainstaluje se nejnovější verze. Pokud už je starší sada nainstalovaná, zkontroluje informační kanál a pokud existuje novější, zobrazí výzvu k aktualizaci – s výjimkou neinteraktivních nebo--use-defaults spuštění, které udržují nainstalovanou sadu. Používejte --template-version latest vždy nejnovější verzi bez výzvy nebo --template-version installed vždy používejte staženou sadu bez kontroly sítě. Předání explicitní verze (např. --template-version 1.2.3) vždy nainstaluje přesně tuto verzi – přeinstalace i v případě, že je již k dispozici novější balíček – takže generování uživatelského rozhraní je reprodukovatelné napříč počítači.

Co to dělá:

  • Ověří, že je nainstalovaná sada .NET SDK (pokud chybí, selže rychle s pokyny – winapp nenainstaluje sady nástrojů).
  • Nainstaluje nebo aktualizuje oficiální sadu šablon WinUI (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) na vyžádání.
  • Vytvoří výčet dostupných šablon z nainstalované sady a deleguje generování na dotnet new <short-name>

Šablony aplikací WinUI už obsahují Windows balení a identity (Package.appxmanifest), takže není potřeba žádný samostatný winapp init krok. Šablony aplikací slouží winapp run k sestavení a spuštění aplikace. Šablona winui-lib vytvoří knihovnu tříd pro odkaz z projektu aplikace (neobsahuje manifest aplikace). Šablona winui-unittest je zabalená aplikace MSTest, jejíž testy se spustí při spuštění aplikace (winapp run) – ne prostřednictvím dotnet test. winapp newGenerování uživatelského rozhraní pro vaši nainstalovanou cílovou architekturu sady .NET SDK a vytiskne příslušný další krok pro zvolenou šablonu.

Pomocí globálního --verbose příznaku (-v) můžete každou základní dotnet vyvolání (dotaz balíčku, kontrolu aktualizací, instalaci, dotnet new listgenerování uživatelského rozhraní) předat spolu s úplným výstupem – užitečné při diagnostice problémů se šablonou nebo generováním uživatelského rozhraní.

Příklady:

# Interactive: pick a template, then a name (output defaults to ./<name>)
winapp new

# List the available templates without scaffolding
winapp new --list

# One-shot with a specific template
winapp new --name MyApp --template winui-navview

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

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.

Poznámka:

U projektů .NET inicializovaných pomocí winapp init neexistuje winapp.yaml. Použijte dotnet restore k obnovení balíčků NuGet.

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)

Předáním více vstupních složek vytvořte .msixbundle distribuci s více architekturami (viz balíčky s více architekturami níže).

winapp pack <input-folder> [input-folder...] [options]

argumenty :

  • input-folder - Jeden nebo více adresářů obsahujících soubory aplikace, které se mají zabalit. Předáním více složek (např ./publish/x64 ./publish/arm64. ) vytvořte sadu MSIX. Pro řídké balíčky identit předejte řídký appxmanifest.xml soubor přímo místo složky (viz balíčky s řídkými identitami níže).

Možnosti:

  • --output <filename> – Název výstupního souboru. Pro jednotlivé balíčky: <name>_<version>_<arch>.msix (vrácení zpět , <name>_<version>.msix<name>_<arch>.msixnebo <name>.msix). Pro svazky: <name>_<version>_<arch1>_<arch2>.msixbundle.
  • --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>– Publisher pro generování certifikátů. Přijímá úplný rozlišující název X.500 nebo úplný název (automaticky zabalený jako CN=<name>).
  • --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í a sváže všechny soubory, na které se v manifestu odkazuje (např. AppExtension manifest.json, konfigurační soubory), z adresáře manifestu nebo vstupní složky, pokud chybí v přípravném prostředí.
  • 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.

Řídké balíčky identit

Pokud je vstup řídkým appxmanifest.xml souborem (jeden deklarující <uap10:AllowExternalContent>true</uap10:AllowExternalContent> pod <Properties>) místo složky, winapp pack sestaví pouze identitu – zabalí pouze .msix manifest bez binárních souborů nebo prostředků aplikace. Toto je krok 2 pracovního postupu zhuštěného balení.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx
  • Výchozí výstup je <PackageName>.identity.msix v aktuálním adresáři (přepsán pomocí --output).
  • Podepisování probíhá pouze v případě, že --cert je k dispozici (nebo --generate-cert).
  • Pokud místo toho předáte složku, jejíž manifest deklaruje AllowExternalContent, použije se stávající chování při balení složek, ale winapp pack upozorní, pokud najde prostředky (/.ico.png/.jpg) nebo binární soubory (.exe.dll//.so) – pro řídké balíčky, které patří do externího umístění, nikoli uvnitř ..msix

Po zabalení spusťte winapp embed-identity <exe> a zaregistrujte balíček v instalačním programu s Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Podívejte se na průvodce řídkým balením.

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

Balíčky s více architekturami

Pokud je předáno více vstupních složek, winapp pack vytvoří se pro každou architekturu .msixbundle jeden .msix obsahující:

# Create unsigned bundle for Microsoft Store submission
winapp pack ./publish/x64 ./publish/arm64

# Create signed bundle for sideloading
winapp pack ./publish/x64 ./publish/arm64 --cert ./devcert.pfx

# Self-contained bundle
winapp pack ./publish/x64 ./publish/arm64 --self-contained --generate-cert

Příkaz automaticky rozpozná architekturu jednotlivých složek z hlavičky PE primárního spustitelného souboru, ověří konzistenci napříč řezy (identita, schopnosti, závislosti) a vytvoří <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Řešení manifestu pro balíčky:

Každý řez v sadě potřebuje manifest. Příkaz vyřeší manifesty v tomto pořadí:

  1. --manifest <path> — Je-li zadán, použije se tento jediný manifest pro všechny řezy. Automaticky ProcessorArchitecture se aktualizuje na řez tak, aby odpovídal zjištěné architektuře.

  2. Manifest pro jednotlivé složky – Pokud každá vstupní složka obsahuje Package.appxmanifest (nebo appxmanifest.xml) manifest této složky se používá pro jeho řez.

  3. Záložní adresář aktuálního adresáře – Pokud složka nemá žádný manifest, příkaz vyhledá Package.appxmanifest v aktuálním pracovním adresáři a použije ho (s automatickým razítkem architektury).

Ve všech případech se manifest automaticky aktualizuje: zástupné symboly se přeloží, vloží se závislosti a ProcessorArchitecture nastaví se na rozpoznanou architekturu. Po vyřešení ověření křížového řezu zajistí, že identita (název, verze, Publisher), schopnosti a závislosti jsou konzistentní ve všech řezech – může se lišit.ProcessorArchitecture Verze balíčku definovaná vřezchm souborech (MSIX) je atributem verze balíčku MSIX s výjimkou případů, kdy se 0.0.0.0v takovém případě automaticky vygeneruje verze založená na časovém razítku.

# Option 1: Single shared manifest (simplest for most projects)
# Place Package.appxmanifest in your project root and run from there
winapp pack ./publish/x64 ./publish/arm64

# Option 2: Explicit manifest path
winapp pack ./publish/x64 ./publish/arm64 --manifest ./src/Package.appxmanifest

# Option 3: Per-folder manifests (useful if slices have different app extensions)
# Each folder already contains its own Package.appxmanifest
winapp pack ./publish/x64 ./publish/arm64

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

embed-identity

Připojte desktopovou aplikaci ke svému řídkému balíčku identity vložením elementu <msix> do manifestu aplikace vedle sebe (fúzní). Toto je krok 3 pracovního postupu zhuštěného balení – informuje Windows, ke kterému balíčku identity patří spuštěný exe.

winapp embed-identity <target> [options]

argumenty :

  • target - Soubor, který chcete aktualizovat. Automaticky zjištěno rozšířením:
    • .exe (EXE mode) – vloží <msix> prvek přímo do manifestu exe vedle sebe pomocí mt.exe.
    • .xml / .manifest (režim XML) – vloží nebo nahradí prvek v externím souboru manifestu <msix> SxS (vytvořený v případě, že neexistuje). Potom znovu sestavte aplikaci, aby se aktualizovaný manifest v binárním souboru vnořel.

Možnosti:

  • --manifest <path> – Cesta ke řídké appxmanifest.xml cestě ke čtení identity (packageName, publisher, applicationId) z. Pokud tento parametr vynecháte, nejprve vyhledá sparse/ složku vedle cíle, pak v aktuálním adresáři, pak v adresáři cíle a aktuálním adresáři.appxmanifest.xml

Příklady:

# EXE mode — embed identity straight into the built exe
winapp embed-identity ./bin/Release/net8.0-windows/MyApp.exe

# XML mode — update a checked-in side-by-side manifest, then rebuild
winapp embed-identity ./app.manifest --manifest ./appxmanifest.xml

Tento příkaz je idempotentní: opětovným spuštěním nahradí všechny existující <msix> elementy místo duplikování.

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 rozlišující název (výchozí hodnota: CN=<current user>). Přijímá všechny platné X.500 DN; Úplné názvy jsou automaticky zabalené jako CN=<name>.
  • --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:

Zástupné symboly manifestu

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

Zástupný symbol Vyřešeno na Příklad
$targetnametoken$ Název spustitelného souboru bez přípony Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Vždy vyřešeno automaticky

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.

winapp run funguje v jednom ze dvou režimů, které se automaticky vyberou ze vstupu:

  • Režim složky – vstup je složka build-output (obsahuje Package.appxmanifest/AppxManifest.xml).
  • Project režim – vstup je .csproj, .sln/.slnx řešení nebo adresář obsahující jeden. winapp run sestaví projekt a spustí ho a podporuje zabalené i rozbalené aplikace WinUI. Viz Project režim níže.

Tip

Ve výchozím nastavení je výběr režimu bezobslužný. Pokud byl adresář považovaný za výstupní složku sestavení, když jste očekávali, že se sestaví jako projekt, spusťte ho znovu --verbose – režim složky hlásí, proč byl vybrán (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Adresář je sestavený pouze jako projekt, pokud .csproj/.slnx/.slnje spuštěná aplikace umístěná na nejvyšší úrovni. Neprohledává se rekurzivně.

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>] [options]

argumenty :

  • input – Aplikace, která se má spustit: výstupní složka sestavení (režim složky), .csproj projekt, .sln/.slnx řešení nebo adresář obsahující jeden z těch na nejvyšší úrovni (režim projektu; adresář se nehledají rekurzivně). Slouží . k sestavení nebo spuštění projektu v aktuálním adresáři. Volitelné – výchozí hodnota aktuálního adresáře, pokud je vynechán (odpovídá dotnet run).

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. Když je aplikace s chybovým ukončením aplikace WinUI 3 (Microsoft.UI.Xaml.dll načtená), automaticky se spustí extra stowed-exception triage passing, aby se zobrazil původní hrESULT, jeho řetězec ErrorContext a kompletní nativní zásobník odesílání XAML; požadované komponenty ladicího programu se stáhnou při prvním použití (viz Ladění, přepisovatelné prostřednictvím WINAPP_DBGTOOLS_DIR proměnné prostředí). 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. Tento příznak také zlepšuje zásobník třídění výjimek winUI pro aplikace WinUI 3. 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

režim Project (projekty sady .NET SDK)

Pokud je vstupem .csprojřešení.slnx/.sln nebo adresář obsahující jeden (včetně.),winapp run sestaví projekt a dotnet build spustí ho. Podporuje zabalené i rozbalené aplikace WinUI a před spuštěním nainstaluje odpovídající architekturu aplikace pro Windows Runtime.

Vstup řešení: bod winapp run na .sln.slnx/(nebo adresář obsahující jeden – řešení je upřednostňované před volnými .csproj soubory) a přeloží spustitelný projekt aplikace a pak ho sestaví s definovanými vlastnostmi $(SolutionDir) na stejné Solution* úrovni, takže projekty, které na nich závisejí, jak to dělají v Visual Studio. Pravidla řešení:

  • Projekty testů se při automatickém výběru přeskočí , takže řešení obsahující aplikaci a jeho testy se přeloží na aplikaci bez --project nutnosti. (Testovací projekt WinUI je sám zabalená aplikace, takže samotný typ výstupu ho nedokáže odlišit.)
  • Pokud je jediným spustitelným projektem testovací projekt, spustí se.
  • Pokud existuje více než jeden spustitelný projekt aplikace, winapp run neuhodne spouštěný projekt – při výpisu kandidátů dojde k chybám. Slouží --project <name> k výběru, který je vždy dodržen, včetně výběru testovacího projektu.

Zabalené vs. rozbalené je rozpoznáno automaticky z efektivní WindowsPackageType vlastnosti MSBuild projektu (nikdy z přítomnosti manifestu):

  • Zabaleno (WindowsPackageType=MSIXvýchozí nastavení balíčku WinUI) – sestavení a pak zaregistruje výstup sestavení jako balíček volného rozložení a spustí se přes AUMID (stejný kanál jako režim složek).
  • Rozbalení (WindowsPackageType=None) – sestavení, zajišťuje instalaci aplikace pro Windows runtime závislé na rozhraní a následném spuštění sestavené .exe přímo. Vynuťte to pro zabalený projekt s -p WindowsPackageType=None.

Project režim vyžaduje .NET SDK 8.0.100 nebo novější (pro MSBuild--getProperty).

možnosti Project režimu (ignorovány v režimu složek):

  • -c, --configuration <name> – Konfigurace sestavení. Výchozí hodnota: Debug.
  • --arch <x64|arm64|x86> - Cílová architektura. Výchozí hodnota: aktuální architektura procesu. Určuje identifikátor RID sestavení i architekturu modulu aplikace pro Windows Runtime, který se nainstaluje.
  • -r, --runtime <rid>- Cílový identifikátor modulu runtime .NET (např. win-x64). Project režim používá pouze architekturu identifikátorů RID, vždy sestaví kanonický win-<arch>identifikátor a odmítne identifikátory RID bez Windows (např. linux-x64). Jeho architektura přepisuje --arch.
  • -f, --framework <tfm> - Cílový rámec moniker pro projekty s více cíli (např. net10.0-windows10.0.26100.0).
  • --project <name-or-path> – Pokud je vstup řešením (.sln/.slnx) nebo adresářem s více spouštěnými projekty aplikací, vybere, který projekt se má spustit (podle názvu projektu nebo cesty).
  • --no-build - Přeskočte sestavení a spusťte existující výstup sestavení (stále vyhodnocuje výstupní vlastnosti).
  • --no-restore - Před sestavením projekt přeskočte.
  • -p, --property <Name=Value> - VLASTNOST MSBuild, přeposlaná do sestavení i vyhodnocení vlastnosti. Opakovatelné (např. -p WindowsPackageType=None).

Vytvoření výstupu a podrobností: projekt je sestavený ve dvou krocích – dotnet build výstupní streamy živě do konzoly , následované rychlým průchodem vyhodnocení vlastností. Winapp vytiskne přesné dotnet build … vyvolání před výstupem a streamuje upozornění i při úspěšném sestavení. Úroveň podrobností:

Flag dotnet verbosity Přidá
(výchozí) minimal —
--verbose minimal Trasování rozhodnutí o sestavení winappu
--quiet quiet —

Pod --json voláním nebo --quiet výstupem sestavení přejděte na stderr, takže stdout zůstane čistý JSON / čistý.

Použitelnost možností: možnosti identity/volného rozložení (--manifest, --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, , --clean) --executablese vztahují pouze na zabalené aplikace. Jsou odmítnuty s jasnou chybou pro rozbalené aplikace (které nemají žádný balíček MSIX). Možnosti spuštění/ladění (--args/--, --detach, --debug-output--symbols, , --json) fungují v obou.

příklady Project režimu:

# Build and run the project in the current directory (input defaults to ".")
winapp run

# Run a specific project
winapp run ./src/MyApp/MyApp.csproj

# Build and run from a solution (resolves the runnable app project, defines $(SolutionDir))
winapp run ./MyApp.sln

# Pick a startup project when the solution has more than one runnable app
winapp run ./MyApp.sln --project MyApp

# Release build for arm64
winapp run . -c Release --arch arm64

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

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í:

Vlastnictví Výchozí Description
EnableWinAppRunSupport true Povolení nebo zakázání funkce podpory spuštění
WinAppLaunchArgs (prázdné) Argumenty, které se mají předat aplikaci při spuštění
WinAppRunUseExecutionAlias false Spuštění prostřednictvím aliasu spuštění místo aktivace AUMID
WinAppRunNoLaunch false Registrace identity pouze bez spuštění
WinAppRunDebugOutput false Zachytávání OutputDebugString zpráv a výjimek s první šancí Současně se může připojit pouze jeden ladicí program (zabraňuje VS/VS Code). Místo toho slouží WinAppRunNoLaunch k připojení jiného ladicího programu.
WinAppRunDetach false Okamžitě po spuštění se vraťte místo čekání na ukončení aplikace. Vytiskne PID.
WinAppRunUnregisterOnExit false Zrušení registrace vývojového balíčku po ukončení aplikace
WinAppRunClean false Před opětovným nasazením odeberte data aplikace existujícího balíčku (LocalState, settings).
WinAppRunSymbols false Stáhněte si symboly ze serveru symbolů Microsoft pro bohatší nativní analýzu chybových ukončení. Má účinek pouze s WinAppRunDebugOutput.
WinAppRunExecutable (prázdné) Spustitelná cesta vzhledem ke složce build-output. Použijte, pokud manifest obsahuje $targetnametoken$ a výstupní složka má více než jednu .exe.
WinAppRunArgs (prázdné) Nezpracované argumenty připojené k příkazovému winapp run řádku pro možnosti bez vyhrazené vlastnosti (například --verbose). Připojeno za každou výše uvedenou vlastnost.

Vzájemně se vylučují nastavení. WinAppRunNoLaunch a WinAppRunDetach každý popisuje jiné chování při spuštění, takže jsou v konfliktu s ostatními vlastnostmi spuštění a s ostatními. Nastavení konfliktní dvojice selže při spuštění s --X and --Y cannot be used together:

Vlastnictví Nelze kombinovat s
WinAppRunNoLaunch WinAppRunDetach, WinAppRunUseExecutionAlias, , WinAppRunDebugOutputWinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, WinAppRunUseExecutionAlias, , WinAppRunDebugOutputWinAppRunUnregisterOnExit

WinAppRunUseExecutionAlias, WinAppRunDebugOutputa WinAppRunUnregisterOnExit lze je kombinovat s sebou. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutablea WinAppLaunchArgs nemají žádná omezení. WinAppRunArgs nepřidá žádné omezení svého vlastního, ale přepínač, který prochází, je kontrolován jako jakýkoli jiný, takže WinAppRunArgs="--detach" stále v konfliktu s WinAppRunNoLaunch.

<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} tak {name}.debug 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>- Publisher pro certifikát. Přijímá úplný rozlišující název X.500 (např CN=Contoso, O=Contoso Ltd, C=US. ) nebo úplný název, který se automaticky zabalí jako CN=<name>
  • --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

az-sign

Podepsání kódu souboru (exe, MSIX nebo msiX bundle) pomocí Důvěryhodné podepisování Azure – podpisové identity spravované v cloudu, takže na místním počítači nikdy nedochází k žádnému privátnímu klíči (PFX).

winapp az-sign <file-path> [options]

argumenty :

  • file-path – Cesta k souboru pro podepsání (exe, msix nebo msixbundle)

Možnosti:

  • --subscription, -s – Azure ID předplatného, které se má použít. Pokud není k dispozici a existuje více předplatných, zobrazí se výzva.
  • --resource-group, -r – Skupina prostředků pro zúžení podpisových účtů
  • --account - Podpisový název účtu. Musí se používat s --resource-group
  • --profile, -p – Název profilu certifikátu. Musí se používat s --account
  • --metadata-file, -m - Cesta k existujícímu metadata.json. Přeskočí výzvy ke zjišťování prostředků a výběru účtu nebo profilu a podepíše se přímo. Neinteraktivní Azure přihlašovací údaje by už měly být dostupné. Rozhraní příkazového řádku se jinak může vrátit k interaktivní výzvě tenanta nebo az login, ale programové rozhraní API npm je vždy neinteraktivní a místo výzvy se nezdaří.

Authentication (Ověřování):

az-signpoužívá standardní řetězec přihlašovacích údajů Azure (DefaultAzureCredential). Pro CI/CD, set AZURE_TENANT_ID, AZURE_CLIENT_IDa AZURE_CLIENT_SECRET (nebo použijte GitHub Actions OIDC / spravovaná identita). Existující relace Azure CLI (az loginvčetně azure/login akce GitHub) je také dodržena v jakémkoli prostředí. Jenom když se nenajde žádné přihlašovací údaje a relace je interaktivní, spustí az-signaz login se za vás.

Požadavky:

  • Účet pro podepisování kódu Azure a profil certifikátu (vytvořený na portálu Azure po ověření identity) a role podepisujícího profilu certifikátu pro podpis kódu přiřazená vaší identitě. Další pokyny najdete v dokumentaci k rychlému startu k podepisování artefaktů Azure.
  • Nainstalovaný modul runtime x64 x64 .NET 8 (nebo novější). Podpisová klientská knihovna Azure je spravované sestavení, které signtool.exe se načte v samostatném procesu. Vlastní modul runtime winapp ho nesplňuje. Pokud podepisování selže s chybou načítání za běhu, nainstalujte ji https://dotnet.microsoft.com/download z ní.
  • Microsoft Visual C++ Redistributable (x64). Podpisová klientská knihovna Azure závisí na modulu runtime VC++ a protože winapp stáhne nezpracovaný balíček NuGet místo oficiálního instalačního programu klientských nástrojů, tato závislost se nenainstaluje automaticky. Čistý počítač může selhat i s .NET a signTool. Nainstalujte nejnovější distribuovatelné součásti x64, pokud https://aka.ms/vs/17/release/vc_redist.x64.exe podepisování selže s chybou 0xc000007b" Aplikace se nepodařilo spustit správně" nebo chyba chybějící knihovny DLL z knihovny dlib.

CI s nejnižšími oprávněními: Automatické zjišťování (výpis předplatných, skupin prostředků, účtů a profilů) vyžaduje přístup pro čtení v nadřazené oblasti. Aby se zabránilo každému volání výpisu kolekce, předejte všechny čtyři z --subscription--resource-group, --accounta --profile: pak az-sign ověří účet a profil s přímými čtením prostředků (GET pro každý pojmenovaný prostředek) místo vytvoření výčtu nadřazené kolekce, takže objekt zabezpečení vymezený pouze na tento účet a profil je dostačující. Vynechání některého z nich znovu zavádí volání výpisu – například vynechání seznamu --subscriptionaz-sign předplatných, ke kterým má vaše identita přístup – což nemusí být povolený úzce vymezený objekt zabezpečení. Objekt zabezpečení vymezený pouze na jeden profil certifikátu může zcela přeskočit ověření předáním předem generovaného --metadata-file profilu (který určuje koncový bod účtu a profil přímo).

Příklady:

# Interactive — discover/select subscription, account, and profile
winapp az-sign ./app.msix

# Fully specified — no prompting (ideal for CI/CD)
winapp az-sign ./app.msix --subscription <sub-id> --resource-group <rg> --account <account> --profile <profile>

# Reuse an existing metadata.json (skips resource discovery and selection; authentication may still prompt)
winapp az-sign ./app.msix --metadata-file ./metadata.json

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 :

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

find-ui

Vyhledejte funkční příklad kódu pro vyhledávání ovládacích prvků a ukázek WinUI . Pouze WinUI: korpus je Galerie WinUI 3 a sada Windows Community Toolkit (plus několik kurátorovaných základních vzorů) – nevztahuje se na WPF (Windows Presentation Foundation), WinForms ani jiné architektury uživatelského rozhraní. Třetí zdroj, microsoft-ui-reactor ReactorGallery, je opt-in: je vyloučen z normálního vyhledávání a prohledán pouze při průchodu --source reactor (jeho deklarativní vzorky jazyka C#-only nevkládat do standardní aplikace XAML, takže se k němu dostanete pouze při vytváření projektu Reactor/MVU).

winapp find-ui "<query>" [options]

Korpus se načte z GitHub při prvním použití a ukládání do mezipaměti pro jednotlivé uživatele<global .winapp>/cache/find-ui, takže první spuštění vyžaduje přístup k síti. Následné spuštění se obsluhují z místní mezipaměti (aktualizují se maximálně každých 7 dnů nebo na vyžádání pomocí --refresh).

Možnosti:

  • --id <id> – Načtení kódu (Galerie/Sada nástrojů vrací XAML a/nebo C#; Reactor je jen C#-only) plus poznámky k předpokladům pro jedno nebo více ID scénářů z předchozího vyhledávání (např. gallery-tabview-1). Opakovatelný. Id nerozlišují malá a velká písmena – GALLERY-TABVIEW-1 řeší se stejně jako gallery-tabview-1.
  • --list - Vypište všechny zjistitelné ID kontroly nebo vzorku místo vyhledávání (Galerie + sada nástrojů + jádro; je vyloučen zdroj opt-in Reactor).
  • --source <gallery|toolkit|reactor|core> – Omezit výsledky hledání na jeden zdroj. (Pouze vyhledávání – není platné s --list/--id.) Reactor je výslovný souhlas – je vyloučen z normálního hledání, takže --source reactor je jediným způsobem, jak ho vyhledat.
  • --max <N> - Maximální počet odpovídajících ovládacích prvků, které se mají vrátit (výchozí hodnota: 3). Platí pouze pro vyhledávání; ignorováno s --list/--id.
  • --refresh- Obejití místní mezipaměti a opětovné načtení korpusu WinUI z GitHub.
  • --json – Generování strukturovaného FORMÁTU JSON (přívětivé pro agenty) Pro hledání každá shoda nese source, , controlscore, descriptiona scenarios pole, jehož položky obsahují jednotlivé scénáře id a header; pro --id, celý kód. Při --jsonkaždém selhání ( včetně chyb argumentu nebo analyzátoru, jako je například celé číslo --max ), se vygeneruje jako plochý {"error": "..."} objekt v režimu stdout s nenulovým ukončovacím kódem, takže výstup zůstane strojově čitelný.

Pracovní postup: Kompaktně vyhledejte správný ovládací prvek a jeho ID scénáře a pak načtěte celý kód pro nejlepší shodu s --id.

Příklady:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

generované vazby uzlu

(K dispozici pouze v balíčku NPM) Generování vazeb JS pro rozhraní API Windows App SDK Vazby jsou deklarovány oborem "winapp": { "jsBindings": {...} } názvů a package.json zapsány do .winapp/bindings/.

npx winapp node generate-bindings [options]

Možnosti:

  • --verbose, -v – Povolení podrobného výstupu kódu pro jednotlivé soubory
  • --quiet, -q – Potlačení průběhu a informačního výstupu

Co to dělá:

  • Přečte blok od posledního zápisu winapp.jsBindingspackage.jsonwinmds.lock.json a pak vygeneruje typovéwinapp restore.js + vazby do .d.ts.winapp/bindings/
  • Neupravujepackage.json – jedná se o pasivní regenerátor. winapp.jsBindings Přidání bloku a @microsoft/dynwinrt závislosti modulu runtime probíhá při winapp init povolení vazeb JS. Tento příkaz selže rychle, pokud blok chybí.
  • Varuje (ale nezapisuje), pokud @microsoft/dynwinrt v závislostech chybí – spustí npm install se po init přidání

Poznámka:

Vazby jsou pouze npm – vyžadují vyvolání prostřednictvím npx winapp ( @microsoft/winappcli balíček npm), samostatné rozhraní příkazového řádku winget je nezpřístupňuje. Před winapp init použitím tohoto příkazu znovu vygenerujte vazby interaktivním spuštěním a výslovným souhlasem nebo použití winapp init . --use-defaults --add-js-bindings. Pokud upravítewinapp.yaml, spusťte npx winapp restore aktualizaci Windows závislostí před opětovném vygenerováním.

Příklady:

# Regenerate JS bindings in the current project
npx winapp node generate-bindings

# Regenerate after editing winapp.jsBindings, with verbose output
npx winapp node generate-bindings --verbose

Informace o kompletním pracovním postupu a možnostech konfigurace najdete v winapp.jsBindings.

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).

Důležité

Existuje známý problém s řídkým balením aplikací Elektron, které způsobí chybové ukončení aplikace při spuštění nebo nevykreslení webového obsahu. Tento problém je opravený v Windows, ale zatím se nešířel na externí Windows zařízení. Pokud se tento problém zobrazuje po volání add-electron-debug-identity, můžete zakázat sandboxing v aplikaci Electron pro účely ladění příznakem --no-sandbox . Tento problém nemá vliv na úplné balení MSIX.

Chcete-li zrušit ladicí identitu Electron, použijte winapp node clear-electron-debug-identity.

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

Možnosti:

Možnost Description
--manifest <path> Cesta k vlastnímu souboru Package.appxmanifest (výchozí hodnota: Package.appxmanifest v aktuálním adresáři)
--no-install Neinstalujte ani neupravujte závislosti; konfigurovat pouze ladicí identitu v Electronu
--keep-identity Ponechte identitu manifestu beze změn, bez připojení .debug k názvu balíčku a ID aplikace.
--verbose Povolení podrobného výstupu

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:

Možnost Description
--verbose Povolení podrobného výstupu

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.

Kontroly aktualizací

Rozhraní příkazového řádku winapp pravidelně kontroluje nové verze a zobrazuje jednořádkový oznámení, když je k dispozici aktualizace. Tato kontrola se spustí na pozadí a nepřidá k příkazům žádnou latenci.

Kontroly aktualizací se automaticky deaktivují v prostředích CI (GitHub Actions, Azure Pipelines atd.).

Chcete-li ručně zakázat kontroly aktualizací, nastavte proměnnou WINAPP_CLI_UPDATE_CHECK prostředí na 0.

V cmd:

set WINAPP_CLI_UPDATE_CHECK=0

V PowerShellu a pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Chcete-li nastavit tuto trvalou:

[System.Environment]::SetEnvironmentVariable('WINAPP_CLI_UPDATE_CHECK', '0', 'User')

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ě)
  • record- Záznam okna nebo oblasti elementu do videa H.264 MP4 (Windows Graphics Capture + Media Foundation)
  • 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í)
  • hover – Přesunutím myši na prvek aktivujte popisy tlačítek, kontextové rámečky a najetí myší (výchozí umístění: 800 ms)
  • drag - Přetáhněte myš z jednoho bodu do druhého, podle selektoru prvků nebo souřadnic obrazovky x,y (změna pořadí, změna velikosti, posuvníky, přetažení)
  • touch- Vkládání syntetických dotykových gest (klepnutí, poklepání, dlouhé stisknutí, potáhnutí, stažení, roztažení) na střed prvku nebo souřadnice obrazovky x,y
  • pen - Vkládání syntetického pera / pera vstup — klepnutí a tahy rukopisu s konfigurovatelným tlakem, nakloněním a režimem gumy
  • send-keys - Odeslání syntetického vstupu klávesnice (pojmenované klávesy, komba, nezpracovaný vk=0xNN nebo text literálu) do okna
  • set-value - Nastavit hodnotu u upravitelného prvku (text, číslo); vrátí zpět na LegacyIAccessible put_accValue for TextPattern-only rich-edit controls
  • 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í)

Záznam uživatelského rozhraní

Zaznamenejte okno nebo oblast elementu do souboru H.264 MP4.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o demo.mp4

Možnosti záznamu:

  • --duration-sec <n> - Délka záznamu v sekundách. 0 zaznamenává, dokud Ctrl+C (výchozí 0).
  • --fps <n> - Snímky za sekundu pro zachycení (výchozí 15).
  • --max-edge <px> - Snížení měřítka tak, aby nejdelší okraj byl maximálně tento počet pixelů (0 = bez snížení měřítka).
  • --capture-screen - Zachytávání z obrazovky tak, aby byly zahrnuty překryvné nebo automaticky otevírané okno (mohou zachytit okna occluding).
  • -o, --output <path> - Výstupní .mp4 cesta (výchozí hodnota recording-<timestamp>-<guid>.mp4je ).
  • --frames - Psát časové razítko JPEG, frames.ndjsona manifest.json do <output-name>.frames. Podporuje 1-30 fps a --max-edge 64-4096 (výchozí 1280) s 1 GiB rám-dat cap.

Konečný --jsonvýsledek zahrnuje výstupní cestu, rozměry, kodek, režim zachycení, četnost, důvod zastavení, volitelné frameArtifactsa upozornění.

Známé omezení: Záznam konkrétního prvku uvnitř automaticky otevíraných oken, které se vykreslí ve vlastním okně nejvyšší úrovně (informační panel WinUI/XAML, tip výuky, popisek), může místo toho zachytit základní hlavní okno. Zaznamenejte celé okno nebo použijte ui screenshot --capture-screen pro překryvné okno. Sledované v č. 646.

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

  • Last updated on