CLI-documentatie en -gebruik

Versie

Druk de geïnstalleerde winapp-versie af met --version of de korte vorm -V:

winapp -V

Kleine letters -v is de korte vorm van --verbose opdrachten (bijvoorbeeld winapp restore -v).

Shell-voltooiing

Schakel tabvoltooiing in voor opdrachten, opties en waarden. Zie de handleiding voor voltooiing van Shell voor installatie-instructies.

# 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

Initialiseer een map met Windows SDK, Windows App SDK en vereiste assets voor moderne Windows-ontwikkeling.

winapp init [base-directory] [options]

Argumenten:

base-directory - Basis-/hoofdmap voor de app/werkruimte (standaard: huidige map)

Opties:

--config-dir <path> - Configuratie van map voor lezen/opslaan (standaard: de geselecteerde projectmap of huidige map als er geen project wordt gedetecteerd)
--setup-sdks - SDK-installatiemodus: 'stabiel' (standaard), 'preview', 'experimenteel' of 'geen' (sdk-installatie overslaan)
--ignore-config, --no-config - Gebruik geen configuratiebestand voor versiebeheer
--no-gitignore - .gitignore-bestand niet bijwerken
--use-defaults, --no-prompt - Niet vragen en standaard van alle prompts gebruiken
--config-only - Alleen bewerkingen van configuratiebestanden verwerken, pakketinstallatie overslaan
--exe <path> - Pad naar het uitvoerbare bestand van de toepassing. Vereist --sparse. Hiermee genereert u een manifest met alleen identiteiten voor de exe in plaats van een volledig pakket/SDK-installatie.
--sparse - Genereer een sparse-identiteitsmanifest (appxmanifest.xml) voor een bestaande desktop-exe. Slaat de installatie van SDK/pakket over. Te gebruiken met --exe.
--name <name> - Overschrijf de pakketnaam (alleen sparse; standaard: afgeleid van de exe)
--publisher <CN> - Overschrijf de uitgevers-CN (alleen sparse; standaard: afgeleid van de bedrijfsnaam van de exe)
--output-dir <path> - Map voor het schrijven van het sparse-manifest en Assets/ (alleen sparse; standaard: een sparse/ map in de huidige map)
--force - Een bestaande appxmanifest.xml in de doelmap overschrijven (alleen sparse). Zonder deze functie mislukt init in plaats van een bestaand manifest/assets te vervangen.
--add-js-bindings (alleen npm) - Toevoegen winapp.jsBindings aan package.json en JS-/TypeScript-bindingen genereren, zonder te vragen (niet compatibel met --setup-sdks none)

Wat het doet:

Hiermee maakt u winapp.yaml een configuratiebestand (alleen wanneer SDK-pakketten worden beheerd; overgeslagen met --setup-sdks none)
Windows SDK- en Windows App SDK-pakketten downloaden
Maakt gebruik van de nieuwste Windows App SDK release in het geselecteerde --setup-sdks kanaal. Als die release nog steeds wordt gepubliceerd en sommige pakketten nog niet beschikbaar zijn, gebruikt u init in plaats daarvan de vorige release en drukt u een opmerking af. Als u later naar de nieuwe release wilt gaan, voert u deze uit winapp updateof voor een .NET project. dotnet add package Microsoft.WindowsAppSDK --version <new version>
Hiermee worden C++/WinRT-headers en binaire bestanden gegenereerd
Maakt Package.appxmanifest
Hiermee stelt u buildhulpprogramma's in en activeert u de ontwikkelaarsmodus.
Werkt .gitignore bij om gegenereerde bestanden uit te sluiten
Slaat deelbare bestanden op in de globale cachemap
Genereert JS-bindingen voor Windows App SDK API's wanneer deze zijn ingeschakeld (alleen npm)

Automatische projectdetectie:

Wanneer init wordt uitgevoerd zonder een mapargument, voert het een breedte-eerste zoekopdracht van de huidige mapstructuur uit om compatibele projecten te vinden (maximaal 10). Ondersteunde projecttypen:

Tauri : tauri.conf.json één niveau onder de map gevonden
Electron , package.json met electron in afhankelijkheden of devDependencies
Flutter - pubspec.yaml in de hoofdmap van het project
.NET - .csproj in de hoofdmap van het project
Rust — Cargo.toml in de hoofdmap van het project
C++ - CMakeLists.txt in de hoofdmap van het project

De zoekactie slaat vaak genegeerde mappen over (node_modules, bin, obj, .git, enzovoort). Wanneer een compatibel project wordt gevonden, worden submappen eronder niet doorzocht.

Als er een mapargument wordt opgegeven (bijvoorbeeld winapp init . of winapp init path/to/project), wordt de zoekopdracht overgeslagen en init wordt alleen die map voor een compatibel project gecontroleerd
Als --use-defaults (of --no-prompt) is ingesteld zonder een mapargument, init slaat u de zoekopdracht over en initialiseert u de huidige map niet-interactief, waarschuwing eerst als er geen bekend projecttype wordt gedetecteerd (bijvoorbeeld winapp init --use-defaults)
In niet-interactieve omgevingen (piped stdin, CI, omgeleide invoer), init wordt automatisch gebruikgemaakt --use-defaults van gedrag en wordt een waarschuwing verzonden: Non-interactive environment detected. Using default values.
Als de huidige map een compatibel project is, init gaat u onmiddellijk verder
Als er ergens anders precies één project wordt gevonden, wordt u gevraagd om te bevestigen
Als er meerdere projecten worden gevonden, kunt u selecteren welke u wilt initialiseren: de huidige map is altijd beschikbaar als een terugvaloptie
Als er geen projecten worden gevonden, wordt u gewaarschuwd en wordt u gevraagd of u toch wilt doorgaan
Als de zoekactie de limiet van 10 projecten bereikt, wordt een waarschuwing voorgesteld om een mapargument op te geven

Automatische .NET projectstroom:

Wanneer een .csproj-bestand wordt gevonden in de doelmap, gebruikt init een gestroomlijnde .NET-specifieke stroom:

Valideert en werkt de TargetFramework bij naar een Windows compatibele TFM (bijvoorbeeld net10.0-windows10.0.26100.0)
Voegt Microsoft.WindowsAppSDK en Microsoft.Windows.SDK.BuildTools als NuGet-vermeldingen PackageReference rechtstreeks toe in de .csproj
Genereert Package.appxmanifest, assets en een ontwikkelingscertificaat
Maakt geen C++-projecties aan winapp.yaml of downloadt ze (gebruik dotnet restore voor NuGet-pakketten)

Sparse-identiteitsmodus (--exe + --sparse):

Genereert een pakketmanifest met alleen identiteiten voor een bestaand uitvoerbaar bureaublad, de eerste stap van de werkstroom voor het parseren van pakketten. In tegenstelling tot de volledige init stroom slaat dit alle SDK-/pakketinstallatie (sparse-identiteitspakketten hebben geen SDK-afhankelijkheden) over en genereert u alleen een manifest en tijdelijke aanduiding voor assets.

Hiermee wordt de pakketnaam, uitgever, beschrijving en versie afgeleid van de exe via FileVersionInfo (onderdrukking met--name--publisher, of interactief)
appxmanifest.xml Schrijft (met de exe-naam vervangen in Executable) plus een Assets/ map naar een sparse/ map in de huidige map (of --output-dir)
Hiermee --use-defaults/--no-prompt kunt u de interactieve onderdrukkingsprompts overslaan (CI-vriendelijk)
--exe zonder --sparse is een fout

Assets zijn extern. De sparse .msix is alleen identiteit: de gegenereerde Assets/ map wordt omgezet vanuit de installatiemap van de app (de externe inhoudslocatie) tijdens runtime, niet gebundeld in de .msixmap . Implementeer deze naast uw toepassing.

Volgende stappen na winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> om de identiteit .msixte bouwen en vervolgens winapp embed-identity <exe>. Zie de handleiding voor Sparse-pakketten voor het volledige overzicht.

Voorbeelden:

# 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

Tip: SDK's installeren na de eerste installatie

Als u de init SDK hebt uitgevoerd --setup-sdks none (of de SDK-installatie hebt overgeslagen) en later de SDK's nodig hebt:

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

Gebruik --setup-sdks preview of --setup-sdks experimental voor preview-/experimentele SDK-versies.

Nieuw

Maak een nieuwe WinUI-app op basis van een officiële Windows App SDK-sjabloondotnet new. Standaard interactief; maakt automatisch gebruik van standaardwaarden in niet-interactieve omgevingen.

winapp new [options]

Opties:

-t, --template <short-name>- Korte naam van sjabloon (bijvoorbeeld winui, , winui-mvvmwinui-navview, , winui-lib, of winui-unittesteen experimentele reactorsjabloon zoals reactor of reactor-mvu). Gevalideerd op basis van het geïnstalleerde pakket tijdens runtime; voer alles uit winapp new --list om alles te zien. Standaard: winui (lege XAML-app).
-n, --name <name> - Naam voor de nieuwe app/het nieuwe project (standaard: afgeleid van --output, else WinUIApp)
-o, --output <path> - Map waarin de app moet worden gemaakt (standaard: ./<name>)
--use-defaults, --no-prompt - Niet vragen; standaardwaarden gebruiken (lege sjabloon, naam van --output/--nameen het geïnstalleerde sjabloonpakket behouden in plaats van het bij te werken)
--force - Scaffold, zelfs als de uitvoermap al bestanden bevat
--template-version <latest|installed|version> - WinUI-sjabloonpakketversie: latest updates voor het nieuwste gepubliceerde pakket zonder te vragen (een geïnstalleerd pakket dat al nieuwer is, zoals een lokale prerelease-build, wordt bewaard; mislukt als de feed niet kan worden gecontroleerd), installed houdt wat er al is gedownload (geen netwerk) of maak een expliciete versie vast, zoals 1.2.3. Standaard: installeer de meest recente wanneer er geen pack aanwezig is, anders wordt u gevraagd om een verlopen pack bij te werken (bewaard as-is).--use-defaults
--list - Vermeld de beschikbare WinUI-sjablonen en sluit (installeert eerst het nieuwste pakket als er geen is geïnstalleerd)
--json - Uitvoer opmaken als JSON

Sjablonen:

Het pakket verzendt twee stijlen van De WinUI-app. XAML-sjablonen definiëren de gebruikersinterface in markeringen met een C#-codeachter. Reactorsjablonen zijn puur C# zonder XAML, met behulp van een MVU-patroon (Model-View-Update). De lijst met sjablonen wordt live gelezen vanuit het geïnstalleerde pakket, zodat deze altijd overeenkomt met de versie die u hebt, wordt uitgevoerd winapp new --list om de huidige set weer te geven. De interactieve kiezer en --list toont eerst de WinUI-sjablonen, vervolgens alle andere groepen in alfabetische volgorde. Algemene sjablonen:

Korte naam	Beschrijving
`winui`	Minimale lege XAML-app (MSIX-verpakking)
`winui-navview`	XAML NavigationView starter-app
`winui-tabview`	XAML TabView starter-app
`winui-mvvm`	XAML MVVM-app (CommunityToolkit.Mvvm)
`winui-lib`	WinUI 3-klassebibliotheek
`winui-unittest`	Verpakte MSTest-app; tests worden uitgevoerd wanneer deze wordt gestart
`reactor`	Experimenteel. Lege Reactor-app - puur C#, geen XAML
`reactor-mvu`	Experimenteel. Reactor-app die het MVU-patroon demonstreert
`reactor-navview`	Experimenteel. Starter-app Reactor NavigationView
`reactor-tabview`	Experimenteel. Starters-app Reactor TabView

Reactorsjablonen zijn experimenteel. Ze verwijzen naar de prereleasepakketten Microsoft.UI.Reactor , waarvan de API's in een toekomstige release kunnen worden gewijzigd of verwijderd. winapp new markeert ze (experimenteel) in --list en in de interactieve kiezer, stelt "Experimental": true in --jsonen drukt een waarschuwing af na het maken van een scaffold. Ze worden nooit gekozen als de standaardsjabloon. Reactor vereist ook de .NET 10 SDK of hoger. Op een oudere SDK winapp new mislukt de versie die nodig is in plaats van een project te bouwen dat u niet kunt bouwen.

De canonieke korte naam van elke sjabloon is de eerste aliaslijstendotnet new. Elke vermelde alias (bijvoorbeeld winui3wasdk-single, winui-reactor) wordt ook geaccepteerd. Als een ander geïnstalleerd sjabloonpakket dezelfde korte naam registreert (bijvoorbeeld reactor van Microsoft.UI.Reactor.Templates), winapp new maakt u nog steeds de sjabloon van het WinUI-pakket met behulp van een van de andere aliassen. Als een ander pakket elke alias registreert die de sjabloon heeft, winapp new stopt en noemt u die pack. Verwijder het met dotnet new uninstall <package> en voer het opnieuw uit. Wanneer u in een bestaand WinUI-project wordt uitgevoerd, dotnet new worden ook itemsjablonen (bijvoorbeeld een lege pagina) weergegeven die winapp new wordt toegevoegd aan het huidige project in plaats van een nieuw project te maken.

Versiebeheer voor sjabloonpakketten:

winapp new maakt geen specifieke sjabloonpakketversie meer vast. Als er geen pack is geïnstalleerd, wordt de meest recente geïnstalleerd. Als een ouder pakket al is geïnstalleerd, controleert het de feed en wordt, wanneer er een nieuwer pakket bestaat, gevraagd of het moet worden bijgewerkt, behalve in niet-interactieve/--use-defaults uitvoeringen, waardoor het geïnstalleerde pakket behouden blijft. Gebruik --template-version latest deze optie om altijd de nieuwste versie te gebruiken zonder te vragen (het vervangt nooit een geïnstalleerd pakket door een ouder pakket en mislukt als de feed niet kan worden gecontroleerd), of --template-version installed om het gedownloade pakket altijd te gebruiken zonder een netwerkcontrole. Door een expliciete versie (bijvoorbeeld --template-version 1.2.3) door te geven, wordt die versie altijd precies geïnstalleerd, zelfs wanneer er al een nieuw pakket aanwezig is, zodat scaffolding op alle computers kan worden gereproduceerd.

Een eerste uitvoering kan langer duren: Het installeren of bijwerken van het sjabloonpakket, of het herstellen van ontbrekende Windows App SDK NuGet-pakketten die door de geselecteerde sjabloon worden gebruikt, kunnen extra downloads vereisen. Dit kan ook gebeuren nadat een nieuwe Windows App SDK versie is gepubliceerd. Als de scaffolding na 10 seconden nog steeds wordt uitgevoerd, winapp new wordt het statusbericht bijgewerkt om aan te geven dat pakketten mogelijk worden gedownload of hersteld.

Wat het doet:

Controleert of de .NET SDK is geïnstalleerd (mislukt snel met richtlijnen als dit ontbreekt, winapp installeert geen hulpprogrammaketens)
Installeert of werkt het officiële WinUI-sjabloonpakket (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) op aanvraag bij
Inventariseert de beschikbare sjablonen van het geïnstalleerde pack en delegeert de scaffolding naar dotnet new <short-name>

WinUI-app-sjablonen bevatten al Windows verpakking en identiteit (Package.appxmanifest), dus er is geen afzonderlijke winapp init stap vereist. Gebruik winapp run voor app-sjablonen om de app te bouwen en te starten. De winui-lib sjabloon produceert een klassebibliotheek waarnaar wordt verwezen vanuit een app-project (het heeft geen app-manifest). De winui-unittest sjabloon is een verpakte MSTest-app waarvan de tests worden uitgevoerd wanneer de app wordt gestart () -winapp run niet via dotnet test. winapp newscaffolds op basis van het doelframework van uw geïnstalleerde .NET SDK en drukt de juiste volgende stap af voor de sjabloon die u kiest.

Geef de globale --verbose vlag (-v) door om elke onderliggende dotnet aanroep weer te geven (packquery, updatecontrole, installatie, dotnet new listscaffold) samen met de volledige uitvoer, handig voor het diagnosticeren van problemen met sjabloonpakketten of scaffolding.

Voorbeelden:

# 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

herstellen

Herstel pakketten en genereer bestanden opnieuw op basis van de bestaande winapp.yaml configuratie.

winapp restore [base-directory] [options]

Argumenten:

base-directory - Te herstellen map (standaard: huidige map). Selecteert ook waar winapp.yaml en nuget.config worden gelezen, tenzij --config-dir deze wordt overschreven.

Opties:

--config-dir <path> - Map met winapp.yaml (standaard: base-directory)

Wat het doet:

Leest de bestaande winapp.yaml configuratie
SDK-pakketten downloaden/bijwerken naar opgegeven versies
Genereert C++/WinRT-headers en binaire bestanden opnieuw
Slaat deelbare bestanden op in de globale cachemap

Opmerking

Voor .NET projecten zijn er geen SDK-versies als PackageReference vermeldingen in de .csproj sdk, dus winapp restore wordt voor u uitgevoerddotnet restore.winapp.yaml

Voorbeelden:

# Restore from winapp.yaml in current directory
winapp restore

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

Aangepaste en persoonlijke NuGet-feeds:

winapp init, restoreen update download de Windows SDK en Windows App SDK pakketten via NuGet, waarbij uw standaardhiërarchie nuget.config wordt gehonoreerd. Privéfeeds en mirrors, feedreferenties (inclusief referentieproviders) en een aangepast globalPackagesFolder werk zoals ze hiervoor dotnet restoredoen. Als u uitsluitend wilt herstellen vanuit uw eigen spiegel, <clear /> worden de overgenomen bronnen gebruikt en voegt u alleen die van u toe:

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

Opmerking

Voor systeemeigen projecten wordt winapp omgezet nuget.config vanuit de map waarop deze werkt: hetrestoreinit/mapargument, --config-dir indien gegeven, anders de huidige map. Voor .NET projecten zijn de bronnen afkomstig uit de eigen nuget.config hiërarchie van het project, omdat dat wat dotnet add package is en dotnet restore gebruikt, dus plaats de configuratie van een privéfeed in de projectmap of een bovenliggend element. Een --config-dir buiten die hiërarchie wordt gerapporteerd en genegeerd in plaats van versies te selecteren die het project niet op de achtergrond kan herstellen. Voer deze opdrachten alleen uit voor directory's die u vertrouwt, dezelfde waarschuwing die van toepassing is op dotnet restore. Wanneer verschillende bronnen zijn geconfigureerd, gebruikt u pakketbrontoewijzing om elk pakket vast te maken aan een feed.

update

Werk pakketten bij naar de nieuwste versies en werk het configuratiebestand bij.

winapp update [options]

Opties:

--setup-sdks <stable|preview|experimental|none> - SDK-installatiemodus: stable (standaard), preview, experimentalof none (sdk-installatie overslaan)

Wat het doet:

Leest de bestaande winapp.yaml configuratie in de huidige map
Hiermee worden alle pakketten bijgewerkt naar de nieuwste beschikbare versies. Een Windows App SDK release die nog steeds wordt gepubliceerd, wordt overgeslagen totdat alle pakketten beschikbaar zijn en update drukt een notitie af met de naam van de release die in plaats daarvan wordt gebruikt. Voer winapp update deze later opnieuw uit om naar de nieuwe release te gaan.
winapp.yaml Het bestand bijwerken met nieuwe versienummers
Genereert C++/WinRT-headers en binaire bestanden opnieuw

Voorbeelden:

# Update packages to latest versions
winapp update

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

pack

MSIX-pakketten maken op basis van een project of voorbereide toepassingsmappen. Vereist dat een manifestbestand (Package.appxmanifest voorkeur, appxmanifest.xml ook ondersteund) aanwezig is in de doelmap, in de huidige map of doorgegeven met de --manifest optie. (een manifest uitvoeren init of manifest generate maken)

Geef één door .csproj om het project te bouwen en de uitvoer in één stap te verpakken (projectmodus, zie Een project direct hieronder verpakken ). Geef meerdere invoermappen door om een .msixbundle voor distributie met meerdere architectuur te maken (zie bundels met meerdere architecturen hieronder).

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

Argumenten:

input-folder - Eén map .csproj die moet worden gebouwd en verpakt (projectmodus) of een of meer mappen met de toepassingsbestanden die moeten worden verpakt. Geef meerdere mappen (bijvoorbeeld) door om een MSIX-bundel ./publish/x64 ./publish/arm64te maken. Voor sparse-identiteitspakketten geeft u een sparse-bestand appxmanifest.xml rechtstreeks door in plaats van een map (zie hieronder Sparse-identiteitspakketten ).

Opties:

--output <filename> - Naam van uitvoerbestand. Voor één pakket: <name>_<version>_<arch>.msix (terugvallen op <name>_<version>.msix, <name>_<arch>.msixof <name>.msix). Voor bundels: <name>_<version>_<arch1>_<arch2>.msixbundle.
--name <name> - Pakketnaam (standaard: van manifest)
--manifest <path> - Pad naar manifestbestand (Package.appxmanifest aanbevolen, appxmanifest.xml ook ondersteund; standaard: automatisch detecteren)
--cert <path> - Pad naar handtekeningcertificaat (automatisch ondertekenen is ingeschakeld)
--cert-password <password> - Certificaatwachtwoord (standaard: 'wachtwoord')
--generate-cert - Een nieuw ontwikkelingscertificaat genereren
--no-sign - Lever het pakket niet-ondertekend, waarbij alle configuraties voor projectondertekening worden overschreven (bijvoorbeeld voor het indienen van de Store of een pijplijn voor externe ondertekening). Kan niet worden gecombineerd met --cert of --generate-cert.
--install-cert - Certificaat installeren op computer
--publisher <name>- Publisher voor het genereren van certificaten. Accepteert een volledige X.500 DN-naam of een lege naam (automatisch verpakt als CN=<name>)
--self-contained - Bundel Windows App SDK runtime
--skip-pri - Het genereren van PRI-bestanden overslaan
--executable <path> - Pad naar het uitvoerbare bestand ten opzichte van de invoermap (ook --exe). Wordt gebruikt om tijdelijke aanduidingen in het manifest op te lossen $targetnametoken$ .

Project modusopties (hiervoor is invoer .csproj vereist; geweigerd voor invoer van map/bundel/manifest):

--configuration <name> (-c) - Buildconfiguratie (standaard: Release)
--arch <arch> - Doelarchitectuur: x64, arm64of x86 (standaard: de huidige procesarchitectuur)
--framework <tfm> (-f) - Doelframework moniker voor projecten met meerdere doelen
--no-build - De bestaande build-uitvoer verpakken zonder opnieuw te bouwen
--no-restore - Sla het herstellen van het project over voordat u het bouwt
--property <name=value> (-p) - MSBuild-eigenschap, doorgestuurd naar build en evaluatie (herhaalbaar)

