CLI-dokumentation och användning

Shell-slutförande

Aktivera flikslutning för kommandon, alternativ och värden. Se guiden för shell-slutförande för installationsinstruktioner.

# 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

Initiera en katalog med Windows SDK, Windows App SDK och nödvändiga tillgångar för modern Windows-utveckling.

winapp init [base-directory] [options]

Argument:

  • base-directory – Bas-/rotkatalog för appen/arbetsytan (standard: aktuell katalog)

Alternativ:

  • --config-dir <path> – Katalog för att läsa/lagra konfiguration (standard: aktuell katalog)
  • --setup-sdks – SDK-installationsläge: "stabilt" (standard), "preview", "experimental" eller "none" (hoppa över SDK-installation)
  • --ignore-config, --no-config – Använd inte konfigurationsfilen för versionshantering
  • --no-gitignore – Uppdatera inte .gitignore-filen
  • --use-defaults, --no-prompt – Fråga inte och använd standardvärdet för alla prompter
  • --config-only – Hantera endast konfigurationsfilåtgärder, hoppa över paketinstallation

Vad den gör:

  • Skapar winapp.yaml konfigurationsfil (endast när SDK-paket hanteras, hoppas över med --setup-sdks none)
  • Laddar ned Windows SDK- och Windows App SDK-paket
  • Genererar C++/WinRT-huvuden och binärfiler
  • Skapar Package.appxmanifest
  • Konfigurerar byggverktyg och aktiverar utvecklarläge
  • Uppdaterar .gitignore för att exkludera genererade filer
  • Lagrar delningsbara filer i den globala cachekatalogen

Automatisk .NET projektdetektering:

När en .csproj-fil finns i målkatalogen använder init ett effektiviserat .NET specifikt flöde:

  • Validerar och uppdaterar TargetFramework till en Windows-kompatibel TFM (t.ex. net10.0-windows10.0.26100.0)
  • Lägger till Microsoft.WindowsAppSDK och Microsoft.Windows.SDK.BuildTools som NuGet-poster PackageReference direkt i .csproj
  • Genererar Package.appxmanifest, tillgångar och ett utvecklingscertifikat
  • Skapar inte eller laddar ned C++-projektioner (använd winapp.yaml för NuGet-paket)

Exempel:

# 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

Tips: Installera SDK:er efter den första installationen

Om du körde init med --setup-sdks none (eller hoppades över SDK-installationen) och senare behöver SDK:erna:

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

Använd --setup-sdks preview eller --setup-sdks experimental för förhandsversioner/experimentella SDK-versioner.

återställ

Återställ paket och återskapa filer baserat på befintlig winapp.yaml konfiguration.

winapp restore [options]

Alternativ:

  • --config-dir <path> – Katalog som innehåller winapp.yaml (standard: aktuell katalog)

Vad den gör:

  • Läser befintlig winapp.yaml konfiguration
  • Laddar ned/uppdaterar SDK-paket till angivna versioner
  • Återskapar C++/WinRT-huvuden och binärfiler
  • Lagrar delningsbara filer i den globala cachekatalogen

Anmärkning

För .NET projekt som initierats med winapp init finns det ingen winapp.yaml. Använd dotnet restore för att återställa NuGet-paket i stället.

Exempel:

# Restore from winapp.yaml in current directory
winapp restore

uppdatering

Uppdatera paketen till de senaste versionerna och uppdatera konfigurationsfilen.

winapp update [options]

Alternativ:

  • --setup-sdks <stable|preview|experimental|none> – SDK-installationsläge: stable (standard), preview, experimentaleller none (hoppa över SDK-installation)

Vad den gör:

  • Läser befintlig winapp.yaml konfiguration i den aktuella katalogen
  • Uppdaterar alla paket till de senaste tillgängliga versionerna
  • winapp.yaml Uppdaterar filen med nya versionsnummer
  • Återskapar C++/WinRT-huvuden och binärfiler

Exempel:

