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
• --exe <path> – Sökväg till det körbara programmet. Kräver --sparse. Genererar ett glest identitetsmanifest för exe i stället för ett fullständigt paket/SDK-konfiguration.
• --sparse – Generera ett glest identitetsmanifest (appxmanifest.xml) för en befintlig skrivbords-exe. Hoppar över SDK/paketinstallation. Använd med --exe.
• --name <name> – Åsidosätt paketnamnet (endast gles; standard: härleds från exe)
• --publisher <CN> – Åsidosätt utgivarens CN (endast gles; standard: härleds från exe:ens företagsnamn)
• --output-dir <path> – Katalog för att skriva det glesa manifestet och Assets/ (endast gles; standard: en sparse/ mapp i den aktuella katalogen)
• --force – Skriv över en befintlig appxmanifest.xml i målkatalogen (endast gles). Utan den misslyckas init i stället för att ersätta ett befintligt manifest/tillgångar.
• --add-js-bindings (endast npm) – Lägg till winapp.jsBindings i package.json och generera JS/TypeScript-bindningar utan att fråga (inkompatibel med --setup-sdks none)

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
• Genererar JS-bindningar för Windows App SDK API:er när det är aktiverat (endast npm)

Automatisk projektidentifiering:

När init körs utan ett katalogargument utför den en bredd-första sökning av det aktuella katalogträdet för att hitta kompatibla projekt (upp till 10). Projekttyper som stöds:

• Tauri – tauri.conf.json hittade en nivå under katalogen
• Elektron – package.json med electron i beroenden eller devDependencies
• Flutter – pubspec.yaml på project root
• .NET – .csproj vid projektroten
• Rust – Cargo.toml vid projektrot
• C++ – CMakeLists.txt vid projektrot

Sökningen hoppar över kataloger som ofta ignoreras (node_modules, bin, obj, .git osv.). När ett kompatibelt projekt hittas genomsöks inte underkataloger nedan.

• Om ett katalogargument anges (t.ex. winapp init . eller winapp init path/to/project) hoppas sökningen över och init kontrollerar endast katalogen för ett kompatibelt projekt
• Om --use-defaults (eller --no-prompt) har angetts utan ett katalogargument hoppar init du över sökningen och initierar den aktuella katalogen icke-interaktivt och varnar först om ingen känd projekttyp har identifierats där (t.ex. winapp init --use-defaults)
• I icke-interaktiva miljöer (piped stdin, CI, redirected input) init använder --use-defaults automatiskt beteende och avger en varning: Non-interactive environment detected. Using default values.
• Om den aktuella katalogen är ett kompatibelt projekt init fortsätter du omedelbart
• Om exakt ett projekt hittas någon annanstans uppmanas du att bekräfta
• Om flera projekt hittas kan du välja vilken som ska initieras – den aktuella katalogen är alltid tillgänglig som reservalternativ
• Om inga projekt hittas varnas du och tillfrågas om du vill fortsätta ändå
• Om sökningen når gränsen på 10 projekt föreslår en varning att du anger ett katalogargument

Automatiskt .NET projektflöde:

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)

Gles identitetsläge (--exe + --sparse):

Genererar ett paketmanifest med endast identiteter för en befintlig körbar dator – det första steget i arbetsflödet för gles paketering. Till skillnad från det fullständiga init flödet hoppar detta över alla SDK/paketinstallationer (glesa identitetspaket har inga SDK-beroenden) och genererar bara ett manifest och platshållartillgångar.

• Härleder paketnamnet, utgivaren, beskrivningen och versionen från exe via FileVersionInfo (åsidosätt med --name, --publishereller interaktivt)
• Skrivningar appxmanifest.xml (med exe-namnet ersatt i Executable) plus en Assets/ mapp till en sparse/ mapp i den aktuella katalogen (eller --output-dir)
• Använder --use-defaults/--no-prompt för att hoppa över de interaktiva åsidosättningsprompterna (CI-vänliga)
• --exe utan --sparse är ett fel

