winapp CLI-parancsok beállításhoz, csomagoláshoz és aláíráshoz

A winapp CLI parancsokat biztosít a modern Windows-alkalmazások beállításához, csomagolásához, aláírásához, futtatásához és közzétételéhez. Ez a cikk az egyes parancsok teljes hivatkozását tartalmazza, beleértve az argumentumait és beállításait.

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> - Olvasási/tárolási konfigurációt tároló könyvtár (alapértelmezett: aktuális könyvtár)
  • --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>- Sablon rövid neve (pl. winui, winui-navview, winui-mvvm, winui-lib, ). winui-unittest Futtatáskor érvényesítve a telepített csomaggal; futtassa winapp new --list az összes megtekintéséhez. Alapértelmezett: winui (üres 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 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 WinUI 3-alkalmazás (MSIX-csomagolás)
winui-navview NavigationView kezdőalkalmazás
winui-tabview TabView kezdőalkalmazás
winui-mvvm 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

Az egyes sablonok rövid nevei az első aliaslisták dotnet new ; a felsorolt aliasok (pl. winui3, wasdk-single) 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.

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

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

Lehetőségek:

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

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 winapp init inicializált .NET projektek esetében nincs winapp.yaml. A dotnet restore használata helyett állítsa vissza a NuGet-csomagokat.

Példák:

# Restore from winapp.yaml in current directory
winapp restore

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

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

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

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 rendelve, kivéve, ha az 0.0.0.0, 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>). Bármely érvényes X.500 DN-t elfogad; 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:

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 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 két 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.

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: egy build-output mappa (mappamód), egy .csproj projekt, egy .sln/.slnx megoldás vagy egy olyan könyvtár, amely a legfelső szintjén található egyiket tartalmazza (projekt mód; a címtár nem rekurzívan keres). 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> - Kimeneti könyvtár a laza elrendezési csomaghoz (alapértelmezett: AppX a bemeneti mappa könyvtárában)
  • --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. Szüksége van egy uap5:ExecutionAlias jegyzékre (egy hozzáadásához).winapp manifest add-alias Nem kombinálható a következővel --no-launch: . Nem kombinálható a következővel --json: .
  • --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 PID nyomtatása stdoutra (vagy JSON-ban a következővel --json: ). 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.

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.

Project mód beállításai (mappa módban figyelmen kívül hagyva):

  • -c, --configuration <name> - Buildkonfiguráció. Alapértelmezett: Debug.
  • --arch <x64|arm64|x86> - Célarchitektúra. Alapértelmezett: az aktuális folyamatarchitektúra. Meghatározza a build RID-jét és a telepített Windows-alkalmazás futtatókörnyezet architektúráját is.
  • -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 a --arch.
  • -f, --framework <tfm> - Célkeret-moniker több célzott projektekhez (pl. net10.0-windows10.0.26100.0).
  • --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).
  • --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).
  • --no-restore – A projekt létrehozásának megkezdése előtt hagyja ki a projekt visszaállítását.
  • -p, --property <Name=Value> - MSBuild tulajdonság, továbbítva mind a build, mind a tulajdonság kiértékelése. Megismételhető (pl. -p WindowsPackageType=None).

Build output & verbosity: a projekt két lépésben épül fel – a dotnet build kimeneti streamek élőben kerülnek a konzolra, majd egy gyors tulajdonságértékelési passz. A winapp a kimenet előtt nyomtatja ki a pontos dotnet build … meghívást, és még egy sikeres build esetén is figyelmeztetéseket streamel. Részletesség:

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

Alatt --json vagy --quiet a meghívás és build kimenet megy stderr így stdout marad tiszta JSON / tiszta.

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

# 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

MSBuild tulajdonságok (NuGet-csomag):

A Microsoft.Windows.SDK.BuildTools.WinApp NuGet-csomag használatakor a dotnet run automatikusan meghívja winapp run. 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 false Indítás végrehajtási aliason keresztül az AUMID aktiválása helyett
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, WinAppRunDebugOutputWinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch, WinAppRunUseExecutionAlias, WinAppRunDebugOutputWinAppRunUnregisterOnExit

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

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 - Hagyja ki a telepítési hely könyvtárának ellenőrzését, és törölje a regisztrációt még akkor is, ha a csomagot egy másik projektfáról regisztrálták
  • --json - Kimenet formázása JSON-ként

A következő teendők:

  • Beolvassa a csomag nevét a jegyzékből
  • 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 telepítési helye az aktuális könyvtárfa alatt van-e (kivéve)--force
  • Az egyező csomagok regisztrációja törlése

Példák:

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

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

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

# JSON output for scripting
winapp unregister --json

cert

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> - Közzétevői információk kinyerve a Package.appxmanifestből
  • --publisher <name>- Publisher a tanúsítványhoz. Elfogad egy teljes X.500 megkülönböztető nevet (pl. ) vagy egy csupasz nevet, CN=Contoso, O=Contoso Ltd, C=USamely automatikusan be van csomagolva CN=<name>
  • --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ány jelszava (alapértelmezett: "jelszó")
  • --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.

tanúsítványadatok

Tanúsítványadatok megjelenítése PFX-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)

Lehetőségek:

  • --password <password> - A PFX-fájl jelszava (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> [options]

Argumentumok:

  • file-path - Az MSIX-csomag elérési útja, vagy végrehajtható az aláíráshoz

Lehetőségek:

  • --cert <path> - Tanúsítvány aláírásának elérési útja
  • --cert-password <password> - Tanúsítvány jelszava (alapértelmezett: "jelszó")

Példák:

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

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

az-sign

Kód-aláírás egy fájl (exe, MSIX vagy MSIX csomag) használatával Azure Artifact Signing – 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 összetevő-aláí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 összetevő-aláíró tanúsítványprofil-aláíró szerepkör. További útmutatásért tekintse meg az Azure Összetevő-aláírás 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 a .NET letöltési oldalról, 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ő 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

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

find-ui

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 korpusz az első használatkor GitHub és felhasználónként <global .winapp>/cache/find-uigyorsítótárazva lesz, így az első futtatáshoz hálózati hozzáférés szükséges. A későbbi futtatások a helyi gyorsítótárból lesznek kiszolgálva (legfeljebb 7 naponta frissülnek, vagy igény szerint).--refresh

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

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

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 (automatikusan rögzíti a párbeszédpaneleket külön)
  • 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

Lehetőségek:

  • -a, --app <app> - Célalkalmazás (név, cím vagy PID)
  • -w, --window <hwnd> - Célablak HWND szerint (stabil)

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 demo.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).
  • --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 használja ui screenshot --capture-screen felugró állóképekhez. Nyomon követve a 646- os probléma.

A teljes dokumentációt a felhasználói felület automatizálási referenciájában találja.

  • Last updated on