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í nastavení: vybraný adresář projektu nebo aktuální adresář, pokud se nezjistí žádný projekt)
• --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-navview, winui-mvvmwinui-lib, , winui-unittest, nebo experimentální šablona Reactor, například reactor nebo reactor-mvu). 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 XAML).
• -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:

Balíček dodává dva styly aplikace WinUI. Šablony XAML definují uživatelské rozhraní v revizích pomocí kódu jazyka C#. Šablony reactor jsou čistě C# bez XAML s využitím vzoru MVU (model-View-Update). 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 XAML (balení MSIX)
winui-navview	Úvodní aplikace XAML NavigationView
winui-tabview	Úvodní aplikace XAML TabView
winui-mvvm	Aplikace XAML MVVM (CommunityToolkit.Mvvm)
winui-lib	Knihovna tříd WinUI 3
winui-unittest	Zabalená aplikace MSTest; testy se spustí při spuštění
reactor	Pokusný. Prázdná aplikace Reactor – čistě C#, bez XAML
reactor-mvu	Pokusný. Aplikace Reactor demonstrující vzor MVU
reactor-navview	Pokusný. Úvodní aplikace Reactor NavigationView
reactor-tabview	Pokusný. Úvodní aplikace Reactor TabView

Šablony reactor jsou experimentální. Odkazují na předběžné Microsoft.UI.Reactor balíčky, jejichž rozhraní API se můžou v budoucí verzi změnit nebo odebrat. winapp new označí je (experimentální) in --list a v interaktivním výběru, nastaví "Experimental": true v --jsona vytiskne upozornění po vygenerování. Nikdy se nevybíraly jako výchozí šablona. Reactor také vyžaduje sadu .NET 10 SDK nebo novější. Ve starší sadě SDK winapp new se nezdaří předem s verzí, kterou potřebuje, místo generování projektu, který nemůžete sestavit.

Kanonický krátký název každé šablony je prvním seznamem aliasů dotnet new . Všechny uvedené aliasy (např. winui3, wasdk-single) winui-reactorjsou 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.

První spuštění může trvat déle: Instalace nebo aktualizace sady šablon nebo obnovení chybějící Windows App SDK ch balíčků NuGet používaných vybranou šablonou může vyžadovat další stahování. K tomu může dojít také po publikování nové verze Windows App SDK. Pokud generování uživatelského rozhraní stále běží po 10 sekundách, winapp new aktualizuje stavovou zprávu, aby indikovala, že se balíčky můžou stahovat nebo obnovovat.

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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# 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 [base-directory] [options]

argumenty :

• base-directory - Adresář k obnovení (výchozí: aktuální adresář). Také vybere, kde winapp.yaml a nuget.config odkud se předčítá, pokud --config-dir ji nepřepíše.

Možnosti:

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

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 .NET projektů neexistuje žádná winapp.yaml – verze sady SDK jsou živé jako PackageReference položky v souboru .csproj – takže winapp restore se spustí dotnet restore za vás.

Příklady:

# Restore from winapp.yaml in current directory
winapp restore

# Restore a specific project directory (reads ./my-project/winapp.yaml)
winapp restore ./my-project

Vlastní a privátní informační kanály NuGet:

winapp init, restorea update stáhněte Windows SDK a Windows App SDK balíčky prostřednictvím NuGetu a respektujte svou standardní nuget.config hierarchii. Soukromé informační kanály a zrcadla, přihlašovací údaje informačního kanálu (včetně poskytovatelů přihlašovacích údajů) a vlastní globalPackagesFolder všechna fungují stejně jako pro dotnet restore. Pokud chcete provést obnovení výhradně z vlastního zrcadla, <clear /> zděděné zdroje a přidat jenom ty vaše:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Poznámka:

V případě nativních projektů winapp se nuget.config překládá z adresáře, na kterém pracuje:restoreinit/argument adresáře, --config-dir pokud je zadaný, jinak aktuální adresář. Pro .NET projekty zdroje pocházejí z vlastní nuget.config hierarchie projektu, protože to je to, co dotnet add package a dotnet restore použití, takže vložte konfiguraci soukromého informačního kanálu do adresáře projektu nebo nadřazeného objektu. Mimo --config-dir tuto hierarchii je hlášena a ignorována místo tichého výběru verzí, které projekt nemůže obnovit. Spusťte tyto příkazy pouze u adresářů, kterým důvěřujete, stejná opatrnost, která platí pro dotnet restore. Pokud je nakonfigurováno několik zdrojů, použijte mapování zdrojů balíčků k připnutí každého balíčku do informačního kanálu.

---

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 projektu nebo 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 jednoho .csproj sestavení projektu a zabalení jeho výstupu v jednom kroku (režim projektu viz Zabalení projektu přímo pod). 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 .csproj pro sestavení a zabalení (režim projektu) nebo 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
• --no-sign – Doručte balíček bez znaménka, přepsání jakékoli konfigurace podepisování projektu (např. pro odeslání storu nebo externí podpisový kanál). Nelze kombinovat s --cert nebo --generate-cert.
• --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.

Project režimových možností (vyžadovat .csproj vstup; odmítnut pro vstupy složky, sady/manifestu):

• --configuration <name> (-c) – Konfigurace sestavení (výchozí: Release)
• --arch <arch> - Cílová architektura: x64, arm64nebo x86 (výchozí: aktuální architektura procesu)
• --framework <tfm> (-f) – Moniker cílového rámce pro projekty s více cíli
• --no-build – Zabalte existující výstup sestavení bez opětovného sestavení.
• --no-restore - Přeskočte obnovení projektu před sestavením.
• --property <name=value> (-p) – vlastnost MSBuild, přeposlaná do sestavení a vyhodnocení (opakovatelná)

Poznámka: V případě projektu WinUI / EnableMsixTooling.csproj (režim nástrojů MSIX) Windows App SDK vlastní manifest, vstupní bod a generování PRI, takže --executable--manifest, a --skip-pri jsou odmítnuty – nakonfigurujte <AppxManifest>vstupní bod projektu a jeho zdroj sestavení v samotném projektu. Tyto tři možnosti se stále vztahují na vstupy složek a na obecný režim projektu (bez MSIX). .csproj

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.

Přímé zabalení projektu

Pokud je vstupem jeden .csproj, winapp pack sestaví projekt (pomocí výše uvedených možností) a zabalí výsledný výstup – nemusíte sestavovat samostatně nebo nejprve najít výstupní složku. Tato zrcadlí winapp runrežim projektu.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Cílová architektura pochází z --archoblasti nebo z lokny -p RuntimeIdentifier=<rid> , když nepřejdete --arch (přesné identifikátory RID se zachovají a řídí sestavení). Předání obou --arch a -p RuntimeIdentifier je konflikt a je odmítnut.

Projekt se musí sestavit jako zabalená aplikace (EnableMsixTooling=true s Package.appxmanifest); projekt, který se sestaví jako rozbalená aplikace (WindowsPackageType=None) nemá žádný manifest MSIX pro zabalení a winapp pack nahlásí chybu, která by se daly provést. Vstupy složek, svazků a řídkých manifestů se nemění.

Project režim vytváří pouze jednu .msix architekturu nebo pouze .msixbundle architekturu (viz balíčky s více architekturami). Nevytváří archivy pro ukládání a nahrávání prostředků (language/scale) sady: explicitní -p UapAppxPackageBuildMode=StoreUpload nebo -p AppxBundleAutoResourcePackageQualifiers=... odmítnutý s poznámkou ke spuštění nativního příkazu pro zabalení sady SDK přímo pro tyto toky.

Ří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á hodnotu X.500 DN s jednohodnotovými komponentami oddělenými čárkami (sítě RDN s více hodnotami + a zpětné lomítka nejsou podporovány); ú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:

• 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í.

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. Soubor musí deklarovat vlastní velikost prostřednictvím nebo viewBox absolutního width atributu a height jeho procentuální šířky bez popisu viewBox žádné konkrétní velikosti. Zdroj, který deklaruje, že není odmítnut, místo SVG image has no usable dimensions vytváření prázdných prostředků.

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 tří režimů, které se vyberou automaticky 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.
• Režim jednoho souboru – vstup je .cs.NET aplikace založená na souborech. winapp run sestaví ho, vygeneruje manifest ze svých #:property direktiv a spustí ho s identitou balíčku.

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), .cs .NET souborová aplikace (režim s jedním souborem), .csproj projekt, .sln/.slnx řešení nebo adresář obsahující jeden z těch na nejvyšší úrovni (režim projektu, adresář se rekurzivně neprohledá). 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é rozložení (výchozí: AppX uvnitř vstupní složky). Výchozí rozložení odebere soubory, které už nejsou v sestavení; vlastní adresář uchovává další soubory. Pokud potřebujete čisté rozložení, použijte nový vlastní adresář.
• --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. Zřídka se vyžaduje: aplikace s OutputType=Exe již tímto způsobem se ve výchozím nastavení spouští. Winapp přidá do manifestu požadované uap5:ExecutionAlias fáze v rozložení AppX, takže není potřeba změnit vrácený manifest. Alias, který aplikace deklaruje, se používá as-is. Nelze kombinovat s --no-launch, --detach, --without-aliasnebo --json.
• --without-alias – Vynuťte aktivaci AUMID pro aplikaci, která by se jinak spustila prostřednictvím aliasu spuštění. Konzolová aplikace pak běží bez konzoly a nic netiskne do tohoto terminálu. Nelze kombinovat s --with-alias.
• --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í. Místní spuštění vytiskne PID; cílové spuštění vytiskne vymezený cíl uživatelského rozhraní. JSON zahrnuje PID a cílový obor. 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.
• --on <target> - Sestavte na hostiteli a pak zaregistrujte a spusťte v cíli. V současné době podporuje sandbox, bez záložního použití do místního spuštění. Použijte --detach před následným příkazem uživatelského rozhraní. Sandbox --debug-output vyžaduje zabalenou aplikaci. Viz Windows spuštění sandboxu, kde najdete informace o instalaci, podpoře modulu runtime a životnosti odpojené aplikace.

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

Nativní AOT: Přidejte tuto skupinu vlastností do elementu souboru project <Project> a pak přidejte--aot:

<PropertyGroup>
  <PublishAot>true</PublishAot>
</PropertyGroup>

winapp run . --aot
winapp run . --aot -c Release

--aot podporuje projekty x64 a ARM64. dotnet publish Spustí se s konfigurací AOT projektu a pak tento výstup spustí. Použije -p PublishAot=true se k jednorázovému přepsání. Neprovádí samostatnou certifikaci modulu runtime a nelze ji kombinovat s --no-build nebo --manifest.

Pro aplikace, které používají identitu balíčku bez vygenerovaného rozložení MSIX, zahrňte Package.appxmanifest do výstupu publikování projektu nebo appxmanifest.xml do výstupu publikování. Winapp připraví publikované soubory s tímto manifestem. Pokud jsou oba názvy přítomny, winapp se zastaví místo toho, aby zvolil jeden; odeberte zastaralý manifest a nakonfigurujte projekt tak, aby publikoval pouze zamýšlený manifest.

Project-režim možnosti (ignorováno v režimu složky, pokud není uvedeno):