# Update packages to latest versions
winapp update

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

pack

Skapa MSIX-paket från förberedda programkataloger. Kräver att en manifestfil (Package.appxmanifest rekommenderas, appxmanifest.xml stöds också) ska finnas i målkatalogen, i den aktuella katalogen eller skickas --manifest med alternativet . (kör init eller manifest generate för att skapa ett manifest)

winapp pack <input-folder> [options]

Argument:

  • input-folder – Katalog som innehåller programfilerna som ska paketera

Alternativ:

  • --output <filename> – Utdata för MSIX-filnamn (standard: <name>_<version>_<arch>.msix, återgår till <name>_<version>.msix, <name>_<arch>.msixeller <name>.msix när version/båge inte kan fastställas)
  • --name <name> – Paketnamn (standard: från manifest)
  • --manifest <path> – Sökväg till manifestfilen (Package.appxmanifest föredras, appxmanifest.xml stöds också; standard: automatisk identifiering)
  • --cert <path> – Sökväg till signeringscertifikat (aktiverar automatisk signering)
  • --cert-password <password> – Certifikatlösenord (standard: "lösenord")
  • --generate-cert – Generera ett nytt utvecklingscertifikat
  • --install-cert – Installera certifikatet på datorn
  • --publisher <name> – Publisher namn för certifikatgenerering
  • --self-contained – Bundle Windows App SDK runtime
  • --skip-pri – Hoppa över PRI-filgenerering
  • --executable <path> – Sökväg till den körbara filen i förhållande till indatamappen (även --exe). Används för att lösa $targetnametoken$ platshållare i manifestet.

Vad den gör:

  • Validerar och bearbetar Package.appxmanifest-filer
  • Löser $placeholder$ token i manifestet (se Platshållare för manifest nedan)
  • Säkerställer rätt ramverksberoenden
  • Uppdaterar manifest sida vid sida med registreringar
  • Identifierar automatiskt WinRT-komponenter från tredje part och registrerar deras aktiverande klasser (se WinRT-komponentidentifiering nedan)
  • Hanterar fristående WinAppSDK-distribution
  • Signerar paket om certifikatet tillhandahålls

WinRT-komponentidentifiering

När du paketerar winapp pack söker du automatiskt igenom NuGet-paket som definierats i winapp.yaml eller *.csproj efter WinRT-komponenter från tredje part (t.ex. Win2D). Den parsar .winmd filer för att extrahera aktiverbara klassnamn och letar upp deras implementerings-DLL:er. De identifierade posterna registreras på följande sätt:

  • Ramverksberoende (standard): Aktiverbara klasser läggs till som <InProcessServer> poster i Package.appxmanifest
  • Fristående (--self-contained): Aktiverbara klasser bäddas in i SxS-manifest (sida vid sida) i den körbara filen

Platshållarmatchning under paketering:

Om manifestet innehåller $targetnametoken$ i attributet Executable :

  1. Om --executable anges (sökväg i förhållande till indatamappen) ersätts platshållaren med det angivna värdet
  2. Annars winapp pack söker indatamappens rot efter .exe filer – om exakt en hittas används den automatiskt
  3. Om noll eller flera .exe filer hittas visas ett fel där du uppmanas att ange --executable

Exempel:

# 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

skapa-debug-identitet

Skapa appidentitet för felsökning med hjälp av gles paketering. Exe stannar kvar på sin ursprungliga plats – Windows associerar identiteten med den via Add-AppxPackage -ExternalLocation.

När du ska använda detta jämfört med winapp run: Använd create-debug-identity när exe är separat från din appkod (t.ex. Electron-appar där electron.exe är i node_modules), eller när du specifikt testar glesa paketbeteende. För de flesta ramverk där exe finns i utdatamappen för bygget använder du winapp run i stället – det registrerar ett fullständigt löst layoutpaket och startar appen. En fullständig jämförelse finns i felsökningsguiden .

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

