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

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

Automatikus .NET projekt felismerés:

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)

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

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 experimental használata--setup-sdks preview.

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 --manifest együtt átadott jegyzékfájlnak (Package.appxmanifestelőnyben részesített, appxmanifest.xml szintén támogatott) szerepelnie kell. (jegyzék futtatása init vagy manifest generate létrehozása)

winapp pack <input-folder> [options]

Argumentumok:

  • input-folder - A csomagolni kívánt alkalmazásfájlokat tartalmazó könyvtár

Lehetőségek:

  • --output <filename> - Kimeneti MSIX-fájl neve (alapértelmezett: <name>_<version>_<arch>.msix, visszaesés <name>_<version>.msix, <name>_<arch>.msixvagy <name>.msix ha a verzió/arch nem határozható meg)
  • --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ás neve
  • --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 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

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

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

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 CN (alapértelmezett: CN=<felhasználó>)
  • --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.

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

Argumentumok:

  • input-folder - A futtatni kívánt alkalmazást tartalmazó könyvtár (kötelező)

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

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. 
<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}.debug csomagot keres {name} (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 tanúsítvány neve
  • --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

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

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 manifest generate ha nem rendelkezik ilyennelwinapp init).

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.

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)
  • 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)
  • set-value – Érték beállítása szerkeszthető elemen (szöveg, szám)
  • 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)

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

  • Last updated on