• -c, --configuration <name> – Konfigurace sestavení. Výchozí hodnota: Debug. (Také se respektuje v režimu s jedním souborem.)
• --arch <x64|arm64|x86> - Cílová architektura. Výchozí hodnota: aktuální architektura procesu. Určuje architekturu identifikátorů RID sestavení a aplikace pro Windows modulu runtime a v případě potřeby efektivního sestavení vybere odpovídající profil publikování závislý na platformě. (Také se respektuje v režimu s jedním souborem.)
• -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řepíše --arch a může vybrat požadovaný profil publikování. (Také se respektuje v režimu s jedním souborem, kde přepíše #:property RuntimeIdentifier deklarovaný soubor.)
• -f, --framework <tfm> - Cílový rámec moniker pro projekty s více cíli (např. net10.0-windows10.0.26100.0). (Odmítnuto v režimu s jedním souborem – použijte #:property TargetFramework=....)
• --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). (Odmítnuto v režimu jednoho souboru – .cs aplikace založená na souborech je sama o sobě projekt.)
• --no-build - Přeskočte sestavení a spusťte existující výstup sestavení (stále vyhodnocuje výstupní vlastnosti). (Také se respektuje v režimu s jedním souborem.)
• --no-restore - Přeskočte obnovení před sestavením nebo nativním publikováním AOT. (Také se respektuje v režimu s jedním souborem.)
• --aot– Spusťte nakonfigurovaný projekt .NET nativní publikování AOT. Vyžaduje efektivní PublishAot=true. Odmítnuto v režimech složek a jednoho souboru.
• -p, --property <Name=Value> - VLASTNOST MSBuild, přeposlaná do sestavení i vyhodnocení vlastnosti. Opakujte -p pro více vlastností; použijte %3B nebo %2C pro literál středník nebo čárku v hodnotě. (Také se respektuje v režimu s jedním souborem, kde je jediným způsobem, jak nastavit TargetFramework.)

Vytvoření výstupu a podrobností: běžné spuštění projektu používá dotnet builda následně vyhodnotí sestavený výstup. Živé obnovení a sestavení výstupního streamu s přihlašovacími údaji z ověřených adres URL informačního kanálu, které jsou znovu upraveny. Pomocí --aotpříkazu winapp se zobrazí --verbosedotnet publishpříkaz pro publikování a vyřešené cesty. Pomocí níže uvedených možností podrobností můžete určit, co se zobrazí:

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

Nativní výstupní datové proudy publikování AOT při doručení, včetně json konečné vlastnosti NÁSTROJE MSBuild. V části --json,restore/build invocations and child output go to stderr so stdout stays pure JSON. Pod --quiet, vyvolání jsou potlačeny a dotnet tiché obnovení nebo výstup sestavení se směruje do stderr, takže stdout zůstane čistý. Nativní výstup publikování AOT také přejde do stderru v některé z možností.

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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# 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

Režim jednoho souboru (.NET aplikace založené na souborech)

.NET 10 umožňuje spustit jeden .cs soubor bez souboru projektu a nakonfigurovat ho direktivami #: v horní části. Najeďte winapp run na tento soubor a aplikaci sestaví, vygeneruje pro ni appxmanifest a spustí ji s identitou balíčku – takže Windows.ApplicationModel.Package.Current funguje, aplikace získá skutečnou položku AUMID a položku nabídky Start a rozhraní API, která jednoduše vyžadují identitu (oznámení aplikací, ApplicationData, AI na zařízení).

Integrace prostředí, jako jsou obslužné rutiny protokolu, přidružení souborů, cíle sdílené složky a spouštěcí úlohy, potřebují deklarovanou <Extensions> položku, kterou vygenerovaný manifest neobsahuje. Pokud chcete přidat vlastní manifest, vytvořte si vlastní manifest – podívejte se na část Používání vlastního manifestu níže.

winapp run counter.cs

Nebo ho spusťte v prostém dotnet run zobrazení – viz Spuštění s dotnet run níže.

Nevytádáte manifest. Popište balíček s direktivami #:property :

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Vlastnosti manifestu Všechny jsou volitelné; každý se vrátí k rozumnému výchozímu nastavení:

Vlastnictví	Nastavuje	Výchozí
WinAppPackageName	Identity/@Name (identita balíčku)	název souboru, sanitizovaný na [-.A-Za-z0-9], plus krátká hodnota hash cesty k souboru (counter.cs → counter-a1b2c3d4)
WinAppDisplayName	Název zobrazený v části Start a Nastavení	název souboru bez jeho přípony
WinAppPublisher	Identity/@Publisher	CN=<your Windows user name>. Holý název je zabalen jako CN=<name>.
WinAppVersion	Identity/@Version	$(Version)normalizované (viz níže)
WinAppDescription	Popis zobrazený během instalace a v Nastavení	zobrazovaný název
WinAppCapabilities	Možnosti deklarování, oddělené nebo ; oddělené ,	none

Version. Verze balíčku musí být přesně čtyři čísla, každá 0–65535. WinAppVersion (nebo pokud ji nenastavíte, je standardní Version vlastnost normalizována tak, aby odpovídala: -preview/-rc Přípona se zahodí a chybějící komponenty se vyplní nulami, takže #:property Version=1.2.3-preview.4 se stane 1.2.3.0 a nastaví verzi sestavení a verzi balíčku dohromady. Hodnota, která se nedá přizpůsobit – součást vyšší než 65535 nebo více než čtyři komponenty – je odmítnuta s chybou , nikoli bezobslužné změny.

Capabilities

Vaše aplikace spouští plnou důvěryhodnost s identitou, která splňuje rozhraní API, která vyžadují pouze zabalenou aplikaci. Některá rozhraní API jsou ale chráněná deklarovanou schopností bez ohledu na to, Windows rozhraní API AI jsou běžným případem. (Integrace prostředí, jako jsou obslužné rutiny protokolu a přidružení souborů, jsou třetím případem: ty potřebují vytvořené <Extensions> položky, nikoli schopnost, takže pro ně používejte vlastní manifest .)

#:property WinAppCapabilities=systemAIModels

To je vše Phi Silica a další rozhraní API modelu na zařízení potřebují z manifestu. Deklarujte několik tak, že je oddělíte:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

Winapp zapíše každý z nich do elementu a oboru názvů XML, který ve skutečnosti vyžaduje, deklaruje MaxVersionTested tento obor názvů a vyvolává, když schopnost potřebuje novější. Záleží na tom víc, než to zní: schopnosti jsou rozložené do několika různých prvků a stejný seznam se stává třemi různými obrazci –

<systemai:Capability Name="systemAIModels" />
<Capability Name="internetClient" />
<DeviceCapability Name="microphone" />

Jména winapp ví, že jsou pro vás napsaná. Pro cokoli jiného – omezená sada roste v průběhu času – kvalifikujte ji sami pomocí předpony oboru názvů:

Předpona	Generuje
rescap:	<rescap:Capability> — omezené možnosti
uap:, uap6:, , uap7:uap11:	<uap*:Capability>
systemai:	<systemai:Capability>
device:	<DeviceCapability>
app:	<Capability> ve výchozím oboru názvů

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Nerozpoznaný holý název je odmítnut s chybou pojmenování těchto předpon, nikoli odhadnutou – schopnost vygenerovaná v nesprávném oboru názvů vytvoří manifest, Windows buď odmítne registraci, nebo přijme, aniž by mu byla udělena.

Používání vlastního manifestu

Pokud potřebujete něco, co vlastnosti nepokrývají – obslužnou rutinu protokolu, přidružení souboru, alias spuštění – vytvořte manifest a winapp run místo generování ho použijete doslovně. Vyzvedne se z:

1. --manifest <path> na příkazovém řádku.
2. #:property WinAppManifestPath=<path> .cs v souboru.
3. Manifest sedící vedle .cs souboru s názvem <filename>.appxmanifest (například counter.appxmanifest vedle counter.cs).

Automaticky se vybere jenom název souboru. A Package.appxmanifest nebo appxmanifest.xml ve stejné složce je záměrně ignorováno – několik .cs souborů může sdílet složku a přijetí sdíleného názvu by bezobslužně spustilo jednu aplikaci pod jinou identitou. Pokud chcete použít jeden manifest pro několik souborů, pojmenujte ho explicitně pomocí --manifest nebo WinAppManifestPath.

Package.appxmanifest V opačném případě se do výstupu sestavení vygeneruje spolu s výchozími prostředky image a při každém spuštění se aktualizuje.

Options. Každá možnost režimu složek funguje: --no-launch, , --with-alias, --detach--without-alias, --clean, --debug-output, --symbols, --unregister-on-exit, --args/--, --json, --executable, --manifest, --output-appx-directoryplus -c/--configuration, --no-build, --no-restorea .-p/--property

Tip

Konzolová aplikace se ve výchozím nastavení vytiskne do terminálu. Zabalená aplikace spuštěná prostřednictvím AUMID nemá žádnou konzolu, takže aplikace jen pro konzolu by běžela správně a nevytiskla nic. Winapp se tomu vyhnout: aplikace se OutputType=Exe spouští prostřednictvím aliasu spuštění, který dědí stdin/stdout/stderr tohoto terminálu. Stále získáte identitu balíčku a nemusíte ji žádat:

winapp run counter.cs

Místo toho předejte --without-alias aktivaci AUMID – aplikace pak běží bez konzoly a nic tady nevytiskne. Aplikace s oknem (WinExe) zobrazuje okno, takže udržuje aktivaci AUMID. Pokud chcete, aby se v tomto terminálu i tak stalo, předejte --with-alias ji. Pokud chcete opravit volbu v souboru místo na každém příkazovém řádku, nastavte stejnou vlastnost jako .csproj :

#:property WinAppRunUseExecutionAlias=false

Alias winapp deklaruje název rodiny balíčku s předponou winapp- , takže com.contoso.counter publikuje .CN=Youwinapp-com.contoso.counter_gspb8g6x97k2t.exe Tato koncová část je hodnota hash vydavatele Windows odvozena, takže dvě aplikace sdílející název pod různými vydavateli stále získávají různé aliasy. Předpona zachovává název jasný od skutečných příkazů: aplikace získá python.cswinapp-… alias, nikdy python.exe. Pokud vytvoříte vlastní manifest, použije se alias, který deklarujete, as-is a winapp nic přidá.

To platí jenom pro alias. Samotná registrace je klíčem k názvu balíčku, takže spuštění druhé aplikace, která deklaruje totéž WinAppPackageName u jiného vydavatele, nahradí první registraci, nikoli sedí vedle ní. Pokud chcete, aby se obě aplikace zaregistrovaly najednou, dejte každé aplikaci vlastní název.

winapp run vytiskne registrovaný alias, takže nemusíte vypočítat hodnotu hash, abyste ji našli.

Alias je příkaz na cestě PATH, který trvá, dokud balíček zůstane zaregistrovaný. Pokud název již vlastní nějaký jiný balíček, winapp to řekne. Když odvozuje alias pro vás, spustí se místo toho přes AUMID, místo aby se spustila nesprávná aplikace; když jste požádali o jednu explicitní ( s --with-alias nebo #:property WinAppRunUseExecutionAlias=true ) se nezdaří, místo aby tiše dělal něco jiného.

Dvě možnosti režimu projektu se nevztahují , protože aplikace založená na souborech se konfiguruje sama. Jsou odmítnuty se zprávou pojmenování direktivy, která se má místo toho použít:

Možnost	Místo toho použít
-f/--framework	#:property TargetFramework=net10.0-windows10.0.22621.0
--project	nothing – .cs soubor je projekt

--arch a -r/--runtime fungují stejně jako v režimu projektu. Pokud ani jeden neprojdete, winapp buildy pro architekturu vašeho počítače – což je to, co samostatná Windows App SDK aplikace potřebuje, protože bez sestavení AnyCPU sady SDK a selže s WindowsAppSDKSelfContained requires a supported Windows architecture. V souboru se respektuje a #:property RuntimeIdentifier=win-arm64 explicitní --arch/--runtime přepsání.

Zabalené i rozbalené obě práce, rozpoznané z efektivního WindowsPackageType přesně jako v režimu projektu: výchozí zaregistruje volné rozložení a spustí ho s identitou, zatímco #:property WindowsPackageType=None sestaví aplikaci, nainstaluje odpovídající aplikace pro Windows Runtime a spustí .exe přímo. (Zabalená aplikace se spouští prostřednictvím svého aliasu spuštění nebo prostřednictvím aktivace AUMID – viz výše uvedená poznámka ke konzole. Tato volba je oddělená od toho, jestli je zabalená.) Možnosti identity (--no-launch, --with-alias, --without-alias, --clean--unregister-on-exit, --manifest--output-appx-directory) se vztahují pouze na zabalené aplikace.

Spuštěno s dotnet run

Nemusíte winapp psát vůbec. Odkaz na Microsoft.Windows.SDK.BuildTools.WinApp balíček ze souboru a prostý dotnet run vám poskytne stejné spuštění balíčku:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Cíl msbuild balíčku přesměruje spuštění na winapp, který balíčky, registruje a spustí aplikaci, která dotnet run je právě sestavená – není znovu vytvořena. Zpracování manifestu je beze změny: winapp ji vyřeší přesně tak, jak to dělá winapp run, takže #:property WinAppManifestPath=… a vedle .cs<filename>.appxmanifest toho jsou ctěny (viz Přineste si vlastní manifest), adresář je Package.appxmanifest stále ignorován a jinak jeden je generován z vašich #:property direktiv a aktualizován každé spuštění.

Aby k přesměrování mohlo dojít, musí být splněny dvě podmínky:

Direktiva	Proč
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*	cíle provádějící přesměrování expedice v tomto balíčku
#:property TargetFramework=net10.0-windows…	prostý net10.0 soubor je ponechán sám, takže se spustí rozbalený

Přidání #:property WindowsPackageType=None také ponechá soubor samotný: dotnet run pak přímo spustí .exe bez identity. Pokud chcete nejprve nainstalovat odpovídající aplikace pro Windows Runtime, použijte winapp run pro rozbalenou cestu.

Nastavte #:property EnableWinAppRunSupport=false možnost odhlásit se od přesměrování zcela a WinAppRun* vlastnosti popsané v části Konfigurace , které mají tvarovat spuštění , například:

#:property WinAppRunUnregisterOnExit=true

Pokud dotnet run se aplikace rozbalí, když jste očekávali identitu, zeptejte se MSBuildu, proč. Používejte dotnet build, ne dotnet msbuild – syntetizuje pouze dotnet build virtuální projekt, pomocí kterého je aplikace založená na souborech zkompilována:

dotnet build counter.cs -t:WinAppRunSupportInfo

Režim jednoho souboru vyžaduje .NET SDK 10.0.300 nebo novější.

Registrace prožije spuštění. winapp run counter.cs po ukončení aplikace ponechá balíček zaregistrovaný, stejně jako režim složky a projektu – takže přežije a znovu spustí stejný soubor, místo LocalState aby se hromadily registrace, znovu použil stejnou identitu. Winapp říká, že poprvé zaregistruje aplikaci a winapp unregister vezme .cs samotnou:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs nepotřebuje žádnou cestu manifestu: vyhodnotí hodnoty souboru #:property stejným způsobem run a odebere pouze balíček zaregistrovaný z výstupu sestavení daného souboru. Aplikace se stejným názvem zaregistrovaná z jiné složky se odmítne, pokud neprojdete --force. Pokud spuštění použilo možnost, která tvaruje identitu nebo rozložení, předejte stejnou možnost:unregister

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p přepíše vlastní direktivy souboru a Directory.Build.props vedle .cs tlačítka může klíč WinAppPackageName vypnout $(Configuration) , nebo $(RuntimeIdentifier) - takže každý z nich může změnit, který balíček se zaregistruje.

Jakmile se dočasný výstup sady SDK vyčistí, už nemůže potvrdit, winapp unregister counter.cs že registrace pochází z daného souboru, a přeskočí – slouží winapp unregister --prune k vymazání registrací, jejichž soubory jsou pryč, nebo --force k odstranění konkrétního souboru. Pokud se používá --output-appx-directoryspuštění, předejte mu stejný adresář unregister , aby rozpoznal rozložení.

Totéž platí pro vlastní výstupní cestu: vlastnictví je potvrzeno ze standardního <root>\bin\<configuration> rozložení sady SDK, takže spuštění vytvořené pomocí nelze spárovat se zdrojovým souborem -p OutputPath=<somewhere-else> . unregister přeskočí místo uhodnutí širšího adresáře – pojmenujte rozložení pomocí --output-appx-directory, nebo použijte --force.

Příklady s jedním souborem:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Poznámka:

Výchozí identita obsahuje krátkou hodnotu hash cesty k souboru – counter.cs stane se něco podobného counter-a1b2c3d4 – takže dva counter.cs soubory v různých složkách jsou různé aplikace a zachovat si vlastní nastavení a LocalState. Hodnota hash je odvozena z cesty, takže přežije úpravy a znovu se spustí a změní se pouze v případě, že soubor přesunete. Nastavte #:property WinAppPackageName=<name> si vlastní volbu stabilní identity; je normalizováno na to, co Identity/@Name umožňuje – znaky mimo [-.A-Za-z0-9] jsou vynechány, názvy kratší než 3 znaky jsou vycpané 1a výsledek je omezen na 50 znaků, takže My App se zaregistruje jako MyApp. V obou směrech se v nabídce Start a nastavení zobrazí vaše WinAppDisplayName (výchozí: název souboru), ne identita. Identita je vždy vymezena na váš uživatelský účet, takže nikdy nekoliduje s jiným uživatelem na stejném počítači.

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

Při použití balíčku NuGet Microsoft.Windows.SDK.BuildTools.WinAppdotnet run automaticky vyvolá winapp run.

Všechno napsané po dotnet run předání vaší aplikaci přesně tak, jak by to bylo bez balíčku. Nakonfigurujte spouštěč s následujícími vlastnostmi nástroje MSBuild:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

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	odvozené z aplikace	Místo aktivace AUMID spusťte alias spuštění. Aplikace winapp ji ponechá bez sady, odvozuje ji: konzolová aplikace používá alias, aby jeho výstup dosáhl terminálu, a aplikace s oknem používá AUMID. Nastavte true nebo false se rozhodněte sami.
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, WinAppRunDebugOutput, WinAppRunUnregisterOnExit
WinAppRunDetach	WinAppRunNoLaunch, WinAppRunDebugOutput, WinAppRunUnregisterOnExit

WinAppRunUseExecutionAliasnení v tom seznamu záměrně, a to v obou směrech. false žádá o aktivaci AUMID, která již nepoužívá žádné spuštění a odpojení; true se jednoduše nepoužije, pokud je nastavena, protože alias spuštění vyžaduje sledovaný a spuštěný proces. Takže projekt, který kontroluje, <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> stále běží čistě v oblasti dotnet run -p:WinAppRunDetach=true, spouští se přes AUMID, a ne selhává.

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

argumenty :

• input– Cesta k .NET souborové aplikaci (jedna.cs), jejíž balíček by se měl zrušit. Jeho identita se vyřeší stejným způsobem winapp run – z vytvořeného manifestu, pokud ji aplikace obsahuje, jinak z jejích #:property hodnot – takže není potřeba žádná cesta manifestu. Vynechání použití --manifest nebo automatického zjištění manifestu v aktuálním adresáři Nelze kombinovat s --manifestnázvy balíčků jiným způsobem a lze je přeložit na jiný.

Možnosti:

• --manifest <path> – Cesta k Package.appxmanifest (výchozí: autodetekce z aktuálního adresáře)
• --force - Pouze pro místní zrušení registrace 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. Je odmítnut s --on; cílové kontroly vlastnictví nelze obejít.
• --on <target> - Odeberte odpovídající registraci vývoje vlastněného winappem z sandboxtohoto počítače, ne z tohoto počítače. Vyžaduje manifest a nepodporuje --force. Viz vyčištění aplikace sandboxu.
• --prune - Odeberte všechny registrace v režimu vývoje, jejichž soubory jsou pryč. Nelze kombinovat se vstupem, , --manifest, --property--configuration, --arch, , --runtimenebo --output-appx-directory.
• -p, --property <Name=Value> – vlastnost MSBuild použitá při překladu .cs identity aplikace založené na souboru. Opakovatelný. Předání stejných vlastností ovlivňujících identitu použitého spuštění (např. -p WinAppPackageName=...), protože vlastnost příkazového řádku přepisuje vlastní #:property direktivy souboru. Platí jenom pro .cs vstup.
• -c, --configuration <name> – Konfigurace sestavení používaná při překladu .cs identity aplikace založené na souborech. Výchozí hodnota: Debug. Předejte stejnou konfiguraci, jakou jste použili: Directory.Build.props vedle .cs můžou být nastaveny WinAppPackageName nebo WinAppManifestPath podmíněně zapnuty $(Configuration). Platí jenom pro .cs vstup.
• --arch <x64|arm64|x86> – Cílová architektura použitá při překladu .cs identity aplikace založené na souborech. Výchozí hodnota: aktuální architektura procesu. Předat stejnou architekturu, jakou se použila, protože identitu je možné také vypnout $(RuntimeIdentifier). Platí jenom pro .cs vstup.
• -r, --runtime <rid>– Cílový identifikátor modulu runtime .NET (např. win-x64) používaný při překladu .cs identity aplikace založené na souborech. Používá se pouze jeho architektura a přepisuje --arch. Platí jenom pro .cs vstup.
• --output-appx-directory <path> – Adresář rozložení AppX, ze které byl balíček zaregistrovaný. Je potřeba pouze při použití --output-appx-directoryspuštění , protože nic v záznamech balíčku, které možnost spuštění vytvořila jeho rozložení.
• --json – Formátování výstupu ve formátu JSON

Co to dělá:

• Určuje název balíčku – z .cs vyřešené identity souboru nebo načtením 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ěří, že balíček patří do aplikace, kterou jste pojmenovali (pokud --force) – jeho umístění instalace musí být umístěné pod adresářem, který jste identifikovali: .cs vlastní výstup sestavení souboru, adresář manifestu, aktuální adresář nebo explicitní --output-appx-directory. Balíček, jehož umístění instalace nelze přeložit (jeho soubory byly odstraněny), se přeskočí, protože samotná identita není důkazem o vlastnictví: dvě aplikace, které nastavily #:property WinAppPackageName=counter stejnou identitu z různých složek. Slouží --prune k vymazání registrací, jejichž soubory jsou pryč.
• Zrušení registrace odpovídajících balíčků

Vyčištění mrtvých registrací (--prune):

Registrace si prožije své soubory. Odstranění výstupu sestavení, stromu projektu nebo (pro souborovou aplikaci) umožňuje Windows vyčištění %LOCALAPPDATA%\Tempa balíček zůstane zaregistrovaný: Windows zachová identitu a její položku nabídky Start, ale aktivace bezobslužně nic nedělá. Ty se hromadí neviditelně.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Zvažují se pouze registrace v režimu vývoje a každý z nich se odebere úplným názvem balíčku, takže stejný pojmenovaný balíček je stále nainstalovaný z živého umístění beze změny. Výzva existuje, protože chybějící umístění instalace je obvykle odstraněná složka, ale popisuje také balíček zaregistrovaný z odpojené síťové sdílené složky nebo vyměnitelné jednotky – před potvrzením zkontrolujte seznam.

Příklady:

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

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

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

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

# Remove every dev registration whose files are gone
winapp unregister --prune

# 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>- Extrahujte certifikát publisher z manifestu Identity/@Publisher. Vyžaduje se jenom vydavatel, takže manifest částečně dokončený stále funguje. Pokud manifest nemá použitelného vydavatele, příkaz se nezdaří místo nahrazení výchozí hodnoty, takže certifikát nemůže nikdy bezobslužně neshodovat manifest.
• --publisher <name>- Publisher pro certifikát. Při generování certifikátu má tato možnost přednost před --manifest; explicitně prázdná hodnota selže místo použití vydavatele manifestu. Přijímá úplný rozlišující název X.500 (např CN=Contoso, O=Contoso Ltd, C=US. ) nebo úplný název X.500, který se automaticky zabalí jako CN=<name>. Součásti musí být s jednou hodnotou a oddělené čárkami; sítě RDN s více hodnotami (CN=Foo+OU=Bar) a zpětné lomítka nejsou podporovány, protože vydavatel manifestu MSIX je nemůže reprezentovat. Poškozený rozlišující název (např. CN= nebo CN=A,,O=B) je odmítnut s nenulovým ukončením a chybou, která problém pojmenovává, a negeneruje certifikát, který se nikdy neshoduje s vydavatelem manifestu.
• --output <path> – Výstupní cesta k souboru certifikátu (podporuje absolutní a relativní cesty)
• --password <password> – Heslo certifikátu (výchozí hodnota: passwordveřejně známá – viz výstup JSON a zabezpečení)
• --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": "..."}).

Výstup JSON:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher je zobrazovaný název a subjectName úplný rozlišující název, pro který byl certifikát vystaven. defaultPasswordIsPublic je vždy přítomen. Pokud ano true, .pfx je chráněn heslem, který může každý odhadnout, takže certifikát musí podepisovat pouze sestavení, která zůstanou na vašich vlastních počítačích – zkontrolujte ho před tím, než skript předá certifikát všemu jinému. warnings obsahuje stejné zpřístupnění jako text a vynechá se, pokud není k dispozici nic, co by se ohlásilo. publicCertificatePath zobrazí pouze s --export-cer.

Informace o certifikátu

Zobrazení podrobností o certifikátu ze souboru PFX nebo CER 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 nebo CER)

Možnosti:

• --password <password> - Heslo pro soubor PFX, ignorováno pro veřejný CER (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> <cert-path> [options]

argumenty :

• file-path – Cesta k balíčku MSIX nebo spustitelnému souboru pro podepsání
• cert-path – Cesta k podpisovým certifikátům (.pfx)

Možnosti:

• --password <password> - Heslo certifikátu (výchozí: "heslo")
• --timestamp <url> – ADRESA URL serveru časového razítka RFC 3161

Příklady:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --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

Ověření podpisu

Nástroje sestavení se stáhnou z NuGetu a pak se spustí, takže aplikace Winapp zkontroluje, jestli má každý z nich platný podpis Microsoft Authenticode bezprostředně před spuštěním. Certifikát musí jako podpisovou organizaci pojmenovat Microsoft Corporation. To platí pro každý příkaz, který je součástí prostředí nástroje SADY SDK, včetně tool, packagea sign. Nástroj, který selže, se nespustí:

'mt.exe' is not validly signed by Microsoft, so it was not run (C:\...\mt.exe).

Chyba v této části znamená, že soubor na disku není to, co Microsoft publikováno – nejčastěji je to poškozené nebo částečné stahování. Odstraňte balíček z mezipaměti NuGet a spusťte příkaz znovu, aby ho winapp znovu stáhl.

Winapp pak nástroj ponechá otevřený tak dlouho, dokud se spustí, takže soubor, který je zaškrtnutý, je soubor, Windows načte. Pokud nástroj nelze uložit na místě, nespustí se ani:

'mt.exe' could not be held open for verification, so it was not run (C:\...\mt.exe).

Ukončete cokoli, co soubor používá – antivirová kontrola nebo otevřený editor je obvyklá příčina – a spusťte příkaz znovu. Pokud se nástroj nepoužívá, odstraňte balíček z mezipaměti NuGet, aby ho aplikace WinApp znovu stáhla.

---

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

---

cíl

Spusťte příkazy, zkopírujte soubory, zkontrolujte stav nebo zachyťte celou plochu hosta.

Každá slovesa přebírá sandbox jako svůj první argument. Kromě toho snapshotmůžou tyto příkazy připravit nebo spustit sandbox. Požadavky, oprávnění, životní cyklus a obnovení najdete v tématu Windows spuštění sandboxu.

target exec

Spusťte příkaz jako uživatel typu host.

winapp target exec <target> [--cwd <path>] [--json] -- <executable> [arguments...]
winapp target exec sandbox -- dotnet --info

Argumenty po -- zachování jejich hranic. Standardní datové proudy a ukončovací kód procesu hosta se přeposílají; to není úplný terminál. --json Formátuje selhání winappu v stderru beze změny stdout podřízeného příkazu. Strukturovaná error.code slouží k rozlišení cílového selhání od vlastního stavu ukončení aplikace.

Explicitní WINAPP_UI_WORKFLOW_ID také seskupuje volání uživatelského rozhraní hosta provedená příkazem. Viz koordinace uživatelského rozhraní sandboxu.

cílové nasdílení změn a přijetí změn cíle

Zkopírujte soubor nebo adresář ve směru pojmenovaném slovesem.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Cílové cesty jsou relativní vzhledem ke spravované pracovní oblasti cíle; absolutní, rootované a cílové cesty UNC jsou odmítnuty. Cíl souboru obsahuje jeho název souboru. Viz Spouštění příkazů a kopírování souborů pro rozložení adresáře, zpracování odkazů a spuštění zkopírovaného skriptu.

cílový snímek

Připravenost, nasazení a okna hosta sestav bez spuštění sandboxu

winapp target snapshot <target> [--json]
winapp target snapshot sandbox

Nepřipojí klienta ani opraví agenta. Žádný spuštěný sandbox není úspěšný výsledek, ne chyba. Viz Kontrola sandboxu pro interpretaci ID připravenosti a procesů.

cílový snímek obrazovky

Zachyťte plochu hosta v nativní velikosti pixelů jako hostitele PNG bez výběru aplikace nebo ohraničení okna hostitele. --json hlásí původ souřadnic hostů.

winapp target screenshot <target> [-o <host-path>] [--json]
winapp target screenshot sandbox -o .\sandbox.png

Použijte ui screenshot --on sandbox -a <app> místo toho okno aplikace. Viz Snímky obrazovek a nahrávky pro požadavky klientů, omezení fokusu a zpracování výstupů.

cílový záznam

Nahrajte plochu hosta do H.264 MP4. Hostování videosouborů a snímků dorazí po dokončení nahrávání; Json a manifest rámce popisují jakékoli škálování nebo odsazení.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Používá dobu trvání, rámec, přepsání a možnosti výsledku ui record, ale zachycuje plochu místo jedné aplikace. Preferujte pozitivní --duration-sec pro bezobslužné použití rozhraní příkazového řádku; pomocník npm vyžaduje durationSec. Informace o částečných důkazech a selhání připravenosti pro zachycení najdete v sandboxu.

---

find-ui

Nejdřív agent. find-ui je sestaven především pro agenty pro kódování AI – umožňuje agenta načíst skutečné kódy WinUI z expediční galerie místo vynalézání a --json každý výsledek (a každé selhání) strojově čitelný. Funguje stejně dobře jako ručně.

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]

Galerie, sada nástrojů a corpora Reactor se dodávají uvnitř rozhraní příkazového řádku, takže find-ui funguje bez přístupu k síti , včetně prvního spuštění v sandboxu agenta nebo za podnikovým proxy serverem, který blokuje raw.githubusercontent.com. Když je GitHub dosažitelný, rozhraní příkazového řádku se z něj aktualizuje a uloží výsledek na uživatele do <global .winapp>/cache/find-uimezipaměti ; integrovaný korpus je pouze podlaha, nikdy strop. Data uložená v mezipaměti se aktualizují maximálně každých 24 hodin nebo na vyžádání.--refresh

Předdefinovaný korpus se znovu načte z GitHub pokaždé, když se sestaví stabilní verze, a aktualizace, která selže, zastaví sestavení vydané verze místo tiše expediční starší data – pekárna načte stejnou cestu --refresh kódu, takže selhání znamená, že živá aktualizace je poškozena a stojí za to prošetřit před odesláním. Uvolnění lze stále snížit proti dříve potvrzeného korpusu, ale pouze jako explicitní přepsání. Když se výsledky obsluhují z předdefinované kopie korpory Galerie/Toolkit/Reactor, find-ui říká to na stderru a --json výstupu "corpus": "embedded" (další hodnoty: "network" pro nové načtení, "cache" pro místní mezipaměť). Požadavek jen na jádro – --source corenebo --id sada, která je všechna základní vzory – také sestavy "embedded" , protože kurátorované základní vzory jsou zkompilovány do rozhraní příkazového řádku a nikdy se nenačtou; nevytiskne žádné oznámení o nestaralosti, protože --refresh je nelze změnit. Pole corpus je hlášeno vždy, když byly výsledky podávány; chybí pouze tehdy, když nelze vůbec načíst žádný korpus.

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

Související:find-ui vyhledává ukázky WinUI; umožňuje find-api prohledávat plochu rozhraní API (typy, členy, výčty) odkazy na projekt a winapp ui search prohledávat strom uživatelského rozhraní spuštěné aplikace .

---

find-api

Nejdřív agent. find-api je postavena především pro agenty kódování AI – zdůvodňuje vygenerovaný kód v rozhraní API, ve skutečnosti odkazuje na projekt místo jeho překryvného modelu a --json plus nenulové ukončovací kódy u chybějících symbolů, aby agent gate codegen na odpovědi. Funguje stejně dobře jako ručně.

Vyhledejte a zkontrolujte povrch rozhraní API Windows/WinRT (typy, členy, výčty, obory názvů), které jsou k dispozici pro projekt, vyřešené z odkazovaných .winmd/.dll metadat. Holý formulář hledá; dílčí příkazy se přečtou do konkrétního typu, oboru názvů nebo samotného indexu.

winapp find-api "<query>" [options]
winapp find-api [command] [options]

Index se sestaví z obnovených balíčků NuGet/SDK projektu (prostřednictvím project.assets.json) při prvním použití a automaticky se aktualizuje při obnovení projektu. Žije v globální .winapp mezipaměti (cache/find-api/) a sdílí se napříč projekty. Nejprve obnovte projekt (winapp restore nebo dotnet restore).

Každá shoda je uvedená v oboru názvů s balíčkem, který ho dodává, a jednořádkovým souhrnem toho, co dělá, takže výsledek je použitelný bez druhého members volání:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Přidejte --verbose také k tisku souboru mezipaměti na disku, který zálohuje každý obor názvů, což je užitečné při diagnostice zastaralého nebo neočekávaného indexu.

Spuštění winapp find-api bez dotazu vůbec vytiskne krátký souhrn využití a ukončí 0 – jedná se o žádost o pomoc, ne hledání, které nic nenašlo.

Obory. Každá odpověď pochází z přesně jednoho oboru, který je hlášený jako scope v --json textovém výstupu a jako poznámka:

• project - projekt v aktuálním adresáři (nebo --project / --project-dir). Pokrývá sadu Windows SDK, Windows App SDK a vlastní balíčky NuGet projektu. Metadata Windows App SDK jsou vydáním odkazů na projekt: pokud má počítač nainstalovaný novější aplikace pro Windows Runtime, zobrazí upozornění a ponechá ho mimo potvrzení typů, find-api které projekt nemůže zkompilovat.
• sdk– machine-wide Windows SDK + Windows App SDK metadata, používá se automaticky, když aktuální adresář neobsahuje žádný projekt a žádné řešení. find-api Díky tomu je možné zkoumat rozhraní API dříve, než nějaký projekt existuje, a nepotřebuje přístup k síti. Záměrně neobsahuje balíčky NuGet třetích stran, takže v tomto rozsahu se nenajde typ z (řekněme) komunitní sady nástrojů.

Dotaz z adresáře bez projektu a řešení vždy odpovídá obor – nikdy podle toho, který projekt se bude indexovat ve sdílené mezipaměti – takže výsledky nikdy nezávisí sdk na nesouvisejícím globálním stavu. Předejte --project sdk výběr oboru sady SDK explicitně z projektu a winapp find-api refresh --project sdk jeho opětovné sestavení po instalaci nové sady Windows SDK.

Adresáře řešení Z adresáře .sln/.slnx , který obsahuje soubor bez souboru projektu, řešení vytvoří odpověď místo sdk oboru – indexují se na vyžádání, takže jsou zahrnuté balíčky NuGet. Když řešení sestaví více než jeden indexovaný projekt, dotaz je vypíše --project <name> a požádá o místo toho, aby ho vybral.

Příkazy:

• (holý)find-api "<query>" ["<query>"...] - Typ hledání a názvy členů, které se vrátí k jejich zdokumentovaným souhrnům seskupeným podle oboru názvů
• members <type> [<type>...] [--filter <text>] - Výpis vlastností, událostí a metod typu (deklarované členy s podpisy, zděděné členy shrnuté deklarací typu)
• check-property <type> <property> [<property>...] – Ověřte, že vlastnosti existují u typu (pokud nějaké chybí, ukončí nenulu). Vlastnost jen pro čtení je hlášena s ⚠️ a "jen pro čtení, nelze jej přiřadit" místo prostého ✅, takže vlastnost, jako ActualWidth je například není omylem pro něco, co můžete nastavit. V názvech vlastností se rozlišují malá a velká písmena, protože jazyk C# a XAML jsou: check-property Button background ukončí nenulu a nabízí Background se jako blízkou shodu a nehlásí název, který ve skutečnosti nepůjde napsat.
• enums <type> [<type>...] [--filter <text>] - Výpis hodnot výčtu (ukončí nenulu, pokud typ není výčtem)
• packages - Vypište indexované balíčky metadat s počtem jednotlivých balíčků nebo členů.
• stats - Zobrazit agregační statistiku indexu (balíčky, obory názvů, typy, členy, .winmd soubory)
• refresh [--scan] - Znovu sestavte index projektu (--scan indexuje každý projekt v adresáři). Název --project <name>, který neodpovídá žádnému indexovaného projektu, se místo indexování aktuálního adresáře nezdaří.

Batching.search, , membersa enumscheck-property přijmout více témat v jednom vyvolání. U agenta umělé inteligence se jedná o jednu největší nákladovou páku: mezní náklady vyhledávání dominují odezvou (každý hovor znovu odešle celou konverzaci), ne velikostí datové části, takže jedna odpověď na deset otázek je mnohem levnější než deset volání.

• Jeden předmět vrátí přesně tvar datové části, který má vždy v textu i --json.
• Dvě nebo více subjektů vrací obálku – { "count": N, "results": [ ... ] } v --json, přičemž každý prvek je normální datovou částí jednoho předmětu; check-property přidává missingCount. Textový výstup vykreslí každý předmět v pořadí pod jedním záhlavím oboru.
• check-property batches properties on one type: první argument je typ, každý argument po jeho vlastnosti. V dávkovém režimu vlastnost, která existuje, vytiskne jeden ✅ řádek. Úplné podrobnosti téměř zmeškané se vytisknou jenom pro ty, které ne.
• Dávka se ukončí 0 pouze v případě, že byl nalezen každý předmět a byl nalezen , takže dávka je stále bezpečná pro bránu codegen.

Pořadí hledání. Dotaz, který přesně odpovídá názvu typu, je seřazený před částečnými shodami a když krátký název sdílí několik oborů názvů, zobrazí se jako nejednoznačný – dotaz, jako NavigationView je třeba hlásí několik oborů názvů, které definují tento přesný typ místo každého oboru názvů obsahujícího podobně pojmenovaný symbol. Seznam nejednoznačnosti --maxdodržuje a normální výsledky jsou stále vytištěny pod ním.

Zadejte názvy.members, check-propertya enums přijměte krátký název (NavigationView) nebo plně kvalifikovaný název (Microsoft.UI.Xaml.Controls.NavigationView). Pokud je krátký název sdílený moderním Microsoft.* typem a starším Windows.* dvojčetem UPW, Microsoft.* typ odpoví – což je projekce, kterou aplikace Windows App SDK používá – a přeložený plně kvalifikovaný název se vždy zobrazí. Všechny ostatní kolize ukončí nenulu a zobrazí seznam kandidátů místo hádání.

Podpisy metody. Podpis se vytiskne tak, jak byste volání napsali: metoda, kterou voláte na typ, místo instance se zobrazí s staticparametrem podle odkazu a zobrazí se parametr podle odkazu s klíčovým slovem, které skutečně potřebuje – out, innebo ref. Proto TryGetValue čte Boolean TryGetValue(String key, out String value), který se zkompiluje jako zapsaný.

Možnosti:

• --max <n> - Maximální počet výsledků hledání seskupených oborem názvů (výchozí 5; pouze vyhledávání). Také zasadí seznam nejednoznačnosti, takže krátký dotaz, který koliduje mezi mnoha obory názvů, zůstane čitelný.
• --filter <text> - Upřesní výpis members a enums: malá a malá písmena se neshodují s podřetěděným podřetědcem u názvu člena/hodnoty. Nejlíbí se na typech se stovkami členů. Většina výčtů je dostatečně malá, aby se vypsaly celé (dokonce i Symbolnejvětší v WinUI při 197 hodnotách), takže jejich filtrování obvykle stojí více, než ušetříte, jakmile vymyslíte druhý odhad. Nikdy znovu nespouštět stejný příkaz s jiným textem filtru – vysujte ho jednou a přečtěte si ho.
• --all - Vypsat membersúplný povrch: úplné podpisy pro zděděné členy, plus statické a popisy vlastností závislostí a popisy jednotlivých členů, z nichž všechny nefiltrované výpisy vynechány (viz velikost výpisu níže). --verbose to znamená; použít --all , pokud chcete --json, který nelze kombinovat s --verbose.
• --scan - Rekurzivní zjišťování a indexování každého projektu v adresáři (refresh pouze)
• --project <name>– Project dotazování (odpovídá .csproj/.vcxproj názvu) nebo sdk dotazování rozsahu sady WINDOWS SDK pro celý počítač
• --project-dir <path>– Project adresář k dotazování (výchozí hodnota je aktuální adresář). Cesta, která neexistuje, je chyba – nikdy není bezobslužná odpověď z sdk oboru.
• --json – Vygenerování strojově čitelné datové části na stdoutu (podporováno každou slovesou). Datové části dotazů identifikují index, který odpovídá ( scopeproject nebo sdk), projectNamea projectDir (chybí pro obor sady SDK) – názvy projektů nejsou jedinečné napříč adresáři, takže projectDir je spolehlivá identita. 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ý.

Příklady:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Když --filter se použije, výstup stále hlásí nefiltrovaný součet (totalValuesnebototalEvents//totalPropertiestotalMethods v--json), takže úzké zobrazení se nikdy nemýlí s malým rozhraním API. Filtr, který se shoduje s nic, se stále ukončí 0 a říká tak explicitně – to je "nic odpovídající vašemu filtru", ne "žádný takový typ".

Velikost výpisu Nefiltrovaný výpis je jeden nákladný members tvar – members Button pokrývá 288 členů, z nichž 280 se dědí ze 6 základních typů. Nefiltrované volání je dotaz orientace ("jaký je tento typ, zhruba to, co to může dělat?"), takže odpoví, že a vynechá části, ze které se nic nezapisuje:

• Zděděné podpisy členů – zděděné členy jsou seskupené pouze deklarací typu a uvedené pouze podle názvu, takže tvar zděděného povrchu je stále viditelný bez 280 úplných podpisů.
• Statické vlastnosti identifikátoru závislostí (BackgroundProperty) – 28% typických vlastností ovládacího prvku WinUI. Existují, aby byly předány GetValue/SetValue, nejsou přiřazeny.
• Popisy jednotlivých členů – prose XML-doc, zhruba 16% datové části.
• Pole odvozená jejich okolím v --json: kind (implikuje obsahující propertiesmethods/events/pole), returnType (počáteční token signature) a inherited když je false (odvozeno ).declaringType

Co bylo vynecháno, je vždy hlášeno (hiddenDependencyPropertiesdescriptionsOmitted, a hint in --json; "Vynecháno:" řádek v textu) a součty stále popisují celý typ. --all Kompletní --filter povrch s úplnými podpisy a popisy, takže members Button --filter BackgroundProperty stále najde identifikátor a members Button --filter Click stále vrátí Clickzděděný podpis. samples/winui-appMěřeno , to trvá members Button --json od 91 954 do 10 567 znaků (−88,5%) při opuštění --filter a --all bajt-identické.

Jak se dotaz shoduje. winapp find-api "language model" seřadí LanguageModel výše uvedená slova, jejichž slova jsou rozptýlena mezi obory názvů a členy, včetně mimo projekt při indexování typu. Hledání je lexikální, ne sémantické: odpovídá celý identifikátor slov místo jakéhokoli spuštění písmen, takže llm vyhledá IImageLLMAdapterSession , ale ne ScrollMode. Když dotaz neodpovídá žádnému názvu, pokusí se proti zdokumentovaným souhrnům typů a členů, což je to, co umožňuje "random-access stream" najít IRandomAccessStream. Popisy se řadí pod každou shodu názvů a pouze souhrny balíčků, které se skutečně dodávají, jsou prohledávatelné – balíček bez dokumentace XML nepřispívá k žádnému textu popisu.

Projekty bez souboru projektu MSBuild Elektronová aplikace (nebo jakákoli jiná aplikace, která není .NET řízená winapp.yaml) nemá žádnou .csproj a proto ne project.assets.json. find-api indexuje ho ze zápisu .winapp/winmds.lock.jsonwinapp restore , který zaznamenává stejnou věc: každý vyřešený balíček, jeho verzi a soubory, které .winmd přispívá. Takový projekt je pojmenován po svém adresáři a jeho index přestane fungovat, když se soubor lockfile přepíše. Adresář, který obsahuje index i .csproj a je winapp.yaml indexován z .csproj, což je přesnější popis toho, co projekt kompiluje.

Záporné odpovědi jsou kvalifikované, pokud je index neúplný. Pokud metadata balíčku nelze přečíst, "žádný takový typ" a "tento balíček nebyl nikdy indexován" vypadají identicky a funguje na první, když je skutečně druhý vygeneruje kód proti rozhraní API, které jste řekli, neexistuje. Takže každá záporná odpověď, včetně search toho, který vrací nulové výsledky, nese poznámku, že index je částečný a ukazuje na winapp find-api refresh. Pozitivní odpovědi nejsou ovlivněné.

Obecné názvy typů Metadata ukládají obecné typy s příponou arity (IAsyncOperation`1), což není způsob, jakým je někdo zapisuje. members, enumsa check-property přijmout každý formulář: IAsyncOperation, IAsyncOperation<StorageFile>a IAsyncOperation`1 všechny přeložit na stejný typ. Holý název odpovídá libovolnému aritu; Musí se shodovat se stavem arity (v obou zápisech), takže Holder<A, B> se nepřeloží na parametr s jedním parametrem Holder<T>.

--json datové části vynechá diagnostiku. Cesty k souborům mezipaměti se zobrazují pouze v části --verbose (odpovídající textový výstup, kde už byly podrobné) a prázdné pole návrhů se vynechá, nikoli serializují jako [].

Ukončovací kódy:search bez přístupů, check-property u chybějící vlastnosti a enums u nesoučtového typu všechny ukončovací nenulové – generování kódu brány a kontroly CI na nich. Dávkové vyvolání ukončí nenulu, pokud některý předmět selže. Vlastnost jen pro čtení není neúspěšná – existuje, takže check-property ji ukončí a označí 0 příznakem ve výstupu (writable: false v --json). Sestavy initwritable: false vlastností ze stejného důvodu: lze jej nastavit v inicializátoru objektů a jeho podpis říká { get; init; }, ale přiřazení poté se nezkompiluje.

Související:find-api odpovědi "existuje toto rozhraní API a jaké jsou její členy?"; slouží find-ui k vyhledání funkční ukázky WinUI pro ovládací prvek.

---

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

Identita pracovního postupu uživatelského rozhraní

winapp ui příkazy, které řídí fyzickou plochu, vždy spolupracují, takže dva pracovní postupy spuštěné najednou nemohou ukrást fokus sebe navzájem nebo zavřít navzájem nabídky. Toto rozhodčí řízení nepotřebuje žádné nastavení a nelze ho vypnout.

Co je volitelné, je kontinuita. Ve výchozím nastavení je každý příkaz samostatným jedním snímkem, který uvolní plochu hned po dokončení. Pokud chcete zachovat plochu napříč několika příkazy, dejte jim stejné ID pracovního postupu:

$env:WINAPP_UI_WORKFLOW_ID = [guid]::NewGuid().ToString()

Použijte stejnou hodnotu pro spolupracující procesy (například záznam a kliknutí, které by mělo zaznamenat) a různé hodnoty pro nezávislé pracovní postupy. Každý příkaz bez ID je vlastní jednorázový pracovní postup, i když se spustí několik z jednoho prostředí, takže hostitelé, kteří spustí nové prostředí na každý příkaz, musí do každého z nich vložit stejnou explicitní hodnotu. Hodnota je neprůrůzná, nikdy se nechová jako přihlašovací údaje a je stále trvalá jako hodnota hash SHA-256. Viz model UI Automation → Koordinace souběžných pracovních postupů uživatelského rozhraní.

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í oken nebo elementu ve formátu PNG (více oken tvoří jeden složený formát PNG; viz rozsah zachycení)
• 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
• yield - Uvolněte uživatelské rozhraní aktuálního pracovního postupu; vyžaduje WINAPP_UI_WORKFLOW_ID

Možnosti:

• -a, --app <app> – Cílová aplikace (název, název nebo PID)
• -w, --window <hwnd> - Cílové okno podle HWND (stabilní)
• --on <target> - Spusťte jakékoli ui příkazy v sandbox; názvy, IDENTIFIKÁTORy PIN a popisovače oken odkazují na hosta. Výstupy se doručí hostiteli. Informace o nastavení, koordinaci pracovních postupů a požadavcích klientů najdete v tématu Automatizace uživatelského rozhraní sandboxu .

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 evidence.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 ).
• --overwrite - Po dokončení nového pořízení nahraďte stávající výstupy záznamu; existující výstupy jsou ve výchozím nastavení odmítnuty. Zachovají se předchozí svazky rámců. Viz Obnovení výstupu záznamu.
• --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 postupujte podle pracovního postupu překryvného snímku obrazovky pro překryvné okno. Sledované v č. 646.

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