Argument:

  • entrypoint – Sökväg till körbar (.exe) eller skript som behöver identitet

Alternativ:

  • --manifest <path> – Sökväg till appmanifestfilen, antingen Package.appxmanifest eller appxmanifest.xml (standard: automatisk identifiering Package.appxmanifest eller appxmanifest.xml i den aktuella katalogen)
  • --no-install – Installera inte paketet när du har skapat det
  • --keep-identity – Behåll manifestidentiteten as-is, utan att lägga .debug till paketnamnet och program-ID:t

Vad den gör:

  • Ändrar körbara manifest sida vid sida
  • Registrerar sparse-paket för identitet
  • Aktiverar felsökning av identitetskrävande API:er

Exempel:

# 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

manifestera

Generera och hantera Package.appxmanifest-filer.

manifestet generera

Generera Package.appxmanifest från mallar.

winapp manifest generate [directory] [options]

Argument:

  • directory – Katalog för att generera manifest i (standard: aktuell katalog)

Alternativ:

  • --package-name <name> – Paketnamn (standard: mappnamn)
  • --publisher-name <name> – Publisher CN (standard: CN=<aktuell användare>)
  • --version <version> – Version (standard: "1.0.0.0")
  • --description <text> – Beskrivning (standard: "Mitt program")
  • --entrypoint <path> – Körbar startpunkt eller skript
  • --template <type> – Malltyp: packaged (standard) eller sparse
  • --logo-path <path> – Sökväg till logotypbildfil
  • --if-exists <Error|Overwrite|Skip> – Beteende när manifestfilen redan finns på målsökvägen (standard: Error)

Mallar:

Platshållare för manifest

Genererade manifest använder $placeholder$ tokens (avgränsade med dollartecken) som löses automatiskt under paketeringen.

Platshållare Löst till Exempel
$targetnametoken$ Körbart namn utan filändelse Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Alltid löst automatiskt

Detta följer samma konvention som används av Visual Studio projektmallar, så manifest är portabla mellan verktyg.

Så här hanteras platshållarna:

  • winapp pack — Under paketeringen $targetnametoken$ löses med hjälp --executable av alternativet eller genom att automatiskt identifiera singeln .exe i indatamappen. Om flera (eller noll) .exe filer hittas och --executable inte anges visas ett fel.
  • winapp create-debug-identity — När ett startpunktsargument anges $targetnametoken$ löses det från det. Utan en startpunkt måste den körbara platshållaren redan matchas i manifestet.
  • winapp manifest generate --executable — När --executable tillhandahålls extraheras manifestmetadata (version, beskrivning) och ikoner från den körbara filen, men det genererade manifestet använder $targetnametoken$.exefortfarande . Platshållaren löses senare (t.ex. winapp pack eller winapp create-debug-identity).

PS: Att hålla $targetnametoken$ i det incheckade manifestet undviker hårdkodande körbara namn och fungerar med både winapp pack och Visual Studio versioner.

Exempel:

# 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

manifesttillägg

Lägg till ett körningsalias (uap5:AppExecutionAlias) i en Package.appxmanifest. På så sätt kan du starta den paketerade appen från kommandoraden genom att skriva aliasnamnet.

winapp manifest add-alias [options]

Alternativ:

  • --name <alias> – Aliasnamn (t.ex. myapp.exe). Standard: härleds från Executable attributet i manifestet.
  • --manifest <path> – Sökväg till Package.appxmanifest (standard: sök aktuell katalog)
  • --app-id <id> – Program-ID för att lägga till aliaset i (standard: första programelementet)

Vad den gör:

  • Läser manifestet och härleder aliaset Executable från attributet (bevarar platshållare som $targetnametoken$.exe)
  • Lägger till namnområdesdeklarationen om den uap5 inte redan finns
  • Lägger till ett <Extensions> block med <uap5:AppExecutionAlias> inuti målprogramelementet
  • Om aliaset redan finns rapporterar det och avslutas korrekt

