A parancssori felület dokumentációja és használata

A rendszerhéj befejezése

Parancsok, beállítások és értékek lapkiegészítésének engedélyezése. A beállítási utasításokért tekintse meg a Rendszerhéj-befejezési útmutatót .

# 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

init

Címtár inicializálása a Windows SDK-val, a Windows App SDK-val, valamint a modern Windows-fejlesztéshez szükséges egyéb eszközökkel.

winapp init [base-directory] [options]

Argumentumok:

• base-directory - Az alkalmazás/munkaterület alap-/gyökérkönyvtára (alapértelmezett: aktuális könyvtár)

Lehetőségek:

• --config-dir <path> - A konfiguráció olvasásához/tárolásához használt címtár (alapértelmezett: a kijelölt projektkönyvtár vagy az aktuális könyvtár, ha nincs projekt észlelve)
• --setup-sdks - SDK telepítési mód: "stabil" (alapértelmezett), "előzetes verzió", "kísérleti" vagy "nincs" (SDK-telepítés kihagyása)
• --ignore-config, --no-config – Ne használjon konfigurációs fájlt a verziókezeléshez
• --no-gitignore - Ne frissítse a .gitignore fájlt
• --use-defaults, --no-prompt - Ne kérje a kérést, és használja az összes kérés alapértelmezett értékét
• --config-only – Csak a konfigurációs fájlműveletek kezelése, a csomag telepítésének kihagyása
• --exe <path> – A végrehajtható alkalmazás elérési útja. Szükséges --sparse. Teljes csomag/SDK-beállítás helyett csak ritkán használt identitásjegyzéket hoz létre az exe számára.
• --sparse – Ritka identitásjegyzék (appxmanifest.xml) létrehozása meglévő asztali exe-hez. Kihagyja az SDK/csomag telepítését. Használja a --exe-vel.
• --name <name> – A csomag nevének felülbírálása (csak ritkán; alapértelmezett: az exe-ből következtetve)
• --publisher <CN> - Felülbírálja a közzétevő CN-jét (csak ritkán, alapértelmezett: az exe cégnevéből következtetve)
• --output-dir <path> - Könyvtár a ritka listában való íráshoz és Assets/ (csak ritkán; alapértelmezett: az sparse/ aktuális könyvtár egyik mappája)
• --force - Felülírja a célkönyvtárban lévő meglévőt appxmanifest.xml (csak ritkán). Nélküle az init egy meglévő jegyzék/eszköz cseréje helyett meghiúsul.
• --add-js-bindings (csak npm) – Hozzáadás winapp.jsBindings package.json és JS-/TypeScript-kötések létrehozása kérés nélkül (nem kompatibilis a --setup-sdks none)

A következő teendők:

• Konfigurációs fájlt hoz létre winapp.yaml (csak akkor, ha az SDK-csomagokat felügyeli; kihagyja a következővel --setup-sdks none: )
• Windows SDK és Windows App SDK csomagok letöltése
• C++/WinRT-fejléceket és bináris fájlokat hoz létre
• Package.appxmanifest létrehozása
• Buildelési eszközök beállítása és fejlesztői mód engedélyezése
• A .gitignore frissítése a létrehozott fájlok kizárásához
• Megosztható fájlok tárolója a globális gyorsítótár könyvtárában
• JS-kötéseket hoz létre Windows App SDK API-khoz, ha engedélyezve van (csak npm)

Automatikus projektészlelés:

Ha init címtárargumentum nélkül fut, az az aktuális könyvtárfa teljes körű első keresését hajtja végre a kompatibilis projektek (legfeljebb 10) megkereséséhez. Támogatott projekttípusok:

• Tauri – tauri.conf.json egy szinttel a könyvtár alatt található
• Elektron – package.json függőségekben electron vagy devDependenciesben
• Flutter – pubspec.yaml a projekt gyökerénél
• .NET – .csproj a projekt gyökérkönyvtárában
• Rozsda – Cargo.toml a projekt gyökerénél
• C++ – CMakeLists.txt a projekt gyökérkönyvtárában

A keresés kihagyja a gyakran figyelmen kívül hagyott könyvtárakat (node_modules, bin, obj, .git stb.). Ha egy kompatibilis projekt található, az alatta lévő alkönyvtárak nem kereshetők.

• Ha egy könyvtárargumentum meg van adva (például), a rendszer kihagyja a keresést, winapp init .winapp init path/to/projectés init csak az adott könyvtárat ellenőrzi egy kompatibilis projekt esetében.
• Ha --use-defaults (vagy --no-prompt) könyvtárargumentum nélkül van beállítva, hagyja ki a keresést, init és inicializálja az aktuális könyvtárat nem interaktív módon, először figyelmeztetést, ha ott nem észlelhető ismert projekttípus (pl. winapp init --use-defaults)
• Nem interaktív környezetekben (vezetékes stdin, CI, átirányított bemenet) init automatikusan viselkedést használ --use-defaults , és figyelmeztetést ad ki: Non-interactive environment detected. Using default values.
• Ha az aktuális könyvtár kompatibilis projekt, init azonnal továbblép
• Ha pontosan egy projekt található máshol, a rendszer kérni fogja, hogy erősítse meg a
• Ha több projekt is található, kiválaszthatja, hogy melyiket inicializálja – az aktuális könyvtár mindig elérhető tartalékként
• Ha nem található projekt, a rendszer figyelmezteti, és megkérdezi, hogy folytatja-e a műveletet.
• Ha a keresés eléri a 10 projektre vonatkozó korlátot, egy figyelmeztetés könyvtárargumentum megadását javasolja

Automatikus .NET projektfolyamat:

Ha .csproj fájl található a célkönyvtárban, init egyszerűsített .NET-specifikus folyamatot használ:

• Ellenőrzi és frissíti a TargetFramework egy Windows kompatibilis TFM-hez (például net10.0-windows10.0.26100.0)
• Microsoft.WindowsAppSDK és Microsoft.Windows.SDK.BuildTools hozzáadása mint NuGet PackageReference bejegyzések közvetlenül a .csproj.
• Létrehoz Package.appxmanifest, eszközöket és fejlesztési tanúsítványt
• Nem hoz létre winapp.yaml és nem tölt le C++-előrejelzéseket (NuGet-csomagokhoz használhatódotnet restore)

Ritka identitás mód (--exe + --sparse):

Létrehoz egy csak identitással rendelkező ritka csomagjegyzéket egy meglévő asztali végrehajtható fájlhoz – ez a ritka csomagolási munkafolyamat első lépése. A teljes init folyamattól eltérően ez kihagyja az összes SDK-/csomagtelepítést (a ritka identitáscsomagok nem rendelkeznek SDK-függőségekkel), és csak jegyzék- és helyőrző objektumokat hoz létre.

• A csomag nevét, közzétevőt, leírást és verziót az exe FileVersionInfo használatával (felülbírálás , --name--publishervagy interaktív módon)
• Írás ( appxmanifest.xml az exe nevének behelyettesítésével Executable) és egy Assets/ mappa sparse/ az aktuális könyvtárban (vagy --output-dir)
• Az --use-defaults/--no-prompt interaktív felülbírálási kérések kihagyása (CI-barát)
• --exehiba nélkül --sparse

Az eszközök külsőek. A ritka .msix identitás csak identitással működik: a generált Assets/ feloldás az alkalmazás telepítési könyvtárából (a külső tartalom helyére) történik futásidőben, nem pedig a .msixprogramba csomagolva. Helyezze üzembe őket az alkalmazás mellett.

Következő lépésekwinapp init --exe <exe> --sparse: az identitás .msixlétrehozásához, majd winapp embed-identity <exe>winapp pack <appxmanifest.xml> . A részletes útmutatóért tekintse meg a Ritka csomagolási útmutatót .

Példák:

# 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

Tipp: SDK-k telepítése a kezdeti telepítés után

Ha futtatott init--setup-sdks none (vagy kihagyott SDK-telepítést), és később szüksége van az SDK-kra:

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

Az előzetes/kísérleti SDK-verziók használata vagy --setup-sdks preview használata--setup-sdks experimental.

---

új

Hozzon létre egy új WinUI-alkalmazást egy hivatalos Windows App SDK dotnet new sablonból. Alapértelmezés szerint interaktív; automatikusan nem interaktív környezetekben használja az alapértelmezett értékeket.

winapp new [options]

Lehetőségek:

• -t, --template <short-name> - A sablon rövid neve (pl. winui, , winui-navview, winui-mvvm, winui-lib, , , winui-unittestvagy kísérleti Reaktor sablon, például reactor vagy reactor-mvu). Futtatáskor érvényesítve a telepített csomaggal; futtassa winapp new --list az összes megtekintéséhez. Alapértelmezett: winui (üres XAML-alkalmazás).
• -n, --name <name> - Az új alkalmazás/projekt neve (alapértelmezett: származtatva --output, más WinUIAppnéven )
• -o, --output <path> - Címtár az alkalmazás létrehozásához (alapértelmezett: ./<name>)
• --use-defaults, --no-prompt - Ne kérje, használja az alapértelmezett beállításokat (üres sablon, név a sablonból --output/--name, és a frissítés helyett tartsa meg a telepített sabloncsomagot)
• --force - Állványzat akkor is, ha a kimeneti könyvtár már tartalmaz fájlokat
• --template-version <latest|installed|version> - WinUI-sabloncsomag verziója: latest telepíti a legújabb közzétett csomagot, installed megtartja a már letöltött csomagot (nincs hálózat), vagy rögzít egy explicit verziót, például 1.2.3. Alapértelmezett: telepítse a legújabbat, ha nincs csomag, ellenkező esetben kérje meg, hogy frissítsen egy elavult csomagot (as-is alatt --use-defaultsmarad).
• --list - Listázni az elérhető WinUI-sablonokat, és kilépni (a legújabb csomagot telepíti először, ha nincs telepítve)
• --json - Kimenet formázása JSON-ként

Sablonok:

A csomag a WinUI-alkalmazás két stílusát kínálja. Az XAML-sablonok A felhasználói felületet egy C#-kód mögötti kóddal definiálják. A reaktorsablonok tiszta C# XAML nélkül, MVU (Model-View-Update) mintával. A sablonlista élőben olvasható a telepített csomagból, így mindig a meglévő verziót tükrözi – futtassa winapp new --list az aktuális készlet megtekintéséhez. Gyakori sablonok:

Rövid név	Leírás
winui	Minimális üres XAML-alkalmazás (MSIX-csomagolás)
winui-navview	XAML NavigationView kezdőalkalmazás
winui-tabview	XAML TabView kezdőalkalmazás
winui-mvvm	XAML MVVM-alkalmazás (CommunityToolkit.Mvvm)
winui-lib	WinUI 3 osztálykódtár
winui-unittest	Csomagolt MSTest-alkalmazás; a tesztek az indításkor futnak
reactor	Kísérleti. Blank Reactor alkalmazás – tiszta C#, nincs XAML
reactor-mvu	Kísérleti. Az MVU-mintát bemutató reaktoralkalmazás
reactor-navview	Kísérleti. Reactor NavigationView kezdőalkalmazás
reactor-tabview	Kísérleti. Reactor TabView kezdőalkalmazás

A reaktorsablonok kísérleti jellegűek. Az előzetes csomagokra Microsoft.UI.Reactor hivatkoznak, amelyek API-jai egy későbbi kiadásban módosíthatók vagy eltávolíthatók. winapp new megjelöli őket (kísérleti)--list az interaktív jelölőben és az abban, be van halmazva "Experimental": true--json, és az állványozás után figyelmeztetést nyomtat ki. Ezek soha nem lesznek alapértelmezett sablonként kiválasztva. A reaktorhoz szükség van a .NET 10 SDK-ra vagy újabbra is; egy régebbi SDK-n winapp new a nem építhető projekt felépítése helyett a szükséges verzióval kell előre leállnia.

Minden sablon vesszővel rendelkező rövid neve az első aliaslista dotnet new ; a felsorolt aliasok (pl. winui3, wasdk-single, winui-reactor) is elfogadottak. Meglévő WinUI-projektben való futtatáskor elemsablonokat (például üres oldalt) is felfedhet, dotnet new amelyek winapp new új projekt létrehozása helyett hozzáadják az aktuális projekthez.

Sabloncsomag verziószámozása:

winapp new már nem rögzít egy adott sabloncsomag-verziót. Ha nincs telepítve csomag, a legújabb telepít. Ha egy régebbi csomag már telepítve van, ellenőrzi a hírcsatornát, és ha egy újabb létezik, megkérdezi , hogy frissít-e – kivéve a nem interaktív/--use-defaults futtatásokat, amelyek megtartják a telepített csomagot. Segítségével --template-version latest mindig a legújabbat használhatja kérés nélkül, vagy --template-version installed mindig használhatja a letöltött csomagot hálózati ellenőrzés nélkül. Az explicit verzió (pl. --template-version 1.2.3) átadása mindig pontosan ezt a verziót telepíti – újratelepíti még akkor is, ha egy újabb csomag már létezik – így az állványzatok reprodukálhatóak a gépek között.

Az első futtatás hosszabb időt vehet igénybe: A sabloncsomag telepítése vagy frissítése, illetve a kiválasztott sablon által használt hiányzó Windows App SDK NuGet-csomagok visszaállítása további letöltéseket igényelhet. Ez az új Windows App SDK verzió közzététele után is megtörténhet. Ha az állványzat 10 másodperc után is fut, frissítse az állapotüzenetét, winapp new hogy jelezze, hogy a csomagok letöltése vagy visszaállítása lehetséges.

A következő teendők:

• Ellenőrzi, hogy a .NET SDK telepítve van-e (ha hiányzik, útmutatással gyorsan meghiúsul – winapp nem telepíti az eszközláncokat)
• Igény szerint telepíti vagy frissíti a hivatalos WinUI-sabloncsomagot (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates)
• A telepített csomagból származó elérhető sablonok számbavétele és a delegáltak állványzatának dotnet new <short-name>

A WinUI-alkalmazássablonok már tartalmazzák Windows csomagolást és identitást (Package.appxmanifest), ezért nincs szükség külön winapp init lépésre. Alkalmazássablonok esetén az alkalmazás létrehozásához és elindításához használhatja winapp run . A winui-lib sablon létrehoz egy osztálytárat egy alkalmazásprojektből való hivatkozáshoz (nincs alkalmazásjegyzéke). A winui-unittest sablon egy csomagolt MSTest-alkalmazás, amelynek tesztjei az alkalmazás indításakor (winapp run) futnak , nem pedig az alkalmazáson keresztül dotnet test. winapp newállványok a telepített .NET SDK cél-keretrendszeréhez, és kinyomtatja a megfelelő következő lépést a választott sablonhoz.

Adja át a globális --verbose (-v) jelzőt, hogy minden mögöttes dotnet hívás (csomag lekérdezése, frissítés ellenőrzése, telepítése, dotnet new listállványzat) és annak teljes kimenete visszhangja legyen – ez hasznos a sabloncsomaggal vagy az állványzattal kapcsolatos problémák diagnosztizálásához.

Példák:

# 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

---

visszaállít

Csomagok visszaállítása és fájlok újragenerálása a meglévő winapp.yaml konfiguráció alapján.

winapp restore [base-directory] [options]

Argumentumok:

• base-directory - Visszaállítandó könyvtár (alapértelmezett: aktuális könyvtár). Azt is kiválasztja, hogy hol winapp.yaml és nuget.config honnan olvassa a rendszer, kivéve, ha --config-dir felülbírálja azt.

Lehetőségek:

• --config-dir <path> - Winapp.yaml fájlt tartalmazó könyvtár (alapértelmezett: base-directory)

A következő teendők:

• Beolvassa a meglévő winapp.yaml konfigurációt
• SDK-csomagok letöltése/frissítése a megadott verziókra
• C++/WinRT-fejlécek és bináris fájlok újragenerálása
• Megosztható fájlok tárolója a globális gyorsítótár könyvtárában

Megjegyzés:

A .NET projektek esetében nincs winapp.yaml – az SDK-verziók bejegyzésként .csprojPackageReference vannak megadva – így winapp restore ön is futtathatódotnet restore.

Példák:

# Restore from winapp.yaml in current directory
winapp restore

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

Egyéni és privát NuGet-hírcsatornák:

winapp init, restoremajd update töltse le a Windows SDK- és Windows App SDK-csomagokat a NuGeten keresztül, tiszteletben tartva a standard nuget.config hierarchiát. A privát hírcsatornák és -tükrözések, a hírcsatornák hitelesítő adatai (beleértve a hitelesítő adatokat is) és az egyéni globalPackagesFolder adatok ugyanúgy működnek, mint a dotnet restore. Ha kizárólag a saját tükörből szeretné visszaállítani az örökölt forrásokat, <clear /> és csak a sajátját adja hozzá:

<?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>

Megjegyzés:

Natív projektek esetén a Winapp a következő könyvtárból oldja fel nuget.config a következő könyvtárat: arestoreinit/könyvtár argumentumát, --config-dir ha van megadva, ellenkező esetben az aktuális könyvtárat. A .NET projektek esetében a források a projekt saját nuget.config hierarchiájából származnak, mert ezt dotnet add package használják és dotnet restore használják, ezért helyezze el a privát hírcsatorna konfigurációját a projektkönyvtárban vagy egy elődben. A --config-dir rendszer nem a projekt által visszaállítható verziók csendes kiválasztását, hanem a hierarchián kívüli hierarchiát jelenti és hagyja figyelmen kívül. Ezeket a parancsokat csak a megbízható címtárakon futtassa, ugyanazzal az óvatossággal, mint ami a parancsokra dotnet restorevonatkozik. Ha több forrás van konfigurálva, a Csomagforrás-megfeleltetés használatával rögzítheti az egyes csomagokat egy hírcsatornában.

---

frissít

Frissítse a csomagokat a legújabb verziókra, és frissítse a konfigurációs fájlt.

winapp update [options]

Lehetőségek:

• --setup-sdks <stable|preview|experimental|none> - SDK telepítési mód: stable (alapértelmezett), preview, experimentalvagy none (kihagyja az SDK-telepítést)

A következő teendők:

• Beolvassa a meglévő winapp.yaml konfigurációt az aktuális könyvtárban
• Az összes csomag frissítése a legújabb elérhető verziókra
• winapp.yaml A fájl frissítése új verziószámokkal
• C++/WinRT-fejlécek és bináris fájlok újragenerálása

Példák:

# Update packages to latest versions
winapp update

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

---

pack

MSIX-csomagok létrehozása projektből vagy előkészített alkalmazáskönyvtárakból. A célkönyvtárban, az aktuális könyvtárban vagy a beállítással Package.appxmanifest együtt átadott jegyzékfájlnak (appxmanifest.xmlelőnyben részesített, --manifest szintén támogatott) szerepelnie kell. (jegyzék futtatása init vagy manifest generate létrehozása)

Adjon át egyetlen .csproj lehetőséget a projekt létrehozásához, és csomagolja a kimenetét egy lépésben (projekt módban, lásd közvetlenül a projekt csomagolását alább). Több bemeneti mappa .msixbundle átadása többarchitektúra-elosztáshoz (lásd az alábbi többarchitektúra-csomagokat ).

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

Argumentumok:

• input-folder - Egyetlen .csproj buildelendő és csomagolható (projektmód), vagy egy vagy több olyan könyvtár, amely tartalmazza a csomagolni kívánt alkalmazásfájlokat. Adjon át több mappát (pl. ./publish/x64 ./publish/arm64) egy MSIX-csomag létrehozásához. Ritka identitáscsomagok esetén a ritka fájlokat appxmanifest.xml közvetlenül, mappa helyett adja át (lásd alább a Ritka identitáscsomagokat).

Lehetőségek:

• --output <filename> - Kimeneti fájl neve. Egyetlen csomag esetén: <name>_<version>_<arch>.msix (visszaesik a következőre <name>_<version>.msix: , <name>_<arch>.msixvagy <name>.msix). Csomagok esetén: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --name <name> - Csomag neve (alapértelmezett: jegyzékből)
• --manifest <path> - A jegyzékfájl elérési útja (Package.appxmanifest előnyben részesítve, appxmanifest.xml szintén támogatott; alapértelmezett: automatikus észlelés)
• --cert <path> - A tanúsítvány aláírásának elérési útja (automatikus aláírás engedélyezése)
• --cert-password <password> - Tanúsítvány jelszava (alapértelmezett: "jelszó")
• --generate-cert – Új fejlesztési tanúsítvány létrehozása
• --no-sign - A csomagot aláíratlanként kézbesítheti, felülírva a projektaláírási konfigurációt (pl. Store-beküldéshez vagy külső aláíró folyamathoz). Nem kombinálható a következővel --cert : vagy --generate-cert.
• --install-cert – Tanúsítvány telepítése a gépre
• --publisher <name>- Publisher tanúsítványgeneráláshoz. Teljes X.500 megkülönböztető nevet vagy csupasz nevet fogad el (automatikusan becsomagolva CN=<name>)
• --self-contained – Csomag Windows App SDK futtatókörnyezet
• --skip-pri – PRI-fájllétrehozás kihagyása
• --executable <path> - A végrehajtható fájl elérési útja a bemeneti mappához képest (is --exe). A jegyzékben szolgáló helyőrzők $targetnametoken$ feloldására használják.

Project mód beállításai (bemenet megkövetelése.csproj; mappa-/csomag-/jegyzékbemenet esetén elutasítva):

• --configuration <name> (-c) – Buildkonfiguráció (alapértelmezett: Release)
• --arch <arch> - Célarchitektúra: x64, arm64vagy x86 (alapértelmezett: az aktuális folyamatarchitektúra)
• --framework <tfm> (-f) – Célkeret-moniker több célzott projektekhez
• --no-build – A meglévő build kimenetének újraépítés nélküli csomagolása
• --no-restore – A projekt visszaállításának kihagyása a projekt létrehozása előtt
• --property <name=value> (-p) - MSBuild tulajdonság, továbbítva a buildeléshez és a kiértékeléshez (megismételhető)

Megjegyzés: WinUI/ EnableMsixTooling.csproj (MSIX-tooling project mode) esetén a Windows App SDK a jegyzék, a belépési pont és a PRI-generálás tulajdonosa, így --executable--manifest– és --skip-pri elutasítva – konfigurálja <AppxManifest>a projekt belépési pontját és az erőforrás-buildjét magában a projektben. Ez a három lehetőség továbbra is érvényes a mappabemenetekre és az általános (nem MSIX-eszközhasználatú) .csproj projektmódra.

A következő teendők:

• Package.appxmanifest-fájlok ellenőrzése és folyamata
• Feloldja $placeholder$ a jegyzékben lévő jogkivonatokat (lásd alább a Jegyzékhelyőrzőket )
• Biztosítja a megfelelő keretrendszerfüggőségeket
• Egymás melletti jegyzékek frissítése regisztrációkkal
• Automatikusan felderíti és csomagolja a jegyzékfájlban hivatkozott nem képfájlokat (pl. AppExtension manifest.json, konfigurációs fájlok) a jegyzékkönyvtárból vagy a bemeneti mappából, ha hiányoznak az előkészítésből
• Automatikusan felderíti a külső WinRT-összetevőket, és regisztrálja az aktiválható osztályokat (lásd alább a WinRT-összetevők felderítését )
• Önálló WinAppSDK-telepítés kezelése
• Csomag aláírása tanúsítvány megadása esetén

Projekt közvetlen csomagolása

Ha a bemenet egyetlen .csproj, winapp pack létrehozza a projektet (a fenti lehetőségeket használva), és csomagolja az eredményül kapott kimenetet – nincs szükség külön buildelésre vagy a kimeneti mappa megkeresésére. Ez tükrözi a winapp runprojekt üzemmódját.

# 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

A célarchitektúra származik --arch, vagy egy magányos -p RuntimeIdentifier=<rid> , ha nem adja át --arch (a pontos RID megmarad, és hajtja a build). Mindkettő átadása --arch-p RuntimeIdentifier , és ütközés, és elutasítva.

A projektnek csomagolt alkalmazásként kell buildelnie (EnableMsixTooling=true egy Package.appxmanifest); a csomagolatlan alkalmazásként (WindowsPackageType=None) buildelt projektnek nincs MSIX-jegyzéke a csomagoláshoz, és winapp pack végrehajtható hibát jelez. A mappa-, csomag- és ritka jegyzékbemenetek nem változnak.

Project mód egyetlen .msix vagy csak .msixbundle architektúrát hoz létre (lásd a többarchitektúra-csomagokat). Nem hoz létre Áruház-feltöltési archívumokat vagy erőforrás-felosztási (nyelvi/méretezési) csomagokat: explicit -p UapAppxPackageBuildMode=StoreUpload vagy -p AppxBundleAutoResourcePackageQualifiers=... elutasított egy megjegyzéssel a natív SDK-csomagolási parancs közvetlen futtatásához ezekhez a folyamatokhoz.

Ritka identitáscsomagok

Ha a bemenet nem appxmanifest.xml mappa, hanem ritkán használt fájl (egy deklarálás <uap10:AllowExternalContent>true</uap10:AllowExternalContent><Properties>alatt) lesz, winapp pack csak .msixidentitást hoz létre – csak a jegyzékfájlt csomagolja, alkalmazás bináris fájljai és eszközei nélkül. Ez a ritka csomagolási munkafolyamat 2. lépése.

# Build a signed identity package from a sparse manifest
winapp pack ./sparse/appxmanifest.xml --cert ./devcert.pfx