Opmerking: Voor een WinUI/ EnableMsixTooling.csproj (MSIX-tooling projectmodus) is het Windows App SDK eigenaar van het manifest, het toegangspunt en pri-generatie, dus --manifest, --executableen --skip-pri worden geweigerd - configureert<AppxManifest>, het toegangspunt van het project en de bijbehorende resourcebuild in het project zelf. Deze drie opties zijn nog steeds van toepassing op mapinvoer en op algemene projectmodus (niet-MSIX-hulpprogramma's .csproj ).

Wat het doet:

Valideert en verwerkt Package.appxmanifest-bestanden
$placeholder$ Hiermee worden tokens in het manifest omgezet (zie tijdelijke aanduidingen voor manifesten hieronder)
Zorgt voor de juiste frameworkafhankelijkheden
Manifesten parallel bijwerken met registraties
Detecteert en bundelt automatisch niet-installatiekopiebestanden waarnaar wordt verwezen in het manifest (bijvoorbeeld AppExtension manifest.json, configuratiebestanden) uit de manifestmap of invoermap als ze ontbreken in fasering
Detecteert automatisch WinRT-onderdelen van derden en registreert hun activeringsklassen (zie hieronder WinRT-onderdeeldetectie )
Verwerkt zelfstandige WinAppSDK-implementatie
Ondertekent het pakket indien het certificaat is verstrekt.

Een project rechtstreeks verpakken

Wanneer de invoer één .csprojis, winapp pack bouwt u het project (met behulp van de bovenstaande opties) en verpakt u de resulterende uitvoer. U hoeft niet eerst afzonderlijk te bouwen of de uitvoermap te zoeken. Dit spiegelt winapp runde projectmodus.

# 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

De doelarchitectuur komt van --arch, of van een eenzame -p RuntimeIdentifier=<rid> wanneer u niet passeert --arch (de exacte RID blijft behouden en de build aanstuurt). Beide doorgeven --arch en -p RuntimeIdentifier is een conflict en wordt geweigerd.

Het project moet worden gebouwd als een verpakte app (EnableMsixTooling=true met een Package.appxmanifest); een project dat wordt gebouwd als een uitgepakte app (WindowsPackageType=None) heeft geen MSIX-manifest om een actiebare fout te verpakken en winapp pack te melden. Map-, bundel- en sparse-manifestinvoer zijn ongewijzigd.

Project modus produceert één .msix of alleen-architectuur .msixbundle (zie bundels met meerdere architectuur). Het produceert geen archief-uploadarchieven of resourcesplitsingbundels (taal/schaal): een expliciete -p UapAppxPackageBuildMode=StoreUpload of -p AppxBundleAutoResourcePackageQualifiers=... wordt geweigerd met een opmerking om de systeemeigen SDK-pakketopdracht rechtstreeks voor deze stromen uit te voeren.

Sparse-identiteitspakketten

Wanneer de invoer een sparse-bestand appxmanifest.xml is (één declaratie <uap10:AllowExternalContent>true</uap10:AllowExternalContent> onder<Properties>) in plaats van een map, winapp pack wordt er alleen een identiteit.msix gemaakt. Het pakket verpakt alleen het manifest, zonder binaire bestanden of assets van toepassingen. Dit is stap 2 van de sparse-verpakkingswerkstroom.

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

Uitvoer wordt standaard ingesteld <PackageName>.identity.msix in de huidige map (overschrijven met --output).
Ondertekening vindt alleen plaats wanneer --cert (of --generate-cert) is opgegeven.
Als u in plaats daarvan een map doorgeeft waarvan het manifest declareertAllowExternalContent, is het gedrag van de bestaande mapverpakking van toepassing, maar winapp pack waarschuwt het als er assets () of binaire bestanden (.jpg//.so/.png.exe.dll.ico/) worden gevonden, voor parseringspakketten die deel uitmaken van de externe locatie, niet binnen de ..msix

Voer na het inpakken winapp embed-identity <exe> het pakket uit en registreer het in uw installatieprogramma bij Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Zie de handleiding voor Sparse-pakketten.

WinRT-onderdeeldetectie

Bij het verpakken winapp pack scant u automatisch NuGet-pakketten die zijn gedefinieerd in of winapp.yaml*.csproj voor WinRT-onderdelen van derden (bijvoorbeeld Win2D). Het parseert .winmd bestanden om activeringsbare klassenamen te extraheren en hun implementatie-DLL's te vinden. De gedetecteerde vermeldingen worden als volgt geregistreerd:

Frameworkafhankelijk (standaard): Activeringsklassen worden toegevoegd als <InProcessServer> vermeldingen in de Package.appxmanifest
Zelfstandige (--self-contained): Activeringsklassen worden ingesloten in SxS-manifesten (side-by-side) binnen het uitvoerbare bestand

Tijdelijke aanduiding voor oplossing tijdens verpakking:

Als het manifest het $targetnametoken$ kenmerk bevatExecutable:

Als --executable dit is opgegeven (pad ten opzichte van de invoermap), wordt de tijdelijke aanduiding vervangen door de opgegeven waarde
winapp pack Anders scant u de hoofdmap van de invoermap voor .exe bestanden, als er precies één wordt gevonden, wordt deze automatisch gebruikt
Als er nul of meerdere .exe bestanden worden gevonden, wordt een fout weergegeven waarin u wordt gevraagd om op te geven --executable

Voorbeelden:

# 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

Bundels met meerdere architectuur

Wanneer meerdere invoermappen worden doorgegeven, winapp pack maakt u een .msixbundle map met één .msix per architectuur:

# 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

De opdracht detecteert automatisch de architectuur van elke map uit de PE-header van het primaire uitvoerbare bestand, valideert consistentie tussen segmenten (identiteit, mogelijkheden, afhankelijkheden) en produceert een <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Manifestoplossing voor bundels:

Elk segment in de bundel heeft een manifest nodig. Met de opdracht worden manifesten in deze volgorde omgezet:

--manifest <path> — Indien opgegeven, wordt dit enkele manifest gebruikt voor alle segmenten. De ProcessorArchitecture functie wordt automatisch per segment bijgewerkt zodat deze overeenkomt met de gedetecteerde architectuur.
Manifest per map : als elke invoermap een Package.appxmanifest (of appxmanifest.xml) bevat, wordt het manifest van die map gebruikt voor het segment.
Huidige mapterugval : als een map geen manifest heeft, zoekt de opdracht naar Package.appxmanifest in de huidige werkmap en gebruikt deze (met automatisch gestempelde architectuur).

In alle gevallen wordt het manifest automatisch bijgewerkt: tijdelijke aanduidingen worden opgelost, afhankelijkheden worden geïnjecteerd en de ProcessorArchitecture is geforceerd ingesteld op de gedetecteerde architectuur. Na de oplossing zorgt een kruissegmentvalidatie ervoor dat identiteit (naam, versie, Publisher), mogelijkheden en afhankelijkheden consistent zijn in alle segmenten. Dit kan alleen ProcessorArchitecture verschillen. De pakketversie die in de segmenten is gedefinieerd, wordt toegewezen aan de MSIX-bundelversie, behalve als dit het geval is 0.0.0.0, in welk geval automatisch een versie op basis van een tijdstempel wordt gegenereerd.

# 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

create-debug-identity

Maak een app-identiteit voor foutopsporing met behulp van sparse-pakketten. De exe blijft op de oorspronkelijke locatie: Windows koppelt er identiteit aan via Add-AppxPackage -ExternalLocation.

Wanneer u dit wilt gebruiken versus winapp run: Gebruik create-debug-identity wanneer de exe losstaat van uw app-code (bijvoorbeeld Electron-apps waarin electron.exe zich bevindt node_modules), of wanneer specifiek het gedrag van het sparse-pakket wordt getest. Voor de meeste frameworks waarin de exe zich in uw build-uitvoermap bevindt, gebruikt winapp run u in plaats daarvan: het registreert een volledig losse lay-outpakket en start de app. Zie de handleiding voor foutopsporing voor een volledige vergelijking.

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

Argumenten:

entrypoint - Pad naar uitvoerbaar bestand (.exe) of script dat identiteit nodig heeft

Opties:

--manifest <path> - Pad naar het manifestbestand van de app of Package.appxmanifestappxmanifest.xml (standaard: automatisch detecteren Package.appxmanifest of appxmanifest.xml in de huidige map)
--no-install - Installeer het pakket niet na het maken
--keep-identity- Houd de manifestidentiteit as-is, zonder toe te voegen aan de pakketnaam en toepassings-id .debug

Wat het doet:

Wijzigt het side-by-side manifest van het uitvoerbare bestand
Sparse-pakket voor identiteit registreren
Hiermee schakelt u de foutopsporing in voor API's waarvoor identiteit nodig is

Voorbeelden:

# 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

insluitidentiteit

Verbind een bureaubladtoepassing met het sparse identiteitspakket door het <msix> element in te sluiten in het manifest naast elkaar (fusion) van de app. Dit is stap 3 van de sparse-verpakkingswerkstroom. Het geeft aan Windows welk identiteitspakket de actieve exe behoort.

winapp embed-identity <target> [options]

Argumenten:

target - Het bestand dat moet worden bijgewerkt. Automatisch gedetecteerd door extensie:
- .exe (EXE-modus) - sluit het <msix> element rechtstreeks in het manifest naast elkaar in met behulp van mt.exehet exe-manifest.
- .xml / .manifest (XML-modus): voegt het element in of vervangt het <msix> element in een extern SxS-manifestbestand (gemaakt als dit niet bestaat). Bouw de app daarna opnieuw, zodat het bijgewerkte manifest is ingesloten in het binaire bestand.

Opties:

--manifest <path> - Pad naar de sparse appxmanifest.xml om identiteit te lezen (packageName, publisher, applicationId) van waaruit. Als u dit weglaat, zoekt de opdracht eerst in een sparse/ map naast het doel, vervolgens in de huidige map, vervolgens de map van het doel en de huidige map, voor appxmanifest.xml.

Voorbeelden:

# 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

Deze opdracht is idempotent: het opnieuw uitvoeren vervangt elk bestaand <msix> element in plaats van het te dupliceren.

manifesteren

Genereer en beheer Package.appxmanifest-bestanden.

manifest genereren

Genereer Package.appxmanifest op basis van sjablonen.

winapp manifest generate [directory] [options]

Argumenten:

directory - Map voor het genereren van manifest in (standaard: huidige map)

Opties:

--package-name <name> - Pakketnaam (standaard: mapnaam)
--publisher-name <name>- Publisher DN-naam (standaard: CN=<huidige gebruiker>). Accepteert een X.500 DN met enkelvoudige, door komma's gescheiden onderdelen (RDN's met meerdere + waarden en backslashes worden niet ondersteund); lege namen worden automatisch verpakt als CN=<name>.
--version <version> - Versie (standaard: "1.0.0.0")
--description <text> - Beschrijving (standaard: "Mijn toepassing")
--entrypoint <path> - Uitvoerbare invoerpunt of script
--template <type> - Sjabloontype: packaged (standaard) of sparse
--logo-path <path> - Pad naar logoafbeeldingsbestand
--if-exists <Error|Overwrite|Skip> - Gedrag wanneer het manifestbestand al bestaat op het doelpad (standaard: Error)

Sjablonen:

packaged - Standaard verpakte app-manifest
sparse - Appmanifest met behulp van spaarzame/externe locatieverpakking

Plaatsaanduidingen van het manifest

Gegenereerde manifesten gebruiken $placeholder$ tokens (door dollartekens gescheiden) die automatisch worden omgezet tijdens het verpakken:

Plaatsaanduiding	Opgelost in	Voorbeeld
$targetnametoken$	Uitvoerbare naam zonder extensie	`Executable="$targetnametoken$.exe"` → `Executable="MyApp.exe"`
$targetentrypoint$	`Windows.FullTrustApplication`	Altijd automatisch opgelost

Dit volgt dezelfde conventie die wordt gebruikt door Visual Studio projectsjablonen, zodat manifesten overdraagbaar zijn in verschillende hulpprogramma's.

Hoe tijdelijke aanduidingen worden omgezet:

winapp pack — Tijdens het verpakken wordt $targetnametoken$ opgelost met behulp van de --executable optie of door de single .exe in de invoermap automatisch te detecteren. Als er meerdere (of nul) .exe bestanden worden gevonden en --executable niet is opgegeven, wordt er een fout weergegeven.
winapp create-debug-identity — Wanneer er een invoerpuntargument wordt opgegeven, $targetnametoken$ wordt dit opgelost. Zonder invoerpunt moet de tijdelijke aanduiding voor uitvoerbare bestanden al in het manifest worden omgezet.
winapp manifest generate --executable— Wanneer --executable deze is opgegeven, worden manifestmetagegevens (versie, beschrijving) en pictogrammen geëxtraheerd uit het uitvoerbare bestand, maar het gegenereerde manifest gebruikt nog steeds$targetnametoken$.exe; deze tijdelijke aanduiding wordt later omgezet (bijvoorbeeld winapp pack ).winapp create-debug-identity

PS: $targetnametoken$ in het ingecheckte manifest vermijdt hardcodering uitvoerbare namen en werkt met zowel winapp pack als Visual Studio builds.

Voorbeelden:

# 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

manifest add-alias

Voeg een uitvoeringsalias (uap5:AppExecutionAlias) toe aan een Package.appxmanifest. Hierdoor kan de verpakte app vanaf de opdrachtregel worden gestart door de aliasnaam te typen.

winapp manifest add-alias [options]

Opties:

--name <alias> - Aliasnaam (bijvoorbeeld myapp.exe). Standaard: afgeleid van het Executable kenmerk in het manifest.
--manifest <path> - Pad naar Package.appxmanifest (standaard: zoeken in huidige map)
--app-id <id> - Toepassings-id waaraan de alias moet worden toegevoegd (standaard: eerste toepassingselement)

Wat het doet:

Leest het manifest en afgeleid de alias van het Executable kenmerk (met behoud van tijdelijke aanduidingen zoals $targetnametoken$.exe)
Voegt de uap5 naamruimtedeclaratie toe als deze nog niet aanwezig is
Voegt een <Extensions> blok toe met <uap5:AppExecutionAlias> binnen het doeltoepassingselement
Als de alias al bestaat, rapporteert u deze en sluit u deze af

Voorbeelden:

# 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 bijwerken-assets

Genereer alle vereiste MSIX-afbeeldingsbronnen van één bronafbeelding.

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

Argumenten:

image-path - Pad naar bronafbeeldingsbestand (PNG, JPG, SVG, ICO, GIF, BMP, enzovoort)

Opties:

--manifest <path> - Pad naar package.appxmanifest-bestand (standaard: zoeken in huidige map)
--light-image <path> - Pad naar een afzonderlijke bronafbeelding voor lichte themavarianten

Description:

Maakt één broninstallatiekopieën en genereert een uitgebreide set MSIX-installatiekopieën op basis van de assetverwijzingen van het manifest:

Voor elke asset waarnaar wordt verwezen in het manifest:

5 schaalvarianten — grondtal (geen achtervoegsel), .scale-125, , .scale-150.scale-200.scale-400

Voor het app-pictogram (Square44x44Logo/AppList, 44×44 basis):

14 vergulde doelvarianten — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
14 niet-geplated doelen maken varianten — .targetsize-{size}_altform-unplated

Additionally:

app.ico — ICO-bestand met meerdere resolutie (16, 24, 32, 48, 256) voor shell-integratie. Als een bestaand .ico bestand wordt gevonden in de map assets (bijvoorbeeld AppIcon.ico van een projectsjabloon), wordt het in-place vervangen in plaats van een duplicaat te maken

Met --light-image:

Lichte thema's zijn gericht op varianten — .targetsize-{size}_altform-lightunplated (app-pictogram)
Lichte themaschaalvarianten — .scale-{factor}_altform-colorful_theme-light (tegels, winkellogo)

SVG-ondersteuning: SVG-bestanden worden volledig ondersteund als bronafbeeldingen. Ze worden weergegeven als vectoren rechtstreeks bij elke doelgrootte, waardoor pixelperfecte resultaten bij alle resoluties worden geproduceerd. Het bestand moet een eigen grootte declareren, via een viewBox of absolute width en height kenmerken; een percentagebreedte zonder viewBox een bepaalde grootte. Een bron die geen van beide declareert, wordt geweigerd SVG image has no usable dimensions in plaats van lege activa te produceren.

Met de opdracht worden afbeeldingen proportioneel geschaald terwijl de hoogte-breedteverhouding behouden blijft, waarbij ze worden gecentreerd met transparante achtergronden wanneer dat nodig is. Assets worden opgeslagen in de Assets map relatief aan de manifestlocatie.

Voorbeelden:

# 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

Maak een los indelingspakket op basis van een build-uitvoermap, registreer het bij Windows met behulp van de Windows.Management.Deployment.PackageManager-API en start de toepassing, waarbij een volledige MSIX-installatie voor foutopsporing wordtged. Retourneert de proces-id voor foutopsporingsprogrammabijlage.

winapp run werkt in een van de drie modi, die automatisch worden gekozen uit de invoer:

Mapmodus : de invoer is een build-output-map (bevat een Package.appxmanifest/AppxManifest.xml).
Project-modus: de invoer is een .csproj, een C++ .vcxprojof een .sln/.slnx oplossing of een map die er een bevat. winapp run bouwt het project en start het, met ondersteuning voor zowel verpakte als uitgepakte apps. Zie Project-modus en C++-projecten hieronder.
Modus voor één bestand: de invoer is een .cs.NET app op basis van bestanden. winapp run bouwt het, genereert een manifest op basis van de #:property instructies en start het met pakketidentiteit.

Tip

Modusselectie is standaard stil. Als een map is behandeld als een build-output-map toen u verwachtte dat deze als een project werd gebouwd, voert u opnieuw uit met --verbose : mapmodus rapporteert waarom deze is gekozen (No .csproj/.vcxproj/.sln/.slnx with a runnable app found in '<path>' — running it as a build-output folder.). Een map is alleen gebouwd als een project wanneer een .csproj.sln///.vcxproj.slnx met een uitvoerbare app zich op het hoogste niveau bevindt; deze wordt niet recursief doorzocht.

Dit is de voorkeursopdracht voor foutopsporing met pakketidentiteit voor de meeste frameworks (.NET, C++, Rust, Flutter, Tauri). In tegenstelling tot create-debug-identity welke een sparse-pakket voor één exe wordt geregistreerd, winapp run registreert u de hele map als een losse indelingspakket, net als een echte MSIX-installatie. Zie de handleiding voor foutopsporing voor veelvoorkomende foutopsporingswerkstromen.

winapp run [<input>] [options]

Argumenten:

input- De app die moet worden uitgevoerd: een map met build-uitvoer (mapmodus), een .cs .NET op bestanden gebaseerde app (modus voor één bestand), een .csproj of C++.vcxproj-project, een .sln/.slnx oplossing of een map met een van deze op het hoogste niveau (projectmodus; de map wordt niet recursief doorzocht). Gebruik . dit om het project in de huidige map te bouwen/uit te voeren. Optioneel: standaard ingesteld op de huidige map wanneer deze wordt weggelaten (overeenkomsten dotnet run).

Opties:

--manifest <path> - Pad naar Package.appxmanifest (standaard: automatisch detecteren uit invoermap of huidige map)
--output-appx-directory <path> - Uitvoermap voor de losse indeling (standaard: AppX in de invoermap). De standaardindeling verwijdert bestanden niet meer in de build; een aangepaste map bewaart extra bestanden. Gebruik een nieuwe aangepaste map wanneer u een schone indeling nodig hebt.
--args <string> - Opdrachtregelargumenten die moeten worden doorgegeven aan de toepassing. U kunt ook gevolgd door argumenten gebruiken -- om escapen te voorkomen (bijvoorbeeld winapp run . -- --flag value).
--no-launch - Maak alleen de foutopsporingsidentiteit en registreer het pakket zonder de toepassing te starten
--with-alias - Start de app met behulp van de uitvoeringsalias in plaats van AUMID-activering. De app wordt uitgevoerd in de huidige terminal met overgenomen stdin/stdout/stderr. Zelden nodig: een app met OutputType=Exe al wordt standaard op deze manier gestart. winapp voegt de vereiste uap5:ExecutionAlias toe aan het manifest dat het faseert in de AppX-indeling, dus er is geen wijziging in het ingecheckte manifest nodig; een alias die de app zelf declareert, wordt gebruikt as-is. Kan niet worden gecombineerd met --no-launch, --detachof --without-alias--json.
--without-alias - Forceer AUMID-activering voor een app die anders zou worden gestart via een uitvoeringsalias. Een console-app wordt vervolgens uitgevoerd zonder console en drukt niets af op deze terminal. Kan niet worden gecombineerd met --with-alias.
--debug-output - Leg OutputDebugString berichten en uitzonderingen voor de eerste kans vast van de gestarte toepassing. Frameworkruis (WinUI, COM, DirectX) wordt gefilterd vanuit console-uitvoer; het volledige logboekbestand legt alles vast. Als de app vastloopt, wordt er automatisch een minidump vastgelegd en geanalyseerd om het uitzonderingstype, bericht en stacktracering weer te geven met bronbestand:regelnummers (omgezet vanuit PDBs in de build-uitvoermap). Beheerde (.NET) crashes worden direct geanalyseerd zonder externe hulpprogramma's. Systeemeigen (C++/WinRT) crashes tonen modulenamen en offsets. Wanneer de vastgelopen app een WinUI 3-app is (Microsoft.UI.Xaml.dll wordt geladen), wordt er automatisch een extra triage-uitzonderingspas uitgevoerd om de oorspronkelijke HRESULT, de Bijbehorende ErrorContext-keten en de volledige systeemeigen XAML-verzendstack weer te geven. De vereiste foutopsporingsprogrammaonderdelen worden gedownload bij eerste gebruik (zie Foutopsporing, overschrijfbaar via de WINAPP_DBGTOOLS_DIR omgevingsvariabele). Slechts één foutopsporingsprogramma kan tegelijk worden gekoppeld aan een proces, dus andere foutopsporingsprogramma's (Visual Studio, VS Code) kunnen niet tegelijkertijd worden gebruikt. Gebruik --no-launch in plaats daarvan als u een ander foutopsporingsprogramma moet koppelen. Kan niet worden gecombineerd met --no-launch. Kan niet worden gecombineerd met --json. Als u zonder deze code uitvoert en de app wordt afgesloten met een niet-zero-code, wordt een hint afgedrukt om opnieuw uit te voeren met --debug-output.
--symbols : download PDB-symbolen van Microsoft Symboolserver voor uitgebreidere systeemeigen crashanalyse met opgeloste functienamen. Alleen gebruikt met --debug-output. Als u dit weglaat en er een systeemeigen crash optreedt, wordt in de uitvoer voorgesteld deze vlag toe te voegen. Deze vlag verbetert ook de WinUI stowed-exception triage stack voor WinUI 3-apps. Eerst worden symbolen gedownload en lokaal in de cache opgeslagen; volgende uitvoeringen maken gebruik van de cache.
--unregister-on-exit - De registratie van het ontwikkelpakket ongedaan maken nadat de toepassing is afgesloten. Verwijdert alleen pakketten die zijn geregistreerd in de ontwikkelingsmodus. Kan niet worden gecombineerd met --no-launch.
--detach - Start de toepassing en keer onmiddellijk terug zonder te wachten tot deze is afgesloten. Handig voor CI/automation waar u na het starten met de app moet communiceren. Lokale uitvoeringen drukken de PID af; doeluitvoeringen drukken het bereik van het UI-doel af. JSON bevat de PID en het doelbereik. Kan niet worden gecombineerd met --no-launch, --debug-outputof --with-alias--unregister-on-exit.
--clean - Verwijder de toepassingsgegevens van het bestaande pakket (LocalState, instellingen, enzovoort) voordat u het opnieuw implementeert. Toepassingsgegevens blijven standaard behouden bij herimplementaties.
--json - Uitvoer opmaken als JSON voor programmatisch verbruik (bijvoorbeeld CI/automation). Handig om --detach de PID vast te leggen. Kan niet worden gecombineerd met --with-alias of --debug-output.
--on <target> - Bouw op de host en registreer en voer deze uit in het doel. sandboxOndersteunt momenteel, zonder terugval naar lokale uitvoering. Gebruik --detach deze voordat u ui-opdrachten opvolgt. Sandbox --debug-output vereist een verpakte app. Zie Windows Sandbox-uitvoering voor installatie, runtime-ondersteuning en de levensduur van de losgekoppelde app.

Persistentie van toepassingsgegevens:

Behoudt standaard winapp run de gegevens van uw toepassing (LocalState, RoamingState, Settingsenzovoort) bij het opnieuw implementeren. Als uw app gegevens naar ApplicationData.Current.LocalFolder of Environment.GetFolderPath(SpecialFolder.LocalApplicationData) binnen de pakketcontext schrijft, blijven die gegevens behouden tijdens winapp run aanroepen.

Gebruik --clean dit wanneer u een nieuwe start nodig hebt (bijvoorbeeld om beschadigde status opnieuw in te stellen of het gedrag van de eerste uitvoering te testen).

Wat het doet:

Zoekt of genereert het Package.appxmanifest
Hiermee maakt en registreert u een foutopsporingsidentiteit met behulp van een los indelingspakket
Berekent de model-id van de toepassingsgebruiker (AUMID)
Start de toepassing met behulp van de geregistreerde identiteit (tenzij --no-launch opgegeven)
De proces-id (PID) afdrukken voor foutopsporingsprogrammabijlage

Voorbeelden:

# 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 modus (.NET SDK-projecten)

Wanneer de invoer een.csproj, een/.slnx.slnoplossing of een map met een (inclusief.) winapp run is, wordt het project gebouwd en dotnet build vervolgens gestart. Het ondersteunt zowel verpakte als uitgepakte WinUI-apps en installeert de overeenkomende architectuur Windows-app Runtime die de app nodig heeft voordat deze wordt gestart.

Oplossingsinvoer: wijs winapp run een .sln.slnx/(of een map met een map) aan, een oplossing heeft de voorkeur boven losse .csproj bestanden) en lost het runnable app-project op, bouwt het vervolgens samen met $(SolutionDir) de gedefinieerde eigenschappen en de eigenschappen op hetzelfde niveauSolution*, zodat projecten die afhankelijk zijn van de build, zoals in Visual Studio. Oplossingsregels:

Testprojecten worden overgeslagen wanneer u automatisch selecteert, zodat een oplossing met een app plus de bijbehorende tests zonder --project dat dit nodig is, wordt omgezet in de app. (Een WinUI-testproject is zelf een verpakte app, dus alleen het uitvoertype kan het niet onderscheiden.)
Als het enige uitvoerbare project een testproject is, wordt het uitgevoerd.
Als er meer dan één runnable app-project bestaat, winapp run wordt er geen opstartproject geraden. Er wordt een fout opgetreden bij het weergeven van de kandidaten. Gebruik --project <name> dit om te kiezen, wat altijd wordt gehonoreerd, inclusief het selecteren van een testproject.

Verpakt versus uitgepakt wordt automatisch gedetecteerd vanuit de effectieve WindowsPackageType MSBuild-eigenschap van het project (nooit van aanwezigheid van manifest):

Verpakt (WindowsPackageType=MSIX, de standaard winUI verpakt) - builds, registreert vervolgens de build-uitvoer als een los-indelingspakket en start via AUMID (dezelfde pijplijn als mapmodus).
Uitgepakt (WindowsPackageType=None) - builds, zorgt ervoor dat de frameworkafhankelijke Windows-app Runtime is geïnstalleerd en start vervolgens de ingebouwde .exe rechtstreeks. Forceer dit voor een verpakt project met -p WindowsPackageType=None.

Project-modus vereist de .NET SDK 8.0.100 of hoger (voor MSBuild--getProperty).

Systeemeigen AOT: voeg deze eigenschapsgroep toe in het element van <Project> het project bestand en voeg vervolgens het volgende toe--aot:

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

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

--aotondersteunt x64- en ARM64-projecten en vereist de .NET SDK 8.0.300 of hoger. Het wordt uitgevoerd dotnet publish met de AOT-configuratie van het project en start vervolgens die uitvoer. Gebruik -p PublishAot=true deze voor een eenmalige onderdrukking. Er wordt geen afzonderlijke runtimecertificering uitgevoerd en kan niet worden gecombineerd met --no-build of --manifest.

Voor apps die gebruikmaken van pakketidentiteit zonder een gegenereerde MSIX-indeling, neemt u deze op Package.appxmanifest of appxmanifest.xml in de publicatie-uitvoer van het project. Winapp faseert de gepubliceerde bestanden met dat manifest. Als beide namen aanwezig zijn, stopt winapp in plaats van er een te kiezen; verwijder het verlopen manifest en configureer het project zodanig dat alleen het beoogde manifest wordt gepubliceerd.

Project-modusopties (genegeerd in de mapmodus, tenzij vermeld):