Tillgångar är externa. Den glesa .msix är endast identitet: den genererade Assets/ löses från appens installationskatalog (platsen för externt innehåll) vid körningen, inte i .msix. Distribuera dem tillsammans med ditt program.

Nästa steg efter winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> för att skapa identiteten .msixoch sedan winapp embed-identity <exe>. Se Sparse Packaging Guide för fullständig genomgång.

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

# 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

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.

Ny

Skapa en ny WinUI-app från en officiell Windows App SDK dotnet new mall. Interaktiv som standard; använder automatiskt standardvärden i icke-interaktiva miljöer.

winapp new [options]

Alternativ:

• -t, --template <short-name>– Mallens korta namn (t.ex. winui, winui-navview, winui-mvvm, winui-lib). winui-unittest Verifierat mot det installerade paketet vid körning. kör winapp new --list för att se alla. Standard: winui (tom app).
• -n, --name <name> – Namn på den nya appen/projektet (standard: härledd från --output, annars WinUIApp)
• -o, --output <path> – Katalog för att skapa appen i (standard: ./<name>)
• --use-defaults, --no-prompt – Fråga inte. Använd standardvärden (tom mall, namn från --output/--nameoch behåll det installerade mallpaketet i stället för att uppdatera det)
• --force – Autogenerera även om utdatakatalogen redan innehåller filer
• --template-version <latest|installed|version> – WinUI-mallpaketversion: latest installerar det senaste publicerade paketet, installed behåller det som redan har laddats ned (inget nätverk) eller fäster en explicit version som 1.2.3. Standard: installera det senaste när inget paket finns, annars uppmanas du att uppdatera ett inaktuellt paket (sparas as-is under --use-defaults).
• --list – Visa en lista över tillgängliga WinUI-mallar och avsluta (installerar det senaste paketet först om inget är installerat)
• --json – Formatera utdata som JSON

Mallar:

Malllistan läss live från det installerade paketet, så den återspeglar alltid den version du har – kör winapp new --list för att se den aktuella uppsättningen. Vanliga mallar:

Varje malls kanoniska kortnamn är de första aliaslistorna dotnet new för den. Alla listade alias (t.ex. winui3, wasdk-single) accepteras också. När det körs i ett befintligt WinUI-projekt dotnet new visas även objektmallar (t.ex. en tom sida), som winapp new läggs till i det aktuella projektet i stället för att skapa en ny.

Versionshantering av mallpaket:

winapp new fäster inte längre en specifik mallpaketversion. Om inget paket har installerats installeras det senaste. Om ett äldre paket redan är installerat kontrollerar det feeden och när det finns ett nyare, tillfrågas om du vill uppdatera – förutom i icke-interaktiva/--use-defaults körningar, som behåller det installerade paketet. Använd --template-version latest för att alltid ta det senaste utan att fråga, eller --template-version installed för att alltid använda det nedladdade paketet utan en nätverkskontroll. Om du skickar en explicit version (t.ex. --template-version 1.2.3) installeras alltid exakt den versionen – ominstallation även när ett nyare paket redan finns – så att byggnadsställningar kan återskapas mellan datorer.

Vad den gör:

• Verifierar att .NET SDK är installerat (misslyckas snabbt med vägledning om det saknas – winapp installerar inte verktygskedjor)
• Installerar eller uppdaterar det officiella WinUI-mallpaketet (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) på begäran
• Räknar upp tillgängliga mallar från det installerade paketet och delegerar byggnadsställningar till dotnet new <short-name>

WinUI-appmallar innehåller redan Windows paketering och identitet (Package.appxmanifest), så inget separat winapp init steg krävs. För appmallar använder du winapp run för att skapa och starta appen. Mallen winui-lib skapar ett klassbibliotek som ska refereras från ett appprojekt (den har inget appmanifest). Mallen winui-unittest är en paketerad MSTest-app vars tester körs när appen startas (winapp run) – inte via dotnet test. winapp newscaffolds mot din installerade .NET SDK:s målramverk och skriver ut lämpligt nästa steg för den mall du väljer.

