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: den valda projektkatalogen eller den aktuella katalogen om inget projekt identifieras)
--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-mvvm, , winui-unittesteller en experimentell reaktormall som reactor eller reactor-mvu). winui-libwinui-navviewwinui Verifierat mot det installerade paketet vid körning. kör winapp new --list för att se alla. Standard: winui (tom XAML-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:

Paketet innehåller två format för WinUI-appen. XAML-mallar definierar användargränssnittet i markering med en C#-kod bakom. Reaktormallar är rena C# utan XAML, med hjälp av ett MVU-mönster (modell-View-Update). 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:

Kort namn	Beskrivning
`winui`	Minimal tom XAML-app (MSIX-paketering)
`winui-navview`	XAML NavigationView-startapp
`winui-tabview`	XAML TabView-startapp
`winui-mvvm`	XAML MVVM-app (CommunityToolkit.Mvvm)
`winui-lib`	WinUI 3-klassbibliotek
`winui-unittest`	Paketerad MSTest-app; tester körs när den startas
`reactor`	Experimentell. Tom reaktorapp – ren C#, ingen XAML
`reactor-mvu`	Experimentell. Reaktorapp som demonstrerar MVU-mönstret
`reactor-navview`	Experimentell. ReaktornavigeringView-startapp
`reactor-tabview`	Experimentell. Startapp för Reactor TabView

Reaktormallar är experimentella. De refererar till förhandsversionspaketen Microsoft.UI.Reactor , vars API:er kan ändras eller tas bort i en framtida version. winapp new markerar dem (Experimentell) i --list och i den interaktiva väljaren, anger "Experimental": true i --jsonoch skriver ut en varning efter att ha skapat en byggnadsställning. De väljs aldrig som standardmall. Reaktorn kräver också .NET 10 SDK eller senare. På en äldre SDK winapp new misslyckas i förväg med den version som behövs i stället för att skapa ett projekt som du inte kan bygga.

Varje malls kanoniska kortnamn är de första aliaslistorna dotnet new för den. Alla listade alias (t.ex. winui3, wasdk-single, winui-reactor) 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.

En första körning kan ta längre tid: Installation eller uppdatering av mallpaketet eller återställning av saknade Windows App SDK NuGet-paket som används av den valda mallen kan kräva ytterligare nedladdningar. Detta kan också inträffa när en ny Windows App SDK version har publicerats. Om scaffolding fortfarande körs efter 10 sekunder winapp new uppdaterar dess statusmeddelande för att indikera att paket kan laddas ned eller återställas.

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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

återställ

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

winapp restore [base-directory] [options]

Argument:

base-directory – Katalog att återställa (standard: aktuell katalog). Väljer också var winapp.yaml och nuget.config läss från om det inte --config-dir åsidosätter det.

Alternativ:

--config-dir <path> – Katalog som innehåller winapp.yaml (standard: base-directory)

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 finns det inget winapp.yaml – SDK-versionerna live som PackageReference poster i .csproj – så winapp restore körs dotnet restore åt dig.

Exempel:

# Restore from winapp.yaml in current directory
winapp restore

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

Anpassade och privata NuGet-feeds:

winapp init, restore, och update ladda ned Windows SDK och Windows App SDK paket via NuGet, vilket respekterar din standardhierarkinuget.config. Privata feeds och speglar, autentiseringsuppgifter för feed (inklusive leverantörer av autentiseringsuppgifter) och ett anpassat globalPackagesFolder allt arbete som de gör för dotnet restore. Om du vill återställa exklusivt från din egen spegel, <clear /> de ärvda källorna och lägga till bara din:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

Anmärkning

För interna projekt löses nuget.config winapp från katalogen som den fungerar på: katalogargumentetrestoreinit/, --config-dir när det anges, annars den aktuella katalogen. För .NET projekt kommer källorna från projektets egen nuget.config hierarki i stället, eftersom det är vad dotnet add package och dotnet restore använder, så placera en privat feeds konfiguration i projektkatalogen eller en överordnad. En --config-dir utanför hierarkin rapporteras och ignoreras i stället för att tyst välja versioner som projektet inte kan återställa. Kör dessa kommandon endast mot kataloger som du litar på, samma försiktighet som gäller för dotnet restore. När flera källor har konfigurerats använder du Paketkällamappning för att fästa varje paket i en feed.

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 ett projekt eller 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 en enda .csproj för att skapa projektet och paketera utdata i ett steg (projektläge, se Paketera ett projekt direkt nedan). 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 enda .csproj för att skapa och paketera (projektläge) eller 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
--no-sign – Leverera paketet osignerat och åsidosätter alla projektsigneringskonfigurationer (t.ex. för lagringsöverföring eller en extern signeringspipeline). Det går inte att kombinera med --cert eller --generate-cert.
--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.

Project-lägesalternativ (kräver indata.csproj, avvisas för mapp-/paket-/manifestindata):

--configuration <name> (-c) – Skapa konfiguration (standard: Release)
--arch <arch> – Målarkitektur: x64, arm64eller x86 (standard: den aktuella processarkitekturen)
--framework <tfm> (-f) – Målramverksmoniker för projekt med flera mål
--no-build – Paketera befintliga byggutdata utan att återskapa
--no-restore – Hoppa över att återställa projektet innan du skapar
--property <name=value> (-p) – MSBuild-egenskap, vidarebefordrad till bygge och utvärdering (repeterbar)

Obs! För ett WinUI/ EnableMsixTooling.csproj (MSIX-verktygsprojektläge) äger Windows App SDK manifestet, startpunkten och PRI-genereringen, så --manifest, --executableoch --skip-pri avvisas – konfigurerar <AppxManifest>, projektets startpunkt och dess resursversion i själva projektet. Dessa tre alternativ gäller fortfarande för mappindata och för generiskt (icke-MSIX-verktyg) .csproj projektläge.

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

Paketera ett projekt direkt

När indata är en enda .csprojskapar winapp pack du projektet (med hjälp av alternativen ovan) och paketerar de resulterande utdata – du behöver inte skapa separat eller leta upp utdatamappen först. Detta speglar winapp runprojektläget.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Målarkitekturen kommer från --arch, eller från en ensam -p RuntimeIdentifier=<rid> när du inte passerar --arch (den exakta RID bevaras och driver bygget). Att skicka både --arch och -p RuntimeIdentifier är en konflikt och avvisas.

Projektet måste byggas som en paketerad app (EnableMsixTooling=true med ett Package.appxmanifest); ett projekt som skapas som en uppackad app (WindowsPackageType=None) har inget MSIX-manifest för att paketera och winapp pack rapporterar ett åtgärdsfel. Mapp-, paket- och sparse-manifestindata är oförändrade.

Project läget genererar en enda .msix eller endast .msixbundle arkitektur (se Paket med flera arkitekturer). Den producerar inte Arkivuppladdningsarkiv eller resursdelningspaket (språk/skala): en explicit -p UapAppxPackageBuildMode=StoreUpload eller -p AppxBundleAutoResourcePackageQualifiers=... avvisas med en anteckning om att köra det interna SDK-paketeringskommandot direkt för dessa flöden.

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 :

Om --executable anges (sökväg i förhållande till indatamappen) ersätts platshållaren med det angivna värdet
Annars winapp pack söker indatamappens rot efter .exe filer – om exakt en hittas används den automatiskt
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:

--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.
Manifest per mapp – Om varje indatamapp innehåller ett Package.appxmanifest (eller appxmanifest.xml) används den mappens manifest för dess sektor.
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 ett X.500 DN med envärdeskomponenter med kommaavgränsade komponenter (multivärdes-RDN + och omvänt snedstreck stöds inte); tomma 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.

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. Filen måste deklarera sin egen storlek, antingen via ett viewBox eller absolut width och height attribut. En procentbredd utan viewBox beskriver ingen särskild storlek. En källa som deklarerar ingetdera avvisas med SVG image has no usable dimensions i stället för att producera tomma tillgångar.

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 tre 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.
Enfilsläge – indata är en .cs.NET filbaserad app. winapp run bygger det, genererar ett manifest från sina #:property direktiv och startar det med paketidentitet.

Tips/Råd

Lägesmarkeringen är tyst som standard. Om en katalog behandlades som en build-output-mapp när du förväntade dig att den skulle skapas som ett projekt, kör du igen med --verbose – mappläget rapporterar varför den valdes (No .csproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). En katalog skapas bara som ett projekt när en .csproj/.slnx/.slnmed en runnable-app finns på den översta nivån. Den söks inte rekursivt.

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), en .cs .NET filbaserad app (enfilslä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 den lösa layouten (standard: AppX i indatamappen). Standardlayouten tar bort filer som inte längre finns i versionen. en anpassad katalog behåller extra filer. Använd en ny anpassad katalog när du behöver en ren layout.
--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. Sällan behövs: en app med OutputType=Exe redan startar på det här sättet som standard. winapp lägger till det som krävs uap5:ExecutionAlias i manifestet i AppX-layouten, så ingen ändring av ditt incheckade manifest behövs. Ett alias som appen deklarerar används as-is. Det går inte att kombinera med --no-launch, --detach, --without-aliaseller --json.
--without-alias – Framtvinga AUMID-aktivering för en app som annars skulle starta via ett körningsalias. En konsolapp körs sedan utan en konsol och skriver ut ingenting till den här terminalen. Det går inte att kombinera med --with-alias.
--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. Lokala körningar skriver ut PID; målkörningar skriver ut det begränsade användargränssnittsmålet. JSON innehåller PID och målomfånget. 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.
--on <target> – Skapa på värden och registrera och kör sedan i målet. sandboxStöder för närvarande , utan återställning till lokal körning. Använd --detach före uppföljande gränssnittskommandon. Sandbox-miljön --debug-output kräver en paketerad app. Se Windows Sandbox-körning för installation, körningsstöd och livslängd för fristående appar.

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

Intern AOT: Lägg till den här egenskapsgruppen i project-filens <Project> element och lägg sedan till --aot:

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

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

--aot stöder x64- och ARM64-projekt. Den körs dotnet publish med projektets AOT-konfiguration och startar sedan utdata. Använd -p PublishAot=true för en åsidosättning en gång. Den utför inte separat körningscertifiering och kan inte kombineras med --no-build eller --manifest.

För appar som använder paketidentitet utan en genererad MSIX-layout ska du inkludera Package.appxmanifest eller appxmanifest.xml i projektets publiceringsutdata. Winapp gör de publicerade filerna stegvisa med det manifestet. Om båda namnen finns stoppas winapp i stället för att välja ett. ta bort det inaktuella manifestet och konfigurera projektet att endast publicera det avsedda manifestet.

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

-c, --configuration <name> – Skapa konfiguration. Standardvärde: Debug. (Respekteras också i enfilsläge.)
--arch <x64|arm64|x86> – Målarkitektur. Standard: den aktuella processarkitekturen. Avgör build RID- och Windows App Runtime-arkitekturen och väljer en matchande plattformsberoende publiceringsprofil när det krävs av den effektiva versionen. (Respekteras också i enfilsläge.)
-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). Arkitekturen åsidosätter --arch och kan välja den publiceringsprofil som krävs. (Respekteras även i enfilsläge, där det åsidosätter en #:property RuntimeIdentifier deklarerad av filen.)
-f, --framework <tfm> – Målramverksmoniker för projekt med flera mål (t.ex. net10.0-windows10.0.26100.0). (Avvisades i enfilsläge – använd #:property TargetFramework=....)
--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). (Avvisad i enfilsläge – en .cs filbaserad app är i sig projektet.)
--no-build – Hoppa över att skapa och köra befintliga byggutdata (utvärderar fortfarande utdataegenskaper). (Respekteras också i enfilsläge.)
--no-restore – Hoppa över återställning innan du skapar eller intern AOT-publicering. (Respekteras också i enfilsläge.)
--aot– Kör projektets konfigurerade .NET intern AOT-publicering. Kräver effektiv PublishAot=true. Avvisades i mapp- och enfilslägen.
-p, --property <Name=Value> – MSBuild-egenskapen vidarebefordras till både bygget och egenskapsutvärderingen. Upprepa -p för flera egenskaper. Använd %3B eller %2C för ett literal semikolon eller kommatecken i ett värde. (Respekteras också i enfilsläge, där det är det enda sättet att ange TargetFramework.)

Skapa utdata och utförlighet: en vanlig projektkörning använder dotnet buildoch utvärderar sedan de inbyggda utdata. Återställ och skapa utdataström live, med autentiseringsuppgifter från autentiserade feed-URL:er redigerade. Med --aotanvänder dotnet publishwinapp ; --verbose publiceringskommandot och lösta sökvägar. Använd verbositetsalternativen nedan för att styra vad som visas:

Flagga	dotnet verbosity	Lägger till
(standard)	`minimal`	—
`--verbose`	`minimal`	winapps byggbeslutsspårningar
`--quiet`	`quiet`	—

Intern AOT publicerar utdataströmmar när de tas emot, inklusive MSBuilds slutliga egenskap JSON. Under --jsongår återställnings-/bygganrop och underordnade utdata till stderr så stdout förblir ren JSON. Under --quietutelämnas anrop och dotnets tysta återställnings-/byggutdata dirigeras till stderr så att stdout förblir ren. Interna AOT-publiceringsutdata går också till stderr under något av alternativen.

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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

# Force an unpackaged run of a packaged project
winapp run . -p WindowsPackageType=None

# Run the existing build output without rebuilding, and capture crash diagnostics
winapp run . --no-build --debug-output

# Show winapp's build decision traces (dotnet build stays at minimal verbosity)
winapp run . --verbose

# Launch and detach (prints PID), forwarding args to the app
winapp run . --detach -- --my-flag value

Enfilsläge (.NET filbaserade appar)

.NET 10 kan du köra en enda .cs fil utan projektfil och konfigurera den med #: direktiv överst. Peka winapp run på filen och den skapar appen, genererar en appxmanifest för den och startar den med paketidentitet – så Windows.ApplicationModel.Package.Current fungerar, appen får en riktig AUMID och en Start-menypost och API:erna som helt enkelt kräver identitet (appmeddelanden, ApplicationData, AI på enheten) fungerar.

Shell-integreringar som protokollhanterare, filassociationer, resursmål och startuppgifter behöver en deklarerad <Extensions> post som det genererade manifestet inte innehåller. Om du vill lägga till ett kan du skapa ett eget manifest – se Ta med ditt eget manifest nedan.

winapp run counter.cs

Eller kör den med klartext dotnet run – se Köra med dotnet run nedan.

Du skapar inte något manifest. Beskriv paketet med #:property direktiv i stället:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Manifestegenskaper. Alla är valfria. varje faller tillbaka till en förnuftig standard:

Property	Uppsättningar	Standardinställning
`WinAppPackageName`	`Identity/@Name` (paketidentiteten)	filnamnet, som är sanerat till `[-.A-Za-z0-9]`, plus en kort hash av filens sökväg (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	Namnet som visas i Start och Inställningar	filnamnet utan dess tillägg
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Ett namn utan namn omsluts som `CN=<name>`.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, normaliserad (se nedan)
`WinAppDescription`	Beskrivningen som visas under installationen och i Inställningar	visningsnamnet
`WinAppCapabilities`	Funktioner att deklarera, avgränsade med `;` eller `,`	inget

Version. En paketversion måste vara exakt fyra siffror, var och en 0–65535. WinAppVersion (eller, om du inte anger den, normaliseras standardegenskapen Version ) så att den passar: -preview/-rc suffixet tas bort och saknade komponenter fylls med nollor, så #:property Version=1.2.3-preview.4 blir 1.2.3.0 och ställer in sammansättningsversionen och paketversionen tillsammans. Ett värde som inte kan anpassas – en komponent över 65535 eller fler än fyra komponenter – avvisas med ett fel i stället för att tyst ändras.

Capabilities

Din app kör fullständigt förtroende med identitet, vilket uppfyller API:er som bara kräver en paketerad app. Men vissa API:er är inhägnade på en deklarerad funktion oavsett – Windows AI-API:er är vanliga. (Shell-integreringar som protokollhanterare och filassociationer är ett tredje fall: de behöver författade <Extensions> poster, inte en funktion, så använd ditt eget manifest för dem.)

#:property WinAppCapabilities=systemAIModels

Det är allt Phi Silica och de andra API:erna för enhetsmodellen som behövs från manifestet. Deklarera flera genom att separera dem:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp skriver var och en till elementet och XML-namnområdet som krävs, deklarerar det namnområdet och genererar MaxVersionTested när funktionen behöver en nyare. Detta är viktigare än det låter: funktionerna är spridda över flera olika element och samma lista ovan blir tre olika former –

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

Namn som winapp vet är skrivna åt dig. För allt annat – den begränsade uppsättningen växer över tid – kvalificerar du den själv med namnområdesprefixet:

Prefix	Genererar
`rescap:`	`<rescap:Capability>` — begränsade funktioner
`uap:`, `uap6:`, , `uap7:uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` i standardnamnområdet

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Ett okänt namn utan namn avvisas med ett fel som namnger dessa prefix, i stället för att gissas på – en funktion som genereras i fel namnområde genererar ett manifest Windows antingen vägrar att registrera eller accepterar utan att bevilja det.

Bring your own manifest

Om du behöver något som egenskaperna inte omfattar – en protokollhanterare, en filassociation, ett körningsalias – skapar ett manifest och winapp run använder det ordagrant i stället för att generera ett. Den hämtas från, i ordning:

--manifest <path> på kommandoraden.
#:property WinAppManifestPath=<path> .cs i filen.
Ett manifest som sitter bredvid .cs filen med namnet <filename>.appxmanifest (till exempel counter.appxmanifest bredvid counter.cs).

Endast namnet per fil hämtas automatiskt. En Package.appxmanifest eller appxmanifest.xml i samma mapp ignoreras avsiktligt – flera .cs filer kan dela en mapp, och om du använder ett delat namn körs en app tyst under en annans identitet. Om du vill använda ett manifest för flera filer namnger du det explicit med --manifest eller WinAppManifestPath.

Annars genereras en Package.appxmanifest i byggutdata, tillsammans med standardvärdet för avbildningstillgångar, och uppdateras vid varje körning.

Options. Varje mapplägesalternativ fungerar: , , , , , , , --symbols, --unregister-on-exit--args/--, --json, , --executable, --manifest, , --output-appx-directory, plus -c/--configuration, --no-build, --no-restoreoch .-p/--property--debug-output--clean--detach--without-alias--with-alias--no-launch

Tips/Råd

En konsolapp skriver ut till terminalen som standard. En paketerad app som startas via AUMID har ingen konsol, så en konsolbaserad app skulle köras korrekt och skriva ut ingenting. winapp undviker det: en app med OutputType=Exe startas via ett körningsalias i stället, vilket ärver den här terminalens stdin/stdout/stderr. Du får fortfarande paketidentitet och du behöver inte be om den:

winapp run counter.cs

Skicka --without-alias för att framtvinga AUMID-aktivering i stället – appen körs sedan utan konsol och skriver ut ingenting här. En fönsterapp (WinExe) visar ett fönster, så den behåller AUMID-aktivering. Skicka --with-alias om du vill ha en i den här terminalen ändå. Om du vill åtgärda valet i filen i stället för på varje kommandorad anger du samma egenskap som används .csproj :

#:property WinAppRunUseExecutionAlias=false

Aliaset winapp deklarerar har fått namnet efter paketfamiljenamnet med ett winapp- prefix – så com.contoso.counter publicerat av CN=You hämtar winapp-com.contoso.counter_gspb8g6x97k2t.exe. Den avslutande delen är den utgivarshash som Windows härleder, så två appar som delar ett namn under olika utgivare får fortfarande olika alias. Prefixet håller namnet fritt från riktiga kommandon: en app i python.cs hämtar ett winapp-… alias, aldrig python.exe. Om du skapar ett eget manifest används aliaset som du deklarerar där as-is och winapp lägger inte till något.

Det gäller endast aliaset. Själva registreringen är keyed på paketnamnet, så att köra en andra app som deklarerar samma WinAppPackageName under en annan utgivare ersätter den första registreringen i stället för att sitta bredvid den. Ge varje app sitt eget namn om du vill att båda ska registreras samtidigt.

winapp run skriver ut aliaset som registrerats, så du behöver inte beräkna hashen för att hitta den.

Aliaset är ett kommando på din PATH som varar så länge paketet förblir registrerat. Om något annat paket redan äger namnet säger winapp det. När aliaset för dig härleds startas det via AUMID i stället för att starta fel app. när du bad om en explicit – med --with-alias eller #:property WinAppRunUseExecutionAlias=true – misslyckas den i stället för att tyst göra något annat.

Två projektlägesalternativ gäller inte eftersom en filbaserad app konfigurerar sig själv. De avvisas med ett meddelande som namnger direktivet som ska användas i stället:

Option	Använd i stället
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	ingenting – `.cs` filen är projektet

--arch och -r/--runtime fungerar som de gör i projektläge. När du inte klarar något av detta skapar winapp för datorns arkitektur – vilket är vad en fristående Windows App SDK app behöver, eftersom SDK:t utan den bygger AnyCPU och misslyckas med WindowsAppSDKSelfContained requires a supported Windows architecture. A #:property RuntimeIdentifier=win-arm64 i filen respekteras, en explicit --arch/--runtime åsidosätter den.

Paketerade och uppackade båda arbete, identifieras från den effektiva WindowsPackageType precis som i projektläge: standard registrerar en lös layout och startar den med identitet, medan #:property WindowsPackageType=None bygger appen, installerar matchande Windows App Runtime och startar .exe direkt. (En paketerad app startas via dess körningsalias eller via AUMID-aktivering – se konsolen ovan. Det valet är skilt från om det är paketerat.) Identitetsalternativen (--no-launch, , --with-alias--without-alias, --clean, --unregister-on-exit, , --manifest) --output-appx-directorygäller endast för paketerade appar.

Körs med `dotnet run`

Du behöver inte skriva winapp alls. Referens till Microsoft.Windows.SDK.BuildTools.WinApp paketet från filen och plain dotnet run ger dig samma paketerade start:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Paketets MSBuild-mål omdirigerar körningen till winapp, som paket, registrerar och startar appen som dotnet run just har skapats – den återskapas inte. Manifesthanteringen är oförändrad: winapp löser det precis som för winapp run, så #:property WinAppManifestPath=… och bredvid <filename>.appxmanifest.cs är båda är hedrade (se Bring your own manifest), en katalogomfattande Package.appxmanifest ignoreras fortfarande och annars genereras en från dina #:property direktiv och uppdateras varje körning.

Två villkor måste vara uppfyllda för att omdirigeringen ska ske:

Directive	Varför
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	målen som gör omdirigeringsskeppet i det här paketet
`#:property TargetFramework=net10.0-windows…`	en vanlig `net10.0` fil lämnas ensam, så den körs uppackad

Att lägga till #:property WindowsPackageType=None lämnar också filen ensam: dotnet run kör .exe sedan direkt, utan identitet. Använd winapp run för den uppackade sökvägen om du vill att matchande Windows App Runtime ska installeras först.

Ställ in #:property EnableWinAppRunSupport=false om du vill välja bort omdirigeringen helt och de WinAppRun* egenskaper som beskrivs under Konfiguration för att forma starten, till exempel:

#:property WinAppRunUnregisterOnExit=true

Om dotnet run appen packas upp när du förväntade dig en identitet frågar du MSBuild varför. Använd dotnet build, inte dotnet msbuild – syntetiserar bara dotnet build det virtuella projekt som en filbaserad app kompileras via:

dotnet build counter.cs -t:WinAppRunSupportInfo

Enfilsläge kräver .NET SDK 10.0.300 eller senare.

Registreringen överlever körningen. winapp run counter.cs lämnar paketet registrerat efter att appen har avslutats, precis som mapp- och projektläge , så LocalState överlever och om du kör samma fil igen återanvänds samma identitet i stället för att samla in registreringar. winapp säger så första gången den registrerar en app och winapp unregister tar .cs sig själv:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs behöver ingen manifestsökväg: den utvärderar filens #:property värden på samma sätt run och tar bara bort ett paket som registrerats från den filens build-utdata. En app med samma namn som registrerats från en annan mapp nekas om du inte skickar --force. Om körningen använde ett alternativ som formar identiteten eller layouten skickar du samma till unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-påsidosätter filens egna direktiv och en bredvid can-tangenten .csWinAppPackageName av $(Configuration) eller $(RuntimeIdentifier) – så att var och en Directory.Build.props av dessa kan ändra vilket paket som registreras.

När SDK:ns temporära utdata har rensats winapp unregister counter.cs kan du inte längre bekräfta att registreringen kom från filen och hoppar över den – använd winapp unregister --prune för att rensa registreringar vars filer är borta eller --force för att ta bort en specifik ändå. Om körningen används --output-appx-directoryskickar du samma katalog till så att unregister den kan identifiera layouten.

Samma sak gäller för en anpassad utdatasökväg: ägarskapet bekräftas från SDK:s standardlayout <root>\bin\<configuration> , så en körning som skapats med -p OutputPath=<somewhere-else> kan inte matchas med källfilen. unregister hoppar över den i stället för att gissa på en bredare katalog – namnge layouten med --output-appx-directoryeller använd --force.

Exempel med en fil:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

Anmärkning

Standardidentiteten innehåller en kort hash av filens sökväg – counter.cs blir ungefär som counter-a1b2c3d4 – så två counter.cs filer i olika mappar är olika appar och behåller sina egna inställningar och LocalState. Hashen härleds från sökvägen, så den överlever redigeringar och omkörningar och ändras bara om du flyttar filen. Ställ in #:property WinAppPackageName=<name> för att välja en stabil identitet själv. Den normaliseras till vad som Identity/@Name tillåter – tecken utanför [-.A-Za-z0-9] tas bort, namn som är kortare än 3 tecken är vadderade med 1och resultatet begränsas till 50 tecken, så My App registreras som MyApp. Hur som helst visar Start-menyn och Inställningar din WinAppDisplayName (standard: filnamnet), inte identiteten. Identiteten är alltid begränsad till ditt användarkonto, så den kolliderar aldrig med en annan användare på samma dator.

MSBuild-egenskaper (NuGet-paket):

När du använder nuget-paketet Microsoft.Windows.SDK.BuildTools.WinApp anropar dotnet run automatiskt winapp run.

Allt som skrivits efter dotnet run skickas till ditt program, precis som det skulle vara utan paketet. Konfigurera startprogrammet med MSBuild-egenskaperna nedan:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

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`	härleds från appen	Starta via körningsalias i stället för AUMID-aktivering. Winapp härleder det från vänster: en konsolapp använder ett alias så att dess utdata når terminalen, en fönsterapp använder AUMID. Ställ in `true` eller `false` bestäm själv.
`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.
`WinAppRunDetach`	`false`	Returnera omedelbart efter start i stället för att vänta på att appen ska avslutas. Skriver ut PID:en.
`WinAppRunUnregisterOnExit`	`false`	Avregistrera utvecklingspaketet när appen har avslutats
`WinAppRunClean`	`false`	Ta bort det befintliga paketets programdata (LocalState, inställningar) innan du distribuerar om
`WinAppRunSymbols`	`false`	Ladda ned symboler från Microsoft Symbol Server för rikare intern kraschanalys. Endast har en effekt med `WinAppRunDebugOutput`.
`WinAppRunExecutable`	(tom)	Körbar sökväg i förhållande till mappen build-output. Använd när manifestet innehåller $targetnametoken$ och utdatamappen har mer än en `.exe`.
`WinAppRunArgs`	(tom)	Raw-argument som läggs till på kommandoraden `winapp run` för alternativ utan dedikerad egenskap (till exempel `--verbose`). Läggs till efter varje egenskap ovan.

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

Property	Det går inte att kombinera med
`WinAppRunNoLaunch`	`WinAppRunDetach`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias avsiktligt inte finns med i denna lista, i någon riktning. false Parlamentet begär AUMID-aktivering, som inte startar och kopplar från redan används. true tillämpas helt enkelt inte när någon av dem har angetts, eftersom ett körningsalias behöver en spårad, pågående process. Så ett projekt som checkar in <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> körs fortfarande rent under dotnet run -p:WinAppRunDetach=true, starta via AUMID i stället för att misslyckas.

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

Argument:

input– Sökväg till en .NET filbaserad app (en enda .cs) vars paket ska avregistreras. Identiteten löses på samma sätt winapp run som den löses – från ett redigeringsmanifest om appen har en, annars från dess #:property värden – så ingen manifestsökväg behövs. Utelämna att använda --manifest eller identifiera ett manifest automatiskt i den aktuella katalogen. Det går inte att kombinera med --manifest, som namnger paketet på ett annat sätt och kan matcha till ett annat.

Alternativ:

--manifest <path> – Sökväg till Package.appxmanifest (standard: automatisk identifiering från aktuell katalog)
--force – För endast lokal avregistrering hoppar du över katalogkontrollen install-location och avregistrerar även om paketet har registrerats från ett annat projektträd. Den avvisas med --on. Kontrollen av målägarskap kan inte kringgås.
--on <target> – Ta bort matchande winapp-ägd utvecklingsregistrering från sandbox, inte den här datorn. Kräver ett manifest och stöder --forceinte . Mer information finns i rensning av sandbox-appar.
--prune – Ta bort alla registreringar i utvecklingsläge vars filer är borta. Det går inte att kombinera med indata, --manifest, --property, --configuration, --arch, --runtimeeller --output-appx-directory.
-p, --property <Name=Value> – MSBuild-egenskapen som används vid matchning av en .cs filbaserad appidentitet. Repeterbar. Skicka samma identitetspåverkande egenskaper som körningen använde (t.ex. -p WinAppPackageName=...), eftersom en kommandoradsegenskap åsidosätter filens egna #:property direktiv. Gäller endast för indata .cs .
-c, --configuration <name> – Skapa konfiguration som används vid matchning av en .cs filbaserad appidentitet. Standardvärde: Debug. Skicka samma konfiguration som den körning som används: en Directory.Build.props bredvid .cs kan ange WinAppPackageName eller WinAppManifestPath villkorligt på $(Configuration). Gäller endast för indata .cs .
--arch <x64|arm64|x86> – Målarkitektur som används vid matchning av en .cs filbaserad appidentitet. Standard: den aktuella processarkitekturen. Skicka samma arkitektur som den körning som används, eftersom identiteten också kan stängas av $(RuntimeIdentifier). Gäller endast för indata .cs .
-r, --runtime <rid>– Mål-.NET körningsidentifierare (t.ex. win-x64) som används vid matchning av en .cs filbaserad appidentitet. Endast dess arkitektur används och åsidosätter --arch. Gäller endast för indata .cs .
--output-appx-directory <path> – AppX-layoutkatalogen som paketet registrerades från. Behövs bara när körningen använde --output-appx-directory, eftersom ingenting på paketposterna som kör alternativet skapade layouten.
--json – Formatera utdata som JSON

Vad den gör:

Avgör paketnamnet – från .cs filens lösta identitet eller genom att läsa 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 paketet tillhör den app som du namngav (om inte --force) – dess installationsplats måste finnas under en katalog som du har identifierat: .cs filens egna build-utdata, manifestets katalog, den aktuella katalogen eller en explicit --output-appx-directory. Ett paket vars installationsplats inte kan matchas (filerna har tagits bort) hoppas över eftersom enbart identitet inte är ett ägarbevis: två appar som båda anger #:property WinAppPackageName=counter registrerar samma identitet från olika mappar. Använd --prune för att rensa registreringar vars filer är borta.
Avregistrerar matchande paket

Rensa upp döda registreringar (--prune):

En registrering överlever sina filer. Ta bort ett byggutdata, projektträd eller (för en filbaserad app) låt Windows rensa %LOCALAPPDATA%\Temp, och paketet förblir registrerat: Windows behåller identiteten och dess Start-menypost, men aktivering gör ingenting. Dessa ackumuleras osynligt.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Endast registreringar i utvecklingsläge beaktas och var och en tas bort med sitt fullständiga paketnamn, så ett paket med samma namn som fortfarande är installerat från en liveplats är orört. Uppmaningen finns eftersom en saknad installationsplats vanligtvis är en borttagen mapp men även beskriver ett paket som registrerats från en frånkopplad nätverksresurs eller flyttbar enhet – granska listan innan du bekräftar det.

Exempel:

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

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

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

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

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

cert

Generera, inspektera och installera utvecklingscertifikat.

certifikat generera

Generera utvecklingscertifikat för paketsignering.

winapp cert generate [options]

Alternativ:

--manifest <Package.appxmanifest>– Extrahera certifikatet publisher från manifestets Identity/@Publisher. Endast utgivaren krävs, så ett delvis komplett manifest fungerar fortfarande. Om manifestet inte har någon användbar utgivare misslyckas kommandot i stället för att ersätta en standard, så certifikatet kan aldrig tyst matcha manifestet.
--publisher <name>- Publisher för certifikatet. När du genererar ett certifikat har det här alternativet företräde framför --manifest. Ett explicit tomt värde misslyckas i stället för att använda manifestutgivaren. 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>. Komponenterna måste vara envärdes- och kommaavgränsade. Multivärdes-RDN (CN=Foo+OU=Bar) och omvänt snedstreck stöds inte eftersom MSIX-manifestutgivaren inte kan representera dem. Ett felaktigt unikt namn (t.ex. CN= eller CN=A,,O=B) avvisas med ett avslut som inte är noll och ett fel som namnger problemet, i stället för att skapa ett certifikat som aldrig kan matcha manifestutgivaren.
--output <path> – Sökvägen för utdatacertifikatfilen (stöder absoluta och relativa sökvägar)
--password <password> – Certifikatlösenord (standard: password, som är offentligt känt – se JSON-utdata och säkerhet)
--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": "..."}).

JSON-utdata:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher är visningsnamnet och subjectName det fullständiga unika namnet som certifikatet utfärdades till. defaultPasswordIsPublic är alltid närvarande. När det är true.pfx , skyddas av ett lösenord som vem som helst kan gissa, så certifikatet får bara signera versioner som finns kvar på dina egna datorer – kontrollera det innan ett skript lämnar certifikatet till något annat. warnings samma avslöjande som text och utelämnas när det inte finns något att rapportera. publicCertificatePath visas endast med --export-cer.

cert info

Visa certifikatinformation från en PFX- eller CER-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 eller CER)

Alternativ:

--password <password> - Lösenord för PFX-filen, ignoreras för en offentlig CER (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> <cert-path> [options]

Argument:

file-path – Sökväg till MSIX-paket eller körbar fil att signera
cert-path – Sökväg till signeringscertifikatet (.pfx)

Alternativ:

--password <password> – Certifikatlösenord (standard: "lösenord")
--timestamp <url> – URL för RFC 3161-tidsstämpelserver

Exempel:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

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:

winapp manifest generate --template sparse — Skapa ett glest manifest med AllowExternalContent
winapp create-external-catalog ./bin – Generera kodintegritetskatalogen för appens körbara filer
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

Signaturverifiering

Byggverktyg laddas ned från NuGet och körs sedan, så winapp kontrollerar var och en för en giltig Microsoft Authenticode-signatur omedelbart innan den körs. Certifikatet måste namnge Microsoft Corporation som signeringsorganisation. Detta gäller för varje kommando som skalar ut till ett SDK-verktyg, inklusive tool, packageoch sign. Ett verktyg som misslyckas med kontrollen körs inte:

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

Ett fel här innebär att filen på disken inte är vad Microsoft publicerat – oftast en skadad eller partiell nedladdning. Ta bort paketet från NuGet-cachen och kör kommandot igen så att winapp laddar ned det igen.

winapp håller sedan verktyget öppet så länge det körs, så filen den kontrollerade är filen Windows läses in. Om verktyget inte kan hållas på plats körs det inte heller:

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

Stäng det som använder filen – en antivirusgenomsökning eller en öppen redigerare är den vanliga orsaken – och kör kommandot igen. Om verktyget är borta i stället för att användas tar du bort paketet från NuGet-cachen så att winapp laddar ned det igen.

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

mål

Kör kommandon, kopiera filer, inspektera tillstånd eller avbilda hela gästskrivbordet.

Varje verb tar sandbox som första argument. snapshotFörutom kan dessa kommandon förbereda eller starta sandbox-miljön. Se Windows Sandbox-körning för krav, behörigheter, livscykel och återställning.

target exec

Kör ett kommando som gästanvändare.

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

Argument efter -- att ha behållit sina gränser. Standardströmmar och gästprocessens slutkod vidarebefordras. Detta är inte en fullständig terminal. --json formaterar winapp-fel på stderr utan att ändra det underordnade kommandots stdout. Använd den strukturerade error.code för att skilja ett målfel från ett programs egen slutstatus.

En explicit grupperar WINAPP_UI_WORKFLOW_ID även gästgränssnittsanrop som görs av kommandot. Mer information finns i Samordning av sandbox-användargränssnitt.

push- och målhämtning för mål

Kopiera en fil eller katalog i den riktning som heter av verbet.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Målsökvägarna är relativa till målets hanterade arbetsyta. absoluta, rotade och UNC-målsökvägar avvisas. Ett filmål innehåller dess filnamn. Se Köra kommandon och kopiera filer för kataloglayout, länkhantering och körning av ett kopierat skript.

målögonblicksbild

Rapportberedskap, distributioner och gästfönster utan att starta en sandbox-miljö.

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

Den återansluter inte en klient eller reparerar inte en agent. Ingen sandbox-miljö som körs är ett lyckat resultat, inte ett fel. Mer information om hur du tolkar beredskaps- och process-ID:t finns i Inspektera sandbox-miljön .

målskärmbild

Avbilda gästskrivbordet med sin ursprungliga pixelstorlek som värd-PNG, utan en appväljare eller kantlinjer för värdfönster. --json rapporterar gästkoordinatens ursprung.

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

Använd ui screenshot --on sandbox -a <app> för ett appfönster i stället. Se Skärmbilder och inspelningar för klientkrav, fokusbegränsningar och utdatahantering.

målpost

Spela in gästskrivbordet till H.264 MP4. Värdvideo- och ramfiler kommer när inspelningen har slutförts. JSON och rammanifestet beskriver all skalning eller utfyllnad.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Använder alternativen varaktighet, ram, överskrivning och resultat för ui record, men samlar in skrivbordet i stället för en app. Föredrar en positiv --duration-sec för obevakad CLI-användning. NPM-hjälpen kräver durationSec. Se Sandbox-avbildning för partiella bevis och fel med avbildningsberedskap.

find-ui

Agent först. find-ui är främst byggt för AI-kodningsagenter – det gör att en agent kan hämta verklig, kompilera WinUI-markering från leveransgallerierna i stället för att uppfinna den, och --json gör varje resultat (och varje fel) maskinläsbart. Det fungerar lika bra skrivet för hand.

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]

Galleriet, Toolkit och Reactor corpora levereras i CLI, så find-ui fungerar utan nätverksåtkomst – inklusive vid en första körning i en agents sandbox-miljö eller bakom en företagsproxy som blockerar raw.githubusercontent.com. När GitHub kan nås uppdateras CLI från den och cachelagrar resultatet per användare under <global .winapp>/cache/find-ui; den inbyggda corpusen är bara en våning, aldrig ett tak. Cachelagrade data uppdateras högst var 24:e timme eller på begäran med --refresh.

Den inbyggda corpus hämtas från GitHub varje gång en stabil version skapas, och en uppdatering som misslyckas stoppar versionsversionen i stället för att i tysthet skicka äldre data – bagaren hämtar genom samma kodsökväg--refresh, så ett fel där innebär att liveuppdateringen också är bruten och är värd att undersöka innan leveransen. En version kan fortfarande klippas ut mot den tidigare incheckade corpusen, men bara som en explicit åsidosättning. När resultaten hanteras från den inbyggda kopian av gallery/toolkit/reactor corpora, find-ui står det så på stderr och --json utdata bär "corpus": "embedded" (andra värden: "network" för en ny hämtning, "cache" för den lokala cachen). En kärnbegäran – --source coreeller en --id uppsättning som är alla kärnmönster – rapporterar "embedded" också, eftersom de kuraterade kärnmönstren kompileras till CLI och aldrig hämtas. Den skriver inte ut något meddelande om inaktuellhet eftersom --refresh det inte går att ändra dem. Fältet rapporteras när resultaten har delgivits. Det corpus saknas bara när ingen corpus kunde läsas in alls.

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

Relaterat:find-ui söker i WinUI-exempel; använd find-api för att söka i API-ytan (typer, medlemmar, uppräkningar) en projektreferens och winapp ui search för att söka i en app som kör appens gränssnittsträd .

find-api

Agent först. find-api är främst byggt för AI-kodningsagenter – det motiverar genererad kod i API-ytan som ett projekt faktiskt refererar till i stället för modellens minne av det, och --json plus icke-noll-slutkoder på saknade symboler låter en agent gate codegen på svaret. Det fungerar lika bra skrivet för hand.

Sök efter och inspektera Windows/WinRT API-ytan (typer, medlemmar, uppräkningar, namnområden) som är tillgängliga för ett projekt, löst från dess refererade .winmd/.dll metadata. Det tomma formuläret söker; underverb detaljgranska i en specifik typ, namnrymd eller själva indexet.

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

Indexet skapas från projektets återställda NuGet/SDK-paket (via project.assets.json) vid första användningen och uppdateras automatiskt när projektet återställs. Den finns under den globala .winapp cachen (cache/find-api/) och delas mellan projekt. Återställ projektet först (winapp restore eller dotnet restore).

Varje matchning visas under dess namnområde med paketet som skickar det och en enradssammanfattning av vad den gör, så ett resultat kan användas utan ett andra members anrop:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Lägg till --verbose för att också skriva ut cachefilen på disken som säkerhetskopierar varje namnområde, vilket är användbart när du diagnostiserar ett inaktuellt eller oväntat index.

När du kör winapp find-api utan någon fråga skrivs en kort användningssammanfattning och avslutas 0 – det är en begäran om hjälp, inte en sökning som inte hittade något.

Scope. Varje svar kommer från exakt ett omfång som rapporteras som scope i --json och som en anteckning i textutdata:

project – projektet i den aktuella katalogen (eller --project / --project-dir). Omfattar Windows SDK, Windows App SDK och projektets egna NuGet-paket. Windows App SDK metadata är den version som projektet refererar till: om datorn har en nyare Windows App Runtime installerad, find-api varnar och utelämnar den i stället för att bekräfta typer som projektet inte kan kompilera mot.
sdk– den datoromfattande Windows SDK + Windows App SDK metadata, som används automatiskt när den aktuella katalogen inte innehåller något projekt och ingen lösning. Detta gör find-api det användbart för att utforska API:er innan något projekt finns och behöver ingen nätverksåtkomst. Det innehåller avsiktligt inte NuGet-paket från tredje part, så en typ från (till exempel) Community Toolkit finns inte i det här omfånget.

En fråga från en katalog utan projekt och ingen lösning besvaras alltid av omfånget sdk – aldrig efter vilket projekt som än indexeras i den delade cachen – så resultatet beror aldrig på orelaterat globalt tillstånd. Godkänn --project sdk för att uttryckligen välja SDK-omfånget inifrån ett projekt och winapp find-api refresh --project sdk återskapa det när du har installerat en ny Windows SDK.

Lösningskataloger. Från en katalog som innehåller en .sln/.slnx utan projektfil bredvid den svarar de projekt som lösningen skapar i stället för omfånget sdk – de indexeras på begäran, så deras NuGet-paket inkluderas. När lösningen skapar fler än ett indexerat projekt visar frågan dem och frågar efter dem i stället för --project <name> att välja ett.

Kommandon:

(bare)find-api "<query>" ["<query>"...] - Söktyp och medlemsnamn som faller tillbaka till deras dokumenterade sammanfattningar, grupperade efter namnområde
members <type> [<type>...] [--filter <text>] - Lista en typs egenskaper, händelser och metoder (deklarerade medlemmar med signaturer, ärvda medlemmar sammanfattade genom att deklarera typ)
check-property <type> <property> [<property>...] – Verifiera att egenskaperna finns på en typ (avslutar icke-noll om någon saknas). En skrivskyddad egenskap rapporteras med ⚠️ och "skrivskyddad, kan inte tilldelas" i stället för en vanlig ✅, så en egenskap som ActualWidth inte misstas för något du kan ange. Egenskapsnamn matchas skiftlägeskänsligt eftersom C# och XAML är: check-property Button background avslutar icke-noll och erbjuder Background som en nära matchning i stället för att rapportera ett namn som du inte kan skriva.
enums <type> [<type>...] [--filter <text>] – Lista ett uppräkningsvärden (avslutar icke-noll när typen inte är en uppräkning)
packages – Lista de indexerade metadatapaketen med antal per pakettyp/medlem
stats – Visa sammanställd indexstatistik (paket, namnområden, typer, medlemmar, .winmd filer)
refresh [--scan] – Återskapa indexet för ett projekt (--scan indexerar varje projekt under katalogen). Med --project <name>misslyckas ett namn som matchar inget enskilt indexerat projekt i stället för att indexera den aktuella katalogen.

Batching.search, members, enumsoch check-property accepterar flera ämnen i ett anrop. För en AI-agent är detta den enskilt största kostnadsspaken: marginalkostnaden för ett uppslag domineras av rundturen (varje samtal skickar hela konversationen igen), inte av nyttolastens storlek, så ett samtal som svarar på tio frågor är mycket billigare än tio samtal.

Ett enskilt ämne returnerar exakt den nyttolastform som den alltid har, i både text och --json.
Två eller flera ämnen returnerar ett kuvert – { "count": N, "results": [ ... ] } i --json, där varje element är den normala nyttolasten för en enskild person, check-property lägger till missingCount. Textutdata renderar varje ämne i sekvens under ett omfångshuvud.
check-property batches-egenskaper på en typ: det första argumentet är typen, varje argument efter att det är en egenskap. I batchläge skrivs en egenskap som finns ut en enda ✅ rad. Fullständig nära-miss-information skrivs bara ut för dem som inte gör det.
En batch avslutas 0 endast om varje ämne löstes och hittades – så en batch är fortfarande säker att gate codegen på.

Sökordning. En fråga som exakt matchar ett typnamn rangordnas före partiella matchningar, och när ett kort namn delas av flera namnområden visas endast exakt namnkollisioner som tvetydiga – en fråga som rapporterar den handfull namnområden som definierar den exakta typen i stället för varje namnområde som innehåller en symbol med NavigationView liknande namn. Tvetydighetslistan följer , och normala resultat skrivs --maxfortfarande ut under den.

Skriv namn.members, check-propertyoch enums acceptera ett kort namn (NavigationView) eller ett fullständigt kvalificerat namn (Microsoft.UI.Xaml.Controls.NavigationView). När ett kort namn delas av en modern Microsoft.* typ och dess äldre Windows.* UWP-tvillingMicrosoft.*, svarar typen – det är projektionen som en Windows App SDK app använder – och det lösta fullständigt kvalificerade namnet visas alltid. Alla andra kollisioner avslutar icke-noll och listar kandidaterna i stället för att gissa.

Metodsignaturer. En signatur skrivs ut på det sätt som du skriver anropet: en metod som du anropar på typen i stället för på en instans visas med static, och en bireferensparameter visas med nyckelordet som den faktiskt behöver – out, ineller ref. Så TryGetValue läser Boolean TryGetValue(String key, out String value), som kompileras som skrivet.

Alternativ:

--max <n> – Maximalt antal namnområdesgrupperade sökresultat (standard 5; endast sökning). Begränsar också tvetydighetslistan, så en kort fråga som kolliderar över många namnområden förblir läsbar.
--filter <text> – Begränsa en lista på members och enums: en skiftlägesokänslig delsträngsmatchning på medlems-/värdenamnet. Används bäst på typer med hundratals medlemmar. De flesta uppräkningar är tillräckligt små för att dumpa hela (även Symbol, den största i WinUI vid 197-värden), så att filtrera dem kostar vanligtvis mer än det sparar när du räknar in en andra gissning. Kör aldrig samma kommando igen med olika filtertext – dumpa en gång och läs det.
--all - På memberslistar du hela ytan: fullständiga signaturer för ärvda medlemmar, plus statiska beroendeegenskapsidentifierare och beskrivningar per medlem, som alla utelämnar en ofiltrerad lista (se Liststorlek nedan). --verbose innebär det. använd --all när du också vill --jsonha , som inte kan kombineras med --verbose.
--scan – Rekursivt identifiera och indexeras varje projekt under katalogen (refresh endast)
--project <name>– Project fråga (matchar .csproj/.vcxproj namnet) eller sdk att fråga det datoromfattande Windows SDK-omfånget
--project-dir <path>– Project katalog att fråga (standardinställningen är den aktuella katalogen). En sökväg som inte finns är ett fel – den besvaras aldrig tyst från omfånget sdk .
--json – Generera en maskinläsbar nyttolast på stdout (stöds av varje verb). Frågenyttolaster identifierar indexet som svarade via ( eller ), och (saknas för SDK-omfånget) – projektnamn är inte unika mellan kataloger, så projectDir är den tillförlitliga identiteten.projectDirprojectNamesdkprojectscope 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.

Exempel:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

När --filter används rapporterar utdata fortfarande den ofiltrerade summan (totalValuesellertotalEvents//totalPropertiestotalMethods i --json), så att en smal vy aldrig misstas för ett litet API. Ett filter som matchar ingenting avslutas 0 fortfarande och säger det explicit – det vill säga "ingenting matchade ditt filter", inte "ingen sådan typ".

Liststorlek. En ofiltrerad members lista är den enda dyra formen – members Button omfattar 288 medlemmar, varav 280 ärvs från 6 bastyper. Ett ofiltrerat anrop är en orienteringsfråga ("vad är den här typen, ungefär vad kan den göra?"), så den svarar på det och utelämnar de delar som ingenting skrivs från:

Ärvda medlemssignaturer – ärvda medlemmar grupperas efter deklareringstyp och listas endast efter namn, så formen på den ärvda ytan är fortfarande synlig utan 280 fullständiga signaturer.
Beroendeegenskapsidentifierare statiska (BackgroundProperty) – 28% av en typisk WinUI-kontrolls egenskaper. De finns för att skickas till GetValue/SetValue, inte tilldelas.
Beskrivningar per medlem – XML-doc-prosa, ungefär 16% av nyttolasten.
Fält som underförstås av omgivningen i --json: kind (underförstådd av den innehållande//methodseventsproperties matrisen), returnType (den inledande token för signature), och inherited när false (underförstådd av ).declaringType

Det som utelämnades rapporteras alltid (hiddenDependencyProperties, descriptionsOmitted, och en hint i --json; en "Utelämnad:"-rad i text), och summor beskriver fortfarande hela typen. Både --filter och --all ser hela ytan med fullständiga signaturer och beskrivningar, så members Button --filter BackgroundProperty hittar fortfarande identifieraren och members Button --filter Click returnerar Clickfortfarande ärvd signatur. Mätt på samples/winui-apptar members Button --json detta från 91 954 till 10 567 tecken (−88,5%) medan byte --filter--all är identiska.

Hur en fråga matchas. winapp find-api "language model" rangordningen LanguageModel ovan matchar vars ord är spridda över namnområden och medlemmar, inklusive utanför ett projekt när typen indexeras. Sökningen är lexikal, inte semantisk: den matchar hela identifierarord snarare än någon körning av bokstäver, så llm hittar IImageLLMAdapterSession men inte ScrollMode. När en fråga inte matchar något namn prövas den mot de dokumenterade sammanfattningarna av typer och medlemmar, vilket är vad som gör att du kan "random-access stream" hitta IRandomAccessStream. Beskrivningar rangordnas under varje namnmatchning och endast sammanfattningar av paketen som faktiskt skickas är sökbara – ett paket utan XML-dokumentation bidrar inte med någon beskrivningstext.

Projekt utan en MSBuild-projektfil. En Electron-app (eller någon annan icke-.NET app som drivs av winapp.yaml) har ingen .csproj och därför ingen project.assets.json. find-api indexerar det från skrivningen .winapp/winmds.lock.jsonwinapp restore , som registrerar samma sak: varje löst paket, dess version och de filer som .winmd det bidrar med. Ett sådant projekt namnges efter dess katalog och dess index blir inaktuellt när låsfilen skrivs om. En katalog som innehåller både en .csproj och en winapp.yaml indexeras från .csproj, vilket är den mer exakta beskrivningen av vad projektet kompilerar mot.

Negativa svar kvalificeras när indexet är ofullständigt. Om ett pakets metadata inte kunde läsas ser "ingen sådan typ" och "paketet har aldrig indexerats" identiskt – och agerar på den första när det verkligen är den andra genererar kod mot ett API som du fick höra inte finns. Så varje negativt svar, inklusive ett search som returnerar noll resultat, bär en anteckning om att indexet är partiellt och pekar på winapp find-api refresh. Positiva svar påverkas inte.

Generiska typnamn. Metadata lagrar generiska typer med ett arity-suffix (IAsyncOperation`1), vilket inte är hur någon skriver dem. members, enums, och check-property acceptera varje formulär: IAsyncOperation, IAsyncOperation<StorageFile>och IAsyncOperation`1 alla matchas till samma typ. Ett namn utan namn matchar alla ariteter. en angiven aritet (i någon av notationerna) måste matcha, så Holder<A, B> matchar inte en enskild parameter Holder<T>.

--json nyttolaster utelämnar diagnostik. Cachefilsökvägar visas endast under --verbose (matchande textutdata, där de redan var utförliga) och tomma förslagsmatriser utelämnas i stället för serialiseras som [].

Slutkoder:search utan träffar, check-property på en saknad egenskap och enums på en icke-uppräkningstyp avslutas alla icke-noll – gatekodgenerering och CI-kontroller på dem. Ett batchbegränsat anrop avslutar icke-noll om något ämne misslyckas. En skrivskyddad egenskap är inte ett fel – den finns, så check-property avslutar och flaggar 0 den i utdata (writable: false i --json). En init egenskap rapporterar writable: false av samma anledning: den kan anges i en objektinitierare och signaturen säger { get; init; }, men att tilldela den efteråt kompileras inte.

Relaterat:find-api svar "finns det här API:et och vad är dess medlemmar?"; använd find-ui för att hitta ett fungerande WinUI-exempel för en kontroll.

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

Anmärkning

Bindningar är endast npm – de kräver anrop via npx winapp ( @microsoft/winappcli npm-paketet); det fristående winget CLI visar dem inte. Kör winapp init interaktivt och välj eller använd winapp init . --use-defaults --add-js-bindingsinnan du använder det här kommandot för att återskapa bindningar. Om du redigerar winapp.yamlkör npx winapp restore du för att uppdatera Windows beroenden innan du återskapar.

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

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.

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

Arbetsflödesidentitet för användargränssnitt

winapp ui kommandon som kör det fysiska skrivbordet tar alltid samarbetssvängningar, så två arbetsflöden som körs samtidigt kan inte stjäla varandras fokus eller stänga varandras menyer. Skiljeförfarandet behöver inte konfigureras och kan inte stängas av.

Det som är valfritt är kontinuitet. Som standard är varje kommando en fristående enbild som släpper skrivbordet så snart det är klart. Om du vill behålla skrivbordet i flera kommandon ger du dem samma arbetsflödes-ID:

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

Använd samma värde för samarbetsprocesser (till exempel en inspelning och de klick som den ska samla in) och olika värden för oberoende arbetsflöden. Varje kommando utan ID är ett eget enskottsarbetsflöde, även när flera startas från ett gränssnitt, så värdar som startar ett nytt gränssnitt per kommando måste mata in samma explicita värde i var och en. Värdet är ogenomskinlig, behandlas aldrig som en autentiseringsuppgift och bevaras bara som en SHA-256-hash. Se UI Automation → Koordinera samtidiga arbetsflöden för användargränssnittet.

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 (flera fönster bildar en märkt sammansatt PNG; se avbildningsomfång)
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
yield – Släpp det aktuella arbetsflödets användargränssnittssväng; kräver WINAPP_UI_WORKFLOW_ID

Alternativ:

-a, --app <app> – Målapp (namn, titel eller PID)
-w, --window <hwnd> - Målfönster efter HWND (stabilt)
--on <target> – Kör valfritt ui verb i sandbox; namn, PID:er och fönsterhandtag refererar till gästen. Utdata levereras till värden. Se Automatisering av sandbox-användargränssnitt för konfiguration, arbetsflödessamordning och klientkrav.

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 evidence.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).
--overwrite – Ersätt befintliga inspelningsutdata när den nya tagningen har slutförts. befintliga utdata avvisas som standard. Tidigare rampaket behålls. Se Inspelning av utdataåterställning.
--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 följ arbetsflödet för skärmbildöverlägg för popup-stillbilder. Spåras i #646.

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

Feedback

Var den här sidan till hjälp?

Last updated on 2026-09-28

CLI-dokumentation och användning

Shell-slutförande

init

Ny

återställ

uppdatering

pack

Paketera ett projekt direkt

Glesa identitetspaket

WinRT-komponentidentifiering

Paket med flera arkitekturer

skapa-debug-identitet

embed-identity

manifestera

manifestet generera

Platshållare för manifest

manifesttillägg

manifest uppdatera-tillgångar

run

Project läge (.NET SDK-projekt)

Enfilsläge (.NET filbaserade appar)

Capabilities

Bring your own manifest

Körs med dotnet run

Avregistrera

cert

certifikat generera

cert info

installera certifikat

tecken

az-sign

create-external-catalog

verktyg

store

get-winapp-path

mål

target exec

push- och målhämtning för mål

målögonblicksbild

målskärmbild

målpost

find-ui

find-api

node generate-bindings

node create-addon

node add-electron-debug-identity

nod clear-electron-debug-identity

Globala alternativ

Global cachekatalog

Uppdatera kontroller

Arbetsflödesidentitet för användargränssnitt

Ui

ui-post

Feedback

Ytterligare resurser

Körs med `dotnet run`