Exempel:

# Add alias inferred from Executable attribute (e.g. $targetnametoken$.exe)
winapp manifest add-alias

# Add alias with explicit name
winapp manifest add-alias --name myapp.exe

# Add alias to specific manifest
winapp manifest add-alias --manifest ./dist/Package.appxmanifest

manifest uppdatera-tillgångar

Generera alla nödvändiga MSIX-avbildningstillgångar från en enda källbild.

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

Argument:

  • image-path – Sökväg till källavbildningsfilen (PNG, JPG, SVG, ICO, GIF, BMP osv.)

Alternativ:

  • --manifest <path> – Sökväg till filen Package.appxmanifest (standard: sök aktuell katalog)
  • --light-image <path> – Sökväg till en separat källbild för lätta temavarianter

Description:

Tar en enda källbild och genererar en omfattande uppsättning MSIX-avbildningstillgångar baserat på manifestets tillgångsreferenser:

För varje tillgång som refereras i manifestet:

  • 5 skalvarianter – bas (inget suffix), .scale-125, .scale-150, , .scale-200, .scale-400

För appikonen (Square44x44Logo/AppList, 44×44 base):

  • 14 pläterade målstorleksvarianter – .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
  • 14 opläterade målstorleksvarianter – .targetsize-{size}_altform-unplated

Additionally:

  • app.ico – ICO-fil med flera upplösningar (16, 24, 32, 48, 256) för gränssnittsintegrering. Om en befintlig .ico fil hittas i katalogen assets (t.ex. AppIcon.ico från en projektmall) ersätts den på plats i stället för att skapa en dubblett

Med --light-image:

  • Ljust tema riktar in sig på varianter – .targetsize-{size}_altform-lightunplated (appikon)
  • Skalningsvarianter för ljust tema – .scale-{factor}_altform-colorful_theme-light (paneler, butikslogotyp)

SVG-stöd: SVG-filer stöds fullt ut som källbilder. De återges som vektorer direkt vid varje målstorlek, vilket ger pixelperfekta resultat vid alla upplösningar.

Kommandot skalar bilderna proportionellt samtidigt som höjdförhållandet bibehålls och centreras med transparenta bakgrunder vid behov. Tillgångar sparas i Assets katalogen i förhållande till manifestets plats.

Exempel:

# 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

run

Skapa ett löst layoutpaket från en version av utdatamappen, registrera det med Windows med hjälp av API:et Windows.Management.Deployment.PackageManager och starta programmet – simulera en fullständig MSIX-installation för felsökning. Returnerar process-ID:t för bifogad felsökningsbilaga.

Det här är det föredragna kommandot för felsökning med paketidentitet för de flesta ramverk (.NET, C++, Rust, Flutter, Tauri). Till skillnad från create-debug-identity vilket registrerar ett sparse-paket för ett enda exe registrerar winapp run hela mappen som ett löst layoutpaket, precis som en riktig MSIX-installation. Se felsökningsguiden för vanliga felsökningsarbetsflöden.

winapp run <input-folder> [options]

Argument:

  • input-folder – Katalog som innehåller appen som ska köras (krävs)