-c, --configuration <name> - Configuratie bouwen. Standaard: Debug. (Ook gehonoreerd in de modus voor één bestand.)
--arch <x64|arm64|x86> - Doelarchitectuur. Standaard: de huidige procesarchitectuur. Bepaalt de build-RID en Windows-app Runtime-architectuur en selecteert een overeenkomend platformafhankelijk publicatieprofiel wanneer dit nodig is voor de effectieve build. (Ook gehonoreerd in de modus voor één bestand.)
-r, --runtime <rid>- Doel-.NET runtime-id (bijvoorbeeld win-x64). Project modus maakt alleen gebruik van de rid-architectuur, bouwt altijd de canonieke win-<arch>en weigert niet-Windows RID's (bijvoorbeeldlinux-x64). De architectuur overschrijft --arch en kan het vereiste publicatieprofiel selecteren. (Ook gehonoreerd in de modus voor één bestand, waarbij een #:property RuntimeIdentifier gedeclareerd door het bestand wordt overschreven.)
-f, --framework <tfm> - Doelframework moniker voor projecten met meerdere doelen (bijvoorbeeld net10.0-windows10.0.26100.0). (Geweigerd in modus voor één bestand - gebruik #:property TargetFramework=....)
--project <name-or-path> - Wanneer de invoer een oplossing (.sln/.slnx) of een map met meerdere runnable app-projecten is, selecteert u welk project moet worden gestart (op projectnaam of pad). (Geweigerd in de modus voor één bestand: een .cs app op basis van bestanden is zelf het project.)
--no-build - Sla het bouwen over en voer de bestaande build-uitvoer uit (evalueert nog steeds uitvoereigenschappen). (Ook gehonoreerd in de modus voor één bestand.)
--no-restore - Sla het herstellen over voordat u een systeemeigen AOT-publicatie maakt. (Ook gehonoreerd in de modus voor één bestand.)
--aot- Voer de geconfigureerde .NET systeemeigen AOT-publicatie van het project uit. Vereist effectief PublishAot=true. Geweigerd in map- en modus voor één bestand.
-p, --property <Name=Value> - MSBuild property, doorgestuurd naar zowel de build als de evaluatie van de eigenschap. Herhaal -p dit voor meerdere eigenschappen; gebruik %3B of %2C voor een letterlijke puntkomma of komma in een waarde. (Ook gehonoreerd in de modus voor één bestand, waar het de enige manier is om in te stellen TargetFramework.)

Uitvoer bouwen en uitgebreidheid: een gewone projectuitvoering gebruikt dotnet builden evalueert vervolgens de ingebouwde uitvoer. Herstel en bouw uitvoerstream live, met referenties van geverifieerde feed-URL's die zijn redacted. Met --aotwinapp gebruikt dotnet publish; --verbose toont de publicatieopdracht en opgeloste paden. Gebruik de onderstaande uitgebreidheidsopties om te bepalen wat er wordt weergegeven:

Flag	uitbreiding van dotnet	Voegt toe
(standaard)	`minimal`	—
`--verbose`	`minimal`	winapp's build decision traces
`--quiet`	`quiet`	—

Systeemeigen AOT publiceert uitvoerstreams zodra deze binnenkomt. Ga onder --jsonherstel-/build-aanroepen en onderliggende uitvoer naar stderr, zodat stdout pure JSON blijft. Onder --quietworden aanroepen onderdrukt en wordt de stille herstel-/build-uitvoer van dotnet gerouteerd naar stderr, zodat stdout schoon blijft. De uitvoer van systeemeigen AOT-publicatie gaat ook naar stderr onder een van beide opties.

Toepasselijkheid van opties: de opties voor identiteit/losse indeling (--manifestalleen voor --no-launch--output-appx-directory--unregister-on-exit--with-alias--cleanverpakte apps, ) --executablezijn van toepassing op verpakte apps. Ze worden geweigerd met een duidelijke fout voor uitgepakte apps (die geen MSIX-pakket hebben). Start-/foutopsporingsopties (--args/--, --detach, --debug-output, --symbols) --jsonwerken in beide.

voorbeelden van Project-modus:

# 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

C++-projecten (.vcxproj)

Wijs winapp run een .vcxproj map of oplossing aan waarvan alleen een runnable app is, en bouwt het project met MSBuild van Visual Studio en start het op dezelfde manier als een .NET project:

winapp run .\MyApp.vcxproj
winapp run . -c Release --arch arm64
winapp run . --no-build --detach --json

Een WinUI 3 C++/WinRT-app uit de sjabloon Visual Studio Lege WinUI-app (verpakt) wordt verpakt. Andere toepassingsprojecten, zoals een console-app of een WinUI-app die is gebouwd met -p WindowsPackageType=None, worden uitgepakt uit de ingebouwde .exeapp uitgevoerd.
Builds Debug voor de huidige architectuur standaard. --arch x64|arm64|x86 of -p Platform=x64|ARM64|Win32 selecteert de architectuur (waarbij beide met verschillende architecturen worden doorgegeven, is een fout); er wordt een aangepaste -p Platform naam doorgegeven.
Herstelt eerst de packages.config NuGet-pakketten (overslaan met--no-restore) en installeert de Windows-app Runtime-versie die ze vastmaken. Verpakte apps krijgen ook de frameworkpakketten van de buildverwijzingen, zoals de VC++-runtime voor foutopsporing, geïnstalleerd wanneer deze ontbreken.
--frameworken --aot zijn alleen van toepassing op .NET projecten.
Build-uitvoer toont alleen waarschuwingen en fouten van MSBuild, met een spinner tijdens het bouwen; --verbose toont de volledige uitvoer en exacte opdracht van MSBuild.
In een map of oplossing die ook een uitvoerbare C#-app heeft, wordt de C#-app geselecteerd; gebruiken --project <name> om de C++-app uit te voeren. C#-bibliotheken en testprojecten naast een C++-app komen niet in de weg.
Een C#-app die verwijst naar een C++-project (bijvoorbeeld een systeemeigen DLL) kan niet worden gebouwd met dotnet. Bouw het met Visual Studio of MSBuild.exevoer winapp run <app>.csproj --no-buildvervolgens de uitvoermap uit of verpakt met winapp package <folder>.

Vereisten: Visual Studio of buildhulpprogramma's voor Visual Studio 2022 versie 17.8 of hoger, met de msVC C++-buildhulpprogramma's voor de doelarchitectuur (de desktopontwikkeling met C++-workload) en de Windows SDK voor de projectdoelen. WinUI 3-apps hebben ook C++ WinUI-app-ontwikkelhulpprogramma's nodig; met verschillende installaties maakt winapp gebruik van de nieuwste installatie die het project kan bouwen. De .NET SDK is niet vereist. Wanneer de buildhulpprogramma's, platformhulpprogramma's (MSB8020) of Windows SDK (MSB8036) ontbreken, winapp run geeft u aan wat u moet installeren, inclusief een winget opdracht.

Zie het voorbeeld van de cpp-winui-app.

Modus voor één bestand (.NET op bestanden gebaseerde apps)

.NET 10 kunt u één .cs bestand zonder projectbestand uitvoeren, waarbij u het configureert met #: instructies bovenaan. Wijs winapp run het bestand aan en bouwt de app, genereert een appxmanifest voor het bestand en start het met pakketidentiteit . De app krijgt dus Windows.ApplicationModel.Package.Current een echte AUMID en een menu-item start en de API's waarvoor alleen identiteiten (app-meldingen, ApplicationDataai op het apparaat) nodig zijn.

Shell-integraties zoals protocolhandlers, bestandskoppelingen, sharedoelen en opstarttaken hebben een gedeclareerde <Extensions> vermelding nodig, die het gegenereerde manifest niet bevat. Als u er een wilt toevoegen, ontwerpt u uw eigen manifest. Zie Hieronder uw eigen manifest gebruiken.

winapp run counter.cs

Of voer het uit met gewone opmaak dotnet run . Zie Uitvoeren met dotnet run hieronder.

U maakt geen manifest. Beschrijf in plaats daarvan het pakket met #:property instructies:

#: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");

Manifesteigenschappen. Alles is optioneel; elke valt terug op een verstandige standaard:

Property	Ingesteld	Verstek
`WinAppPackageName`	`Identity/@Name` (de pakketidentiteit)	de bestandsnaam, opgeschoond naar `[-.A-Za-z0-9]`, plus een korte hash van het pad van het bestand (`counter.cs` → `counter-a1b2c3d4`)
`WinAppDisplayName`	De naam die wordt weergegeven in Start en Instellingen	de bestandsnaam zonder de extensie
`WinAppPublisher`	`Identity/@Publisher`	`CN=<your Windows user name>`. Een lege naam wordt verpakt als `CN=<name>`.
`WinAppVersion`	`Identity/@Version`	`$(Version)`, genormaliseerd (zie hieronder)
`WinAppDescription`	De beschrijving die wordt weergegeven tijdens de installatie en in Instellingen	de weergavenaam
`WinAppCapabilities`	Mogelijkheden om te declareren, gescheiden door `;` of `,`	none

Version. Een pakketversie moet exact vier nummers zijn, elk 0-65535. WinAppVersion (of, als u deze niet instelt, wordt de standaardeigenschap Version genormaliseerd om aan te passen: -preview/-rc Achtervoegsel wordt verwijderd en ontbrekende onderdelen worden gevuld met nullen, dus #:property Version=1.2.3-preview.4 wordt 1.2.3.0 en stelt u de assemblyversie en pakketversie samen. Een waarde die niet passend kan worden gemaakt ( een onderdeel boven 65535 of meer dan vier onderdelen) wordt geweigerd met een fout in plaats van op de achtergrond te wijzigen.

Capabilities

Uw app wordt volledig vertrouwd uitgevoerd met identiteit, die voldoet aan API's waarvoor alleen een verpakte app is vereist. Maar sommige API's zijn afhankelijk van een gedeclareerde mogelijkheid. De Windows AI-API's zijn echter het meest voorkomende geval. (Shell-integraties, zoals protocolhandlers en bestandskoppelingen, zijn een derde geval: deze hebben geschreven <Extensions> vermeldingen nodig, geen mogelijkheid, dus gebruik uw eigen manifest hiervoor.)

#:property WinAppCapabilities=systemAIModels

Dat is allemaal phi-silicium en de andere on-device model-API's nodig uit het manifest. Declareer verschillende door ze te scheiden:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp schrijft elke naam naar het element en de XML-naamruimte die het daadwerkelijk vereist, declareert die naamruimte en verhoogt MaxVersionTested wanneer de mogelijkheid een nieuwer nodig heeft. Dit is belangrijker dan het klinkt: de mogelijkheden zijn verdeeld over verschillende elementen en dezelfde lijst hierboven wordt drie verschillende vormen —

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

Namen die winapp kent, worden voor u geschreven. Voor alle andere dingen, de beperkte set groeit in de loop van de tijd, moet u deze kwalificeren met het voorvoegsel van de naamruimte:

voorvoegsel	Verzendt
`rescap:`	`<rescap:Capability>` — beperkte mogelijkheden
`uap:`,`uap6:`,`uap7:`,`uap11:`	`<uap*:Capability>`
`systemai:`	`<systemai:Capability>`
`device:`	`<DeviceCapability>`
`app:`	`<Capability>` in de standaardnaamruimte

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Een niet-herkende bare naam wordt geweigerd met een fout bij het benoemen van deze voorvoegsels, in plaats van te raden: een mogelijkheid die wordt verzonden in de verkeerde naamruimte produceert een manifest Windows weigert te registreren of te accepteren terwijl het op de achtergrond niet wordt verleend.

Bring Your Own Manifest

Als u iets nodig hebt dat niet door de eigenschappen wordt behandeld, zoals een protocolhandler, een bestandskoppeling, een uitvoeringsalias, maakt u een manifest en winapp run gebruikt u deze exacte bewoordingen in plaats van er een te genereren. Het wordt opgehaald uit, in volgorde:

--manifest <path> op de opdrachtregel.
#:property WinAppManifestPath=<path> in het .cs bestand.
Een manifest dat naast het .cs bestand staat, genaamd <filename>.appxmanifest (bijvoorbeeld counter.appxmanifest naast counter.cs).

Alleen die naam per bestand wordt automatisch opgehaald. Een Package.appxmanifest of appxmanifest.xml in dezelfde map wordt opzettelijk genegeerd: verschillende .cs bestanden kunnen een map delen en als u een gedeelde naam gebruikt, wordt de ene app op de achtergrond uitgevoerd onder de identiteit van een andere. Als u één manifest voor meerdere bestanden wilt gebruiken, moet u het expliciet een naam geven met --manifest of WinAppManifestPath.

Anders wordt er een Package.appxmanifest gegenereerd in de build-uitvoer, samen met de standaardinstallatiekopieënassets en vernieuwd bij elke uitvoering.

Options. Elke mapmodusoptie werkt: --no-launch, , --with-alias, --without-alias--detach, , --clean, , --symbols--args--unregister-on-exit/--executable--json----debug-output--manifest, --output-appx-directory, plus -c/--configuration, --no-builden . --no-restore-p/--property

Tip

Een console-app wordt standaard afgedrukt naar uw terminal. Een verpakte app die via AUMID wordt gestart, heeft geen console, dus een alleen-console-app zou correct worden uitgevoerd en niets afdrukken. winapp vermijdt dat: een app met OutputType=Exe wordt gestart via een uitvoeringsalias, die in plaats daarvan de stdin/stdout/stderr van deze terminal over neemt. U krijgt nog steeds pakketidentiteit en u hoeft er niet om te vragen:

winapp run counter.cs

Pass --without-alias to forceer in plaats daarvan AUMID-activering: de app wordt vervolgens uitgevoerd zonder een console en drukt hier niets af. In een gevensterde app (WinExe) wordt een venster weergegeven, waardoor AUMID-activering wordt bijgehouden. Geef --with-alias een app door als u er toch een wilt in deze terminal. Als u de keuze in het bestand wilt herstellen in plaats van op elke opdrachtregel, stelt u dezelfde eigenschap in die wordt .csproj gebruikt:

#:property WinAppRunUseExecutionAlias=false

De alias winapp declareert is vernoemd naar de familienaam van het pakket, met een winapp- voorvoegsel, dus com.contoso.counter gepubliceerd door CN=You wordt.winapp-com.contoso.counter_gspb8g6x97k2t.exe Dat volgonderdeel is de hash van de uitgever Windows afgeleid, dus twee apps die een naam delen onder verschillende uitgevers krijgen nog steeds verschillende aliassen. Het voorvoegsel houdt de naam leeg van echte opdrachten: een app python.cs krijgt een winapp-… alias, nooit python.exe. Als u uw eigen manifest maakt, wordt de alias die u declareert gebruikt as-is en winapp voegt niets toe.

Dit geldt alleen voor de alias. Registratie zelf is gekoppeld aan de pakketnaam, dus als u een tweede app uitvoert die hetzelfde WinAppPackageName declareert onder een andere uitgever, wordt de eerste registratie vervangen in plaats van ernaast te zitten. Geef elke app een eigen naam als u beide tegelijk wilt registreren.

winapp run hiermee wordt de alias afgedrukt die is geregistreerd, zodat u de hash niet hoeft te berekenen om deze te vinden.

De alias is een opdracht op uw PATH die duurt zolang het pakket geregistreerd blijft. Als een ander pakket al eigenaar is van de naam, zegt Winapp dat. Wanneer de alias voor u wordt afgeleid, wordt deze in plaats daarvan gestart via AUMID, in plaats van de verkeerde app te starten; wanneer u expliciet om een aanvraag hebt gevraagd , met --with-alias of #:property WinAppRunUseExecutionAlias=true - mislukt het in plaats van iets anders te doen.

Er zijn geen twee opties voor projectmodus van toepassing, omdat een app op basis van bestanden zichzelf configureert. Ze worden geweigerd met een bericht met de naamgeving van de instructie die in plaats daarvan moet worden gebruikt:

Option	Gebruik in plaats daarvan
`-f/--framework`	`#:property TargetFramework=net10.0-windows10.0.22621.0`
`--project`	niets — het `.cs` bestand is het project

--arch en -r/--runtime werken zoals ze doen in de projectmodus. Wanneer u ook geen winapp-builds doorgeeft voor de architectuur van uw computer, wat een zelfstandige Windows App SDK app nodig heeft, omdat zonder de SDK-builds AnyCPU en mislukt met WindowsAppSDKSelfContained requires a supported Windows architecture. Een #:property RuntimeIdentifier=win-arm64 in het bestand wordt gerespecteerd; een expliciete --arch/--runtime onderdrukking.

Verpakt en uitgepakt beide werk, gedetecteerd op basis van de effectieveWindowsPackageType, precies zoals in de projectmodus: de standaardinstelling registreert een losse indeling en start deze met identiteit, terwijl #:property WindowsPackageType=None de app wordt gebouwd, de overeenkomende Windows-app Runtime installeert en het .exe rechtstreeks start. (Er wordt een verpakte app gestart via de uitvoeringsalias of via AUMID-activering. Zie de bovenstaande consolenotitie; deze keuze staat los van of deze is verpakt.) De identiteitsopties (--no-launch, --with-alias, --without-alias, --clean, --unregister-on-exit, , ) --manifest--output-appx-directoryzijn alleen van toepassing op verpakte apps.

Wordt uitgevoerd met `dotnet run`

Je hoeft helemaal niet te typen winapp . Verwijs naar het pakket uit het Microsoft.Windows.SDK.BuildTools.WinApp bestand en zonder opmaak dotnet run geeft u dezelfde verpakte lancering:

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

De MSBuild-doelen van het pakket leiden de uitvoering om naar winapp, die pakketten, registers en lanceringen van de app die dotnet run zojuist is gebouwd, wordt niet opnieuw opgebouwd. De verwerking van manifesten is ongewijzigd: winapp lost het precies op zoals het doet, winapp rundus #:property WinAppManifestPath=… en een <filename>.appxmanifest naast de .cs beide worden gehonoreerd (zie Bring your own manifest), een mapbrede Package.appxmanifest wordt nog steeds genegeerd en anders wordt er een gegenereerd op basis van uw #:property instructies en elke uitvoering vernieuwd.

Er moeten twee voorwaarden zijn om de omleiding te laten plaatsvinden:

Directive	Waarom
`#:package Microsoft.Windows.SDK.BuildTools.WinApp@*`	de doelen die het omleidingsschip in dit pakket uitvoeren
`#:property TargetFramework=net10.0-windows…`	een gewoon `net10.0` bestand wordt alleen gelaten, dus het wordt uitgepakt

Als u het #:property WindowsPackageType=None toevoegt, dotnet run blijft het bestand ook alleen. Vervolgens wordt het .exe rechtstreeks uitgevoerd, zonder identiteit. Gebruik winapp run dit voor het uitgepakte pad als u de overeenkomende Windows-app Runtime eerst wilt installeren.

Stel #:property EnableWinAppRunSupport=false deze optie in om de omleiding volledig af te wijzen en de WinAppRun* eigenschappen die worden beschreven onder Configuratie om de lancering vorm te geven, bijvoorbeeld:

#:property WinAppRunUnregisterOnExit=true

Als dotnet run de app wordt uitgevoerd die is uitgepakt wanneer u de verwachte identiteit verwacht, vraagt u MSBuild waarom. Gebruik dotnet buildniet dotnet msbuild — alleen dotnet build het virtuele project dat door een app op basis van bestanden wordt gecompileerd:

dotnet build counter.cs -t:WinAppRunSupportInfo

Voor de modus voor één bestand is de .NET SDK 10.0.300 of hoger vereist.

De registratie overleeft de uitvoering. winapp run counter.cs laat het pakket geregistreerd nadat de app is afgesloten, precies zoals in de map- en projectmodus, dus LocalState blijft hetzelfde bestand behouden en wordt dezelfde identiteit opnieuw uitgevoerd in plaats van registraties op te stapelen. winapp zegt dat de eerste keer dat het een app registreert en winapp unregister de .cs zelf neemt:

# 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 heeft geen manifestpad nodig: hiermee worden de waarden van #:property het bestand op dezelfde manier run geëvalueerd en wordt alleen een pakket verwijderd dat is geregistreerd in de build-uitvoer van dat bestand. Een app met dezelfde naam die is geregistreerd in een andere map, wordt geweigerd, tenzij u doorgeeft --force. Als de uitvoering een optie heeft gebruikt waarmee de identiteit of de indeling wordt bepaald, geeft u dezelfde door aan 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 overschrijft de eigen instructies van het bestand en een Directory.Build.props naast de .cs kan uit- WinAppPackageName$(Configuration) of $(RuntimeIdentifier) - zodat elk van deze kan wijzigen welk pakket wordt geregistreerd.

Zodra de tijdelijke uitvoer van de SDK is opgeschoond, winapp unregister counter.cs kunt u niet meer bevestigen dat de registratie afkomstig is van dat bestand en wordt deze overgeslagen. Gebruik dit om winapp unregister --prune registraties te wissen waarvan de bestanden zijn verdwenen of --force om een specifiek bestand toch te verwijderen. Als de uitvoering wordt gebruikt --output-appx-directory, geeft u dezelfde map door zodat unregister deze de indeling kan herkennen.

Hetzelfde geldt voor een aangepast uitvoerpad: eigendom wordt bevestigd vanuit de standaardindeling <root>\bin\<configuration> van de SDK, zodat een uitvoering die is gebouwd met -p OutputPath=<somewhere-else> het bronbestand niet kan worden vergeleken. unregister slaat het over in plaats van te raden in een bredere map: geef de indeling een naam of --output-appx-directorygebruik --force.

Voorbeelden van één bestand:

# 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

Opmerking

De standaardidentiteit bevat een korte hash van het pad van het bestand , counter.cs wordt ongeveer als counter-a1b2c3d4 volgt: twee counter.cs bestanden in verschillende mappen zijn verschillende apps en behouden hun eigen instellingen en LocalState. De hash wordt afgeleid van het pad, zodat het wijzigingen en opnieuw wordt uitgevoerd en alleen wijzigingen als u het bestand verplaatst. Stel deze #:property WinAppPackageName=<name> optie in om zelf een stabiele identiteit te kiezen; het wordt genormaliseerd voor wat Identity/@Name toestaat: tekens buiten [-.A-Za-z0-9] worden verwijderd, namen korter dan 3 tekens worden opgevuld en 1het resultaat wordt beperkt tot 50 tekens, dus My App wordt geregistreerd als MyApp. In beide gevallen worden in het menu Start en Instellingen uw WinAppDisplayName (standaardnaam: de bestandsnaam) weergegeven, niet de identiteit. Identiteit is altijd afgestemd op uw gebruikersaccount, zodat deze nooit botst met een andere gebruiker op dezelfde computer.

MSBuild-eigenschappen (NuGet-pakket):

Wanneer u het NuGet-pakket Microsoft.Windows.SDK.BuildTools.WinApp gebruikt, roept dotnet run automatisch winapp run aan.

Alles dat na dotnet run is geschreven, wordt doorgegeven aan uw toepassing, precies zoals het zou zijn zonder het pakket. Configureer het startprogramma met de onderstaande MSBuild-eigenschappen:

# 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

De volgende MSBuild-eigenschappen kunnen worden ingesteld in uw .csproj om gedrag te beheren:

Property	Verstek	Beschrijving
`EnableWinAppRunSupport`	`true`	De functionaliteit van de run-ondersteuning in- of uitschakelen
`WinAppLaunchArgs`	(leeg)	Argumenten die moeten worden doorgegeven aan de app bij het starten
`WinAppRunUseExecutionAlias`	afgeleid van de app	Starten via uitvoeringsalias in plaats van AUMID-activering. Niet-gestart, winapp afgeleid het: een console-app maakt gebruik van een alias, zodat de uitvoer de terminal bereikt, een gevensterde app gebruikt AUMID. Stel `true` deze zelf in of `false` om deze zelf te bepalen.
`WinAppRunNoLaunch`	`false`	Alleen identiteit registreren zonder te starten
`WinAppRunDebugOutput`	`false`	Berichten en uitzonderingen voor de eerste kans vastleggen `OutputDebugString` . Er kan slechts één foutopsporingsprogramma tegelijk worden gekoppeld (voorkomt VS/VS Code). Gebruik `WinAppRunNoLaunch` in plaats daarvan om een ander foutopsporingsprogramma toe te voegen.
`WinAppRunDetach`	`false`	Ga onmiddellijk terug nadat de app is gestart in plaats van te wachten totdat de app is afgesloten. Hiermee drukt u de PID af.
`WinAppRunUnregisterOnExit`	`false`	De registratie van het ontwikkelpakket ongedaan maken nadat de app is afgesloten
`WinAppRunClean`	`false`	Verwijder de toepassingsgegevens van het bestaande pakket (LocalState, instellingen) voordat u het opnieuw implementeert
`WinAppRunSymbols`	`false`	Download symbolen van de Microsoft Symbol Server voor uitgebreidere systeemeigen crashanalyse. Alleen heeft een effect met `WinAppRunDebugOutput`.
`WinAppRunExecutable`	(leeg)	Uitvoerbaar pad ten opzichte van de map build-output. Gebruik deze optie wanneer het manifest bevat $targetnametoken$ en de uitvoermap meer dan één `.exe`map bevat.
`WinAppRunArgs`	(leeg)	Onbewerkte argumenten die zijn toegevoegd aan de `winapp run` opdrachtregel, voor opties zonder toegewezen eigenschap (bijvoorbeeld `--verbose`). Toegevoegd na elke eigenschap hierboven.

Wederzijds exclusieve instellingen. WinAppRunNoLaunch en WinAppRunDetach elk beschrijven een ander startgedrag, zodat ze conflicteren met de andere starteigenschappen en met elkaar. Het instellen van een conflicterend paar mislukt de uitvoering met --X and --Y cannot be used together:

Property	Kan niet worden gecombineerd met
`WinAppRunNoLaunch`	`WinAppRunDetach`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`
`WinAppRunDetach`	`WinAppRunNoLaunch`, `WinAppRunDebugOutput`, `WinAppRunUnregisterOnExit`

WinAppRunUseExecutionAlias is bewust niet in die lijst, in beide richtingen. false vraagt om AUMID-activering, die al zonder starten en loskoppelen wordt gebruikt; true wordt gewoon niet toegepast wanneer een van beide is ingesteld, omdat een uitvoeringsalias een bijgehouden, actief proces nodig heeft. Een project waarin wordt ingecheckt <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> , wordt dus nog steeds schoon uitgevoerd dotnet run -p:WinAppRunDetach=true, dat via AUMID wordt gestart in plaats van te mislukken.

WinAppRunUseExecutionAlias, WinAppRunDebugOutputen WinAppRunUnregisterOnExit kan met elkaar worden gecombineerd. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutableen WinAppLaunchArgs hebben geen beperkingen. WinAppRunArgs voegt geen beperking van zijn eigen toe, maar een switch die wordt doorgegeven, wordt gecontroleerd als elke andere, dus WinAppRunArgs="--detach" nog steeds conflicteert met WinAppRunNoLaunch.

<PropertyGroup>
  <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias>
  <WinAppRunDebugOutput>true</WinAppRunDebugOutput>
</PropertyGroup>

Unregister

Registratie van een sideloaded ontwikkelingspakket ongedaan maken. Verwijdert alleen pakketten die zijn geregistreerd in de ontwikkelingsmodus (bijvoorbeeld via winapp run of create-debug-identity). Op de store geïnstalleerde of MSIX-geïnstalleerde pakketten worden nooit verwijderd.

winapp unregister [input] [options]

Argumenten:

input- Pad naar een .NET op bestanden gebaseerde app (één.cs) waarvan het pakket moet worden opgehefd. De identiteit wordt op dezelfde manier winapp run omgezet, vanuit een geschreven manifest als de app er een heeft, anders vanuit de #:property waarden, zodat er geen manifestpad nodig is. Laat weg om een manifest in de huidige map te gebruiken --manifest of automatisch te detecteren. Kan niet worden gecombineerd met --manifest, waarmee het pakket op een andere manier wordt genoemd en kan worden omgezet in een andere.

Opties:

--manifest <path> - Pad naar Package.appxmanifest (standaard: automatisch detecteren vanuit de huidige map)
--force - Voor alleen lokale registratie slaat u de installatielocatiemapcontrole over en verwijdert u de registratie, zelfs als het pakket is geregistreerd vanuit een andere projectstructuur. Het wordt geweigerd met --on; doeleigendomscontroles kunnen niet worden overgeslagen.
--on <target> - Verwijder de overeenkomende winapp-ontwikkelingsregistratie van sandbox, niet van deze computer. Vereist een manifest en biedt geen ondersteuning --force. Zie Het opschonen van sandbox-apps.
--prune - Verwijder elke registratie in de ontwikkelingsmodus waarvan de bestanden zijn verdwenen. Kan niet worden gecombineerd met invoer, --manifest, --property, --configuration, , --arch, of --output-appx-directory--runtime.
-p, --property <Name=Value> - MSBuild-eigenschap die wordt gebruikt bij het omzetten van de identiteit van een app op basis van bestanden .cs . Herhaalbare. Geef dezelfde eigenschappen door die invloed hebben op de gebruikte uitvoering (bijvoorbeeld -p WinAppPackageName=...), omdat een opdrachtregeleigenschap de eigen #:property instructies van het bestand overschrijft. Alleen van toepassing op een .cs invoer.
-c, --configuration <name> - Bouwconfiguratie die wordt gebruikt bij het omzetten van de identiteit van een .cs app op basis van bestanden. Standaard: Debug. Geef dezelfde configuratie door die de uitvoering heeft gebruikt: een Directory.Build.props naast de .cs uitvoering kan worden ingesteld WinAppPackageName of WinAppManifestPath voorwaardelijk.$(Configuration) Alleen van toepassing op een .cs invoer.
--arch <x64|arm64|x86> - Doelarchitectuur die wordt gebruikt bij het omzetten van de identiteit van een app op basis van bestanden .cs . Standaard: de huidige procesarchitectuur. Geef dezelfde architectuur door die wordt gebruikt, omdat identiteit ook kan worden uitgeschakeld $(RuntimeIdentifier). Alleen van toepassing op een .cs invoer.
-r, --runtime <rid>- Doel-.NET runtime-id (bijvoorbeeldwin-x64) die wordt gebruikt bij het omzetten van de identiteit van een .cs app op basis van bestanden. Alleen de architectuur wordt gebruikt en overschrijft --arch. Alleen van toepassing op een .cs invoer.
--output-appx-directory <path> - De AppX-indelingsmap waaruit het pakket is geregistreerd. Alleen nodig wanneer de uitvoering werd gebruikt --output-appx-directory, omdat niets op de pakketrecords die de uitvoeringsoptie heeft geproduceerd de indeling.
--json - Uitvoer opmaken als JSON

Wat het doet:

Bepaalt de pakketnaam, van de opgeloste identiteit van het .cs bestand of door het manifest te lezen
Zoekt naar zowel {name}{name}.debug pakketten als pakketten (de foutopsporingsvariant wordt gemaakt door create-debug-identity)
Controleert of elk pakket is geregistreerd in de ontwikkelingsmodus (IsDevelopmentMode == true)
Controleert of het pakket deel uitmaakt van de app met de naam (tenzij --force) - de installatielocatie ervan moet zich bevinden onder een map die u hebt geïdentificeerd: de eigen build-uitvoer van het .cs bestand, de map van het manifest, de huidige map of een expliciete --output-appx-directory. Een pakket waarvan de installatielocatie niet kan worden opgelost (de bestanden zijn verwijderd) wordt overgeslagen, omdat de identiteit alleen geen eigendomsbewijs is: twee apps die beide dezelfde identiteit uit verschillende mappen instellen #:property WinAppPackageName=counter , registreren. Gebruik --prune dit om registraties te wissen waarvan de bestanden zijn verdwenen.
Registratie van overeenkomende pakketten ongedaan maken

Dode registraties opschonen (--prune):

Een registratie overleeft de bestanden. Verwijder een build-uitvoer, projectstructuur of (voor een app op basis van een bestand) laat Windows opschonen %LOCALAPPDATA%\Tempen het pakket blijft geregistreerd: Windows behoudt de identiteit en de vermelding van het menu Start, maar activering op de achtergrond doet niets. Deze accumuleren onzichtbaar.

# 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

Alleen registraties in de ontwikkelingsmodus worden overwogen en elk wordt verwijderd door de volledige pakketnaam, dus een hetzelfde benoemd pakket dat nog steeds vanaf een livelocatie is geïnstalleerd, blijft ongewijzigd. De prompt bestaat omdat een ontbrekende installatielocatie meestal een verwijderde map is, maar ook een pakket beschrijft dat is geregistreerd vanaf een niet-verbonden netwerkshare of een verwisselbaar station. Controleer de lijst voordat u dit bevestigt.

Voorbeelden:

# 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

Ontwikkelingscertificaten genereren, inspecteren en installeren.

certificaat genereren

Ontwikkelcertificaten genereren voor pakketondertekening.

winapp cert generate [options]

Opties:

--manifest <Package.appxmanifest>- Pak het certificaat publisher uit het manifestIdentity/@Publisher. Alleen de uitgever is vereist, dus een gedeeltelijk volledig manifest werkt nog steeds. Als het manifest geen bruikbare uitgever heeft, mislukt de opdracht in plaats van een standaardwaarde te vervangen, zodat het certificaat nooit op de achtergrond niet overeenkomt met het manifest.
--publisher <name>- Publisher voor het certificaat. Bij het genereren van een certificaat heeft deze optie voorrang op --manifest; een expliciet lege waarde mislukt in plaats van de manifestuitgever te gebruiken. Accepteert een volledige X.500 DN-naam (bijvoorbeeld CN=Contoso, O=Contoso Ltd, C=US) of een lege naam die automatisch wordt verpakt als CN=<name>. Onderdelen moeten één waarde hebben en door komma's gescheiden zijn; RDN's met meerdere waarden (CN=Foo+OU=Bar) en backslashes worden niet ondersteund omdat de MSIX-manifestuitgever deze niet kan vertegenwoordigen. Een onjuist gevormde DN-naam (bijvoorbeeld CN= of CN=A,,O=B) wordt geweigerd met een niet-nul afsluiten en een fout bij het benoemen van het probleem, in plaats van een certificaat te produceren dat nooit overeenkomt met de uitgever van het manifest.
--output <path> - Pad naar uitvoercertificaatbestand (ondersteunt absolute en relatieve paden)
--password <password> - Certificaatwachtwoord (standaard: password, dat openbaar bekend is — zie JSON-uitvoer en -beveiliging)
--valid-days <valid-days> - Aantal dagen dat het certificaat geldig is (standaard: 365)
--install - Het certificaat na het genereren installeren in het lokale computerarchief
--if-exists <Error|Overwrite|Skip> - Gedrag instellen als het certificaatbestand al bestaat (standaard: fout)
--export-cer - Exporteer een .cer bestand (alleen openbare sleutel) naast de .pfx. Handig voor het afzonderlijk distribueren van het openbare certificaat voor de installatie van vertrouwensrelaties.
--json - Uitvoer opmaken als JSON voor programmatisch verbruik. Fouten worden ook geretourneerd als JSON ({"error": "..."}).

JSON-uitvoer:

{
  "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."
  ],
  "skipped": false
}

publisher is de weergavenaam en subjectName de volledige DN-naam waaraan het certificaat is verleend. defaultPasswordIsPublic is altijd aanwezig wanneer een certificaat wordt gegenereerd. Wanneer dit het is true, wordt het .pfx beveiligd door een wachtwoord dat iedereen kan raden, dus het certificaat moet alleen builds ondertekenen die op uw eigen computers blijven- controleer het voordat een script het certificaat aan iets anders geeft. warnings draagt dezelfde openbaarmaking als tekst en wordt weggelaten wanneer er niets te melden is. publicCertificatePath wordt alleen weergegeven met --export-cer.

Wanneer --if-exists skiphet certificaatbestand al bestaat, blijft de opdracht ongewijzigd en wordt alleen het pad geretourneerd:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "skipped": true
}

Controleer skipped voordat u de andere velden leest. Voer winapp cert infohet uit om het bestaande certificaat te controleren.

certificaatgegevens

Geef certificaatgegevens weer uit een PFX- of CER-bestand. Handig om te controleren of een certificaat overeenkomt met uw manifest voordat u zich ondertekent.

winapp cert info <cert-path> [options]

Argumenten:

cert-path - Pad naar het certificaatbestand (PFX of CER)

Opties:

--password <password> - Wachtwoord voor het PFX-bestand, genegeerd voor een openbare CER (standaard: 'wachtwoord')
--json - Uitvoer opmaken als JSON

certificaat installeren

Installeer het certificaat in de certificaatopslag van de machine.

winapp cert install <cert-path> [options]

Argumenten:

cert-path - Pad naar certificaatbestand dat moet worden geïnstalleerd

Voorbeelden:

# 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

teken

Onderteken MSIX-pakketten en uitvoerbare bestanden met certificaten.

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

Argumenten:

file-path - Pad naar MSIX-pakket of uitvoerbaar bestand om te ondertekenen
cert-path - Pad naar het handtekeningcertificaat (.pfx)

Opties:

--password <password> - Certificaatwachtwoord (standaard: 'wachtwoord')
--timestamp <url> - URL van rfc 3161-tijdstempelserver

Voorbeelden:

# 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

Een bestand (exe, MSIX of MSIX-bundel) ondertekenen met behulp van Vertrouwde ondertekening van Azure: een door de cloud beheerde ondertekeningsidentiteit, dus er is nooit een persoonlijke sleutel (PFX) op de lokale computer.

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

Argumenten:

file-path - Pad naar het bestand om te ondertekenen (exe, msix of msixbundle)

Opties:

--subscription, -s - Azure abonnements-id die moet worden gebruikt. Als deze niet is opgegeven en er meerdere abonnementen bestaan, wordt u gevraagd
--resource-group, -r - Resourcegroep voor het beperken van ondertekeningsaccounts
--account - Naam van handtekeningaccount. Moet worden gebruikt met --resource-group
--profile, -p - Naam van certificaatprofiel. Moet worden gebruikt met --account
--metadata-file, -m - Pad naar een bestaande metadata.json. Slaat resourcedetectie en account-/profielselectieprompts en -profielen rechtstreeks over. Er moet al een niet-interactieve Azure referentie beschikbaar zijn; de CLI kan anders terugvallen op een interactieve tenantprompt of az login, maar de npm-programmatische API is altijd niet interactief en mislukt in plaats van vragen

Verificatie:

az-signmaakt gebruik van de standaardreferentieketen (DefaultAzureCredential) van Azure. Voor CI/CD stelt AZURE_TENANT_IDu in en AZURE_CLIENT_IDAZURE_CLIENT_SECRET (of gebruikt u GitHub Actions OIDC/beheerde identiteit). Een bestaande Azure CLI-sessie (az logininclusief de azure/login GitHub Action) wordt ook in elke omgeving gehonoreerd. Alleen als er geen referenties worden gevonden en de sessie interactief wordt az-sign voor u gestart az login .

Voorwaarden:

Een Azure-account voor ondertekening van programmacode en een certificaatprofiel (gemaakt in de Azure-portal na identiteitsvalidatie), plus de rol handtekeningcertificaatprofiel die is toegewezen aan uw identiteit. Ga voor meer informatie naar Azure quickstart voor artefactondertekening.
Er is een x64-runtime voor de hele machine .NET 8 (of hoger) geïnstalleerd. De Azure clientbibliotheek voor ondertekening is een beheerde assembly die signtool.exe in een afzonderlijk proces wordt geladen. De eigen zelf-ingesloten runtime van WinApp voldoet er niet aan. Installeer deze vanuit https://dotnet.microsoft.com/download als de ondertekening mislukt met een runtime-laadfout.
De Microsoft Visual C++ Redistributable (x64). De Azure clientbibliotheek voor ondertekening is afhankelijk van de VC++-runtime en omdat winapp het onbewerkte NuGet-pakket downloadt in plaats van het officiële installatieprogramma voor clienthulpprogramma's, wordt deze afhankelijkheid niet automatisch geïnstalleerd. Een schone machine kan zelfs met .NET en SignTool aanwezig zijn. Installeer de meest recente x64-herdistribueerbare versie als https://aka.ms/vs/17/release/vc_redist.x64.exe de ondertekening mislukt met de fout 0xc000007b'De toepassing kan niet correct worden gestart' of een dll-fout van de dlib ontbreekt.

CI met minimale bevoegdheden: Automatische detectie (met abonnementen, resourcegroepen, accounts en profielen) heeft leestoegang nodig voor een bovenliggend bereik. Als u elke aanroep voor verzamelingen wilt voorkomen, geeft u alle vier --subscriptionde , --resource-group--accounten --profileaz-sign : valideert u vervolgens het account en profiel met directe bronleesbewerkingen (een GET op elke benoemde resource) in plaats van de bovenliggende verzameling op te sommen, zodat een principal die alleen het bereik van dat account en profiel heeft, voldoende is. Als u een van deze personen weglaat, wordt een vermeldingsoproep weggelaten, bijvoorbeeld door een lijst te verlaten --subscriptionaz-sign waartoe de abonnementen waartoe uw identiteit toegang heeft, waartoe een beperkte principal mogelijk niet is toegestaan. Een principal die slechts is gericht op één certificaatprofiel, kan de validatie volledig overslaan door een vooraf gegenereerde --metadata-file validatie door te geven (waarmee het accounteindpunt en het profiel rechtstreeks worden opgegeven).

Voorbeelden:

# 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

Genereer een CodeIntegrityExternal.cat catalogusbestand met hashes van uitvoerbare bestanden uit opgegeven mappen. Deze catalogus wordt gebruikt met de vlag TrustedLaunch in MSIX sparse-pakketmanifesten (AllowExternalContent) om uitvoering van externe bestanden toe te staan die niet zijn opgenomen in het pakket zelf.

Dit is vergelijkbaar met hoe signtool.exe er wordt gemaakt AppxMetadata\CodeIntegrity.cat bij het ondertekenen van een MSIX-pakket, maar er wordt een externe catalogus gegenereerd voor gebruik met sparse/externe locatieverpakkingen.

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

Argumenten:

input-folder - Een of meer mappen met uitvoerbare bestanden die moeten worden verwerkt. Meerdere mappen scheiden met puntkomma's (bijvoorbeeld "dir1;dir2")

Opties:

--recursive, -r - Bestanden uit submappen opnemen
--use-page-hashes - Pagina-hashes opnemen bij het genereren van de catalogus (produceert een grotere catalogus met hashgegevens per pagina)
--compute-flat-hashes - Platte bestands-hashes opnemen bij het genereren van de catalogus
--if-exists <Error|Overwrite|Skip> - Gedrag wanneer het uitvoerbestand al bestaat (standaard: Error)
--output, -o - Pad naar uitvoercatalogusbestand. Als dit niet is opgegeven, CodeIntegrityExternal.cat wordt deze gemaakt in de huidige map. Als er een map is opgegeven, wordt de standaardbestandsnaam toegevoegd.

Wat het doet:

Scant opgegeven mappen voor uitvoerbare bestanden (BINAIRE PE-bestanden met codesecties)
Genereert een CATALOG Definition File (CDF) met hashes van alle gevonden uitvoerbare bestanden
Maakt gebruik van Windows CryptoCAT-API's om het .cat-catalogusbestand te produceren
Niet-uitvoerbare bestanden (bijvoorbeeld .txt, .dll zonder codesecties) worden automatisch overgeslagen

Voorbeelden:

# 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

Wanneer te gebruiken:

Gebruik deze opdracht bij het bouwen van een sparse MSIX-pakket dat TrustedLaunch gebruikt om externe uitvoerbare bestanden te verifiëren. De gebruikelijke werkstroom is:

winapp manifest generate --template sparse — Een sparse-manifest maken met AllowExternalContent
winapp create-external-catalog ./bin — Genereer de code-integriteitscatalogus voor de uitvoerbare bestanden van uw app
winapp pack — Het manifest, de assets en de catalogus verpakken in een MSIX

werktuig

Toegang tot Windows SDK-hulpprogramma's rechtstreeks. Maakt gebruik van hulpprogramma's die beschikbaar zijn in Microsoft.Windows. SDK. BuildTools

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

Beschikbare hulpprogramma's:

makeappx - App-pakketten maken en bewerken
signtool - Bestanden ondertekenen en handtekeningen verifiëren
mt - Manifesthulpprogramma voor assembly's naast elkaar
En andere Windows SDK-hulpprogramma's van Microsoft.Windows. SDK. BuildTools

Voorbeelden:

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

Handtekeningverificatie

Build-hulpprogramma's worden gedownload van NuGet en vervolgens uitgevoerd, dus winapp controleert elk hulpprogramma voor een geldige Microsoft Authenticode-handtekening direct voordat deze wordt uitgevoerd. Het certificaat moet Microsoft Corporation een naam hebben als de ondertekeningsorganisatie. Dit is van toepassing op elke opdracht die wordt uitgevoerd op een SDK-hulpprogramma, inclusief tool, packageen sign. Een hulpprogramma dat de controle mislukt, wordt niet uitgevoerd:

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

Een fout hier betekent dat het bestand op schijf niet is wat Microsoft gepubliceerd, meestal een beschadigde of gedeeltelijke download. Verwijder het pakket uit de NuGet-cache en voer de opdracht opnieuw uit, zodat winapp het opnieuw downloadt.

winapp houdt het hulpprogramma geopend zolang het wordt uitgevoerd, dus het bestand dat wordt gecontroleerd, is het bestand Windows wordt geladen. Als het hulpprogramma niet kan worden opgeslagen, wordt het niet uitgevoerd:

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

Sluit wat het bestand gebruikt ( een antivirusscan of een open editor is de gebruikelijke oorzaak ) en voer de opdracht opnieuw uit. Als het hulpprogramma is verdwenen in plaats van in gebruik, verwijdert u het pakket uit de NuGet-cache, zodat winapp het opnieuw downloadt.

store

Voer een Microsoft Store Developer CLI-opdracht uit. Met deze opdracht wordt de Microsoft Store Developer CLI gedownload als deze nog niet is gedownload. Meer informatie over de Microsoft Store Developer CLI.

winapp store [args...]

Argumenten:

args... – Argumenten die rechtstreeks aan de msstore CLI moeten worden doorgegeven. Zie de MSStore CLI-documentatie voor beschikbare opdrachten en opties.

Wat het doet:

Zorgt ervoor dat de Microsoft Store Developer CLI (msstore) is gedownload en beschikbaar is op uw systeem.
Alle argumenten doorsturen naar de msstore CLI.
Hiermee wordt de opdracht uitgevoerd met uitvoer rechtstreeks in uw terminal.

Voorbeelden:

# 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

Paden ophalen naar geïnstalleerde Windows SDK-onderdelen.

winapp get-winapp-path [options]

Wat wordt geretourneerd:

Paden naar .winapp werkruimtemap
Pakketinstallatiemappen
Gegenereerde headerlocaties

target

Voer opdrachten uit, kopieer bestanden, inspecteer de status of leg het hele gast bureaublad vast.

Elk werkwoord krijgt sandbox als eerste argument. Met uitzondering van snapshotdeze opdrachten kunt u de sandbox voorbereiden of starten. Zie Windows Sandbox-uitvoering voor vereisten, machtigingen, levenscyclus en herstel.

target exec

Voer een opdracht uit als gastgebruiker.

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

Argumenten na -- behoud van hun grenzen. Standaardstreams en de afsluitcode van het gastproces worden doorgestuurd; dit is geen volledige terminal. --json hiermee worden winapp-fouten op stderr opgemaakt zonder de stdout van de onderliggende opdracht te wijzigen. Gebruik de gestructureerde error.code indeling om een doelfout te onderscheiden van de eigen afsluitstatus van een toepassing.

Een expliciete WINAPP_UI_WORKFLOW_ID groep groepeer gastgebruikersinterfaceaanroepen die door de opdracht worden gedaan. Zie De coördinatie van de sandbox-gebruikersinterface.

doelpush en doel pull

Kopieer een bestand of map in de richting met de naam van het werkwoord.

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

Doelpaden zijn relatief ten opzichte van het beheerde werkgebied van het doel; absolute, geroote en UNC-doelpaden worden geweigerd. Een bestandsbestemming bevat de bestandsnaam. Zie Opdrachten uitvoeren en bestanden kopiëren voor mapindeling, koppelingsafhandeling en het uitvoeren van een gekopieerd script.

doelmomentopname

Gereedheid, implementaties en gastvensters rapporteren zonder een sandbox te starten.

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

Er wordt geen verbinding gemaakt met een client of een agent hersteld. Geen actieve sandbox is een geslaagd resultaat, geen fout. Zie De sandbox inspecteren voor het interpreteren van gereedheids- en proces-id's.

doelschermopname

Leg het gast bureaublad vast op de systeemeigen pixelgrootte als host PNG, zonder app-selector of hostvensterranden. --json rapporteert de oorsprong van de gastcoördinaat.

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

Gebruik ui screenshot --on sandbox -a <app> in plaats daarvan voor een app-venster. Zie schermopnamen en opnamen voor clientvereisten, focusbeperkingen en uitvoerafhandeling.

doelrecord

Noteer het gast desktop naar H.264 MP4. Hostvideo- en framebestanden komen aan nadat de opname is voltooid; JSON en het framemanifest beschrijven eventuele schaling of opvulling.

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

Gebruikt de opties voor duur, frame, overschrijven en resultaat van, maar legt het bureaublad vast in plaats van ui recordéén app. Geef de voorkeur aan een positief --duration-sec voor cli-gebruik zonder toezicht; de npm-helper vereist durationSec. Zie Sandbox-opname voor gedeeltelijke bewijs- en vastleggereedheidsfouten.

find-ui

Agent-first. find-ui is voornamelijk gebouwd voor AI-coderingsagenten. Hiermee kan een agent echte WinUI-markeringen ophalen uit de verzendgalerieën in plaats van deze uit te vinden en --json maakt elk resultaat (en elke fout) machineleesbaar. Het werkt net zo goed met de hand.

Zoek in WinUI-besturingselementen en -voorbeelden naar een voorbeeld van een werkende code. Alleen WinUI: het corpus is de WinUI 3 Gallery en de Windows Community Toolkit (plus een paar gecureerde kernpatronen) - het heeft geen betrekking op WPF, WinForms of andere UI-frameworks. Een derde bron, de reactorGallery van microsoft-ui-reactor, is opt-in: deze wordt uitgesloten van een normale zoekopdracht en wordt alleen doorzocht wanneer u passeert --source reactor (de C#-only declaratieve steekproeven plakken niet in een standaard XAML-app, dus bereik het alleen bij het bouwen van een Reactor/MVU-project).

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

De Galerie, Toolkit en Reactor corpora schip binnen de CLI, dus find-ui werkt zonder netwerktoegang, inclusief een eerste uitvoering in een agent sandbox of achter een bedrijfsproxy die blokkeert raw.githubusercontent.com. Wanneer GitHub bereikbaar is, vernieuwt de CLI ermee en slaat het resultaat per gebruiker in <global .winapp>/cache/find-uide cache op; het ingebouwde corpus is slechts een vloer, nooit een plafond. Gegevens in de cache worden maximaal elke 24 uur vernieuwd, of op aanvraag met --refresh.

Het ingebouwde corpus wordt opnieuw opgehaald uit GitHub telkens wanneer een stabiele release wordt gebouwd, en een vernieuwing die mislukt, stopt de release-build in plaats van stil oudere gegevens te verzenden- de bakker haalt via hetzelfde codepad --refresh dat wordt gebruikt, dus een fout daar betekent dat de livevernieuwing ook wordt verbroken en de moeite waard is om te onderzoeken voordat de verzending wordt verzonden. Een release kan nog steeds worden afgekapt tegen het eerder vastgelegde corpus, maar alleen als expliciete onderdrukking. Wanneer resultaten worden geleverd vanuit de ingebouwde kopie van gallery/toolkit/reactor corpora, find-ui zegt u dat op stderr en --json uitvoer ( "corpus": "embedded" andere waarden: "network" voor een nieuwe ophaalbewerking, "cache" voor de lokale cache). Een kernaanvraag ( --source coreof een --id set die alle kernpatronen is ) rapporteert "embedded" ook omdat de gecureerde kernpatronen worden gecompileerd in de CLI en nooit worden opgehaald; er wordt geen verouderingsmelding afgedrukt, omdat --refresh ze niet kunnen worden gewijzigd. Het corpus veld wordt gerapporteerd wanneer er resultaten worden geleverd; het is alleen afwezig wanneer er helemaal geen corpus kan worden geladen.

Opties:

--id <id> - Haal de code op (Galerie/Toolkit retourneert XAML en/of C#; Reactor is C#-only) plus vereistennotities voor een of meer scenario-id's van een eerdere zoekopdracht (bijvoorbeeld gallery-tabview-1). Herhaalbare. Id's zijn niet hoofdlettergevoelig , GALLERY-TABVIEW-1 lost hetzelfde op als gallery-tabview-1.
--list - Vermeld elke detecteerbare controle-/voorbeeld-id in plaats van te zoeken (Gallery + Toolkit + core; de opt-in Reactor-bron is uitgesloten).
--source <gallery|toolkit|reactor|core> - Zoekresultaten beperken tot één bron. (Alleen zoeken - niet geldig met --list/--id.) Reactor is opt-in - het wordt uitgesloten van een normale zoekopdracht, dus --source reactor is de enige manier om het te doorzoeken.
--max <N> - Maximum aantal overeenkomende besturingselementen dat moet worden geretourneerd (standaard: 3). Alleen van toepassing op zoekopdrachten; genegeerd met --list/--id.
--refresh- Sla de lokale cache over en haal het WinUI-corpus opnieuw op uit GitHub.
--json - Gestructureerde JSON verzenden (agentvriendelijk). Voor zoekopdrachten sourcebevat elke overeenkomst , control, score, descriptionen een scenarios matrix waarvan de vermeldingen het per scenario id bevatten en header; voor --id, volledige code. Onder --jsonelke fout, inclusief argument-/parserfouten, zoals een niet-geheel getal --max , wordt verzonden als een plat {"error": "..."} object op stdout met een afsluitcode die niet nul is, zodat uitvoer machineleesbaar blijft.

Werkstroom: zoek compact om het juiste besturingselement en de bijbehorende scenario-id's te vinden en haal vervolgens de volledige code op voor de beste overeenkomst met --id.

Voorbeelden:

# 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

Gerelateerd:find-ui zoekt naar WinUI-voorbeelden; gebruikt find-api om te zoeken in het API-oppervlak (typen, leden, opsommingen) van een project en winapp ui search om te zoeken in de ui-structuur van een actieve app .

find-api

Agent-first. find-api is voornamelijk gebouwd voor AI-coderingsagenten. Het genereert code in de API om een project daadwerkelijk verwijzingen te laten zien in plaats van de verzameling van het model en --json plus niet-nul afsluitcodes op ontbrekende symbolen laten een agentpoortcodegen op het antwoord zien. Het werkt net zo goed met de hand.

Zoek en inspecteer het Windows/WinRT API-oppervlak (typen, leden, opsommingen, naamruimten) die beschikbaar zijn voor een project, opgelost op basis van de metagegevens .winmd/.dll waarnaar wordt verwezen. De bare formulierzoekopdrachten; subwerkwoorden zoomen in op een specifiek type, naamruimte of de index zelf.

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

De index wordt gebouwd op basis van de herstelde NuGet/SDK-pakketten van het project (via project.assets.json) bij het eerste gebruik en automatisch vernieuwd wanneer het project wordt hersteld. Het bevindt zich onder de globale .winapp cache (cache/find-api/) en wordt gedeeld tussen projecten. Herstel eerst het project (winapp restore of dotnet restore).

Elke overeenkomst wordt vermeld onder de naamruimte met het pakket dat het verzendt en een samenvatting van wat het doet, zodat een resultaat bruikbaar is zonder een tweede members aanroep:

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

Voeg --verbose toe om ook het cachebestand op de schijf af te drukken met een back-up van elke naamruimte, wat handig is bij het diagnosticeren van een verouderde of onverwachte index.

Als u geen query uitvoert winapp find-api , wordt een kort gebruiksoverzicht 0 afgedrukt en wordt afgesloten. Het is een verzoek om hulp, geen zoekopdracht die niets heeft gevonden.

Bereiken. Elk antwoord komt uit precies één bereik, gerapporteerd als scope in --json en als opmerking in tekstuitvoer:

project - het project in de huidige map (of --project / --project-dir). Behandelt de Windows SDK, de Windows App SDK en de eigen NuGet-pakketten van het project. De Windows App SDK metagegevens zijn de release van het project: als op de computer een nieuwere Windows-app Runtime is geïnstalleerd, find-api waarschuwt u en laat u dit weg in plaats van te bevestigen dat het project niet kan worden gecompileerd op basis van typen.
sdk- de machinebrede Windows SDK + Windows App SDK metagegevens, die automatisch worden gebruikt wanneer de huidige map geen project en geen oplossing bevat. Dit maakt find-api bruikbaar voor het verkennen van API's voordat er een project bestaat en heeft geen netwerktoegang nodig. Het omvat opzettelijk geen NuGet-pakketten van derden, dus een type van (bijvoorbeeld) de Community Toolkit wordt niet gevonden in dit bereik.

Een query uit een map zonder project en geen oplossing wordt altijd beantwoord door het sdk bereik, nooit door welk project ook in de gedeelde cache moet worden geïndexeerd. De resultaten zijn dus nooit afhankelijk van een niet-gerelateerde globale status. Geef --project sdk door om het SDK-bereik expliciet te selecteren vanuit een project en winapp find-api refresh --project sdk om het opnieuw te bouwen nadat u een nieuwe Windows SDK hebt geïnstalleerd.

Oplossingsmappen. Vanuit een map met een .sln/.slnx projectbestand zonder ernaast, worden de projecten die de oplossing bouwt antwoord in plaats van het sdk bereik- ze worden geïndexeerd op aanvraag, zodat hun NuGet-pakketten worden opgenomen. Wanneer de oplossing meer dan één geïndexeerd project bouwt, worden deze door de query weergegeven en wordt er niet om gevraagd --project <name> .

Opdrachten:

(naakt)find-api "<query>" ["<query>"...] - Zoektype- en lidnamen, terugvallen op de gedocumenteerde samenvattingen, gegroepeerd op naamruimte
members <type> [<type>...] [--filter <text>] - De eigenschappen, gebeurtenissen en methoden van een type weergeven (gedeclareerde leden met handtekeningen, overgenomen leden samengevat door het type te declareren)
check-property <type> <property> [<property>...] - Controleer of er eigenschappen bestaan op een type (sluit niet-nul af als er iets ontbreekt). Een alleen-lezen eigenschap wordt gerapporteerd met ⚠^ en 'alleen-lezen, kan niet worden toegewezen' in plaats van een gewone ✅, dus een eigenschap zoals ActualWidth is niet per ongeluk voor iets dat u kunt instellen. Eigenschapsnamen worden hoofdlettergevoelig vergeleken, omdat C# en XAML zijn: check-property Button background sluit niet-nul af en biedt Background als een bijna-overeenkomst in plaats van een naam te rapporteren die u niet daadwerkelijk kunt schrijven.
enums <type> [<type>...] [--filter <text>] - De waarden van een enum vermelden (sluit niet-nul af wanneer het type geen enum is)
packages - Vermeld de geïndexeerde metagegevenspakketten, met aantal per pakkettype/leden
stats - Statistische indexstatistieken weergeven (pakketten, naamruimten, typen, leden, .winmd bestanden)
refresh [--scan] - Herbouw de index voor een project (--scan indexeert elk project onder de map). Met --project <name>een naam die overeenkomt met geen enkel geïndexeerd project mislukt in plaats van de huidige map te indexeren.

Batching.search, membersen enumscheck-property accepteer meerdere onderwerpen in één aanroep. Voor een AI-agent is dit de enige grootste kostenhendel: de marginale kosten van een zoekopdracht worden gedomineerd door de retour (elke oproep verzendt het hele gesprek opnieuw), niet door de grootte van de nettolading, dus één oproep die tien vragen beantwoordt, is veel goedkoper dan tien oproepen.

Eén onderwerp retourneert precies de nettoladingshape die het altijd heeft, in zowel tekst als --json.
Twee of meer onderwerpen retourneren een envelop, { "count": N, "results": [ ... ] } waarbij --jsonelk element de normale nettolading met één onderwerp is; check-property voegt toe missingCount. Tekstuitvoer geeft elk onderwerp op volgorde weer onder één bereikkop.
check-property batches-eigenschappen voor één type: het eerste argument is het type, elk argument nadat het een eigenschap is. In de batchmodus wordt een eigenschap die bestaat één ✅ regel afgedrukt. Volledige bijna-gemiste details worden alleen afgedrukt voor degenen die dat niet doen.
Een batch wordt alleen afgesloten 0 als elk onderwerp is opgelost en is gevonden, zodat een batch nog steeds veilig is om codegen aan te sluiten.

Zoekrangschikking. Een query die exact overeenkomt met een typenaam wordt vóór gedeeltelijke overeenkomsten gerangschikt en wanneer een korte naam wordt gedeeld door verschillende naamruimten, worden alleen de conflicten met exacte namen als dubbelzinnig weergegeven. Een query rapporteert NavigationView bijvoorbeeld de handvol naamruimten die dat type definiëren in plaats van elke naamruimte die een soortgelijk symbool bevat. De dubbelzinnigheidslijst gehoorzaamt --maxen de normale resultaten worden er nog steeds onder afgedrukt.

Typ namen.members, check-propertyen enums accepteer een korte naam (NavigationView) of een volledig gekwalificeerde (Microsoft.UI.Xaml.Controls.NavigationView). Wanneer een korte naam wordt gedeeld door een modern Microsoft.* type en de verouderde Windows.* UWP-dubbel, wordt het Microsoft.* type antwoorden ( dat is de projectie die een Windows App SDK app gebruikt) en wordt de opgeloste volledig gekwalificeerde naam altijd weergegeven. Elke andere botsing verlaat niet-nul en vermeldt de kandidaten in plaats van te raden.

Methodehandtekeningen. Een handtekening wordt afgedrukt zoals u de aanroep zou schrijven: een methode die u aanroept voor het type in plaats van bij een exemplaar, en er wordt een by-reference-parameter weergegeven staticmet het trefwoord dat het daadwerkelijk nodig heeft , outof inref. Leesbewerkingen TryGetValueBoolean TryGetValue(String key, out String value), die als geschreven worden gecompileerd.

Opties:

--max <n> - Maximum aantal met naamruimte gegroepeerde zoekresultaten (standaard 5; alleen zoeken). De dubbelzinnigheidslijst wordt ook niet gebruikt, dus een korte query die in meerdere naamruimten botst, blijft leesbaar.
--filter <text> - Een vermelding beperken op members en enums: een niet-hoofdlettergevoelige subtekenreeksovereenkomst voor de naam van het lid/de waarde. Het meest geschikt voor typen met honderden leden. De meeste enums zijn klein genoeg om geheel te dumpen (zelfs Symbol, de grootste in WinUI bij 197 waarden), dus het filteren kost meestal meer dan het bespaart zodra u een tweede schatting. Voer nooit dezelfde opdracht met andere filtertekst opnieuw uit: dump één keer en lees deze.
--all members- Geef het volledige oppervlak weer: volledige handtekeningen voor overgenomen leden, plus statics van afhankelijkheidseigenschaps-id's en beschrijvingen per lid, waarvan allemaal een niet-gefilterde vermelding weglaat (zie Vermeldingsgrootte hieronder). --verbose impliceert het; gebruik --all wanneer u ook wilt --json, wat niet kan worden gecombineerd met --verbose.
--scan - Recursief elk project onder de map detecteren en indexeren (refresh alleen)
--project <name>- Project om een query uit te voeren (komt overeen met de .csproj/.vcxproj naam) of sdk om een query uit te voeren op het Windows SDK-bereik van de machine
--project-dir <path>- Project map om een query uit te voeren (standaard ingesteld op de huidige map). Een pad dat niet bestaat, is een fout. Het wordt nooit op de achtergrond beantwoord vanuit het sdk bereik.
--json - Een door de machine leesbare nettolading verzenden op stdout (ondersteund door elk werkwoord). Querypayloads identificeren de index die wordt beantwoord via scope (project of sdk), projectNameen projectDir (afwezig voor het SDK-bereik) - projectnamen zijn niet uniek in mappen, dus projectDir is de betrouwbare identiteit. Onder --jsonelke fout, inclusief argument-/parserfouten, zoals een niet-geheel getal --max , wordt verzonden als een plat {"error": "..."} object op stdout met een afsluitcode die niet nul is, zodat uitvoer machineleesbaar blijft.

Voorbeelden:

# 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

Wanneer --filter deze wordt toegepast, rapporteert de uitvoer nog steeds het niet-gefilterde totaal (totalValuesoftotalEvents//totalPropertiestotalMethods in--json), zodat een smalle weergave nooit wordt verward met een kleine API. Een filter dat overeenkomt met niets wordt 0 nog steeds afgesloten en zegt dat expliciet, dat is 'niets overeenkomt met uw filter', niet 'geen dergelijk type'.

Lijstgrootte. Een niet-gefilterde members vermelding is de ene dure vorm: members Button omvat 288 leden, waarvan 280 worden overgenomen van 6 basistypen. Een niet-gefilterde aanroep is een afdrukquery ('wat is dit type, ruwweg wat kan het doen?'), zodat het antwoord geeft dat en de onderdelen weggelaten worden waaruit niets is geschreven:

Overgenomen ledenhandtekeningen : overgenomen leden worden gegroepeerd door alleen het type te declareren en op naam te vermelden, zodat de vorm van het overgenomen oppervlak nog steeds zichtbaar is zonder 280 volledige handtekeningen.
Afhankelijkheids-id statics (BackgroundProperty) — 28% van de eigenschappen van een typisch WinUI-besturingselement. Ze moeten worden doorgegeven aan GetValue/SetValue, niet toegewezen.
Beschrijvingen per lid: de XML-doc prose, ongeveer 16% van de nettolading.
Velden die worden geïmpliceerd door hun omgeving in --json: kind (impliciet door de matrix/eventsproperties/methods), returnType (het voorlooptoken van signature) en inherited wanneer ze onwaar zijn (impliciet door).declaringType

Wat is weggelaten, wordt altijd gerapporteerd (hiddenDependencyPropertiesdescriptionsOmitteden een hint in--json; een regel 'Weggelaten:') en totalen beschrijven nog steeds het hele type. Zowel --filter als --all u het volledige oppervlak met volledige handtekeningen en beschrijvingen ziet, vindt members Button --filter BackgroundProperty u de id nog steeds en members Button --filter Click retourneert Clicku nog steeds de overgenomen handtekening. Gemeten op samples/winui-app, dit duurt members Button --json van 91.954 tot 10.567 tekens (−88,5%) tijdens het verlaten --filter en --all byte-identiek.

Hoe een query overeenkomt. winapp find-api "language model" rangschikt LanguageModel bovenstaande overeenkomsten waarvan de woorden worden verspreid over naamruimten en leden, inclusief buiten een project wanneer het type wordt geïndexeerd. Zoeken is lexical, niet semantisch: het komt overeen met hele id-woorden in plaats van een willekeurige reeks letters, dus llm vindt IImageLLMAdapterSession maar niet ScrollMode. Wanneer een query overeenkomt met geen naam, wordt deze geprobeerd op basis van de gedocumenteerde samenvattingen van typen en leden, wat kan "random-access stream" worden gevonden IRandomAccessStream. Beschrijvingen rangschikken onder elke naamovereenkomst en alleen samenvattingen van de pakketten die daadwerkelijk worden verzonden, zijn doorzoekbaar. Een pakket zonder XML-documentatie draagt geen beschrijvingstekst bij.

Projecten zonder MSBuild-projectbestand. Een Electron-app (of een andere niet-.NET app aangestuurd door winapp.yaml) heeft geen .csproj en dus geen project.assets.json. find-api indexeert het van de .winapp/winmds.lock.json schrijfbewerking winapp restore , die hetzelfde registreert: elk opgelost pakket, de bijbehorende versie en de .winmd bestanden die het bijdraagt. Een dergelijk project wordt vernoemd naar de map en de index is verlopen wanneer het vergrendelingsbestand opnieuw wordt geschreven. Een map waarin zowel een als .csproj een winapp.yaml map is geïndexeerd, .csprojwat de preciezere beschrijving is van waarop het project wordt gecompileerd.

Negatieve antwoorden worden gekwalificeerd wanneer de index onvolledig is. Als de metagegevens van een pakket niet kunnen worden gelezen, ziet 'geen dergelijk type' en 'dat pakket is nooit geïndexeerd' er identiek uit en werkt het eerst wanneer het echt de tweede code genereert op basis van een API die u hebt verteld, niet bestaat. Elk negatief antwoord, inclusief een search antwoord dat nulresultaten retourneert, bevat dus een opmerking dat de index gedeeltelijk is en verwijst naar winapp find-api refresh. Positieve antwoorden worden niet beïnvloed.

Algemene typenamen. Met metagegevens worden algemene typen opgeslagen met een arity-achtervoegsel (IAsyncOperation`1). Dit is niet hoe iemand ze schrijft. members, enumsen check-property accepteer elk formulier: IAsyncOperation, IAsyncOperation<StorageFile>en IAsyncOperation`1 alle worden omgezet in hetzelfde type. Een lege naam komt overeen met elke arity; een vermelde arity (in beide notaties) moet overeenkomen, dus Holder<A, B> wordt niet omgezet in één parameter Holder<T>.

--json nettoladingen laten diagnostische gegevens weg. Cachebestandspaden worden alleen weergegeven onder --verbose (overeenkomende tekstuitvoer, waarbij ze al uitgebreid waren) en lege suggestiematrices worden weggelaten in plaats van geserialiseerd als [].

Afsluitcodes:search zonder treffers, check-property bij een ontbrekende eigenschap en enums op een niet-enum typt u alle afsluit-niet-nul- en CI-controles op deze. Een batchgewijze aanroep sluit niet-nul af als een onderwerp mislukt. Een eigenschap met het kenmerk Alleen-lezen is geen fout; deze bestaat, dus check-property sluit 0 deze af en markeert deze in de uitvoer (writable: false in --json). Een init eigenschap rapporteert writable: false om dezelfde reden: deze kan worden ingesteld in een object-initialisatiefunctie, en de handtekening zegt { get; init; }, maar als u deze later toewijst, wordt deze niet gecompileerd.

Gerelateerd:find-api antwoorden 'bestaat deze API en wat zijn de leden?'; gebruikt find-ui om een werkend WinUI-voorbeeld voor een besturingselement te vinden.

knooppunt genereren-bindingen

(Alleen beschikbaar in NPM-pakket) JS-bindingen genereren voor Windows App SDK API's. De bindingen worden gedeclareerd door een "winapp": { "jsBindings": {...} } naamruimte in package.json en geschreven naar .winapp/bindings/.

npx winapp node generate-bindings [options]

Opties:

--verbose, -v - Uitgebreide uitvoer per bestand codegen inschakelen
--quiet, -q - Voortgang en informatieve uitvoer onderdrukken

Wat het doet:

Leest het winapp.jsBindings blok van package.json en de winmds.lock.json geschreven door de laatste winapp restore, en verzendt vervolgens getypte .js + .d.ts bindingen naar .winapp/bindings/
Wijzigt nietpackage.json - het is een passieve regenerator. Het toevoegen van het winapp.jsBindings blok en de @microsoft/dynwinrt runtime-afhankelijkheid vindt plaats wanneer winapp init JS-bindingen zijn ingeschakeld. Deze opdracht mislukt snel als het blok afwezig is
Waarschuwt (maar schrijft niet) als @microsoft/dynwinrt deze ontbreekt in uw afhankelijkheden. Voer deze uit npm install nadat init deze is toegevoegd

Opmerking

Bindingen zijn alleen npm- ze vereisen aanroepen via npx winapp (het npm-pakket); de @microsoft/winappcli zelfstandige winget CLI maakt ze niet zichtbaar. Voer interactief uit winapp init en meld u aan voordat u deze opdracht gebruikt winapp init . --use-defaults --add-js-bindingsom bindingen opnieuw te genereren. Als u bewerktwinapp.yaml, voert u de opdracht uit npx winapp restore om Windows afhankelijkheden te vernieuwen voordat u opnieuw gaat genereren.

Voorbeelden:

# 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

Zie de handleiding voor JS-bindingen voor de end-to-end-werkstroom en de winapp.jsBindings configuratieopties.

node uitbreiding-aanmaken

(alleen beschikbaar in NPM-pakket) Systeemeigen C++ of C#-invoegtoepassingssjablonen genereren met Windows SDK en Windows App SDK-integratie.

npx winapp node create-addon [options]

Opties:

--name <name> - Naam van invoegtoepassing (standaard: "nativeWindowsAddon")
--template - Selecteer het type invoegtoepassing. Opties zijn cs of cpp (standaard: cpp)
--verbose - Uitgebreide uitvoer inschakelen

Wat het doet:

Maakt een map voor invoegtoepassingen met sjabloonbestanden
Genereert binding.gyp en addon.cc met Windows SDK-voorbeelden
Installeert vereiste npm-afhankelijkheden (nan, node-addon-api, node-gyp)
Hiermee voegt u een buildscript toe aan package.json

Voorbeelden:

# Generate addon with default name
npx winapp node create-addon

# Generate custom named addon
npx winapp node create-addon --name myWindowsAddon

knooppunt add-electron-debug-identity

(Alleen beschikbaar in NPM-pakket) Voeg app-identiteit toe aan het Electron-ontwikkelingsproces met behulp van sparse-pakketten. Vereist een Package.appxmanifest (maak er een met winapp init of winapp manifest generate als u er nog geen hebt).

Belangrijk

Er is een bekend probleem met sparse packaging Electron-toepassingen die ervoor zorgen dat de app vastloopt bij het starten of niet genereren van de webinhoud. Het probleem is opgelost in Windows, maar het is nog niet doorgegeven aan externe Windows apparaten. Als u dit probleem ziet na het aanroepen add-electron-debug-identity, kunt u sandboxing in uw Electron-app uitschakelen voor foutopsporingsdoeleinden met de --no-sandbox vlag. Dit probleem heeft geen invloed op volledige MSIX-pakketten.

Als u de Electron-foutopsporingsidentiteit ongedaan wilt maken, gebruikt u winapp node clear-electron-debug-identity.

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

Opties:

Option	Beschrijving
`--manifest <path>`	Pad naar aangepast Package.appxmanifest (standaard: Package.appxmanifest in de huidige map)
`--no-install`	Installeer of wijzig geen afhankelijkheden; alleen de Electron-foutopsporingsidentiteit configureren
`--keep-identity`	Houd de manifestidentiteit zoals het is, zonder `.debug` toe te voegen aan de pakketnaam en toepassings-ID.
`--verbose`	Uitgebreide uitvoer inschakelen

Wat het doet:

Registreert foutopsporingsidentiteit voor electron.exe proces
Maakt het testen van identiteits-vereiste API's in Electron-ontwikkeling mogelijk
Maakt gebruik van bestaand Package.appxmanifest voor identiteitsconfiguratie

Voorbeelden:

# 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

knooppunt clear-electron-debug-identity

(Alleen beschikbaar in NPM-pakket) Verwijder pakketidentiteit uit het electron-foutopsporingsproces door de oorspronkelijke electron.exe te herstellen uit de back-up.

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

Opties:

Option	Beschrijving
`--verbose`	Uitgebreide uitvoer inschakelen

Wat het doet:

Herstelt electron.exe van de back-up die is gemaakt door add-electron-debug-identity
Verwijdert de back-upbestanden na herstel
Retourneert Electron naar de oorspronkelijke staat zonder pakketidentiteit

Voorbeelden:

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

Algemene opties

Alle opdrachten ondersteunen deze algemene opties:

--verbose, -v - Uitgebreide uitvoer inschakelen voor gedetailleerde logboekregistratie
--quiet, -q - Voortgangsberichten onderdrukken
--help, -h - Help voor opdrachten weergeven

Globale cachemap

Winapp maakt een map voor het opslaan van bestanden die kunnen worden gedeeld tussen meerdere projecten.

Winapp maakt standaard een map op $UserProfile/.winapp als de globale cachemap.

Als u een andere locatie wilt gebruiken, stelt u de WINAPP_CLI_CACHE_DIRECTORY omgevingsvariabele in.

In cmd:

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

In PowerShell en pwsh:

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

Winapp maakt deze map wanneer een opdracht deze eerst nodig heeft.

Wanneer winapp niet kan schrijven naar de globale cachemap

Sommige omgevingen, zoals agent-sandboxes die alleen schrijfbewerkingen naar het huidige project toestaan, blokkeren de toegang tot %USERPROFILE%\.winapp. De meeste opdrachten werken nog steeds en de updatecontrole wordt overgeslagen. Als winapp de eerste uitvoering in die map niet heeft voltooid, drukt elke uitvoering ook een telemetriemelding met één regel af op stderr.

Deze opdrachten moeten naar de cachemap schrijven en stoppen met een fout die het pad een naam geeft:

Command	Wat er wordt geschreven
`find-api`	De API-index, wanneer deze moet worden gebouwd of vernieuwd. Een bestaande, up-to-datumindex wordt nog steeds gelezen.
`store`	De Microsoft Store Developer CLI, de eerste keer dat deze is geïnstalleerd.

U kunt dit probleem oplossen door in te stellen WINAPP_CLI_CACHE_DIRECTORY op een map-winapp waarnaar kan worden geschreven (bijvoorbeeld één in uw project) en het vervolgens opnieuw proberen.

winapp ui opdrachten houden hun turn-taking status in %USERPROFILE%\.winapp\state\ui. Als ze er geen toegang toe hebben, worden ze nog steeds uitgevoerd, maar zonder te wachten op andere winapp ui opdrachten op hetzelfde bureaublad en één waarschuwing (weggelaten met --json of --quiet). Vermijd het tegelijkertijd uitvoeren van andere winapp ui opdrachten op dat bureaublad.

Windows Sandbox-opdrachten hun status behouden%USERPROFILE%\.winapp\state. Als deze map niet schrijfbaar is, stoppen ze met sandbox_state_unavailable de variabele en geven ze de naam die u wilt instellen.

Updatecontroles

De winapp CLI controleert regelmatig op nieuwe versies en geeft een melding van één regel weer wanneer er een update beschikbaar is. Deze controle wordt op de achtergrond uitgevoerd en voegt geen latentie toe aan opdrachten.

Updatecontroles worden automatisch uitgeschakeld in CI-omgevingen (GitHub Actions, Azure-pipelines, enzovoort).

Als u updatecontroles handmatig wilt uitschakelen, stelt u de WINAPP_CLI_UPDATE_CHECK omgevingsvariabele in op 0.

In cmd:

set WINAPP_CLI_UPDATE_CHECK=0

In PowerShell en pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

Ga als volgt te werk om dit permanent te maken:

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

Ui-werkstroomidentiteit

winapp ui opdrachten die het fysieke bureaublad stimuleren, nemen altijd coöperatieve beurten, dus twee werkstromen die tegelijk worden uitgevoerd, kunnen elkaars focus niet stelen of elkaars menu's sluiten. Deze arbitrage heeft geen instelling nodig en kan niet worden uitgeschakeld.

Wat optioneel is, is continuïteit. Standaard is elke opdracht een zelfstandige opdracht die het bureaublad vrijgeeft zodra deze is voltooid. Als u het bureaublad over verschillende opdrachten wilt houden, geeft u ze allemaal dezelfde werkstroom-id:

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

Gebruik dezelfde waarde voor samenwerkende processen (bijvoorbeeld een opname en de klikken die erop moeten worden vastgelegd) en verschillende waarden voor onafhankelijke werkstromen. Elke opdracht zonder id is een eigen werkstroom met één opname, zelfs wanneer er meerdere worden gestart vanuit één shell, zodat hosts die een nieuwe shell per opdracht starten, dezelfde expliciete waarde in elke shell moeten invoeren. De waarde is ondoorzichtig, wordt nooit behandeld als referentie en wordt alleen bewaard als een SHA-256-hash. Zie UI Automation → Gelijktijdige UI-werkstromen coördineren.

gebruikersinterface

Inspecteer en communiceer met het uitvoeren van Windows app-API's met behulp van UI Automation (UIA). Uitvoeren winapp ui --help voor de kernwerkstroom. Zie UI-automatisering voor de volledige handleiding.

winapp ui [command] [options]

Opdrachten:

status - Verbinding maken met app en informatie weergeven
inspect - Elementstructuur weergeven
search - Elementen zoeken op selector
get-property - Eigenschappen van element lezen
get-text / get-value - Waarde/tekst lezen van element (TextPattern, ValuePattern of Name)
screenshot - Venster/element vastleggen als PNG (meerdere vensters vormen één gelabelde samengestelde PNG; zie bereik vastleggen)
record- Neem een venster-/elementregio op naar een H.264 MP4-video (Windows Graphics Capture + Media Foundation)
invoke - Element activeren (klik, wisselknop, uitvouwen); --action selecteert een exacte bewerking (zie aanroepen)
click - Klik op element via muissimulatie (voor besturingselementen die geen ondersteuning bieden voor aanroepen)
hover - Beweeg de muis naar het element om knopinfo, flyouts en aanwijsstatussen te activeren (standaardbewoner: 800 ms)
drag - Sleep de muis van het ene punt naar het andere, op elementkiezer of schermcoördinaten x,y (de volgorde wijzigen, het formaat wijzigen, schuifregelaars, slepen en neerzetten)
touch- Synthetische aanraakbewegingen injecteren (tikken, dubbeltikken, lang drukken, swipen, knijpen, uitrekken) op een elementcentrum of schermcoördinaten x,y
pen - Injecteer synthetische pen-/stylusinvoer - tikken en pennenstreken met configureerbare druk-, kantelen- en gummodus
send-keys - Stuur synthetische toetsenbordinvoer (benoemde toetsen, combinaties, onbewerkt vk=0xNN of letterlijke tekst) naar een venster
set-value - Waarde instellen voor bewerkbaar element (tekst, getal); valt terug naar LegacyIAccessible put_accValue voor besturingselementen voor rich-edit van TextPattern
focus - Focus van toetsenbord verplaatsen
scroll-into-view - Schuifelement zichtbaar
wait-for - Wacht op elementstatus
list-windows - Alle vensters voor een app weergeven
get-focused - Het momenteel gerichte element rapporteren
yield - Laat de gebruikersinterface van de huidige werkstroom los; vereist WINAPP_UI_WORKFLOW_ID

Opties:

-a, --app <app> - Doel-app (naam, titel of PID)
-w, --window <hwnd> - Doelvenster door HWND (stabiel)
--on <target> - Voer een ui werkwoord uit; sandboxnamen, PID's en venstergrepen verwijzen naar de gast. Uitvoer wordt geleverd aan de host. Zie Sandbox UI-automatisering voor installatie, werkstroomcoördinatie en clientvereisten.
--type, , --root--class-name - Een selector beperken voor de opdrachten die worden vermeld in Scoped en getypte query's

ui-record

Noteer een venster of elementgebied naar een 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

Recordopties:

--duration-sec <n> - Opnamelengte in seconden. 0 records tot Ctrl+C (standaard 0).
--fps <n> - Frames per seconde om vast te leggen (standaard 15).
--max-edge <px> - Omlaag schalen zodat de langste rand maximaal zoveel pixels (0 = geen downscale) is.
--capture-screen - Vastleggen vanaf het scherm, zodat overlays/pop-ups zijn opgenomen (kan occluding vensters vastleggen).
-o, --output <path> - Uitvoerpad .mp4 (standaard ingesteld recording-<timestamp>-<guid>.mp4op).
--overwrite - Bestaande opname-uitvoer vervangen nadat de nieuwe uitvoering is voltooid; bestaande uitvoer wordt standaard geweigerd. Eerdere framebundels worden bewaard. Zie Herstel van opname-uitvoer.
--frames - Schrijf tijdstempel JPEG's, frames.ndjsonen manifest.json naar <output-name>.frames. Ondersteunt 1-30 fps en --max-edge 64-4096 (standaard 1280), met een 1 GiB frame-data cap.

Met --jsonhet uiteindelijke resultaat bevat het uitvoerpad, dimensies, codec, opnamemodus, frequentie, reden voor stoppen, optioneel frameArtifactsen waarschuwingen.

Zie docs/ui-automation.md voor volledige documentatie.

Feedback

Is deze pagina nuttig?

Laatst bijgewerkt om 2026-10-08

CLI-documentatie en -gebruik

Versie

Shell-voltooiing

init

Nieuw

herstellen

update

pack

Een project rechtstreeks verpakken

Sparse-identiteitspakketten

WinRT-onderdeeldetectie

Bundels met meerdere architectuur

create-debug-identity

insluitidentiteit

manifesteren

manifest genereren

Plaatsaanduidingen van het manifest

manifest add-alias

manifest bijwerken-assets

run

Project modus (.NET SDK-projecten)

C++-projecten (.vcxproj)

Modus voor één bestand (.NET op bestanden gebaseerde apps)

Capabilities

Bring Your Own Manifest

Wordt uitgevoerd met dotnet run

Unregister

cert

certificaat genereren

certificaatgegevens

certificaat installeren

teken

az-sign

create-external-catalog

werktuig

store

get-winapp-path

target

target exec

doelpush en doel pull

doelmomentopname

doelschermopname

doelrecord

find-ui

find-api

knooppunt genereren-bindingen

node uitbreiding-aanmaken

knooppunt add-electron-debug-identity

knooppunt clear-electron-debug-identity

Algemene opties

Globale cachemap

Wanneer winapp niet kan schrijven naar de globale cachemap

Updatecontroles

Ui-werkstroomidentiteit

gebruikersinterface

ui-record

Feedback

Aanvullende resources

Wordt uitgevoerd met `dotnet run`