Skicka den globala --verbose flaggan (-v) för att upprepa varje underliggande dotnet anrop (packfråga, uppdateringskontroll, installation, dotnet new list, scaffold) tillsammans med dess fullständiga utdata – användbart för att diagnostisera problem med mallpaket eller byggnadsställningar.

Exempel:

# 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

å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

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)

Skicka flera indatamappar för att skapa en .msixbundle för distribution med flera arkitekturer (se Paket med flera arkitekturer nedan).

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

Argument:

• input-folder – En eller flera kataloger som innehåller programfilerna som ska paketeras. Skicka flera mappar (t.ex. ./publish/x64 ./publish/arm64) för att skapa ett MSIX-paket. För glesa identitetspaket skickar du en gles appxmanifest.xml fil direkt i stället för en mapp (se Sparse-identitetspaket nedan).

Alternativ:

• --output <filename> - Namn på utdatafil. För enskilda paket: <name>_<version>_<arch>.msix (faller tillbaka till <name>_<version>.msix, <name>_<arch>.msixeller <name>.msix). För paket: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --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 för generering av certifikat. Accepterar ett fullständigt X.500-unikt namn eller ett namn utan namn (automatiskt omslutet som CN=<name>)
• --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 och paketerar automatiskt alla icke-bildfiler som refereras i manifestet (t.ex. AppExtension manifest.json, konfigurationsfiler) från manifestkatalogen eller indatamappen om de saknas i mellanlagringen
• 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

Glesa identitetspaket

När indata är en gles appxmanifest.xml fil (en som deklarerar <uap10:AllowExternalContent>true</uap10:AllowExternalContent> under <Properties>) i stället för en mapp, winapp pack skapar en endast identitet.msix – paketerar den bara manifestet, utan programbinärfiler eller tillgångar. Det här är steg 2 i arbetsflödet för gles paketering.

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