Alternativ:

  • --manifest <path> – Sökväg till Package.appxmanifest (standard: automatisk identifiering från indatamapp eller aktuell katalog)
  • --output-appx-directory <path> – Utdatakatalog för det lösa layoutpaketet (standard: AppX i katalogen för indatamappen)
  • --args <string> – Kommandoradsargument som ska skickas till programmet. Du kan också använda -- följt av argument för att undvika att komma undan (t.ex. winapp run . -- --flag value).
  • --no-launch – Skapa endast felsökningsidentiteten och registrera paketet utan att starta programmet
  • --with-alias – Starta appen med dess körningsalias i stället för AUMID-aktivering. Appen körs i den aktuella terminalen med ärvda stdin/stdout/stderr. Kräver en uap5:ExecutionAlias i manifestet (använd winapp manifest add-alias för att lägga till en). Det går inte att kombinera med --no-launch. Det går inte att kombinera med --json.
  • --debug-output – Samla in OutputDebugString meddelanden och undantag från första chansen från det startade programmet. Framework-brus (WinUI, COM, DirectX) filtreras från konsolutdata. den fullständiga loggfilen samlar in allt. Om appen kraschar samlar den automatiskt in en minidump och analyserar den för att visa undantagstypen, meddelandet och stackspårningen med källfil:radnummer (lösta från PDF-filer i mappen build output). Hanterade (.NET) krascher analyseras omedelbart utan externa verktyg. Interna krascher (C++/WinRT) visar modulnamn och förskjutningar. Endast ett felsökningsprogram kan ansluta till en process i taget, så andra felsökningsprogram (Visual Studio, VS Code) kan inte användas samtidigt. Använd --no-launch i stället om du behöver bifoga ett annat felsökningsprogram. Det går inte att kombinera med --no-launch. Det går inte att kombinera med --json.
  • --symbols – Ladda ned PDB-symboler från Microsoft Symbol Server för rikare intern kraschanalys med lösta funktionsnamn. Används endast med --debug-output. Om det utelämnas och en intern krasch inträffar föreslår utdata att den här flaggan läggs till. Första körningen laddar ned symboler och cachelagrar dem lokalt. efterföljande körningar använder cachen.
  • --unregister-on-exit – Avregistrera utvecklingspaketet när programmet har avslutats. Tar endast bort paket som registrerats i utvecklingsläge. Det går inte att kombinera med --no-launch.
  • --detach – Starta programmet och returnera omedelbart utan att vänta på att det ska avslutas. Användbart för CI/automation där du behöver interagera med appen efter starten. Skriver ut PID till stdout (eller i JSON med --json). Det går inte att kombinera med --no-launch, --debug-output, --with-aliaseller --unregister-on-exit.
  • --clean – Ta bort det befintliga paketets programdata (LocalState, inställningar osv.) innan du distribuerar om. Som standard bevaras programdata mellan omdistributioner.
  • --json – Formatera utdata som JSON för programmatisk förbrukning (t.ex. CI/automation). Användbart med --detach för att samla in PID. Det går inte att kombinera med --with-alias eller --debug-output.

Beständighet för programdata:

Som standard winapp run bevarar programmets data (LocalState, RoamingState, Settings, osv.) vid omdistribution. Om din app skriver data till ApplicationData.Current.LocalFolder eller Environment.GetFolderPath(SpecialFolder.LocalApplicationData) inom paketkontexten kommer dessa data att överleva över winapp run anrop.

Använd --clean när du behöver en nystart (t.ex. för att återställa skadat tillstånd eller testa beteendet vid första körningen).

Vad den gör:

  • Letar upp eller genererar Package.appxmanifest
  • Skapar och registrerar en felsökningsidentitet med hjälp av ett löst layoutpaket
  • Beräknar programanvändarens modell-ID (AUMID)
  • Startar programmet med den registrerade identiteten (såvida inte --no-launch anges)
  • Skriver ut process-ID (PID) för bifogad felsökningsbilaga

Exempel:

# 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-egenskaper (NuGet-paket):

När du använder nuget-paketet Microsoft.Windows.SDK.BuildTools.WinApp anropar dotnet run automatiskt winapp run. Följande MSBuild-egenskaper kan anges i för .csproj att styra beteendet:

Property Standardinställning Beskrivning
EnableWinAppRunSupport true Aktivera/inaktivera körningssupportfunktionen
WinAppLaunchArgs (tom) Argument som ska skickas till appen vid start
WinAppRunUseExecutionAlias false Starta via körningsalias i stället för AUMID-aktivering
WinAppRunNoLaunch false Registrera endast identitet utan att starta
WinAppRunDebugOutput false Samla in OutputDebugString meddelanden och undantag från första chansen. Endast ett felsökningsprogram kan kopplas åt gången (förhindrar VS/VS Code). Använd WinAppRunNoLaunch i stället för att koppla ett annat felsökningsprogram. 
<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Avregistrera