• A kimenet alapértelmezés szerint <PackageName>.identity.msix az aktuális könyvtárban van (felülbírálás a következővel --output: ).
• Az aláírás csak akkor történik, ha --cert (vagy --generate-cert) meg van adva.
• Ha ehelyett olyan mappát ad át, amelynek a jegyzékfájlja deklarálva AllowExternalContentvan, a meglévő mappacsomagolási viselkedés érvényes, de winapp pack figyelmezteti, ha objektumokat (/.ico.png/.jpg) vagy bináris fájlokat (.exe.dll//.so) talál – a ritka csomagok esetében ezek a külső helyen találhatók, nem a .msixtárolóban.

A csomagolás után futtassa winapp embed-identity <exe> és regisztrálja a csomagot a telepítőben a következővel Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>: . Tekintse meg a ritka csomagolási útmutatót.

WinRT-összetevő felderítése

Csomagoláskor winapp pack a rendszer automatikusan megvizsgálja a winapp.yaml*.csproj WinRT-összetevőkben definiált NuGet-csomagokat (pl. Win2D). Elemzi a .winmd fájlokat az aktiválható osztálynevek kinyeréséhez, és megkeresi a megvalósítási DLL-eket. A felderített bejegyzések a következőképpen vannak regisztrálva:

• Keretrendszerfüggő (alapértelmezett): Az aktiválható osztályok bejegyzésként <InProcessServer> lesznek hozzáadva a Package.appxmanifest
• Önálló (--self-contained): Az aktiválható osztályok egymás mellett (SxS) vannak beágyazva a végrehajtható fájlba

Helyőrző felbontás a csomagolás során:

Ha a jegyzék tartalmazza $targetnametoken$ az Executable attribútumot:

1. Ha --executable meg van adva (a bemeneti mappához viszonyított elérési út), a helyőrzőt a megadott értékre cseréli a rendszer
2. winapp pack Ellenkező esetben fájlokat keres a bemeneti mappa gyökerében .exe – ha pontosan egy található, a rendszer automatikusan használja
3. Ha nulla vagy több .exe fájl található, hibaüzenet jelenik meg, amely arra kéri, hogy adja meg --executable

Példák:

# 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

Többarchitektúra-csomagok

Ha több bemeneti mappát ad át, winapp pack architektúránként egyet .msixbundle.msix hoz létre:

# 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

A parancs automatikusan észleli az egyes mappák architektúráját az elsődleges végrehajtható fájl PE fejlécéből, ellenőrzi a szeletek konzisztenciáját (identitás, képességek, függőségek), és létrehoz egy <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Jegyzékfeloldás csomagokhoz:

A köteg minden egyes szeletének jegyzékre van szüksége. A parancs az alábbi sorrendben oldja fel a jegyzékfájlokat:

1. --manifest <path> – Ha meg van adva, a rendszer ezt az egyetlen jegyzékfájlt használja az összes szelethez. A ProcessorArchitecture rendszer automatikusan frissíti a szeletenkénti frissítést az észlelt architektúrának megfelelően.

2. Mappánkénti jegyzék – Ha minden bemeneti mappa tartalmaz egy Package.appxmanifest (vagy appxmanifest.xml) fájlt, a rendszer a mappa jegyzékfájlját használja a szelethez.

3. Aktuális címtár-tartalék – Ha egy mappa nem rendelkezik jegyzékfájllal, a parancs az aktuális munkakönyvtárban keres Package.appxmanifest , és azt használja (automatikusan lepecsételt architektúrával).

A jegyzék minden esetben automatikusan frissül: a helyőrzők feloldódnak, a függőségek be lesznek adva, és a ProcessorArchitecture rendszer kényszeríti az észlelt architektúrát. A megoldás után a szeletek közötti ellenőrzés biztosítja, hogy az identitás (név, verzió, Publisher), a képességek és a függőségek minden szeletben konzisztensek legyenek – csak ProcessorArchitecture eltérőek lehetnek. A szeletekben definiált csomagverzió az MSIX-csomagverzióhoz van osztva, kivéve, ha 0.0.0.0az , ebben az esetben automatikusan létrejön egy időbélyeg-alapú verzió.

# 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

---

hozzon-létre-hibakeresési-azonosság

Alkalmazásdentitás létrehozása a ritka csomagolással végzett hibakereséshez. Az exe az eredeti helyén marad – Windows társítja hozzá az identitást Add-AppxPackage -ExternalLocation keresztül.

Mikor használja ezt a vs winapp run: Akkor használja create-debug-identity , ha az exe külön van az alkalmazáskódtól (pl. Electron apps where electron.exe is in node_modules), vagy ha kifejezetten a ritkán használt csomag viselkedését teszteli. A legtöbb keretrendszer esetében, ahol az exe a build kimeneti mappájában található, használja winapp run inkább – regisztrál egy teljes laza elrendezési csomagot, és elindítja az alkalmazást. A teljes összehasonlításért tekintse meg a hibakeresési útmutatót .

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

Argumentumok:

• entrypoint - Az identitást igénylő végrehajtható (.exe) vagy szkript elérési útja

Lehetőségek:

• --manifest <path> - Az alkalmazásjegyzékfájl elérési útja vagy Package.appxmanifestappxmanifest.xml (alapértelmezett: automatikus észlelés Package.appxmanifest vagy appxmanifest.xml az aktuális könyvtárban)
• --no-install – Ne telepítse a csomagot a létrehozás után
• --keep-identity - Tartsa meg a jegyzék-identitást as-is, anélkül, hogy hozzáfűzne .debug a csomag nevére és az alkalmazásazonosítóra

A következő teendők:

• Módosítja a programfájl mellékelt manifestjét
• Ritka csomag regisztrálása identitáshoz
• Engedélyezi az identitást igénylő API-k hibakeresését

Példák:

# 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

---

beágyazási identitás

Csatlakoztassa az asztali alkalmazásokat a ritka identitáscsomaghoz az <msix> elem egymás melletti (fúziós) jegyzékbe való beágyazásával. Ez a ritka csomagolási munkafolyamat 3. lépése – azt jelzi Windows, hogy melyik identitáscsomaghoz tartozik a futó exe.

winapp embed-identity <target> [options]

Argumentumok:

• target - A frissíteni kívánt fájl. Bővítmény által automatikusan észlelt:
  • .exe (EXE mód) – beágyazza az <msix> elemet közvetlenül az exe egymás melletti jegyzékébe a használatával mt.exe.
  • .xml / .manifest (XML mód) – beszúrja vagy lecseréli az <msix> elemet egy külső SxS-jegyzékfájlba (amely akkor jön létre, ha nem létezik). Később újraépítheti az alkalmazást, hogy a frissített jegyzékfájl beágyazódjon a bináris fájlba.

Lehetőségek:

• --manifest <path> - Elérési út a ritka ritkához appxmanifest.xml az identitás (packageName, publisher, applicationId) olvasásához. Ha nincs megadva, a parancs először a cél mellett keres egy sparse/ mappát, majd az aktuális könyvtárban, majd a célkönyvtárban és az aktuális könyvtárban a következőt appxmanifest.xml: .

Példák:

# 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

Ez a parancs idempotens: az újrafuttatás a meglévő <msix> elemeket helyettesíti ahelyett, hogy duplikálja.

---

jegyzékfájl

Package.appxmanifest-fájlok létrehozása és kezelése.

manifest létrehozása

Package.appxmanifest létrehozása sablonokból.

winapp manifest generate [directory] [options]

Argumentumok:

• directory - Jegyzékfájl létrehozása a címtárban (alapértelmezett: aktuális könyvtár)

Lehetőségek:

• --package-name <name> - Csomagnév (alapértelmezett: mappanév)
• --publisher-name <name>- Publisher megkülönböztető név (alapértelmezett: CN=<current user>). Elfogad egy X.500 DN-t egyértékű, vesszővel elválasztott összetevőkkel (a többértékű + RDN-ek és fordított perjelek nem támogatottak); a csupasz nevek automatikusan CN=<névként> vannak becsomagolva.
• --version <version> - Verzió (alapértelmezett: "1.0.0.0")
• --description <text> - Leírás (alapértelmezett: "Saját alkalmazás")
• --entrypoint <path> - Belépési pont végrehajtható vagy szkript
• --template <type> - Sablon típusa: packaged (alapértelmezett) vagy sparse
• --logo-path <path> - Az embléma képfájl elérési útja
• --if-exists <Error|Overwrite|Skip> - Viselkedés, ha a jegyzékfájl már létezik a célútvonalon (alapértelmezett: Error)

Sablonok:

• packaged - Standard csomagolt alkalmazásjegyzék
• sparse - Alkalmazásmanifeszt ritka/külső helyen csomagolva

Jegyzékhelyőrzők

A létrehozott jegyzékek olyan $placeholder$ tokeneket használnak, amelyek dollárjellel elhatároltak, és a csomagoláskor automatikusan feloldódnak.

Placeholder	Megoldva	Example
$targetnametoken$	Végrehajtható név bővítmény nélkül	Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$	Windows.FullTrustApplication	Mindig automatikusan feloldva

Ez ugyanazt a konvenciót követi, amelyet Visual Studio projektsablonok használnak, így a jegyzékek hordozhatóak az eszközök között.

A helyőrzők megoldása:

• winapp pack — A csomagolás $targetnametoken$ során a megoldás a --executable beállítással vagy a bemeneti mappában lévő önálló .exe fájl automatikus észlelésével oldható fel. Ha több (vagy nulla) .exe fájl található, és --executable nincs megadva, hibaüzenet jelenik meg.
• winapp create-debug-identity — Amikor megad egy belépésipont-argumentumot, $targetnametoken$ az abból lesz feloldva. Belépési pont nélkül a végrehajtható helyőrzőt már fel kell oldani a jegyzékben.
• winapp manifest generate --executable— Ha --executable meg van adva, a rendszer kinyeri a jegyzék metaadatait (verzió, leírás) és ikonokat a végrehajtható fájlból, de a létrehozott jegyzékfájl továbbra is használ$targetnametoken$.exe; ezt a helyőrzőt később feloldja (példáulwinapp pack).winapp create-debug-identity

PS: A $targetnametoken$ megőrzése a beadott jegyzékben elkerüli a végrehajtható nevek kemény kódolását, és winapp pack és Visual Studio buildekkel is működik.

Példák:

# 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

jegyzék add-alias

Végrehajtási alias (uap5:AppExecutionAlias) hozzáadása a Package.appxmanifesthez. Ez lehetővé teszi a csomagolt alkalmazás parancssorból való elindítását az aliasnév beírásával.

winapp manifest add-alias [options]

Lehetőségek:

• --name <alias> - Alias neve (pl. myapp.exe). Alapértelmezett: a jegyzékben szereplő attribútumból Executable következtet.
• --manifest <path> - A Package.appxmanifest elérési útja (alapértelmezett: keresés az aktuális könyvtárban)
• --app-id <id> - Alkalmazásazonosító az alias hozzáadásához (alapértelmezett: első alkalmazáselem)

A következő teendők:

• Beolvassa a jegyzékfájlt, és az aliast kikövetkezése az Executable attribútumból (a helyőrzők, például $targetnametoken$.exea )
• Hozzáadja a uap5 névtér deklarációt, ha még nincs jelen
• Blokk hozzáadása <Extensions> a célalkalmazás-elemen <uap5:AppExecutionAlias> belül
• Ha az alias már létezik, jelenti és sikeresen kilép

Példák:

# 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

jegyzék-frissítési eszközök

Egyetlen forrásrendszerképből hozza létre az összes szükséges MSIX-rendszerkép-objektumot.

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

Argumentumok:

• image-path - A forrásképfájl elérési útja (PNG, JPG, SVG, ICO, GIF, BMP stb.)

Lehetőségek:

• --manifest <path> - A Package.appxmanifest fájl elérési útja (alapértelmezett: keresés az aktuális könyvtárban)
• --light-image <path> – Egy különálló forráskép elérési útja világos témavariánsokhoz

Description:

Egyetlen forrásrendszerképet hoz létre, és az MSIX-rendszerkép-objektumok átfogó készletét hozza létre a jegyzék eszközhivatkozásai alapján:

A jegyzékben hivatkozott összes eszköz esetében:

• 5 skálázási változat – alap (utótag nélkül), .scale-125, .scale-150, .scale-200.scale-400

Az alkalmazás ikonja (Square44x44Logo / AppList, 44×44 alap):

• 14 lemezes célváltozat –.targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14 nem iktatott célértékváltozat –.targetsize-{size}_altform-unplated

Additionally:

• app.ico – Többfelbontású ICO-fájl (16, 24, 32, 48, 256) a rendszerhéj-integrációhoz. Ha egy meglévő .ico fájl található az eszközkönyvtárban (például AppIcon.ico egy projektsablonból), a rendszer a helyben cseréli le ahelyett, hogy duplikátumot hoz létre

A következővel --light-image:

• Világos téma a változatok célba osztása – .targetsize-{size}_altform-lightunplated (alkalmazásikon)
• Világos témaskálázási változatok – .scale-{factor}_altform-colorful_theme-light (csempék, áruház emblémája)

SVG-támogatás: Az SVG-fájlok teljes mértékben támogatottak forrásképként. Ezek vektorokként jelennek meg közvetlenül minden célméretben, így minden felbontásban pixel-tökéletes eredményeket eredményeznek. A fájlnak saját méretét kell deklarálnia egy viewBox vagy abszolút width és height attribútumok alapján; a százalékos szélesség nem viewBox ír le konkrét méretet. A nem deklarált forrás nem lesz elutasítva SVG image has no usable dimensions üres eszközök létrehozása helyett.

A parancs a képarány fenntartása mellett arányosan skálázza a képeket, és szükség esetén transzparens háttérrel középre állítja őket. Az állományok a Assets könyvtárba vannak mentve a jegyzék helyéhez képest.

Példák:

# 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

---

futtat

Hozzon létre egy laza elrendezéscsomagot egy buildkimeneti mappából, regisztrálja azt Windows a Windows.Management.Deployment.PackageManager API használatával, és indítsa el az alkalmazást – a hibakereséshez szimulálva a teljes MSIX-telepítést. A hibakereső melléklet folyamatazonosítóját adja vissza.

winapp run a bemenetből automatikusan kiválasztott három mód egyikében működik:

• Mappa mód – a bemenet egy buildkimeneti mappa (egy Package.appxmanifest/AppxManifest.xml).
• Project mód – a bemenet egy.csproj, egy .sln/.slnx megoldást vagy egy könyvtárat tartalmazó. winapp run létrehozza és elindítja a projektet, amely támogatja a csomagolt és a csomagolatlan WinUI-alkalmazásokat is. Lásd alább Project módot.
• Egyfájlos mód – a bemenet egy .cs.NET fájlalapú alkalmazás. winapp run felépíti, az irányelveiből #:property létrehoz egy jegyzékfájlt, és csomagadentitással indítja el.

Tip

A mód kiválasztása alapértelmezés szerint csendes. Ha egy könyvtárat buildkimeneti mappaként kezeltek, amikor azt várta, hogy projektként készül, futtassa --verbose újra a következővel: mappamóddal jelzi, hogy miért lett kiválasztva (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). A címtárak csak projektként vannak létrehozva, ha egy .csproj/.slnx/.slnfuttatható alkalmazás a legfelső szintjén helyezkedik el, és nem keres rekurzívan.

A legtöbb keretrendszer (.NET, C++, Rust, Flutter, Tauri) esetében ez az előnyben részesített parancs a csomagidentitással való hibakereséshez. Ellentétben create-debug-identity a ritka csomag egyetlen exe regisztrálja, winapp run a teljes mappát laza elrendezési csomagként regisztrálja, ugyanúgy, mint egy valódi MSIX-telepítés. A gyakori hibakeresési munkafolyamatokhoz tekintse meg a hibakeresési útmutatót .

winapp run [<input>] [options]

Argumentumok:

• input- A futtatni kívánt alkalmazás: build-output mappa (mappa mód), .cs .NET fájlalapú alkalmazás (egyfájlos mód), egy .csproj projekt, megoldás .sln/.slnx vagy egy könyvtár, amely a legfelső szinten található egyiket tartalmazza (projekt mód; a könyvtárat nem rekurzív módon keresik). A projekt az aktuális könyvtárban való létrehozásához/futtatásához használható . . Nem kötelező – az aktuális könyvtár alapértelmezett értéke, ha nincs megadva (egyezés dotnet run).

Lehetőségek:

• --manifest <path> - A Package.appxmanifest elérési útja (alapértelmezett: automatikus észlelés a bemeneti mappából vagy az aktuális könyvtárból)
• --output-appx-directory <path> - A laza elrendezés kimeneti könyvtára (alapértelmezett: AppX a bemeneti mappában). Az alapértelmezett elrendezés eltávolítja a már nem a buildben lévő fájlokat; egy egyéni könyvtár további fájlokat tart meg. Ha tiszta elrendezésre van szüksége, használjon új egyéni könyvtárat.
• --args <string> - Az alkalmazásnak átadni kívánt parancssori argumentumok. Alternatív megoldásként használjon -- argumentumokat a menekülés elkerüléséhez (pl. winapp run . -- --flag value).
• --no-launch – Csak a hibakeresési identitás létrehozása és a csomag regisztrálása az alkalmazás elindítása nélkül
• --with-alias - Indítsa el az alkalmazást az AUMID-aktiválás helyett annak végrehajtási aliasával. Az alkalmazás az aktuális terminálon fut örökölt stdin/stdout/stderr használatával. Ritkán van szükség: egy olyan alkalmazás, amely OutputType=Exe már alapértelmezés szerint így indul el. A winapp hozzáadja a szükségest uap5:ExecutionAlias az AppX-elrendezésben található jegyzékszakaszokhoz, így nincs szükség a beadott jegyzék módosítására; egy aliast, amelyet az alkalmazás deklarál, as-is. Nem kombinálható a --no-launch, --detach, --without-aliasvagy --json.
• --without-alias - Kényszerítse az AUMID aktiválását egy olyan alkalmazáshoz, amely egyébként végrehajtási aliason keresztül indulna el. A konzolalkalmazás ezután konzol nélkül fut, és semmit sem nyomtat erre a terminálra. Nem kombinálható a következővel --with-alias: .
• --debug-output - Rögzítse az OutputDebugString üzeneteket és az első véletlen kivételeket az elindított alkalmazásból. A keretrendszer zaja (WinUI, COM, DirectX) szűrve van a konzol kimenetéből; a teljes naplófájl mindent rögzít. Ha az alkalmazás összeomlik, automatikusan rögzít egy minidumpot, és elemzi, hogy megjelenítse a kivétel típusát, az üzenetet és a verem nyomkövetését a forrásfájl:sorszámokkal (feloldva a build kimeneti mappájában lévő PDF-fájlokból). A felügyelt (.NET) összeomlásokat a rendszer azonnal elemzi külső eszközök nélkül. A natív (C++/WinRT) összeomlások a modulneveket és az eltolásokat jelenítik meg. Ha az összeomlott alkalmazás egy WinUI 3-alkalmazás (Microsoft.UI.Xaml.dll betöltve), a rendszer automatikusan lefut egy extra levédett kivétel-osztályozási passz, amely a forrásként szolgáló HRESULT, annak ErrorContext lánca és a teljes natív XAML-küldési vermet fogja felszínre tenni; a szükséges hibakereső összetevők első használatkor töltődnek le (lásd a hibakeresést, amely felülbírálható a WINAPP_DBGTOOLS_DIR környezeti változón keresztül). Egyszerre csak egy hibakereső csatolható egy folyamathoz, így más hibakeresők (Visual Studio, VS Code) nem használhatók egyszerre. Használja --no-launch inkább, ha másik hibakeresőt kell csatolnia. Nem kombinálható a következővel --no-launch: . Nem kombinálható a következővel --json: .
• --symbols – PDF-szimbólumok letöltése Microsoft Szimbólumkiszolgálóról a natív összeomlások részletesebb elemzéséhez feloldott függvénynevekkel. Csak a --debug-output. Ha nincs megadva, és natív összeomlás történik, a kimenet a jelző hozzáadását javasolja. Ez a jelző emellett javítja a WinUI által a 3. WinUI-alkalmazásokhoz tartozó leküldett kivétel-osztályozási vermet is. Először futtatja a letöltési szimbólumokat, és helyileg gyorsítótárazza őket; a későbbi futtatások a gyorsítótárat használják.
• --unregister-on-exit – Az alkalmazás kilépése után törölje a fejlesztési csomag regisztrációjának megszüntetését. Csak a fejlesztési módban regisztrált csomagokat távolítja el. Nem kombinálható a következővel --no-launch: .
• --detach - Indítsa el az alkalmazást, és azonnal térjen vissza anélkül, hogy várnia kell a kilépésre. Olyan CI-/automatizálási alkalmazásokhoz használható, ahol az alkalmazással az indítás után kell kommunikálnia. A helyi futtatások kinyomtatják a PID-t; a célfuttatások kinyomtatják a hatókörbe tartozó felhasználói felületi célt. A JSON tartalmazza a PID-t és a cél hatókört. Nem kombinálható a --no-launch, --debug-output, --with-aliasvagy --unregister-on-exit.
• --clean – Az újratelepítés előtt távolítsa el a meglévő csomag alkalmazásadatait (LocalState, beállítások stb.). Alapértelmezés szerint az alkalmazásadatok megmaradnak az újratelepítések során.
• --json - A kimenetet JSON-ként formázza programozott felhasználás céljából (pl. CI/automation). Hasznos a --detach PID rögzítéséhez. Nem kombinálható a következővel --with-alias : vagy --debug-output.
• --on <target> - Építsen a gazdagépre, majd regisztrálja és futtassa a célhelyen. Jelenleg a helyi végrehajtásra való visszalépés nélkül támogatja sandboxa elemet. A felhasználói felület következő parancsai előtt használható --detach . A tesztkörnyezethez --debug-output csomagolt alkalmazás szükséges. Tekintse meg Windows tesztkörnyezeti végrehajtást a beállításhoz, a futtatókörnyezet támogatásához és a leválasztott alkalmazás élettartamához.

Alkalmazásadatok megőrzése:

Alapértelmezés szerint winapp run megőrzi az alkalmazás adatait (LocalState, RoamingStatestb Settings.) az újbóli üzembe helyezéskor. Ha az alkalmazás adatokat ír a csomagkörnyezetbe ApplicationData.Current.LocalFolder vagy Environment.GetFolderPath(SpecialFolder.LocalApplicationData) azon belül, az adatok a meghívások során winapp run is megmaradnak.

Akkor érdemes használni --clean , ha új kezdésre van szüksége (például a sérült állapot visszaállításához vagy az első futtatási viselkedés teszteléséhez).

A következő teendők:

• Megkeresi vagy létrehozza a Package.appxmanifestet
• Hibakeresési identitás létrehozása és regisztrálása laza elrendezési csomag használatával
• Kiszámítja az alkalmazásfelhasználói modell azonosítóját (AUMID)
• Elindítja az alkalmazást a regisztrált identitással (hacsak nincs --no-launch megadva)
• A hibakereső melléklet folyamatazonosítójának (PID) nyomtatása

Példák:

# 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

Project mód (SDK-projektek .NET)

Ha a bemenet egy .csproj, egy/.slnx.slnmegoldás vagy egy (beleértve.) winapp run könyvtárat tartalmaz, azzal létrehozza a projektetdotnet build, majd elindítja azt. Támogatja a csomagolt és a csomagolatlan WinUI-alkalmazásokat is, és telepíti az alkalmazáshoz szükséges egyező architektúrát Windows-alkalmazás futtatókörnyezetet az indítás előtt.

Megoldás bemenete: mutasson winapp run egy .sln.slnx/(vagy egy olyan könyvtárra, amely tartalmazza az egyiket – a megoldást előnyben részesítik a laza .csproj fájloknál), és feloldja a futtatható alkalmazásprojektet, majd létrehozza és $(SolutionDir) meghatározza a testvértulajdonságokatSolution*, így a tőlük függő projektek úgy épülnek fel, mint a Visual Studio. Megoldási szabályok:

• A tesztprojektek automatikus kiválasztásakor a rendszer kihagyja a tesztprojekteket , így egy alkalmazást és annak tesztjeit tartalmazó megoldás szükség nélkül --project feloldja az alkalmazást. (A WinUI-tesztprojekt maga egy csomagolt alkalmazás, így a kimeneti típus önmagában nem tudja megkülönböztetni.)
• Ha az egyetlen futtatható projekt egy tesztprojekt, akkor az fut.
• Ha egynél több futtatható alkalmazásprojekt létezik, winapp run nem talál ki indítási projektet – a jelöltek felsorolásával kapcsolatos hibák. A --project <name> mindig megtisztelő lehetőségek közül választhat, beleértve egy tesztprojekt kiválasztását is.

A csomagolt és a csomagolatlan állapot automatikusan észlelhető a projekt tényleges WindowsPackageType MSBuild tulajdonságából (soha nem a jegyzékbeli jelenlétből):

• Csomagolva (WindowsPackageType=MSIXa WinUI-csomag alapértelmezett eleme) – buildek, majd a build kimenetét laza elrendezésű csomagként regisztrálja, és az AUMID-en keresztül indul el (ugyanaz a folyamat, mint a mappa mód).
• Csomagolatlan (WindowsPackageType=None) – buildeli, biztosítja a keretrendszertől függő Windows-alkalmazás futtatókörnyezet telepítését, majd közvetlenül elindítja a beépített .exe modult. Kényszerítse ezt egy csomagolt projekthez a következővel -p WindowsPackageType=None: .

Project módhoz a .NET SDK 8.0.100 vagy újabb (MSBuild --getPropertyesetén) szükséges.

Natív AOT: adja hozzá ezt a tulajdonságcsoportot a project fájl eleméhez<Project>, majd adja hozzá a következőt--aot:

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

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

--aot támogatja az x64- és ARM64-projekteket. A projekt AOT-konfigurációjával fut dotnet publish , majd elindítja a kimenetet, és egyszeri felülbíráláshoz használja -p PublishAot=true . Nem végez külön futtatókörnyezeti minősítést, és nem kombinálható a következővel --no-build : vagy --manifest.

A csomagidentitást generált MSIX-elrendezés nélkül használó alkalmazások esetén vegye fel vagy appxmanifest.xml vegye fel Package.appxmanifest a projekt közzétételi kimenetét. A Winapp a közzétett fájlokat ezzel a jegyzékfájllal szakaszozza. Ha mindkét név jelen van, a winapp leáll ahelyett, hogy egyet választanál; távolítsa el az elavult jegyzékfájlt, és konfigurálja a projektet úgy, hogy csak a kívánt jegyzékfájlt tegye közzé.

Project mód beállításai (mappa módban figyelmen kívül hagyva, kivéve, ha feljegyzik):

• -c, --configuration <name> - Buildkonfiguráció. Alapértelmezett: Debug. (Egyfájlos módban is megtisztelő.)
• --arch <x64|arm64|x86> - Célarchitektúra. Alapértelmezett: az aktuális folyamatarchitektúra. Meghatározza a build RID-jét és Windows-alkalmazás Futtatókörnyezet architektúrát, és kiválaszt egy megfelelő platformfüggetlen közzétételi profilt, ha az érvényes build megköveteli. (Egyfájlos módban is megtisztelő.)
• -r, --runtime <rid>- Cél .NET futtatókörnyezet azonosítója (pl. win-x64). Project mód csak a RID architektúráját használja, mindig létrehozza a canonicaltwin-<arch>, és elutasítja a nem Windows AZONOSÍTÓkat (pl. linux-x64). Az architektúra felülbírálja --arch , és kiválaszthatja a szükséges közzétételi profilt. (Egyfájlos módban is megtisztelő, ahol felülbírálja #:property RuntimeIdentifier a fájl által deklaráltakat.)
• -f, --framework <tfm> - Célkeret-moniker több célzott projektekhez (pl. net10.0-windows10.0.26100.0). (Elutasítva egyfájlos módban – használja #:property TargetFramework=...a .)
• --project <name-or-path> - Ha a bemenet egy megoldás (.sln/.slnx) vagy egy több futtatható alkalmazásprojektet tartalmazó könyvtár, kiválasztja, hogy melyik projektet kell elindítania (a projekt neve vagy elérési útja alapján). (Elutasítva egyfájlos módban – .cs egy fájlalapú alkalmazás maga a projekt.)
• --no-build - Hagyja ki a meglévő buildkimenet kiépítését és futtatását (továbbra is kiértékeli a kimeneti tulajdonságokat). (Egyfájlos módban is megtisztelő.)
• --no-restore – A visszaállítás kihagyása a natív AOT-közzététel előtt. (Egyfájlos módban is megtisztelő.)
• --aot- Futtassa a projekt konfigurált .NET natív AOT-közzétételt. Hatékony PublishAot=true. Mappa- és egyfájlos módban elutasítva.
• -p, --property <Name=Value> - MSBuild tulajdonság, továbbítva mind a build, mind a tulajdonság kiértékelése. Ismételje meg a -p műveletet több tulajdonság esetén; használjon vagy használjon %3B%2C literális pontosvesszőt vagy vesszőt egy értékben. (Egyfájlos módban is megtisztelő, ahol ez az egyetlen mód a beállításra TargetFramework.)

Build kimenete > részletesség: egy átlagos projektfuttatás használja dotnet build, majd kiértékeli a beépített kimenetet. Állítsa vissza és hozza létre élőben a kimeneti streamet a hitelesített hírcsatorna URL-címeinek hitelesítő adataival. Ezzel --aota winappot használja dotnet publish; --verbose megjeleníti a közzétételi parancsot és a feloldott elérési utakat. Az alábbi részletességi beállítások segítségével szabályozhatja, hogy mi jelenjen meg:

Flag	dotnet verbosity	Hozzáadások
(alapértelmezett)	minimal	—
--verbose	minimal	winapp builddöntési nyomkövetései
--quiet	quiet	—

A natív AOT a beérkezéskor közzéteszi a kimeneti streameket, beleértve az MSBuild végleges JSON tulajdonságát is. Az alatt --jsona visszaállítási/buildhívások és a gyermekkimenet az stderrre kerül, így az stdout tiszta JSON marad. Alatta --quieta rendszer letiltja a hívásokat, és a dotnet csendes visszaállítási/buildkimenete a stderrhez lesz irányítva, így az stdout tiszta marad. A natív AOT-közzétételi kimenet a stderrre is megy mindkét lehetőségnél.

A beállítás alkalmazhatósága: az identitás-/laza elrendezési beállítások (--manifest, , --output-appx-directory, --no-launch, --with-alias--unregister-on-exit, --clean) --executablecsak a csomagolt alkalmazásokra vonatkoznak. A csomagolatlan alkalmazások (amelyek nem rendelkeznek MSIX-csomaggal) esetében egyértelmű hibával kerülnek elutasításra. Az indítási/hibakeresési lehetőségek (--args/--, --detach, --debug-output, --symbols) --jsonmindkettőben működnek.

Project módú példák:

# 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

Egyfájlos mód (.NET fájlalapú alkalmazások)

.NET 10 lehetővé teszi egyetlen fájl futtatását .cs projektfájl nélkül, felül pedig irányelvek szerint #: konfigurálva. Mutasson winapp run erre a fájlra, és létrehozza az alkalmazást, létrehoz egy appxmanifestet, és csomagidentitással indítja el – így működik Windows.ApplicationModel.Package.Current , az alkalmazás valódi AUMID-t és Start-menübejegyzést kap, és az identitást (alkalmazásértesítéseket, ApplicationDataeszközalapú AI-t) igénylő API-k működnek.

A rendszerhéj-integrációknak, például a protokollkezelőknek, a fájltársításoknak, a megosztási céloknak és az indítási feladatoknak deklarált <Extensions> bejegyzésre van szükségük, amelyet a létrehozott jegyzék nem tartalmaz. Ha hozzá szeretne adni egyet, saját jegyzékfájlt kell létrehoznia – lásd alább a Saját jegyzék létrehozása című témakört.

winapp run counter.cs

Vagy futtassa egyszerűként dotnet run – lásd a Futtatás az alábbival című témakört dotnet run .

Nem hoz létre jegyzékfájlt. Írja le inkább a csomagot irányelvekkel #: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");

Jegyzéktulajdonságok. Az összes nem kötelező; mindegyik visszaesik egy ésszerű alapértelmezett értékre:

Ingatlan	Beállítások	Alapértelmezett
WinAppPackageName	Identity/@Name (a csomag identitása)	a fájl neve, megtisztítva [-.A-Za-z0-9]a fájl elérési útjának rövid kivonatával (counter.cs → counter-a1b2c3d4)
WinAppDisplayName	A Start és a Beállítások területen megjelenő név	a fájlnév kiterjesztése nélkül
WinAppPublisher	Identity/@Publisher	CN=<your Windows user name>. A csupasz név a következőképpen van becsomagolva CN=<name>: .
WinAppVersion	Identity/@Version	$(Version), normalizált (lásd alább)
WinAppDescription	A telepítés során és a Beállításokban megjelenő leírás	a megjelenítendő név
WinAppCapabilities	A deklarálható, a ;,	none

Version. A csomagverziónak pontosan négy számnak kell lennie, mindegyik 0–65535 számnak. WinAppVersion (vagy ha nem állítja be, a standard Version tulajdonság) normalizálva van a következőhöz: bármely -preview/-rc a rendszer elveti az utótagot, és a hiányzó összetevők nullákkal vannak kitöltve, így #:property Version=1.2.3-preview.4 a szerelvény és a csomag verziója össze lesz 1.2.3.0 adva. A 65535-nél nagyobb vagy négynél több összetevőhöz nem illeszthető értékeket a rendszer nem csendes módosítással, hanem hibával utasítja el .

Capabilities

Az alkalmazás teljes megbízhatóságot futtat identitással, amely megfelel azoknak az API-knak, amelyek csak csomagolt alkalmazást igényelnek. Egyes API-k azonban egy deklarált képességen vannak, függetlenül attól, hogy a Windows AI API-k a gyakoriak. (A Rendszerhéj-integrációk, például a protokollkezelők és a fájltársítások harmadik esetnek számítanak: ezek szerzői bejegyzéseket igényelnek <Extensions> , nem pedig képességeket, ezért használja a saját jegyzéküket .)

#:property WinAppCapabilities=systemAIModels

Ez az összes Phi Silica és a többi eszközmodell API-nak szüksége van a jegyzékből. Több deklarálása a következő elválasztással:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

A winapp mindegyiket beírja a ténylegesen igényelt elembe és XML-névtérbe, deklarálja ezt a névteret, és akkor emeli ki MaxVersionTested , ha a képességnek újabbra van szüksége. Ez többet számít, mint hangzik: a képességek több különböző elem között oszlanak el, és a fenti lista három különböző alakzattá válik –

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

A winapp által ismert nevek az Ön számára vannak megírva. Bármi más esetében – a korlátozott készlet idővel növekszik – minősítse magát a névtér előtagjával:

Előtag	Bocsát ki
rescap:	<rescap:Capability> — korlátozott képességek
uap:, uap6:, uap7:uap11:	<uap*:Capability>
systemai:	<systemai:Capability>
device:	<DeviceCapability>
app:	<Capability> az alapértelmezett névtérben

#:property WinAppCapabilities=rescap:broadFileSystemAccess

A nem felismert csupasz nevet a rendszer az előtagok elnevezésével kapcsolatos hibával utasítja el, és nem találgatja, hogy a nem megfelelő névtérben kibocsátott képesség jegyzékfájlt hoz létre, Windows vagy megtagadja a regisztrációt, vagy elfogadja, miközben csendben nem adja meg.

Saját jegyzék létrehozása

Ha olyan dologra van szüksége, amelyet a tulajdonságok nem fednek le – egy protokollkezelőt, egy fájltársítást, egy végrehajtási aliast –, akkor egy jegyzékfájlt kell létrehoznia, és winapp run szó szerint fogja használni ahelyett, hogy létrehoz egyet. A következő sorrendben vehető fel:

1. --manifest <path> parancsot a parancssorban.
2. #:property WinAppManifestPath=<path> fájlban .cs .
3. A fájl mellett .cs található jegyzékfájl neve <filename>.appxmanifest (például counter.appxmanifest mellette counter.cs).

Csak a fájlonkénti név lesz automatikusan felvéve. Egy Package.appxmanifest vagy appxmanifest.xml ugyanabban a mappában szándékosan figyelmen kívül hagyják – több .cs fájl is megoszthat egy mappát, és a megosztott név bevezetése csendben futtatná az egyik alkalmazást a másik identitása alatt. Ha több fájlhoz szeretne egy jegyzékfájlt használni, nevezze el kifejezetten a következővel --manifest : vagy WinAppManifestPath.

Ellenkező esetben a rendszer létrehoz egy Package.appxmanifest buildkimenetet az alapértelmezett rendszerkép-eszközökkel együtt, és minden futtatáskor frissül.

Options. Minden mappamód-beállítás működik: --no-launch, --with-alias, , --without-alias, --detach, --debug-output--clean, --symbols, --unregister-on-exit, ,----args/ , --json, --executable, --manifest, , --output-appx-directoryplusz -c/--configuration, --no-build, --no-restoreés .-p/--property

Tip

A konzolalkalmazás alapértelmezés szerint a terminálra nyomtat. Az AUMID-n keresztül indított csomagolt alkalmazásoknak nincs konzoljuk, így a csak konzolos alkalmazások megfelelően futnak, és semmit sem nyomtatnak ki. a winapp elkerüli ezt: egy alkalmazás OutputType=Exe egy végrehajtási aliason keresztül indul el, amely örökli a terminál stdin/stdout/stderr azonosítóját. Továbbra is megkapja a csomag identitását, és nem kell kérnie:

winapp run counter.cs

Pass(át) --without-alias az AUMID aktiválás kényszerítéséhez – az alkalmazás ezután konzol nélkül fut, és itt semmit sem nyomtat ki. Az ablakos alkalmazások (WinExe) megjelenítik az ablakot, így megtartják az AUMID-aktiválást; ha --with-alias azt szeretné, hogy a terminálban is legyen. Ha nem minden parancssorban, hanem a fájlban szeretné kijavítani a választást, állítsa be ugyanazt a tulajdonságot, amelyet a .csproj rendszer használ:

#:property WinAppRunUseExecutionAlias=false

Az alias winapp deklarált neve a csomagcsalád neve után van elnevezve, egy winapp- előtaggal – így com.contoso.counter a rendszer winapp-com.contoso.counter_gspb8g6x97k2t.exeközzétesziCN=You. Ez a záró rész a közzétevő kivonata, Windows származik, így két alkalmazás, amelyek különböző közzétevők alatt osztanak meg egy nevet, továbbra is különböző aliasokat kapnak. Az előtag tisztán tartja a nevet a valós parancsok közül: egy alkalmazás python.cs aliast winapp-… kap, soha.python.exe Ha saját jegyzékfájlt hoz össze, az ott deklarált alias as-is és a winapp nem ad hozzá semmit.

Ez csak az aliasra vonatkozik. Maga a regisztráció a csomag nevére van kapcsolva, így egy másik közzétevőnél ugyanazt WinAppPackageName deklaráló második alkalmazás futtatása az első regisztrációt helyettesíti ahelyett, hogy a csomag mellett ülne. Adjon saját nevet az egyes alkalmazásoknak, ha mindkettőt egyszerre szeretné regisztrálni.

winapp run kinyomtatja a regisztrált aliast, így nem kell kiszámolnia a kivonatot, hogy megtalálja.

Az alias egy olyan parancs a PATH-on, amely addig tart, amíg a csomag regisztrálva marad. Ha egy másik csomag már rendelkezik a névvel, a winapp ezt mondja. Amikor az aliast arra következteti, hogy az AUMID-en keresztül indul el, ahelyett, hogy rossz alkalmazást indítanának el; amikor kifejezetten – vagy #:property WinAppRunUseExecutionAlias=true vele --with-alias együtt – kért egyet, az ahelyett, hogy csendben csinálnál valamit.

Két projektmód-beállítás nem alkalmazható, mert egy fájlalapú alkalmazás konfigurálja magát. A rendszer elutasítja őket egy üzenettel, amely az irányelv helyett az alábbi nevet használja:

Lehetőség	Használat helyett
-f/--framework	#:property TargetFramework=net10.0-windows10.0.22621.0
--project	semmi – a .cs fájl a projekt

--arch és -r/--runtime a projekt módban is működnek. Ha egyiket sem adja át, a winapp a gép architektúrájához készít buildeket – erre van szüksége egy önálló Windows App SDK alkalmazásnak, mivel nélküle az SDK buildel AnyCPU és meghiúsulWindowsAppSDKSelfContained requires a supported Windows architecture. A #:property RuntimeIdentifier=win-arm64 fájl egy része tiszteletben van tartva; explicit --arch/--runtime felülbírálja azt.

A csomagolt és a kicsomagolt munka is ugyanúgy működikWindowsPackageType, mint a projekt módban: az alapértelmezett rendszer egy laza elrendezést regisztrál, és identitással indítja el, miközben #:property WindowsPackageType=None létrehozza az alkalmazást, telepíti a megfelelő Windows-alkalmazás futtatókörnyezetet, és közvetlenül elindítja azt.exe. (A csomagolt alkalmazás a végrehajtási aliasán vagy az AUMID aktiválásán keresztül indul el – lásd a fenti konzoljegyzetet; ez a választási lehetőség eltér attól, hogy becsomagolt-e.) Az identitásbeállítások (--no-launch, , --without-alias--with-alias, --clean, --unregister-on-exit, --manifest) --output-appx-directorycsak a csomagolt alkalmazásokra vonatkoznak.

Futtatás a dotnet run

Egyáltalán nem kell gépelnie winapp . Hivatkozzon a Microsoft.Windows.SDK.BuildTools.WinApp fájlból származó csomagra, és az egyszerű dotnet run fájl ugyanazt a csomagolt indítást biztosítja:

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

A csomag MSBuild-példányai átirányítják a futtatásokat a winappra, amely csomagokat tartalmaz, regisztrál és elindítja az imént létrehozott alkalmazást dotnet run – ez nem újjáépített. A jegyzékkezelés nem változik: a winapp pontosan ugyanúgy oldja fel, winapp runmint a többi esetében, így #:property WinAppManifestPath=…<filename>.appxmanifest a két cím mellett .cs (lásd: Saját jegyzék létrehozása) a rendszer továbbra is figyelmen kívül hagyja a címtárszintűt Package.appxmanifest , ellenkező esetben pedig az irányelvekből #:property jön létre, és minden futtatáskor frissül.

Az átirányításhoz két feltételnek kell teljesülnie:

Directive	Miért
#:package Microsoft.Windows.SDK.BuildTools.WinApp@*	az átirányítási hajót ebben a csomagban végző célokat
#:property TargetFramework=net10.0-windows…	egy egyszerű net10.0 fájl egyedül marad, ezért csomagolatlan

A hozzáadás #:property WindowsPackageType=None önmagában is hagyja a fájlt: dotnet run ezután közvetlenül, identitás nélkül futtatja a .exe fájlt. Ha először telepíteni szeretné a megfelelő Windows-alkalmazás futtatókörnyezetet, használja winapp run a csomagolatlan elérési utat.

Állítsa be #:property EnableWinAppRunSupport=false úgy, hogy az átirányítás teljes egészében ki legyen tiltva, és a WinAppRun*konfigurációban leírt tulajdonságok alakítsák az indítást – például:

#:property WinAppRunUnregisterOnExit=true

Ha dotnet run az alkalmazást kicsomagolva futtatja, amikor az identitást várta, kérdezze meg az MSBuild miért. dotnet msbuild Nem – dotnet buildcsak dotnet build a fájlalapú alkalmazás által lefordított virtuális projektet szintetizálja:

dotnet build counter.cs -t:WinAppRunSupportInfo

Az egyfájlos módhoz a .NET SDK 10.0.300 vagy újabb verzió szükséges.

A regisztráció túllépi a futást. winapp run counter.cs A csomag az alkalmazás kilépése után marad regisztrálva, pontosan úgy, mint a mappa és a projekt mód – így LocalState megmarad, és ugyanazt a fájlt újra futtatja, és a regisztrációk helyett ugyanazt az identitást használja újra. winapp mondja, így az első alkalommal regisztrálja az alkalmazást, és winapp unregister veszi magát .cs :

# 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 nem igényel jegyzék elérési utat: ugyanúgy értékeli ki a fájl #:property értékeit run , és csak a fájl buildkimenetéből regisztrált csomagot távolít el. Egy másik mappából regisztrált azonos nevű alkalmazás csak akkor lesz elutasítva, ha ön át nem adja.--force Ha a futtatás olyan beállítást használt, amely az identitást vagy az elrendezést formázta, adja át ugyanazt a következőnek 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 felülbírálja a fájl saját irányelveit, és a Directory.Build.props.cs can key WinAppPackageName off $(Configuration) vagy $(RuntimeIdentifier) – így ezek mindegyike megváltoztathatja, hogy melyik csomag legyen regisztrálva.

Miután az SDK ideiglenes kimenete megtisztítva lett, már nem tudja ellenőrizni, hogy a regisztráció az adott fájlból származik-e, winapp unregister counter.cs és kihagyja azt – ezzel winapp unregister --prune törli azokat a regisztrációkat, amelyeknek a fájljai eltűntek, vagy --force ha mégis eltávolít egy adottat. Ha a futtatás használt --output-appx-directory, adja át ugyanazt a könyvtárat unregister , hogy felismerje az elrendezést.

Ugyanez vonatkozik az egyéni kimeneti útvonalra is: a tulajdonjog az SDK szokásos <root>\bin\<configuration> elrendezéséből van megerősítve, így a beépített -p OutputPath=<somewhere-else> futtatás nem felelhet meg a forrásfájlnak. unregister kihagyja, és nem találgat egy szélesebb könyvtárban – adja meg az elrendezést a következővel --output-appx-directory: vagy használja --force.

Egyfájlos példák:

# 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

Megjegyzés:

Az alapértelmezett identitás tartalmaz egy rövid kivonatot a fájl elérési útról – counter.cs hasonlóvá válik counter-a1b2c3d4 –, így a különböző mappákban lévő két counter.cs fájl különböző alkalmazások, és megtartják a saját beállításait és LocalState. A kivonat az elérési útból származik, így túléli a szerkesztéseket és az újrafuttatásokat, és csak akkor változik, ha áthelyezi a fájlt. Állítsa be #:property WinAppPackageName=<name> a stabil identitás kiválasztását; a normalizálása Identity/@Name a megengedett módon történik – a külső [-.A-Za-z0-9] karakterek elvetve, a 3 karakternél rövidebb nevek ki vannak jelölve 1, és az eredmény 50 karakterre van leképezve, így My App regisztrálja magát MyApp. A Start menü és a Beállítások bármelyik módon is megjelenítheti az Ön WinAppDisplayName (alapértelmezett: a fájl nevét), és nem az identitást. Az identitás mindig a felhasználói fiókra terjed ki, ezért soha nem ütközik egy másik felhasználóval ugyanazon a gépen.

MSBuild tulajdonságok (NuGet-csomag):

A Microsoft.Windows.SDK.BuildTools.WinApp NuGet-csomag használatakor a dotnet run automatikusan meghívja winapp run.

Minden megírt után dotnet run továbbítja az alkalmazásnak, pontosan úgy, ahogy a csomag nélkül lenne. Konfigurálja a indítót az alábbi MSBuild tulajdonsággal:

# 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

A következő MSBuild tulajdonságok állíthatók be a .csproj vezérlési viselkedéshez:

Ingatlan	Alapértelmezett	Leírás
EnableWinAppRunSupport	true	A futtatás támogatásának engedélyezése/letiltása
WinAppLaunchArgs	(üres)	Az alkalmazásnak az indításkor átadandó argumentumok
WinAppRunUseExecutionAlias	az alkalmazásból következtetve	Az AUMID aktiválás helyett végrehajtási aliason keresztül indítható el. A winapp a következőre következtet: egy konzolalkalmazás aliast használ, így a kimenete eléri a terminált, az ablakos alkalmazás pedig az AUMID azonosítót használja. Állítsa be true vagy false döntse el saját maga.
WinAppRunNoLaunch	false	Csak identitás regisztrálása indítás nélkül
WinAppRunDebugOutput	false	Üzenetek és első esélyű kivételek rögzítése OutputDebugString . Egyszerre csak egy hibakereső csatolható (megakadályozza a VS/VS Code használatát). Ehelyett WinAppRunNoLaunch használjon másik hibakeresőt.
WinAppRunDetach	false	Ahelyett, hogy az alkalmazás kilépésére vár, azonnal visszatérhet az indítás után. Kinyomtatja a PID-t.
WinAppRunUnregisterOnExit	false	A fejlesztési csomag regisztrációjának törlése az alkalmazás elhagyása után
WinAppRunClean	false	Az újratelepítés előtt távolítsa el a meglévő csomag alkalmazásadatait (LocalState, beállítások)
WinAppRunSymbols	false	Szimbólumok letöltése a Microsoft Szimbólumkiszolgálóról a natív összeomlási elemzések gazdagabb elemzéséhez. Csak a .WinAppRunDebugOutput
WinAppRunExecutable	(üres)	Végrehajtható elérési út a build-output mappához képest. Akkor használható, ha a jegyzékfájl tartalmaz $targetnametoken$ , és a kimeneti mappa több eggyel .exerendelkezik.
WinAppRunArgs	(üres)	A parancssorhoz winapp run fűzött nyers argumentumok a dedikált tulajdonság nélküli beállításokhoz (például --verbose). Minden fenti tulajdonság után hozzáfűzve.

Kölcsönösen kizáró beállítások. WinAppRunNoLaunch és WinAppRunDetach mindegyik más indítási viselkedést ír le, ezért ütköznek a többi indítási tulajdonsággal és egymással. Az ütköző pár beállítása a következővel --X and --Y cannot be used togethermeghiúsul:

Ingatlan	Nem kombinálható a következővel:
WinAppRunNoLaunch	\, \, \
WinAppRunDetach	\, \, \

WinAppRunUseExecutionAlias szándékosan nem szerepel ebben a listában, egyik irányban sem. false az AUMID aktiválását kéri, amely nem indítható el, és a leválasztása már használatban van; true egyszerűen nincs alkalmazva, ha valamelyik be van állítva, mert egy végrehajtási aliasnak nyomon követett, futó folyamatra van szüksége. Így a bejelentkező <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> projektek továbbra is tisztán dotnet run -p:WinAppRunDetach=truefutnak az AUMID-en keresztül, nem pedig sikertelenül.

WinAppRunUseExecutionAlias, WinAppRunDebugOutputés WinAppRunUnregisterOnExit kombinálható egymással. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutableés WinAppLaunchArgs nincsenek korlátozások. WinAppRunArgsnem ad hozzá saját korlátozást, de a rajta áthaladó kapcsolót a rendszer minden máshoz hasonlóan ellenőrzi, így WinAppRunArgs="--detach" továbbra is ütközik a .WinAppRunNoLaunch

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

---

Unregister

Oldaltöltésű fejlesztési csomag regisztrációja törlése. Csak a fejlesztési módban regisztrált csomagokat távolítja el (pl. via winapp run vagy create-debug-identity). A tárolóra vagy AZ MSIX-ra telepített csomagok soha nem lesznek eltávolítva.

winapp unregister [input] [options]

Argumentumok:

• input- Elérési út egy .NET fájlalapú alkalmazáshoz (egyetlen .cs), amelynek a csomagját nem kell regisztrálni. Identitásának feloldása ugyanúgy történik, mint a winapp run szerzői jegyzékből, ha az alkalmazás rendelkezik ilyen azonosítóval, ellenkező esetben az értékeiből #:property , így nincs szükség jegyzékútvonalra. Ne használjon --manifest vagy automatikusan észleljen jegyzékfájlt az aktuális könyvtárban. Nem kombinálható más néven a csomaggal --manifest, és egy másikra is feloldható.

Lehetőségek:

• --manifest <path> - A Package.appxmanifest elérési útja (alapértelmezett: automatikus észlelés az aktuális könyvtárból)
• --force – Ha csak a helyi regisztrációt szünteti meg, hagyja ki a telepítési hely könyvtárának ellenőrzését, és törölje a regisztrációt akkor is, ha a csomagot egy másik projektfáról regisztrálták. A rendszer elutasítja; --ona céltulajdon-ellenőrzést nem lehet megkerülni.
• --on <target> - Távolítsa el a megfelelő winapp-tulajdonú fejlesztési regisztrációt, nem erről a gépről sandbox. Jegyzékfájlt igényel, és nem támogatja --force. Lásd: Tesztkörnyezeti alkalmazások karbantartása.
• --prune - Távolítsa el az összes olyan fejlesztési módú regisztrációt, amelynek fájljai el lettek távolítva. Nem kombinálható bemenettel, --manifest, --property, --configuration, --archvagy --runtime--output-appx-directory.
• -p, --property <Name=Value> - A fájlalapú alkalmazások identitásának feloldásakor .cs használt MSBuild tulajdonság. Ismételhető. Adja át ugyanazokat az identitást befolyásoló tulajdonságokat, amelyeket a használt futtatás (például -p WinAppPackageName=...) használ, mivel egy parancssori tulajdonság felülírja a fájl saját #:property irányelveit. Csak bemenetre .cs vonatkozik.
• -c, --configuration <name> – Fájlalapú alkalmazás identitásának feloldásakor .cs használt buildkonfiguráció. Alapértelmezett: Debug. Adja át ugyanazt a konfigurációt, amelyet a futtatás használt: a Directory.Build.props mellette .cs lehet beállítani WinAppPackageName vagy WinAppManifestPath feltételesen.$(Configuration) Csak bemenetre .cs vonatkozik.
• --arch <x64|arm64|x86> – A fájlalapú alkalmazások identitásának .cs feloldásához használt célarchitektúra. Alapértelmezett: az aktuális folyamatarchitektúra. Adja át ugyanazt az architektúrát, amelyet a használt futtatás használ, mivel az identitás is le $(RuntimeIdentifier)van kapcsolva. Csak bemenetre .cs vonatkozik.
• -r, --runtime <rid>- A fájlalapú alkalmazás identitásának .cs feloldásához használt cél .NET futtatókörnyezet-azonosító (pl. win-x64) Csak az architektúráját használja, és felülbírálja --arch. Csak bemenetre .cs vonatkozik.
• --output-appx-directory <path> - Az AppX-elrendezés könyvtár, amelyből a csomag regisztrálva lett. Csak a futtatás használatakor --output-appx-directoryvolt szükség rá, mivel a futtatási lehetőséget futtató csomagrekordokon semmi sem hozta létre az elrendezést.
• --json - Kimenet formázása JSON-ként

A következő teendők:

• Meghatározza a csomag nevét – a .cs fájl feloldott identitásából vagy a jegyzékfájl olvasásával
• Mindkettőt és {name} csomagot keres {name}.debug (a hibakeresési változatot a következő hozza create-debug-identitylétre: )
• Ellenőrzi, hogy minden csomag fejlesztési módban lett-e regisztrálva (IsDevelopmentMode == true)
• Ellenőrzi, hogy a csomag az Ön által elnevezett alkalmazáshoz tartozik-e (kivéve) --force– a telepítési helynek egy ön által azonosított könyvtár alatt kell lennie: a .cs fájl saját buildkimenete, a jegyzék könyvtára, az aktuális könyvtár vagy egy explicit --output-appx-directory. A rendszer kihagyja azt a csomagot, amelynek telepítési helye nem oldható fel (a fájljai törölve lettek), mert az identitás önmagában nem bizonyítja a tulajdonjogot: két alkalmazás, amelyek mindkét beállítás ugyanazt #:property WinAppPackageName=counter az identitást regisztrálják a különböző mappákból. Azoknak a regisztrációknak a törlésére használható --prune , amelyek fájljai eltűntek.
• Az egyező csomagok regisztrációja törlése

Halott regisztrációk törlése (--prune):

A regisztráció túllépi a fájljait. Ha töröl egy buildkimenetet, projektfát vagy (fájlalapú alkalmazás esetén) lehetővé teszi a Windows a tisztítást%LOCALAPPDATA%\Temp, és a csomag regisztrálva marad: Windows megőrzi az identitást és a Start menübejegyzést, de az aktiválás nem tesz semmit. Ezek láthatatlanul halmozódnak fel.

# 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

A rendszer csak a fejlesztési módú regisztrációkat veszi figyelembe, és azokat a teljes csomagnév eltávolítja, így az élő helyről telepített azonos nevű csomag érintetlen marad. A kérés azért létezik, mert a hiányzó telepítési hely általában törölt mappa, de egy leválasztott hálózati megosztásról vagy cserélhető meghajtóról regisztrált csomagot is ír le – a megerősítés előtt tekintse át a listát.

Példák:

# 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

Fejlesztési tanúsítványok létrehozása, vizsgálata és telepítése.

tanúsítvány létrehozása

Fejlesztési tanúsítványok létrehozása a csomagaláíráshoz.

winapp cert generate [options]

Lehetőségek:

• --manifest <Package.appxmanifest>- A tanúsítvány publisher kinyerése Identity/@Publishera jegyzékfájlból. Csak a közzétevőre van szükség, így a részlegesen teljes jegyzék továbbra is működik. Ha a jegyzékfájl nem rendelkezik használható közzétevővel, a parancs az alapértelmezett helyett meghiúsul, így a tanúsítvány soha nem tudja csendben elnémulni a jegyzékfájlt.
• --publisher <name>- Publisher a tanúsítványhoz. Tanúsítvány létrehozásakor ez a beállítás elsőbbséget --manifestélvez; a jegyzék-közzétevő használata helyett egy explicit módon üres érték meghiúsul. Elfogad egy teljes X.500 megkülönböztető nevet (például ) vagy egy csupasz nevet, CN=Contoso, O=Contoso Ltd, C=USamely automatikusan be van csomagolva.CN=<name> Az összetevőknek egyértékűnek és vesszővel elválasztottnak kell lenniük; A többértékű RDN-ek (CN=Foo+OU=Bar) és fordított perjelek nem támogatottak, mert az MSIX-jegyzékkiadó nem tudja megjeleníteni őket. A rendszer elutasítja a hibásan formázott megkülönböztető nevet (például CN= vagy CN=A,,O=B) egy nem nulla értékű kilépéssel és a probléma elnevezésével kapcsolatos hibával ahelyett, hogy olyan tanúsítványt állít elő, amely soha nem felel meg a jegyzék közzétevőjének.
• --output <path> - Kimeneti tanúsítványfájl elérési útja (támogatja az abszolút és relatív elérési utakat)
• --password <password> - Tanúsítványjelszó (alapértelmezett: password, amely nyilvánosan ismert – lásd : JSON-kimenet és biztonság)
• --valid-days <valid-days> - A tanúsítvány érvényes napjainak száma (alapértelmezett: 365)
• --install – A tanúsítvány telepítése a helyi géptárolóba a létrehozás után
• --if-exists <Error|Overwrite|Skip> – Viselkedés beállítása, ha a tanúsítványfájl már létezik (alapértelmezett: Hiba)
• --export-cer - Fájl exportálása .cer (csak nyilvános kulcs) a .pfxfájl mellett. Hasznos a nyilvános tanúsítvány külön-külön történő terjesztéséhez a megbízhatósági telepítéshez.
• --json - A kimenet formázása JSON-ként programozott felhasználás céljából. A rendszer JSON ({"error": "..."}) néven is visszaadja a hibákat.

JSON-kimenet:

{
  "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 a megjelenítendő név és subjectName a teljes megkülönböztető név, amelynek a tanúsítványt kiállították. defaultPasswordIsPublic mindig jelen van. Ha igen true, akkor a .pfx jelszót bárki kitalálhatja, így a tanúsítványnak csak a saját gépein maradó buildeket kell aláírnia – ellenőrizze, mielőtt egy szkript bármi másnak átadja a tanúsítványt. warnings ugyanazt a közzétételt végzi, mint a szöveg, és kihagyja, ha nincs mit jelenteni. publicCertificatePath csak a .-val --export-cerjelenik meg.

tanúsítványadatok

Tanúsítványadatok megjelenítése PFX- vagy CER-fájlból. Hasznos, ha aláírás előtt ellenőrzi, hogy egy tanúsítvány megfelel-e a jegyzéknek.

winapp cert info <cert-path> [options]

Argumentumok:

• cert-path - A tanúsítványfájl elérési útja (PFX vagy CER)

Lehetőségek:

• --password <password> - A PFX-fájl jelszava, nyilvános tanúsítvány esetén figyelmen kívül hagyva (alapértelmezett: "jelszó")
• --json - Kimenet formázása JSON-ként

tanúsítvány telepítése

Telepítse a tanúsítványt a gépi tanúsítványtárolóba.

winapp cert install <cert-path> [options]

Argumentumok:

• cert-path – A telepíteni kívánt tanúsítványfájl elérési útja

Példák:

# 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

---

jel

MSIX-csomagokat és végrehajtható fájlokat írhat alá tanúsítványokkal.

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

Argumentumok:

• file-path - Az MSIX-csomag elérési útja, vagy végrehajtható az aláíráshoz
• cert-path - Az aláíró tanúsítvány elérési útja (.pfx)

Lehetőségek:

• --password <password> - Tanúsítvány jelszava (alapértelmezett: "jelszó")
• --timestamp <url> - RFC 3161 időbélyegző kiszolgáló URL-címe

Példák:

# 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

Fájl (exe, MSIX vagy MSIX-csomag) kódolása a Megbízható Azure-aláírás – egy felhőalapú aláírási identitás használatával, így soha nem található titkos kulcs (PFX) a helyi gépen.

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

Argumentumok:

• file-path - Az aláírandó fájl elérési útja (exe, msix vagy msixbundle)

Lehetőségek:

• --subscription, -s - Azure használni kívánt előfizetés-azonosítót. Ha nincs megadva, és több előfizetés is létezik, a rendszer kérni fogja
• --resource-group, -r – Erőforráscsoport az aláíró fiókok szűkítéséhez
• --account - Fióknév aláírása. A --resource-group
• --profile, -p - Tanúsítványprofil neve. A --account
• --metadata-file, -m - Meglévő elérési metadata.jsonútja. Kihagyja az erőforrás-felderítést, valamint a fiók/profil kiválasztására vonatkozó utasításokat és jeleket. Egy nem interaktív Azure hitelesítő adatnak már elérhetőnek kell lennie; a parancssori felület egyébként visszaeshet egy interaktív bérlői parancssorba, vagy az login, de az npm programozott API mindig nem interaktív, és ahelyett, hogy rákérdezne

Hitelesítés:

az-signAzure szabványos hitelesítőadat-láncát (DefaultAzureCredential). CI/CD esetén állítsa beAZURE_TENANT_IDAZURE_CLIENT_ID, és AZURE_CLIENT_SECRET (vagy használja GitHub Actions OIDC/felügyelt identitást). A meglévő Azure CLI munkamenet (az loginbeleértve a azure/login GitHub-műveletet) is tiszteletben tart minden környezetben. Csak akkor indul el az login a munkamenet, ha nem található hitelesítő adat, és a munkamenet interaktívaz-sign.

Előfeltételek:

• Egy Azure kódaláíró fiók és egy tanúsítványprofil (amelyet az identitás érvényesítése után hoztak létre a Azure portálon), valamint az identitáshoz rendelt kódaláíró tanúsítványprofil-aláíró szerepkör. További útmutatásért tekintse meg Azure Artifact Signing rövid útmutatóját.
• Egy gépre kiterjedő x64 .NET 8 (vagy újabb) futtatókörnyezet van telepítve. Az Azure aláíró ügyfélkódtár egy olyan felügyelt szerelvény, amely signtool.exe egy külön folyamatba töltődik be; a Winapp saját önálló futtatókörnyezete nem felel meg ennek. Telepítse, https://dotnet.microsoft.com/download ha az aláírás futásidejű betöltési hibával meghiúsul.
• A Microsoft Visual C++ terjeszthető (x64). A Azure aláíró ügyfélkódtár a VC++ futtatókörnyezettől függ, és mivel a Winapp a hivatalos ügyféleszközök telepítője helyett a nyers NuGet-csomagot tölti le, ez a függőség nem lesz automatikusan telepítve. A tiszta gépek akkor is betölthetnek feladatokat, ha .NET és SignTool van jelen. Telepítse a legújabb x64-terjeszthető https://aka.ms/vs/17/release/vc_redist.x64.exe fájlt, ha az aláírás meghiúsul 0xc000007begy "Az alkalmazás nem tudott megfelelően elindulni", vagy hiányzó DLL-hiba a dlib-ből.

Minimális jogosultságú CI: Az automatikus felderítéshez (előfizetések, erőforráscsoportok, fiókok és profilok felsorolásához) olvasási hozzáférésre van szükség egy szülőhatókörben. Az összes gyűjtemény-listás hívás elkerülése érdekében adja át mind a négyet--subscription, --resource-group--accountmajd --profilea következőt: az-sign a fiók és a profil ellenőrzése közvetlen erőforrás-olvasásokkal (minden nevesített erőforráson get) ahelyett, hogy a szülőgyűjteményt számba veszi, így elegendő az adott fiókra és profilra vonatkozó egyszerű hatókör. Ha bármelyiküket kihagyja, újra bevezet egy listahívást – például kihagyva --subscriptionaz-sign azokat az előfizetéseket, amelyekhez az identitása hozzáférhet –, amelyeket egy szűk hatókörű tag nem tehet meg. A csak egyetlen tanúsítványprofilra hatókörrel rendelkező egyszerű rendszer teljes egészében kihagyhatja az ellenőrzést egy előre létrehozott --metadata-file (közvetlenül a fiókvégpontot és profilt meghatározó) átadásával.

Példák:

# 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

Hozzon létre egy katalógusfájlt CodeIntegrityExternal.cat , amely a megadott könyvtárakból származó végrehajtható fájlok kivonatait tartalmazza. Ez a katalógus az MSIX ritka csomagjegyzékeiben (AllowExternalContent) található TrustedLaunch jelzővel használható, hogy lehetővé tegye a csomagban nem szereplő külső fájlok végrehajtását.

Ez hasonló ahhoz, ahogyan signtool.exe az MSIX-csomagok aláírásakor létrejön AppxMetadata\CodeIntegrity.cat , de létrehoz egy külső katalógust a ritka/külső hely csomagolásához.

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

Argumentumok:

• input-folder – Egy vagy több feldolgozandó végrehajtható fájlt tartalmazó könyvtár. Több könyvtár elkülönítése pontosvesszőkkel (pl. "dir1;dir2")

Lehetőségek:

• --recursive, -r - Alkönyvtárak fájljainak belefoglalása
• --use-page-hashes - Oldalkivonatok hozzáadása a katalógus létrehozásakor (nagyobb katalógust hoz létre laponkénti kivonatadatokkal)
• --compute-flat-hashes – A katalógus létrehozásakor adjon meg egybesimított fájlkivonatokat
• --if-exists <Error|Overwrite|Skip> – Viselkedés, ha a kimeneti fájl már létezik (alapértelmezett: Error)
• --output, -o - Kimeneti katalógus fájl elérési útja. Ha nincs megadva, CodeIntegrityExternal.cat az aktuális könyvtárban jön létre. Ha egy könyvtár van megadva, a program hozzáfűzi az alapértelmezett fájlnevet.

A következő teendők:

• Futtatható fájlok megadott könyvtárainak vizsgálata (kódszakaszokkal rendelkező PE bináris fájlok)
• Katalógusdefiníciós fájlt (CDF) hoz létre az összes talált végrehajtható fájl kivonatával
• Windows CryptoCAT API-kat használ a .cat katalógusfájl létrehozásához
• A nem végrehajtható fájlok (például .txtkódszakaszok .dll nélkül) automatikusan ki lesznek hagyva

Példák:

# 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

Mikor érdemes használni:

Ezt a parancsot akkor használja, ha olyan ritka MSIX-csomagot hoz létre, amely a TrustedLaunch használatával ellenőrzi a külső végrehajtható fájlokat. A tipikus munkafolyamat a következő:

1. winapp manifest generate --template sparse — Ritka jegyzék létrehozása a AllowExternalContent
2. winapp create-external-catalog ./bin — Hozza létre az alkalmazás végrehajtható fájljaihoz tartozó kódintegritási katalógust
3. winapp pack — A jegyzék, az eszközök és a katalógus becsomagolása EGY MSIX-be

---

eszköz

Használja a Windows SDK-eszközöket közvetlenül. A Microsoft.Windows-ban elérhető eszközöket használja. SDK. BuildTools

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

Elérhető eszközök:

• makeappx - Alkalmazáscsomagok létrehozása és kezelése
• signtool – Fájlok aláírása és aláírások ellenőrzése
• mt - Manifeszt eszköz egymás melletti szerelvényekhez
• És más Windows SDK-eszközöket Microsoft.Windows. SDK. BuildTools

Példák:

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

Aláírás ellenőrzése

A buildelési eszközöket a Rendszer letölti a NuGetből, majd végrehajtja, így a Winapp közvetlenül a futtatás előtt ellenőrzi, hogy van-e érvényes Microsoft Authenticode-aláírás. A tanúsítványnak Microsoft Corporation nevet kell adnia aláíró szervezetként. Ez minden olyan parancsra vonatkozik, amely egy SDK-eszközhöz tartozik, beleértve a tool, packageés signa . A rendszer nem futtat egy olyan eszközt, amely nem felel meg az ellenőrzésnek:

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

A hiba itt azt jelenti, hogy a lemezen lévő fájl nem az, amit Microsoft közzétenni – leggyakrabban sérült vagy részleges letöltés. Törölje a csomagot a NuGet-gyorsítótárból, és futtassa újra a parancsot, hogy a WinApp újra letöltse.

A winapp ezután addig nyitva tartja az eszközt, amíg fut, így az ellenőrzött fájl az a fájl, Windows betöltődik. Ha nem tudja a helyén tartani az eszközt, akkor az sem fut:

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

Zárja be a fájlt használó elemeket – a víruskeresést vagy a nyílt szerkesztőt –, és futtassa újra a parancsot. Ha az eszköz használaton kívül van, törölje a csomagot a NuGet-gyorsítótárból, hogy a WinApp újra letöltse.

---

tárol

Futtassa a Microsoft Store fejlesztői parancssori felületének parancsát. Ez a parancs letölti a Microsoft Store fejlesztői parancssori felületet, ha még nem töltötte le. További információ a Microsoft Store fejlesztői parancssori felületről.

winapp store [args...]

Argumentumok:

• args... – A parancssori msstore felületnek közvetlenül továbbítandó argumentumok. Az elérhető parancsokat és lehetőségeket az MSStore CLI dokumentációjában találja.

A következő teendők:

• Biztosítja, hogy a Microsoft Store fejlesztői parancssori felület (msstore) le legyen töltve és elérhető legyen a rendszeren.
• Az összes argumentumot továbbítja a parancssori msstore felületre.
• A kimenetet közvetlenül a terminálban megjelenítő parancsot futtatja.

Példák:

# 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

A telepített Windows SDK-összetevők elérési útjai.

winapp get-winapp-path [options]

Mit ad vissza:

• A munkaterület könyvtárának .winapp elérési útjai
• Csomagtelepítési könyvtárak
• Generált fejléchelyek

---

céladatbázis

Parancsok futtatása, fájlok másolása, állapot vizsgálata vagy a teljes vendégasztal rögzítése.

Minden ige az sandbox első argumentuma. snapshotKivéve, hogy ezek a parancsok előkészíthetik vagy elindíthatják a tesztkörnyezetet. Tekintse meg Windows tesztkörnyezet végrehajtásának előfeltételeit, engedélyeit, életciklusát és helyreállítását.

cél exec

Futtasson egy parancsot vendégfelhasználóként.

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

Argumentumok a határaik megtartása után -- . A standard streamek és a vendégfolyamat kilépési kódja továbbításra kerül; ez nem teljes terminál. --json a winapp-hibák formázása az stderren a gyermekparancs stdoutjának módosítása nélkül. A strukturált error.code használatával megkülönböztethet egy célhibát az alkalmazás saját kilépési állapotától.

Explicit módon WINAPP_UI_WORKFLOW_ID a parancs által kezdeményezett vendég felhasználói felületi hívások is csoportosítva lesznek. Lásd: Tesztkörnyezeti felhasználói felület koordinációja.

leküldéses cél és cél lekérése

Másolja a fájlt vagy könyvtárat az ige által elnevezett irányba.

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

A célútvonalak a cél felügyelt munkaterületéhez viszonyítva vannak; a rendszer elutasítja az abszolút, a gyökerező és az UNC-célútvonalakat. A fájl célhelye tartalmazza a fájlnevét. Lásd: Parancsok futtatása és fájlok másolása könyvtárelrendezéshez, hivatkozáskezeléshez és másolt szkript futtatásához.

célpillanatkép

Jelentéskészség, üzemelő példányok és vendégablakok tesztkörnyezet indítása nélkül.

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

Nem csatlakoztat újra egy ügyfelet, és nem javít ügynököt. A futó tesztkörnyezet nem sikeres eredmény, nem hiba. Lásd : Tesztkörnyezet vizsgálata a készültség és a folyamatazonosítók értelmezéséhez.

cél képernyőképe

Rögzítse a vendég asztalt natív képpontméretben gazdagép PNG-ként, alkalmazásválasztó vagy gazdagépablak szegélye nélkül. --json jelenti a vendégkoordináta forrását.

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

Alkalmazásablakhoz használható ui screenshot --on sandbox -a <app> . Tekintse meg az ügyfélkövetelmények, a fókuszkorlátozások és a kimeneti kezelés képernyőképeit és felvételeit .

célrekord

Rögzítse a vendégasztalt a H.264 MP4-be. A gazdavideó- és képkockák a felvétel befejezése után érkeznek; A JSON és a keretjegyzék bármilyen méretezést vagy kitöltést ír le.

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

Az időtartamot, a keretet, a felülírást és az eredménybeállításokat ui recordhasználja, de nem egy alkalmazás, hanem az asztalt rögzíti. Előnyben részesítse a felügyelet --duration-sec nélküli parancssori felület használatát; az npm-segítőnek szüksége van a pozitív értékre durationSec. Tekintse meg a tesztkörnyezeti rögzítést a részleges bizonyítékok és a rögzítési készültségi hibák esetén.

---

find-ui

Ügynök-első. find-ui elsősorban AI kódolási ügynökök számára készült – lehetővé teszi, hogy egy ügynök valós módon lekérje a WinUI-korrektúrát a szállítási gyűjteményekből ahelyett, hogy feltalálja, és --json minden eredményt (és minden hibát) gépi olvashatóvá tesz. Ugyanúgy működik, mint kézzel gépelve.

Keressen WinUI-vezérlőket és -mintákat egy működő kód példájára. WinUI-only: a korpusz a WinUI 3 katalógus és a Windows közösségi eszközkészlet (plusz néhány válogatott alapvető minta) – nem terjed ki WPF, WinForms vagy más felhasználói felületi keretrendszerekre. Egy harmadik forrás, a microsoft-ui-reactor ReactorGallery, az opt-in: ki van zárva a normál keresésből, és csak akkor keres, amikor ön áthalad --source reactor (a C#-only deklaratív minták nem illeszthetők be egy szabványos XAML-alkalmazásba, ezért csak egy Reactor/MVU projekt létrehozásakor érheti el).

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

A Katalógus, az Eszközkészlet és a Reactor corpora hajója a parancssori felületen belül működik, így find-ui hálózati hozzáférés nélkül működik – beleértve az ügynök tesztkörnyezetében vagy egy letiltott raw.githubusercontent.comvállalati proxy mögötti első futtatáskor is. Ha GitHub elérhető, a parancssori felület frissül belőle, és felhasználónként <global .winapp>/cache/find-uigyorsítótárazza az eredményt; a beépített korpusz csak padló, soha nem plafon. A gyorsítótárazott adatok legfeljebb 24 óránként frissülnek, vagy igény szerint a --refresh.

A beépített korpusz újra lekéri a GitHub minden alkalommal, amikor egy stabil kiadás készül, és egy sikertelen frissítés leállítja a kiadás buildet, nem pedig a régebbi adatok csendes szállítását – a pék ugyanazt a kódútvonalat --refresh használja, így a hiba azt jelenti, hogy az élő frissítés is megszakadt, és érdemes megvizsgálni a szállítás előtt. A kiadás továbbra is vágható a korábban véglegesített korpuszhoz, de csak explicit felülbírálásként. Ha az eredmények a Gallery/Toolkit/Reactor corpora beépített másolatából származnak, find-ui a stderr és --json a kimenet tovább folytatódik "corpus": "embedded" (egyéb értékek: "network" friss beolvasáshoz, "cache" a helyi gyorsítótárhoz). Egy csak magalapú kérés – --source corevagy egy --id olyan készlet, amely az összes alapvető minta – is jelentést készít "embedded" , mivel a válogatott magminták a parancssori felületre vannak lefordítva, és soha nem lesznek beolvasva; nem nyomtat elavultsági értesítést, mivel --refresh nem módosíthatók. A corpus mező az eredmények kézbesítésekor jelenik meg; csak akkor jelenik meg, ha egyáltalán nem tölthető be korpusz.

Lehetőségek:

• --id <id> - A kód beolvasása (Gallery/Toolkit return XAML and/or C#; A Reactor c#-only) és egy vagy több forgatókönyv-azonosító előfeltétel-megjegyzései egy korábbi keresésből (pl. gallery-tabview-1). Ismételhető. Az azonosítók nem érzékenyek a kis- és nagybetűkre – GALLERY-TABVIEW-1 a feloldás ugyanaz, mint gallery-tabview-1a .
• --list - Keresés helyett sorolja fel az összes felderíthető vezérlő/mintaazonosítót (Katalógus + Eszközkészlet + mag; az opt-in Reactor-forrás ki van zárva).
• --source <gallery|toolkit|reactor|core> – A keresési eredmények korlátozása egyetlen forrásra. (Csak keresés – érvénytelen a --list/--id.) A reactor a bejelentkezés – ez ki van zárva a normál keresés, így --source reactor az egyetlen módja annak, hogy keressen rá.
• --max <N> - A visszaadni kívánt egyező vezérlők maximális száma (alapértelmezett: 3). Csak a keresésre vonatkozik; figyelmen kívül hagyva a --list/--id.
• --refresh- Megkerülheti a helyi gyorsítótárat, és újra lekérheti a WinUI-korpuszt a GitHub.
• --json - Strukturált JSON-t bocsát ki (ügynökbarát). A kereséshez minden egyezés hordozza sourcea , control, score, descriptionés egy scenarios tömböt, amelynek bejegyzései a forgatókönyvenkénti id és headera ; --idteljes kódot tartalmazhatják. Minden hiba esetén --json – beleértve az argumentum-/elemzőhibákat, például a nem egész számokat --max – a rendszer egy nem nulla kilépési kóddal rendelkező stdout-objektumként {"error": "..."} bocsátja ki, így a kimenet gépi olvasható marad.

Munkafolyamat: Keressen tömören a megfelelő vezérlő és a forgatókönyv azonosítóinak megkereséséhez, majd kérje le a teljes kódot a legjobban megfeleltetéshez --id.

Példák:

# 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

Kapcsolódó:find-uiWinUI-mintákat keres; használatával find-api kereshet az API-felületen (típusok, tagok, enumerálások) egy projekthivatkozásban, és winapp ui search kereshet egy futó alkalmazás felhasználói felületi fájában .

---

find-api

Ügynök-első. find-api elsősorban AI-kódolási ügynökök számára készült – az API-felületen létrehozott kód alapján a projekt valójában hivatkozik a modell visszaemlékezése helyett, valamint --json a hiányzó szimbólumokon lévő nem nulla kilépési kódok lehetővé teszik, hogy egy ügynök kodenizálja a választ. Ugyanúgy működik, mint kézzel gépelve.

Keresse meg és vizsgálja meg a projekt számára elérhető Windows/WinRT API-felületet (típusok, tagok, enumerációk, névterek) a hivatkozott metaadatok alapján feloldva.winmd/.dll. A csupasz űrlap keresése; al verbák részleteznek egy adott típust, névteret vagy magát az indexet.

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

Az index a projekt visszaállított NuGet/SDK-csomagjaiból épül fel (via project.assets.json) az első használatkor, és automatikusan frissül a projekt visszaállításakor. A globális .winapp gyorsítótár (cache/find-api/) alatt található, és a projektek között meg van osztva. Először állítsa vissza a projektet (winapp restore vagy dotnet restore).

Az egyes egyezések a névtér alatt jelennek meg az azt tartalmazó csomaggal és a művelet egysoros összegzésével, így az eredmény második members hívás nélkül is használható:

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

Adja hozzá --verbose a lemezen tárolt gyorsítótárfájlt is, amely az egyes névterek háttérrendszerét tartalmazza, ami hasznos lehet egy elavult vagy váratlan index diagnosztizálásakor.

A lekérdezés nélküli futtatás winapp find-api rövid használati összegzést és kilépést 0 jelenít meg – ez egy segítségkérés, nem pedig egy olyan keresés, amely nem talált semmit.

Hatókörök. Minden válasz pontosan egy hatókörből származik, amely a szöveges kimenetben --json szereplőként és megjegyzésként jelentscope:

• project - a projekt az aktuális könyvtárban (vagy --project / --project-dir). Ismerteti a Windows SDK-t, a Windows App SDK és a projekt saját NuGet-csomagjait. A Windows App SDK metaadatok a projekthivatkozások kiadását jelentik: ha a gépen újabb Windows-alkalmazás futtatókörnyezet van telepítve, ahelyett, hogy megerősítené a projekt által nem lefordítható típusokat, find-api figyelmezteti és hagyja ki.
• sdk- a gépi Windows SDK + Windows App SDK metaadatokat, amelyeket automatikusan használnak, ha az aktuális könyvtár nem tartalmaz projektet és megoldást. Ez lehetővé teszi find-api az API-k feltárását, mielőtt bármilyen projekt létezik, és nincs szükség hálózati hozzáférésre. Szándékosan nem tartalmaz harmadik féltől származó NuGet-csomagokat, így a közösségi eszközkészlet egy típusa (például) nem található ebben a hatókörben.

Egy projekt nélküli címtárból származó lekérdezésre és megoldásra a hatókör mindig választ ad sdk – soha nem történik meg, hogy melyik projekt legyen indexelve a megosztott gyorsítótárban – így az eredmények soha nem függnek a nem kapcsolódó globális állapottól. Az átadással --project sdk explicit módon kiválaszthatja az SDK-hatókört egy projekten belülről, és winapp find-api refresh --project sdk újraépítheti azt egy új Windows SDK telepítése után.

Megoldáskönyvtárak. Egy olyan könyvtárból, amely .sln/.slnx mellett nincs projektfájl, a megoldás a hatókör helyett sdk választ hoz létre – igény szerint indexeli őket, így a NuGet-csomagjaik is benne vannak. Ha a megoldás egynél több indexelt projektet hoz létre, a lekérdezés felsorolja őket, és ahelyett, hogy --project <name> kiválasztanak egyet.

Parancsok:

• (csupasz)find-api "<query>" ["<query>"...] - Keresési típus és tagnevek, visszaesve a dokumentált összefoglalókba, névtér szerint csoportosítva
• members <type> [<type>...] [--filter <text>] - Egy típus tulajdonságainak, eseményeinek és metódusainak felsorolása (deklarált tagok aláírással, öröklődő tagok a típus deklarálásával összegezve)
• check-property <type> <property> [<property>...] - Ellenőrizze, hogy a tulajdonságok léteznek-e egy típuson (ha hiányzik valamelyik, akkor a nem nulla értéket adja meg). Az írásvédett tulajdonságot a ️ és az "írásvédett, nem lehet hozzárendelni" értékekkel ⚠jelenti, nem pedig egyszerűként ✅, így egy tulajdonság, például ActualWidth nem tévesztendő össze a beállítható értékkel. A tulajdonságnevek megkülönböztetik a kis- és nagybetűket, mivel a C# és az XAML a következő: check-property Button background nem nulla, és közel egyezésként kínál, Background nem pedig olyan nevet, amelyet valójában nem tud írni.
• enums <type> [<type>...] [--filter <text>] - Egy szám értékeinek listázása (ha a típus nem enumerálás)
• packages – Az indexelt metaadat-csomagok listázása csomagtípusonként/tagszámmal
• stats - Összesített indexstatisztikák (csomagok, névterek, típusok, tagok, .winmd fájlok) megjelenítése
• refresh [--scan] - Egy projekt indexének újraépítése (--scan a címtárban lévő összes projektet indexeli). Ezzel --project <name>a névvel egyetlen indexelt projekt sem felel meg az aktuális könyvtár indexelése helyett.

Kötegelés.search, members, enumsés check-property egy meghívásban több témát is elfogad. Egy AI-ügynök esetében ez az egyetlen legnagyobb költségkulcs: a keresések marginális költségét a kerek utazás (minden hívás újraküldi az egész beszélgetést) uralja, nem pedig a hasznos adat mérete, így egy tíz kérdésre válaszoló hívás sokkal olcsóbb tíz hívásnál.

• Egyetlen tárgy pontosan azt a hasznos adatalakzatot adja vissza, amelyben mindig szerepel, mind a szövegben--json, mind a .
• Két vagy több alany egy borítékot ad vissza , { "count": N, "results": [ ... ] } amelyben --jsonminden elem a normál egyszemélyes hasznos adat; check-property hozzáadja missingCount. A szöveges kimenet sorrendben jeleníti meg az egyes tárgyokat egy hatókörfejléc alatt.
• check-property egy típuson kötegeli a tulajdonságokat: az első argumentum a típus, az azt követő argumentumok pedig egy tulajdonság. Köteg módban egy létező tulajdonság egyetlen ✅ sort nyomtat ki; a teljes, majdnem kihagyott részletet csak azok nyomtatják ki, amelyek nem.
• A kötegek csak akkor lépnek 0 ki, ha minden tárgy megoldódott és megtalálható – így a kötegek továbbra is biztonságosak a kódban.

Keresési rangsor. A típusnévvel pontosan egyező lekérdezések a részleges egyezések előtt kerülnek rangsorolásra, és ha egy rövid nevet több névtér is megoszt, csak a pontos név ütközései jelennek meg nem egyértelműként – egy olyan lekérdezés, amely NavigationView a pontos típust meghatározó névtereket jelenti, nem pedig minden hasonló nevű szimbólumot tartalmazó névteret. A kétértelműségi lista engedelmeskedik --max, és a normál eredmények továbbra is megjelennek alatta.

Írja be a neveket.members, check-propertyés enums fogadjon el egy rövid nevet (NavigationView) vagy egy teljesen minősített nevet (Microsoft.UI.Xaml.Controls.NavigationView). Ha egy rövid nevet egy modern Microsoft.* típus és annak örökölt Windows.* UWP ikerpéldánya oszt meg, a Microsoft.* típus választ ad – ez a Windows App SDK alkalmazás által használt kivetítés –, és a feloldott teljes név mindig megjelenik. Minden más ütközés nem nulláról lép ki, és találgatás helyett listázza a jelölteket.

Metódus-aláírások. Az aláírás a hívás megírásához hasonlóan jelenik meg: a metódus, amelyet nem példányon, hanem típuson hív meg, megjelenik staticegy hivatkozási paraméter a ténylegesen szükséges kulcsszóval – outinvagy ref. Így TryGetValue olvas, Boolean TryGetValue(String key, out String value)amely lefordítja az írott.

Lehetőségek:

• --max <n> - A névtér által csoportosított keresési eredmények maximális száma (alapértelmezett 5; csak keresés). A kétértelműségi listát is lekorlátozza, így egy rövid lekérdezés, amely sok névtérben ütközik, olvasható marad.
• --filter <text>- Szűkítse a listaelemeket, members és : egy kis- ésenumsnagybetűs részszűkítési egyezést a tag/érték neve alapján. A legjobban több száz tagú típusok esetén használható. A legtöbb enumerálás elég kicsi ahhoz, hogy az egész (még a WinUI legnagyobb 197-es értékénél is Symbol) legyen kivédve, ezért a szűrés általában többe kerül, mint amennyit megtakarít, ha egy második becslést is figyelembe vesz. Soha ne futtassa újra ugyanazt a parancsot különböző szűrőszöveggel – egyszer memóriaképet, majd olvassa el.
• --all - A membersteljes felület listázása: az örökölt tagok teljes aláírása, valamint a függőség-tulajdonság azonosító statikusai és a tagonkénti leírások, amelyekből egy szűretlen lista kimarad (lásd az alábbi Listaméretet ). --verbose azt jelenti; akkor is használható --all , ha azt is szeretné --json, amely nem kombinálható a következővel --verbose:
• --scan - Rekurzívan felderíti és indexeli az összes projektet a könyvtár alatt (refresh csak)
• --project <name>- Project lekérdezésre (a .csproj/.vcxproj névvel egyező) vagy sdk a gépszintű Windows SDK-hatókör lekérdezésére
• --project-dir <path>- Project lekérdezésre szolgáló könyvtárat (alapértelmezés szerint az aktuális könyvtárra). A nem létező elérési út hiba – a hatókörből sdk soha nem válaszol csendben.
• --json - Géppel olvasható hasznos adat kibocsátása az stdouton (minden ige támogatja). A lekérdezés hasznos adatai azonosítják a ( vagy ), és (az SDK hatókörében hiányzó) indexet scope – a projektnevek nem egyediek a könyvtárak között, így projectDir a megbízható identitás is.projectDirprojectNamesdkproject Minden hiba esetén --json – beleértve az argumentum-/elemzőhibákat, például a nem egész számokat --max – a rendszer egy nem nulla kilépési kóddal rendelkező stdout-objektumként {"error": "..."} bocsátja ki, így a kimenet gépi olvasható marad.

Példák:

# 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

Ha --filter alkalmazva van, a kimenet továbbra is a szűretlen összegről (totalValuesvagy totalProperties--json/totalEvents/totalMethods abban) számol be, így a keskeny nézet soha nem téveszt össze egy kis API-t. A semmivel egyező szűrő továbbra is kilép 0 , és kifejezetten azt mondja, hogy "semmi sem felel meg a szűrőnek", nem pedig "nincs ilyen típus".

Listaméret. A szűretlen members lista az egyetlen drága alakzat – members Button 288 tagot fed le, amelyek közül 280 6 alaptípustól öröklődik. A szűretlen hívás egy tájolási lekérdezés ("mi ez a típus, nagyjából mit tehet?"), így választ ad erre, és kihagyja azokat a részeket, amelyekből semmit sem írnak:

• Öröklődő tagazonos aláírások – az örökölt tagok csoportosítása típus szerint történik, és csak név szerint van felsorolva, így az öröklött felület alakja továbbra is látható 280 teljes aláírás nélkül.
• Dependency-property identifier statics (BackgroundProperty) – Egy tipikus WinUI-vezérlő tulajdonságainak 28%. Léteznek, amelyeket át kell adni nekik GetValue/SetValue, nem hozzárendelve.
• Tagonkénti leírások – az XML-doc próza, amely nagyjából 16% hasznos adat.
• A környezetük által sugallt mezők a következőben--json: kind (a tömböt tartalmazó tömbből következtetve/eventsproperties/methods), returnType (a vezető jogkivonat signature), és inherited ha hamis (a ).declaringType

Amit kihagyott, az mindig be van jelentve (hiddenDependencyPropertiesés descriptionsOmittedegy hint a; --json"Kihagyva:" sor a szövegben), és az összegek továbbra is a teljes típust írják le. A --filter teljes felületet teljes aláírásokkal és leírásokkal láthatja, így members Button --filter BackgroundProperty továbbra is megtalálja az azonosítót, és members Button --filter Click továbbra is visszaadja Clickaz örökölt aláírást--all. samples/winui-appA mért érték 91 954-től 10 567 karakterig (−88,5%) tartmembers Button --json, miközben a bájtok --filter--all megegyeznek.

A lekérdezések egyeztetésének menete. winapp find-api "language model" a fenti rangsorok olyan egyezések LanguageModel , amelyeknek a szavai a névterekben és a tagokban szétszórva vannak, beleértve a projekten kívülieket is, amikor a típus indexelt. A keresés lexikális, nem szemantikai: a teljes azonosító szavakat felelteti meg a betűk futtatása helyett, így llm megtalálja IImageLLMAdapterSession , de nem ScrollMode. Ha egy lekérdezés nem felel meg a névnek, a rendszer megpróbálja a típusok és tagok dokumentált összegzésével próbálkozni, ami lehetővé teszi a keresést "random-access stream"IRandomAccessStream. A leírások minden névegyeztetés alatt vannak, és csak a ténylegesen szállított csomagok összesítése kereshető – az XML-dokumentációval nem rendelkező csomagok nem adnak leírási szöveget.

MSBuild projektfájl nélküli projektek. Az Electron-alkalmazások (vagy bármely más, nem .NET által winapp.yamlhajtott alkalmazás) nem .csproj rendelkezik, ezért nemproject.assets.json. find-api indexeli az .winapp/winmds.lock.jsonwinapp restore írásból, amely ugyanazt rögzíti: minden feloldott csomagot, annak verzióját és az .winmd általa használt fájlokat. Az ilyen projektek neve a címtára után történik, és az indexe elavult lesz a lockfile újraírásakor. Az a .csproj és a winapp.yaml könyvtárat is tartalmazó könyvtár indexelt a .csprojkönyvtárból, amely a projekt fordításának pontosabb leírása.

A negatív válaszok akkor lesznek minősítve, ha az index hiányos. Ha egy csomag metaadatai nem olvashatók, az "ilyen típusú" és "a csomag soha nem indexelt" kifejezés azonosnak tűnik – és az elsőn működik, amikor valóban a második generál kódot egy olyan API-n, amelyről azt mondták, hogy nem létezik. Tehát minden negatív válasz, beleértve a search nullát eredményül adó választ is, feljegyezi, hogy az index részleges, és a következőre winapp find-api refreshmutat: . A pozitív válaszok nem változnak.

Általános típusnevek. A metaadatok általános típusokat tárolnak egy arity utótaggal (IAsyncOperation`1), amelyet senki nem így ír. members, enumsés check-property fogadja el az összes űrlapot: IAsyncOperation, IAsyncOperation<StorageFile>és IAsyncOperation`1 mindegyik azonos típusúra van feloldva. A csupasz név bármilyen aritásnak felel meg; a megadott aritásnak (bármelyik jelölésben) egyeznie kell, ezért Holder<A, B> nem oldható fel egyetlen paraméterrel Holder<T>.

--json a hasznos adatok nem hagyják ki a diagnosztikát. A gyorsítótárfájl elérési útjai csak az alatt --verbose jelennek meg (egyező szövegkimenet, ahol már csak részletesek voltak), és az üres javaslattömbök nem szerializálva vannak [].

Kilépési kódok:search találatok nélkül, check-property egy hiányzó tulajdonságon, és enums egy nem szám típusú típuson az összes kilépés nem nulla – a kapukód létrehozása és a CI ellenőrzi őket. A kötegelt hívás nem nulláról lép ki, ha valamelyik tárgy meghibásodik. Az írásvédett tulajdonság nem hiba – létezik, ezért check-property kilép 0 és megjelöli a kimenetben (writable: false a következőben --json). Egy init tulajdonság ugyanerről az okból jelent writable: false : beállítható egy objektum inicializálójában, és az aláírása azt mondja { get; init; }, hogy a hozzárendelése nem fordítható le.

Kapcsolódó:find-api "létezik ez az API, és mik a tagjai?"; segítségével find-ui megkereshet egy működő WinUI-mintát egy vezérlőhöz.

---

csomópont-létrehozási kötések

(Csak NPM-csomagban érhető el) JS-kötések létrehozása Windows App SDK API-khoz. A kötéseket egy "winapp": { "jsBindings": {...} } névtér deklarálja, amelybe package.json be van írva .winapp/bindings/.

npx winapp node generate-bindings [options]

Lehetőségek:

• --verbose, -v - Fájlonkénti részletes kódrészletek kimenetének engedélyezése
• --quiet, -q - Az előrehaladás és az információs kimenet letiltása

A következő teendők:

• Beolvassa a winapp.jsBindings blokkot package.json és az winmds.lock.json utolsó winapp restoreáltal írt szöveget, majd gépelt .js + .d.ts kötéseket bocsát ki a .winapp/bindings/
• Nem módosítja package.json – ez egy passzív regenerátor. winapp.jsBindings A blokk és a futtatókörnyezet függőségének @microsoft/dynwinrt hozzáadása a JS-kötések engedélyezésekor winapp init történik. Ez a parancs gyorsan meghiúsul, ha a blokk hiányzik
• Figyelmeztet (de nem ír), ha @microsoft/dynwinrt hiányzik a függőségeiből – futtatás npm install a hozzáadás után init

Megjegyzés:

A kötések csak npm-alapúak – meghívást igényelnek (az npx winapp npm-csomagon keresztül @microsoft/winappcli ); az önálló winget CLI nem jeleníti meg őket. A kötések újragenerálása előtt futtassa winapp init interaktívan, és jelentkezzen be vagy használja winapp init . --use-defaults --add-js-bindingsa parancsot. Szerkesztés esetén winapp.yamlfuttassa npx winapp restore a Windows függőségek frissítéséhez az újragenerálás előtt.

Példák:

# 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

Tekintse meg a JS-kötések útmutatóját a végpontok közötti munkafolyamathoz és a winapp.jsBindings konfigurációs beállításokhoz.

---

node create-addon (bővítmény létrehozása)

(Csak NPM-csomagban érhető el) Natív C++ vagy C# bővítménysablonok létrehozása Windows SDK-val és Windows App SDK integrációval.

npx winapp node create-addon [options]

Lehetőségek:

• --name <name> - Addon name (alapértelmezett: "nativeWindowsAddon")
• --template - Válassza ki a bővítmény típusát. A beállítások vagy cscpp (alapértelmezett: cpp)
• --verbose – Részletes kimenet engedélyezése

A következő teendők:

• Kiegészítő könyvtár létrehozása sablonfájlokkal
• Kötés.gyp és addon.cc generál Windows SDK-példákkal
• Telepíti a szükséges npm-függőségeket (nan, node-addon-api, node-gyp)
• Hozzáad egy buildszkriptet a package.json fájlhoz

Példák:

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

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

---

node add-electron-debug-identity

(Csak NPM-csomagban érhető el) Alkalmazásdentitás hozzáadása az Electron fejlesztési folyamatához a ritka csomagolás használatával. Package.appxmanifest szükséges (hozzon létre egyet, vagy winapp init ha nem rendelkezik ilyennelwinapp manifest generate).

Fontos

Ismert probléma merült fel a ritkán csomagolt Electron-alkalmazások esetében, amely miatt az alkalmazás összeomlik az indításkor, vagy nem jeleníti meg a webes tartalmat. A problémát kijavítottuk Windows, de még nem propagáltuk külső Windows eszközökre. Ha ezt a problémát a hívás add-electron-debug-identityután tapasztalja, letilthatja a tesztkörnyezetet az Electron alkalmazásban hibakeresési célokra a --no-sandbox jelzővel. Ez a probléma nem érinti a teljes MSIX-csomagolást.

Az Electron hibakeresési identitásának visszavonásához használja a winapp node clear-electron-debug-identity.

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

Lehetőségek:

Lehetőség	Leírás
--manifest <path>	Az egyéni Package.appxmanifest elérési útja (alapértelmezett: Package.appxmanifest az aktuális könyvtárban)
--no-install	Ne telepítse vagy módosítsa a függőségeket; csak az Electron hibakeresési identitásának konfigurálása
--keep-identity	A manifest identitás as-is megőrzése a csomag nevének és alkalmazásazonosítójának nélkül .debug hozzáfűzése.
--verbose	Részletes kimenet engedélyezése

A következő teendők:

• Hibakeresési identitás regisztrálása electron.exe folyamathoz
• Lehetővé teszi az identitásigényes API-k tesztelését az Electron-fejlesztésben
• Meglévő Package.appxmanifest használata identitáskonfigurációhoz

Példák:

# 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-electron-debug-identity

(Csak NPM-csomagban érhető el) Távolítsa el a csomagdentitást az Electron hibakeresési folyamatából az eredeti electron.exe biztonsági mentésből való visszaállításával.

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

Lehetőségek:

Lehetőség	Leírás
--verbose	Részletes kimenet engedélyezése

A következő teendők:

• Visszaállítja a electron.exe a biztonsági másolatból, amelyet add-electron-debug-identity
• A visszaállítás után eltávolítja a biztonsági mentési fájlokat
• Az Electron eredeti állapotát adja vissza csomagadentitás nélkül

Példák:

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

---

Globális beállítások

Minden parancs támogatja ezeket a globális beállításokat:

• --verbose, -v - Részletes kimenet engedélyezése részletes naplózáshoz
• --quiet, -q - Folyamatjelző üzenetek letiltása
• --help, -h - Parancs súgójának megjelenítése

---

Globális gyorsítótár könyvtára

A Winapp létrehoz egy könyvtárat a több projekt között megosztható fájlok gyorsítótárazásához.

A winapp alapértelmezés szerint globális gyorsítótár-címtárként hoz létre egy könyvtárat $UserProfile/.winapp .

Másik hely használatához állítsa be a környezeti változót WINAPP_CLI_CACHE_DIRECTORY .

A parancsmagban:

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

A PowerShellben és a pwsh-ban:

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

A Winapp automatikusan létrehozza ezt a könyvtárat, amikor olyan parancsokat futtat, mint vagy initrestore.

Frissítési ellenőrzések

A winapp CLI rendszeres időközönként ellenőrzi az új verziókat, és egysoros értesítést jelenít meg, ha egy frissítés elérhető. Ez az ellenőrzés a háttérben fut, és nem ad késést a parancsokhoz.

A frissítési ellenőrzések automatikusan le vannak tiltva CI-környezetekben (GitHub Actions, Azure Pipelines stb.).

A frissítési ellenőrzések manuális letiltásához állítsa a környezeti változót a WINAPP_CLI_UPDATE_CHECK következőre 0: .

A parancsmagban:

set WINAPP_CLI_UPDATE_CHECK=0

A PowerShellben és a pwsh-ban:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Ennek véglegessé tétele:

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

Felhasználói felület munkafolyamat-identitása

winapp ui a fizikai asztalt meghajtó parancsok mindig kooperatív fordulatokat hajtanak végre, így az egyszerre futó két munkafolyamat nem tudja ellopni egymás fókuszát, vagy nem tudják bezárni egymás menüit. Ennek a választottbírósági eljárásnak nincs szüksége beállításra, és nem kapcsolható ki.

Ami nem kötelező, az a folytonosság. Alapértelmezés szerint minden parancs egy önálló egylövetű, amely amint befejeződik, kiadja az asztalt. Ha több parancson szeretné tartani az asztalt, adja meg nekik ugyanazt a munkafolyamat-azonosítót:

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

Használja ugyanazt az értéket az együttműködési folyamatokhoz (például egy felvételhez és a rögzítendő kattintásokhoz) és a független munkafolyamatok különböző értékeihez. Az azonosító nélküli összes parancs saját egylövetű munkafolyamat, még akkor is, ha egy rendszerhéjból több is elindul, így a parancsonként új rendszerhéjat indító gazdagépeknek ugyanazt a explicit értéket kell beszúrni mindegyikbe. Az érték átlátszatlan, soha nem kezeli hitelesítő adatként, és csak SHA-256 kivonatként marad meg. Lásd: UI-automatizálás → Egyidejű felhasználói felületi munkafolyamatok koordinálása.

ui

Az UI-automatizálás (UIA) használatával vizsgálja meg és használja az Windows alkalmazás felhasználói felületét.

winapp ui [command] [options]

Parancsok:

• status – Csatlakozás az alkalmazáshoz és adatok megjelenítése
• inspect - Elemfa megtekintése
• search – Elemek keresése választó szerint
• get-property – Elem tulajdonságainak olvasása
• get-text / get-value - Érték/szöveg olvasása elemből (TextPattern, ValuePattern vagy Name)
• screenshot - Ablak/elem rögzítése PNG-ként (több ablak alkotja az egy címkével ellátott összetett PNG-t; lásd a rögzítési hatókört)
• record- Ablak/elem régió rögzítése egy H.264 MP4-videóra (Windows Grafikus rögzítés + Media Foundation)
• invoke - Elem aktiválása (kattintás, váltógomb, kibontás)
• click - Kattintson az elemre az egérszimuláción keresztül (olyan vezérlők esetén, amelyek nem támogatják a meghívást)
• hover – Egér áthelyezése elemre elemleírások, úszó panelek és rámutatási állapotok aktiválásához (alapértelmezett tartózkodási hely: 800 ms)
• drag - Húzza az egeret egyik pontról a másikra elemválasztó vagy képernyőkoordináta x,y szerint (átrendezés, átméretezés, csúszkák, húzással)
• touch- Szintetikus érintéses kézmozdulatok (koppintás, dupla koppintás, hosszú lenyomás, pöccintés, csippentés, nyújtás) injektálása elem középen vagy képernyőkoordinátákon x,y
• pen - Szintetikus toll/toll bemenetének injektálása – csapok és tollvonások konfigurálható nyomással, dőlésszöggel és radír móddal
• send-keys – Szintetikus billentyűzetbemenet (elnevezett billentyűk, kombinált kombinációk, nyers vk=0xNN vagy literális szöveg) küldése egy ablakba
• set-value - Érték beállítása szerkeszthető elemre (szöveg, szám); visszaesik a LegacyIAccessible put_accValue for TextPattern-only rich-edit vezérlőkhöz
• focus – Billentyűzetfókusz áthelyezése
• scroll-into-view - Látható görgetési elem
• wait-for - Várakozás az elemállapotra
• list-windows – Alkalmazás összes ablakának listázása
• get-focused – Az aktuálisan szűrt elem jelentése
• yield – Az aktuális munkafolyamat felhasználói felületi fordulatának feloldása; megköveteli WINAPP_UI_WORKFLOW_ID

Lehetőségek:

• -a, --app <app> - Célalkalmazás (név, cím vagy PID)
• -w, --window <hwnd> - Célablak HWND szerint (stabil)
• --on <target> - Futtasson bármilyen ui igét a vendégre hivatkozó nevekben, PID-kben sandboxés ablakfogópontokban. A kimenetek a gazdagépre érkeznek. A beállítási, munkafolyamat-koordinációs és ügyfélkövetelményekről lásd a tesztkörnyezet felhasználói felületének automatizálását .

felhasználói felület rekordja

Ablak- vagy elemrégió rögzítése H.264 MP4-es verzióra.

# 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

Rekordbeállítások:

• --duration-sec <n> - Rögzítési hossz másodpercben. 0 rekordokat a Ctrl+C billentyűkombinációig (alapértelmezett 0).
• --fps <n> - Képkockák másodpercenként rögzítendők (alapértelmezett 15).
• --max-edge <px> - Leskálázás, így a leghosszabb él legfeljebb ennyi képpont (0 = nincs leskálázás).
• --capture-screen - Rögzítse a képernyőről, hogy az átfedések/előugró ablakok is szerepelhessenek (rögzítheti az elzárt ablakokat).
• -o, --output <path> - Kimeneti .mp4 elérési út (alapértelmezett érték: recording-<timestamp>-<guid>.mp4).
• --overwrite - Cserélje le a meglévő felvételi kimeneteket az új felvétel befejezése után; a meglévő kimenetek alapértelmezés szerint elutasítva lesznek. A korábbi keretkötegek megmaradnak. Lásd : A kimeneti helyreállítás rögzítése.
• --frames- Írási időszeletelt JPEG-k, frames.ndjsonés manifest.json a .<output-name>.frames Támogatja az 1-30 fps és --max-edge a 64-4096 (alapértelmezett 1280) 1 GiB frame-data cap.

Ezzel --jsonegyütt a végeredmény tartalmazza a kimeneti útvonalat, a dimenziókat, a kodeket, a rögzítési módot, az ütemet, a leállítás okát, az opcionálist frameArtifactsés a figyelmeztetéseket.

Ismert korlátozás: ha egy adott elemet rögzít egy előugró ablakban, amely a saját felső szintű ablakában jelenik meg (WinUI/XAML-úszó panel, oktatási tipp, elemleírás) a mögöttes főablakot rögzítheti. Rögzítse a teljes ablakot, vagy kövesse az előugró állóképek képernyőképes átfedési munkafolyamatát . Nyomon követve a 646.

A teljes dokumentációt a docs/ui-automation.md fájlban találja.