• Utdata är som standard i den aktuella katalogen (åsidosättning <PackageName>.identity.msix med --output).
• Signering sker endast när --cert (eller --generate-cert) tillhandahålls.
• Om du i stället skickar en mapp vars manifest deklarerar AllowExternalContentgäller det befintliga mapppaketeringsbeteendet, men winapp pack varnar om den hittar tillgångar (.ico/.jpg/.png) eller binärfiler (.exe.dll//.so) – för glesa paket hör dessa till på den externa platsen, inte i ..msix

När du har packat kör winapp embed-identity <exe> och registrerar du paketet i installationsprogrammet med Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Se Glesa förpackningsguide.

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

Paket med flera arkitekturer

När flera indatamappar skickas winapp pack skapar en som innehåller en .msixbundle.msix per arkitektur:

# 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

Kommandot identifierar automatiskt varje mapps arkitektur från pe-huvudet för den primära körbara filen, validerar konsekvens mellan sektorer (identitet, funktioner, beroenden) och skapar en <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Manifestmatchning för paket:

Varje segment i paketet behöver ett manifest. Kommandot löser manifest i den här ordningen:

1. --manifest <path> — Om det anges används det här enskilda manifestet för alla sektorer. ProcessorArchitecture Uppdateras automatiskt per sektor för att matcha den identifierade arkitekturen.

2. Manifest per mapp – Om varje indatamapp innehåller ett Package.appxmanifest (eller appxmanifest.xml) används den mappens manifest för dess sektor.

3. Aktuell katalogåterställning – Om en mapp inte har något manifest söker Package.appxmanifest kommandot efter i den aktuella arbetskatalogen och använder den (med autostämplad arkitektur).

I samtliga fall uppdateras manifestet automatiskt: platshållarna löses, beroenden matas in och ProcessorArchitecture är force-set till den identifierade arkitekturen. Efter lösning säkerställer en validering mellan sektorer att identiteten (namn, version, Publisher), funktioner och beroenden är konsekventa mellan alla sektorer – endast ProcessorArchitecture kan skilja sig åt. Paketversionen som definieras i segmenten är atributed till MSIX-paketversionen, förutom om det är , i vilket fall en tidsstämpelbaserad 0.0.0.0version genereras automatiskt.

# 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

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

embed-identity

Anslut ett skrivbordsprogram till dess glesa identitetspaket genom att bädda in elementet <msix> i appens fusionsmanifest sida vid sida. Det här är steg 3 i det glesa paketeringsarbetsflödet – det talar om för Windows vilket identitetspaket som exe som körs tillhör.

winapp embed-identity <target> [options]

Argument:

• target – Filen som ska uppdateras. Identifieras automatiskt med tillägg:
  • .exe (EXE-läge) – bäddar in elementet <msix> direkt i exe-manifestet sida vid sida med hjälp av mt.exe.
  • .xml / .manifest (XML-läge) – infogar eller ersätter elementet <msix> i en extern SxS-manifestfil (skapas om det inte finns). Återskapa appen efteråt så att det uppdaterade manifestet bäddas in i binärfilen.

Alternativ:

• --manifest <path> – Sökväg till den glesa appxmanifest.xml att läsa identiteten (packageName, publisher, applicationId) från. När det utelämnas söker kommandot efter en sparse/ mapp bredvid målet först, sedan i den aktuella katalogen, sedan målets katalog och den aktuella katalogen för appxmanifest.xml.

Exempel:

# 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

Det här kommandot är idempotent: om du kör det ersätter det alla befintliga <msix> element i stället för att duplicera det.

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 unikt namn (standard: CN=<aktuell användare>). Accepterar valfritt giltigt X.500 DN; bare-namn omsluts automatiskt som CN=<name>.
• --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:

• packaged – Standardpaketerad appmanifest
• sparse – Appmanifest med gles/extern plats paketering

Platshållare för manifest

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

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.

winapp run fungerar i något av två lägen, som väljs automatiskt från indata:

• Mappläge – indata är en build-output-mapp (innehåller en Package.appxmanifest/AppxManifest.xml).
• Project läge – indata är en .csproj, en .sln/.slnx lösning eller en katalog som innehåller en. winapp run bygger projektet och startar det med stöd för både paketerade och uppackade WinUI-appar. Se Project läge nedan.

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

Argument:

• input – Appen som ska köras: en mapp med byggutdata (mappläge), ett .csproj projekt, en .sln/.slnx lösning eller en katalog som innehåller en av dem på den översta nivån (projektläge, katalogen söks inte rekursivt). Använd . för att skapa/köra projektet i den aktuella katalogen. Valfritt – standardvärdet för den aktuella katalogen när den utelämnas (matchar dotnet run).

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. När den kraschade appen är en WinUI 3-app (Microsoft.UI.Xaml.dll läses in) körs ett extra sorteringspass för undantag automatiskt för att visa den ursprungliga HRESULT:en, dess ErrorContext-kedja och den fullständiga interna XAML-sändningsstacken. De nödvändiga felsökningskomponenterna laddas ned vid första användning (se Felsökning, åsidosätts via WINAPP_DBGTOOLS_DIR miljövariabeln). 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. Den här flaggan förbättrar även Triage-stacken för Undantagsstack för WinUI 3 för WinUI 3-appar. 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

Project läge (.NET SDK-projekt)

När indata är en .csproj, en .sln/.slnx lösning eller en katalog som innehåller en (inklusive .), winapp runskapas projektet med dotnet build och startar det sedan. Den stöder både paketerade och uppackade WinUI-appar och installerar matchande arkitektur Windows App Runtime som appen behöver innan den startas.

Lösningsindata: peka winapp run på en/.slnx.sln(eller en katalog som innehåller en – en lösning föredras framför lösa .csproj filer) och den löser det körbara appprojektet och skapar det sedan med $(SolutionDir) och de samma Solution* egenskaperna definieras, så att projekt som är beroende av dem skapas som de gör i Visual Studio. Lösningsregler:

• Testprojekt hoppas över när du väljer automatiskt, så en lösning som innehåller en app plus dess tester matchar appen utan --project att det behövs. (Ett WinUI-testprojekt är i sig en paketerad app, så endast utdatatypen kan inte särskilja den.)
• Om det enda körbara projektet är ett testprojekt körs det.
• Om det finns fler än ett runnable-appprojekt gissar winapp run du inte på ett startprojekt – det fel vid listan över kandidater. Använd --project <name> för att välja, vilket alltid respekteras, inklusive att välja ett testprojekt.

Paketerad eller uppackad identifieras automatiskt från projektets effektiva WindowsPackageType MSBuild-egenskap (aldrig från manifestnärvaro):

• Paketerad (WindowsPackageType=MSIX, WinUI-paketerad standard) – bygger och registrerar sedan byggutdata som ett löst layoutpaket och startar via AUMID (samma pipeline som mappläge).
• Packa upp (WindowsPackageType=None) – bygger, säkerställer att den ramverksberoende Windows App Runtime installeras och sedan startar den skapade .exe direkt. Framtvinga detta för ett paketerat projekt med -p WindowsPackageType=None.

Project läge kräver .NET SDK 8.0.100 eller senare (för MSBuild --getProperty).

Project-lägesalternativ (ignoreras i mappläge):

• -c, --configuration <name> – Skapa konfiguration. Standardvärde: Debug.
• --arch <x64|arm64|x86> – Målarkitektur. Standard: den aktuella processarkitekturen. Avgör både build RID och arkitekturen för Windows App Runtime som installeras.
• -r, --runtime <rid>– Mål-.NET körningsidentifierare (t.ex. win-x64). Project läge använder endast RID-arkitekturen, skapar alltid kanoniska win-<arch>och avvisar icke-Windows RID:er (t.ex. linux-x64). Dess arkitektur åsidosätter --arch.
• -f, --framework <tfm> – Målramverksmoniker för projekt med flera mål (t.ex. net10.0-windows10.0.26100.0).
• --project <name-or-path> – När indata är en lösning (.sln/.slnx) eller en katalog med flera körbara appprojekt väljer du vilket projekt som ska startas (efter projektnamn eller sökväg).
• --no-build – Hoppa över att skapa och köra befintliga byggutdata (utvärderar fortfarande utdataegenskaper).
• --no-restore – Hoppa över att återställa projektet innan du skapar det.
• -p, --property <Name=Value> – MSBuild-egenskapen vidarebefordras till både bygget och egenskapsutvärderingen. Repeterbar (t.ex. -p WindowsPackageType=None).

Skapa utdata och utförlighet: projektet är inbyggt i två steg – en dotnet build vars utdata strömmar live till konsolen, följt av ett snabbt egenskapsutvärderingspass. winapp skriver ut exakt dotnet build … anrop före utdata och strömmar varningar även i en lyckad version. Utförlighet:

Under --json eller --quiet anropet och byggutdata går till stderr så stdout förblir ren JSON / ren.

Alternativtillämpbarhet: alternativen för identitet/lös layout (--manifest, , --output-appx-directory, --no-launch--with-alias, --unregister-on-exit, --clean, --executable) gäller endast för paketerade appar. De avvisas med ett tydligt fel för uppackade appar (som inte har något MSIX-paket). Start-/felsökningsalternativ (--args/--, , --debug-output--detach, --symbols, --json) fungerar i båda.

Project-lägesexempel:

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

Ömsesidigt uteslutande inställningar. WinAppRunNoLaunch och var och WinAppRunDetach en beskriver olika startbeteenden, så de är i konflikt med de andra startegenskaperna och med varandra. Om du anger ett par som är i konflikt misslyckas körningen med --X and --Y cannot be used together:

WinAppRunUseExecutionAlias, WinAppRunDebugOutputoch WinAppRunUnregisterOnExit kan kombineras med varandra. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutableoch WinAppLaunchArgs har inga begränsningar. WinAppRunArgs lägger inte till någon egen begränsning, men en växel som skickas genom den kontrolleras som alla andra, så WinAppRunArgs="--detach" fortfarande står i konflikt med WinAppRunNoLaunch.

<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 för certifikatet. Accepterar ett fullständigt X.500-unikt namn (t.ex. CN=Contoso, O=Contoso Ltd, C=US) eller ett namn utan namn som automatiskt omsluts som CN=<name>
• --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

az-sign

Kodsignera en fil (exe, MSIX eller MSIX-paket) med Betrodd Azure-signering – en molnhanterad signeringsidentitet, så att ingen privat nyckel (PFX) någonsin finns på den lokala datorn.

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

Argument:

• file-path – Sökväg till filen som ska signeras (exe, msix eller msixbundle)

Alternativ:

• --subscription, -s – Azure prenumerations-ID som ska användas. Om det inte tillhandahålls och det finns flera prenumerationer uppmanas du att
• --resource-group, -r – Resursgrupp för att begränsa signeringskonton
• --account - Signeringskontonamn. Måste användas med --resource-group
• --profile, -p – Certifikatprofilnamn. Måste användas med --account
• --metadata-file, -m – Sökväg till en befintlig metadata.json. Hoppar över frågor och tecken för resursidentifiering och konto/profilval direkt. En icke-interaktiv Azure autentiseringsuppgifter bör redan vara tillgänglig. CLI kan annars återgå till en interaktiv klientprompt eller az login, men npm-programmatiska API:et är alltid icke-interaktivt och misslyckas i stället för att fråga

Autentisering:

az-signanvänder Azure standardkedja för autentiseringsuppgifter (DefaultAzureCredential). För CI/CD anger du AZURE_TENANT_ID, AZURE_CLIENT_IDoch AZURE_CLIENT_SECRET (eller använder GitHub Actions OIDC/hanterad identitet). En befintlig Azure CLI session (az logininklusive azure/login GitHub åtgärd) respekteras också i alla miljöer. Endast när inga autentiseringsuppgifter hittas och sessionen är interaktiv startas az-signaz login åt dig.

Förutsättningar:

• Ett Azure kodsigneringskonto och en certifikatprofil (som skapats i Azure-portalen efter identitetsverifiering) plus den roll för kodsigneringscertifikatprofilen som tilldelats din identitet. Mer vägledning finns i snabbstartsdokumenten för Azure Artifact Signing.
• En datoromfattande x64-.NET 8 (eller senare) körning installerad. Det Azure signeringsklientbiblioteket är en hanterad sammansättning som signtool.exe läses in i en separat process. Winapps egen fristående körning uppfyller inte den. Installera den från https://dotnet.microsoft.com/download om signeringen misslyckas med ett körningsbelastningsfel.
• Microsoft Visual C++ Redistributable (x64). Det Azure signeringsklientbiblioteket beror på VC++-körningen, och eftersom winapp laddar ned det råa NuGet-paketet i stället för det officiella installationsprogrammet för klientverktyg installeras inte det här beroendet automatiskt. En ren dator kan belastnings-misslyckas även med .NET och SignTool närvarande. Installera den senaste x64-omdistribuerbara versionen från https://aka.ms/vs/17/release/vc_redist.x64.exe om signeringen misslyckas med , 0xc000007b"Programmet kunde inte starta korrekt" eller felet missing-DLL från dlib.

Ci med lägsta behörighet: Automatisk identifiering (lista prenumerationer, resursgrupper, konton och profiler) behöver läsåtkomst i ett överordnat omfång. För att undvika varje samlingslistningsanrop skickar du alla fyra av --subscription, --resource-group, --accountoch --profile: az-sign validerar sedan kontot och profilen med direkt resursläsningar (en GET för varje namngiven resurs) i stället för att räkna upp den överordnade samlingen, så att ett huvudområde som är begränsat till just det kontot och profilen räcker. Om du utelämnar någon av dem introduceras ett listanrop igen – till exempel om du utelämnar --subscriptionaz-sign listan över prenumerationer som din identitet kan komma åt – vilket ett smalt huvudnamn kanske inte tillåts att göra. Ett huvudnamn som endast är begränsat till en enda certifikatprofil kan hoppa över valideringen helt och hållet genom att skicka en förgenererad --metadata-file (som anger kontoslutpunkten och profilen direkt).

Exempel:

# 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

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

find-ui

Sök efter ett fungerande kodexempel genom att söka efter WinUI-kontroller och exempel. Endast WinUI: corpus är WinUI 3-galleriet och Windows Community Toolkit (plus några utvalda kärnmönster) – det omfattar inte WPF, WinForms eller andra gränssnittsramverk. En tredje källa, microsoft-ui-reactor ReactorGallery, är opt-in: den undantas från en normal sökning och söks bara när du passerar --source reactor (dess C#-only deklarativa exempel klistrar inte in i en XAML-standardapp, så sträck dig efter den endast när du skapar ett Reactor/MVU-projekt).

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

Corpus hämtas från GitHub vid första användningen och cachelagras per användare under <global .winapp>/cache/find-ui, så den första körningen kräver nätverksåtkomst. Efterföljande körningar hanteras från den lokala cachen (uppdateras högst var sjunde dag eller på begäran med --refresh).

Alternativ:

• --id <id> – Hämta koden (Gallery/Toolkit returnerar XAML och/eller C#; Reactor är C#-only) plus nödvändiga anteckningar för ett eller flera scenario-ID:n från en tidigare sökning (t.ex. gallery-tabview-1). Repeterbar. ID:t är skiftlägeskänsliga – GALLERY-TABVIEW-1 löser samma sak som gallery-tabview-1.
• --list – Visa en lista över alla identifieringsbara kontroll-/exempel-ID:t i stället för att söka (Gallery + Toolkit + core; opt-in Reactor-källan är exkluderad).
• --source <gallery|toolkit|reactor|core> – Begränsa sökresultat till en enda källa. (Sök endast – inte giltigt med --list/--id.) Reaktorn är opt-in – den undantas från en normal sökning, så --source reactor är det enda sättet att söka den.
• --max <N> – Maximalt antal matchade kontroller som ska returneras (standard: 3). Gäller endast för sökning. ignoreras med --list/--id.
• --refresh– Kringgå den lokala cachen och hämta WinUI-corpus igen från GitHub.
• --json – Avge strukturerad JSON (agentvänligt). För sökning bär sourcevarje matchning , control, score, descriptionoch en scenarios matris vars poster innehåller per scenario id och header, för --id, fullständig kod. Under --jsonvarje fel , inklusive argument-/parser-fel, till exempel ett icke-heltal --max , genereras som ett platt {"error": "..."} objekt på stdout med en slutkod som inte är noll, så att utdata förblir maskinläsbara.

Arbetsflöde: Sök kompakt för att hitta rätt kontroll och dess scenario-ID:t och hämta sedan den fullständiga koden för bästa matchning med --id.

Exempel:

# 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

node generate-bindings

(Endast tillgängligt i NPM-paket) Generera JS-bindningar för Windows App SDK API:er. Bindningarna deklareras av ett "winapp": { "jsBindings": {...} } namnområde i package.json och skrivs till .winapp/bindings/.

npx winapp node generate-bindings [options]

Alternativ:

• --verbose, -v – Aktivera utförliga codegen-utdata per fil
• --quiet, -q – Utelämna förlopp och informationsutdata

Vad den gör:

• winapp.jsBindings Läser blocket från package.json och skrivet winmds.lock.json av den sista winapp restoreoch genererar sedan inskrivna .js + .d.ts bindningar till.winapp/bindings/
• Ändrar intepackage.json – det är en passiv regenerator. winapp.jsBindings Att lägga till blocket och @microsoft/dynwinrt körningsberoendet sker under winapp init när JS-bindningar är aktiverade. Det här kommandot misslyckas snabbt om blocket saknas
• Varnar (men skriver inte) om @microsoft/dynwinrt det saknas i dina beroenden – kör npm install efter init att den har lagts till

Exempel:

# 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

Se guiden för JS-bindningar för arbetsflödet från slutpunkt till slutpunkt och konfigurationsalternativen winapp.jsBindings .

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

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

Alternativ:

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:

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.

Uppdatera kontroller

Winapp CLI söker regelbundet efter nya versioner och visar ett meddelande med en rad när en uppdatering är tillgänglig. Den här kontrollen körs i bakgrunden och lägger inte till någon svarstid för kommandon.

Uppdateringskontroller inaktiveras automatiskt i CI-miljöer (GitHub Actions, Azure-pipelines osv.).

Om du vill inaktivera uppdateringskontroller manuellt anger du WINAPP_CLI_UPDATE_CHECK miljövariabeln till 0.

I cmd:

set WINAPP_CLI_UPDATE_CHECK=0

I PowerShell och pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Så här gör du detta permanent:

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

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)
• record– Spela in en fönster-/elementregion till en H.264 MP4-video (Windows Graphics Capture + Media Foundation)
• invoke - Aktivera element (klicka, växla, expandera)
• click – Klicka på element via mussimulering (för kontroller som inte stöder anropa)
• hover – Flytta musen till elementet för att utlösa knappbeskrivningar, utfällbara objekt och hovringstillstånd (standard uppehåll: 800 ms)
• drag – Dra musen från en punkt till en annan, efter elementväljare eller skärmkoordinater x,y (ändra ordning, ändra storlek, skjutreglage, dra och släpp)
• touch- Mata in syntetiska touchgester (tryck, dubbeltryck, långtryck, svep, nypa, sträcka) i ett element i mitten eller skärmkoordinater x,y
• pen - Mata in syntetisk penna/penna - kranar och pennstreck med konfigurerbart tryck, lutnings- och radergummiläge
• send-keys - Skicka syntetiska tangentbordsindata (namngivna nycklar, kombinationer, rå vk=0xNN eller literaltext) till ett fönster
• set-value – Ange värde för redigerbart element (text, tal); återgår till LegacyIAccessible put_accValue för rt-edit-kontroller med endast TextPattern
• 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)

ui-post

Registrera ett fönster eller en elementregion till en H.264 MP4.

# Record a window for 10 seconds at 15 fps
winapp ui record -a Calculator --duration-sec 10 --fps 15 -o demo.mp4

# Record until Ctrl+C, downscaled so the longest edge is 1280px
winapp ui record -a "My App" --duration-sec 0 --max-edge 1280 -o capture.mp4

# Record just one element's region
winapp ui record -a "My App" btn-save-1234 -o button.mp4

# Keep an agent-readable timeline alongside the MP4
winapp ui record -a Calculator --frames --duration-sec 10 --fps 10 -o demo.mp4

Postalternativ:

• --duration-sec <n> - Inspelningslängd i sekunder. 0 poster tills Ctrl+C (standard 0).
• --fps <n> – Bildrutor per sekund som ska avbildas (standard 15).
• --max-edge <px> - Nedskala så den längsta kanten är som mest så här många bildpunkter (0 = ingen nedskalning).
• --capture-screen - Fånga från skärmen så överlägg / popup-fönster ingår (kan fånga occluding fönster).
• -o, --output <path> – Utdatasökväg .mp4 (standardvärdet recording-<timestamp>-<guid>.mp4).
• --frames – Skriva tidsstämplade JPEG:er, frames.ndjsonoch manifest.json till <output-name>.frames. Stöder 1-30 fps och --max-edge 64-4096 (standard 1280), med en 1 GiB ram-data tak.

Med --jsoninnehåller slutresultatet utdatasökvägen, dimensionerna, codec, avbildningsläget, kadensen, stopporsaken, valfria frameArtifactsoch varningar.

Känd begränsning: Inspelning av ett specifikt element i ett popup-fönster som återges i ett eget fönster på den översta nivån (WinUI/XAML utfällt, undervisningstips, knappbeskrivning) kan fånga det underliggande huvudfönstret i stället. Spela in hela fönstret eller använd ui screenshot --capture-screen för popup-stillbilder. Spåras i #646.

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