Avregistrera ett separat inläst utvecklingspaket. Tar endast bort paket som har registrerats i utvecklingsläge (t.ex. via winapp run eller create-debug-identity). Butiksinstallerade eller MSIX-installerade paket tas aldrig bort.

winapp unregister [options]

Alternativ:

  • --manifest <path> – Sökväg till Package.appxmanifest (standard: automatisk identifiering från aktuell katalog)
  • --force – Hoppa över katalogkontrollen för installationsplats och avregistrera även om paketet har registrerats från ett annat projektträd
  • --json – Formatera utdata som JSON

Vad den gör:

  • Läser paketnamnet från manifestet
  • Söker efter både {name} och {name}.debug paket (felsökningsvarianten skapas av create-debug-identity)
  • Verifierar att varje paket har registrerats i utvecklingsläge (IsDevelopmentMode == true)
  • Verifierar att paketets installationsplats finns under det aktuella katalogträdet (om inte --force)
  • Avregistrerar matchande paket

Exempel:

# 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

Generera, inspektera och installera utvecklingscertifikat.

certifikat generera

Generera utvecklingscertifikat för paketsignering.

winapp cert generate [options]

Alternativ:

  • --manifest <Package.appxmanifest> – Extrahera utgivarinformation från Package.appxmanifest
  • --publisher <name> – Publisher namn för certifikat
  • --output <path> – Sökvägen för utdatacertifikatfilen (stöder absoluta och relativa sökvägar)
  • --password <password> – Certifikatlösenord (standard: "lösenord")
  • --valid-days <valid-days> – Antal dagar som certifikatet är giltigt (standard: 365)
  • --install – Installera certifikatet i det lokala datorarkivet efter generering
  • --if-exists <Error|Overwrite|Skip> – Ange beteende om certifikatfilen redan finns (standard: Fel)
  • --export-cer – Exportera en .cer fil (endast offentlig nyckel) tillsammans med .pfx. Användbart för att distribuera det offentliga certifikatet separat för förtroendeinstallation.
  • --json – Formatera utdata som JSON för programmatisk förbrukning. Fel returneras också som JSON ({"error": "..."}).

cert info

Visa certifikatinformation från en PFX-fil. Användbart för att verifiera att ett certifikat matchar manifestet innan du loggar in.

winapp cert info <cert-path> [options]

Argument:

  • cert-path – Sökväg till certifikatfilen (PFX)

Alternativ:

  • --password <password> – Lösenord för PFX-filen (standard: "lösenord")
  • --json – Formatera utdata som JSON

installera certifikat

Installera certifikat till certifikatlager för maskin.

winapp cert install <cert-path> [options]

Argument:

  • cert-path – Sökväg till certifikatfilen som ska installeras

Exempel:

# 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

tecken

Signera MSIX-paket och körbara filer med certifikat.

winapp sign <file-path> [options]

Argument:

  • file-path – Sökväg till MSIX-paket eller körbar fil att signera

Alternativ:

  • --cert <path> – Sökväg till signeringscertifikat
  • --cert-password <password> – Certifikatlösenord (standard: "lösenord")

Exempel:

# 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

Generera en CodeIntegrityExternal.cat katalogfil som innehåller hashvärden för körbara filer från angivna kataloger. Den här katalogen används med flaggan TrustedLaunch i MSIX sparse-paketmanifest (AllowExternalContent) för att tillåta körning av externa filer som inte ingår i själva paketet.

Det här liknar hur signtool.exe du skapar AppxMetadata\CodeIntegrity.cat när du signerar ett MSIX-paket, men genererar en extern katalog för användning med gles/extern platspaketering.

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

Argument:

  • input-folder – En eller flera kataloger som innehåller körbara filer att bearbeta. Avgränsa flera kataloger med semikolon (t.ex. "dir1;dir2")

Alternativ:

  • --recursive, -r – Inkludera filer från underkataloger
  • --use-page-hashes – Inkludera sidshashvärden när du genererar katalogen (skapar en större katalog med hashdata per sida)
  • --compute-flat-hashes – Inkludera flata fil-hashar när du genererar katalogen
  • --if-exists <Error|Overwrite|Skip> – Beteende när utdatafilen redan finns (standard: Error)
  • --output, -o – Filsökväg för utdatakatalog. Om det inte anges CodeIntegrityExternal.cat skapas i den aktuella katalogen. Om en katalog anges läggs standardfilnamnet till.

Vad den gör:

  • Söker igenom angivna kataloger efter körbara filer (PE-binärfiler med kodavsnitt)
  • Genererar en katalogdefinitionsfil (CDF) med hashvärden för alla körbara filer som hittats
  • Använder Windows CryptoCAT-API:er för att skapa katalogfilen .cat
  • Filer som inte kan köras (t.ex. .txt, .dll utan kodavsnitt) hoppas automatiskt över

Exempel:

# 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

När du ska använda:

Använd det här kommandot när du skapar ett glest MSIX-paket som använder TrustedLaunch för att verifiera externa körbara filer. Det vanliga arbetsflödet är:

  1. winapp manifest generate --template sparse — Skapa ett glest manifest med AllowExternalContent
  2. winapp create-external-catalog ./bin – Generera kodintegritetskatalogen för appens körbara filer
  3. winapp pack – Paketera manifestet, tillgångarna och katalogen i en MSIX

verktyg

Åtkomst till Windows SDK-verktyg direkt. Använder verktyg som är tillgängliga i Microsoft.Windows. SDK. BuildTools

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

Tillgängliga verktyg:

  • makeappx – Skapa och manipulera apppaket
  • signtool – Signera filer och verifiera signaturer
  • mt – Manifestverktyg för sammansättningar sida vid sida
  • Och andra Windows SDK-verktyg från Microsoft.Windows. SDK. BuildTools

Exempel:

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

store

Kör ett CLI-kommando för Microsoft Store Developer. Det här kommandot laddar ned Microsoft Store Developer CLI om det inte redan har laddats ned. Läs mer om Microsoft Store Developer CLI.

winapp store [args...]

Argument:

  • args... – Argument för att skicka direkt till msstore CLI. Se MSStore CLI-dokumentationen för tillgängliga kommandon och alternativ.

Vad den gör:

  • Säkerställer att Microsoft Store Developer CLI (msstore) laddas ned och är tillgängligt i systemet.
  • Vidarebefordrar alla argument till msstore CLI.
  • Kör kommandot som visar utdata direkt i terminalen.

Exempel:

# 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

Hämta sökvägar till installerade Windows SDK-komponenter.

winapp get-winapp-path [options]

Vad den returnerar:

  • Sökvägar till .winapp arbetsytans katalog
  • Paketinstallationskataloger
  • Genererade huvudplatser

node create-addon

(endast tillgängligt i NPM-paketet) Skapa interna C++ eller C#-tilläggsmallar med Windows SDK och Windows App SDK integrering.

npx winapp node create-addon [options]

Alternativ:

  • --name <name> – Addon-namn (standard: "nativeWindowsAddon")
  • --template – Välj typ av tillägg. Alternativen är cs eller cpp (standard: cpp)
  • --verbose – Aktivera utförliga utdata

Vad den gör:

  • Skapar addon-katalog med mallfiler
  • Genererar binding.gyp och addon.cc med Windows SDK-exempel
  • Installerar nödvändiga npm-beroenden (nan, node-addon-api, node-gyp)
  • Lägger till byggskript i package.json

Exempel:

# 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

(Endast tillgängligt i NPM-paket) Lägg till appidentitet i Electron-utvecklingsprocessen med hjälp av gles paketering. Kräver en Package.appxmanifest (skapa en med winapp init eller winapp manifest generate om du inte har någon).

Viktigt!

Det finns ett känt problem med gles paketering av Elektronprogram som gör att appen kraschar vid start eller inte renderar webbinnehållet. Problemet har åtgärdats i Windows men har ännu inte spridits till externa Windows enheter. Om du får det här problemet efter att du har anropat add-electron-debug-identitykan du inaktivera sandbox-miljön i din Electron-app i felsökningssyfte med --no-sandbox flaggan. Det här problemet påverkar inte fullständig MSIX-paketering.

Om du vill ångra Electron-felsökningsidentiteten använder du winapp node clear-electron-debug-identity.

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

Alternativ:

Option Beskrivning
--manifest <path> Sökväg till anpassad Package.appxmanifest (standard: Package.appxmanifest i den aktuella katalogen)
--no-install Installera eller ändra inte beroenden. konfigurera endast electron-felsökningsidentiteten
--keep-identity Behåll manifestidentiteten as-is, utan att lägga .debug till paketnamnet och program-ID:t
--verbose Aktivera utförliga utdata

Vad den gör:

  • Registrerar felsökningsidentitet för electron.exe process
  • Möjliggör testning av identitetskrävande API:er i elektronutveckling
  • Använder befintlig Package.appxmanifest för identitetskonfiguration

Exempel:

# 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

nod clear-electron-debug-identity

(Endast tillgängligt i NPM-paket) Ta bort paketidentiteten från Electron-felsökningsprocessen genom att återställa den ursprungliga electron.exe från säkerhetskopian.

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

Alternativ:

Option Beskrivning
--verbose Aktivera utförliga utdata

Vad den gör:

  • Återställer electron.exe från säkerhetskopian som skapats av add-electron-debug-identity
  • Tar bort säkerhetskopieringsfilerna efter återställning
  • Returnerar Electron till sitt ursprungliga tillstånd utan paketidentitet

Exempel:

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

Globala alternativ

Alla kommandon har stöd för följande globala alternativ:

  • --verbose, -v – Aktivera utförliga utdata för detaljerad loggning
  • --quiet, -q – Ignorera förloppsmeddelanden
  • --help, -h – Visa kommandohjälp

Global cachekatalog

Winapp skapar en katalog för cachelagring av filer som kan delas mellan flera projekt.

Som standard skapar winapp en katalog som $UserProfile/.winapp global cachekatalog.

Om du vill använda en annan plats anger du WINAPP_CLI_CACHE_DIRECTORY miljövariabeln.

I cmd:

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

I PowerShell och pwsh:

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

Winapp skapar den här katalogen automatiskt när du kör kommandon som init eller restore.

Ui

Inspektera och interagera med att köra Windows app-UIs med hjälp av UI Automation (UIA).

winapp ui [command] [options]

Kommandon:

  • status – Anslut till appen och visa information
  • inspect – Visa elementträd
  • search – Hitta element efter väljare
  • get-property – Läsa elementegenskaper
  • get-text / get-value – Läs värde/text från element (TextPattern, ValuePattern eller Namn)
  • screenshot – Avbilda fönster/element som PNG (automatiskt avbildar dialogrutor separat)
  • invoke - Aktivera element (klicka, växla, expandera)
  • click – Klicka på element via mussimulering (för kontroller som inte stöder anropa)
  • set-value – Ange värde för redigerbart element (text, nummer)
  • focus - Flytta tangentbordsfokus
  • scroll-into-view – Rullningselementet är synligt
  • wait-for – Vänta på elementtillstånd
  • list-windows – Visa en lista över alla fönster för en app
  • get-focused – Rapportera det aktuella fokuserade elementet

Alternativ:

  • -a, --app <app> – Målapp (namn, titel eller PID)
  • -w, --window <hwnd> - Målfönster efter HWND (stabilt)

Fullständig dokumentation finns i docs/ui-automation.md.

  • Last updated on