CLI-documentatie en -gebruik

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: huidige map)
  • --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
  • 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 sjabloonnaam (bijvoorbeeld winui, winui-navview, winui-mvvm, , winui-lib, ). winui-unittest Gevalideerd op basis van het geïnstalleerde pakket tijdens runtime; voer alles uit winapp new --list om alles te zien. Standaard: winui (lege 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 installeert het nieuwste gepubliceerde pakket, installed houdt alles wat 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:

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. Algemene sjablonen:

Korte naam Beschrijving
winui Minimaal lege WinUI 3-app (MSIX-verpakking)
winui-navview Navigatieweergave starter-app
winui-tabview TabView starter-app
winui-mvvm MVVM-app (CommunityToolkit.Mvvm)
winui-lib WinUI 3-klassebibliotheek
winui-unittest Verpakte MSTest-app; tests worden uitgevoerd wanneer deze wordt gestart

De canonieke korte naam van elke sjabloon is de eerste aliaslijstendotnet new. Elke vermelde alias (bijvoorbeeld winui3wasdk-single) wordt ook geaccepteerd. 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 te gebruiken zonder te vragen of --template-version installed om altijd het gedownloade pakket 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.

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

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

Opties:

  • --config-dir <path> - Map met winapp.yaml (standaard: huidige map)

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 die zijn geïnitialiseerd met winapp init, is er geen winapp.yaml. Gebruik dotnet restore in plaats daarvan om NuGet-pakketten te herstellen.

Voorbeelden:

# Restore from winapp.yaml in current directory
winapp restore

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
  • Alle pakketten bijwerken naar de nieuwste beschikbare versies
  • 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 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 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 - 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
  • --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$ .

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.

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:

  1. Als --executable dit is opgegeven (pad ten opzichte van de invoermap), wordt de tijdelijke aanduiding vervangen door de opgegeven waarde
  2. winapp pack Anders scant u de hoofdmap van de invoermap voor .exe bestanden, als er precies één wordt gevonden, wordt deze automatisch gebruikt
  3. 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:

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

  2. Manifest per map : als elke invoermap een Package.appxmanifest (of appxmanifest.xml) bevat, wordt het manifest van die map gebruikt voor het segment.

  3. 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 elke geldige X.500 DN; 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:

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.

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 twee modi, die automatisch worden gekozen op basis van de invoer:

  • Mapmodus : de invoer is een build-output-map (bevat een Package.appxmanifest/AppxManifest.xml).
  • Project-modus: de invoer is een.csproj, een .sln/.slnx oplossing of een map die een map bevat. winapp run bouwt het project en start het, ter ondersteuning van zowel verpakte als uitgepakte WinUI-apps. Zie Project onderstaande modus.

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/.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/.slnx/.slnmet 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 build-outputmap (mapmodus), een .csproj 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 het losse indelingspakket (standaard: AppX in de map invoermap)
  • --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. Vereist een uap5:ExecutionAlias in het manifest (gebruik winapp manifest add-alias om er een toe te voegen). Kan niet worden gecombineerd met --no-launch. Kan niet worden gecombineerd met --json.
  • --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.
  • --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. Hiermee drukt u de PID af op stdout (of in JSON met --json). 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.

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

Project-modusopties (genegeerd in de mapmodus):

  • -c, --configuration <name> - Configuratie bouwen. Standaard: Debug.
  • --arch <x64|arm64|x86> - Doelarchitectuur. Standaard: de huidige procesarchitectuur. Bepaalt zowel de build-RID als de architectuur van de Windows-app Runtime die wordt geïnstalleerd.
  • -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.
  • -f, --framework <tfm> - Doelframework moniker voor projecten met meerdere doelen (bijvoorbeeld net10.0-windows10.0.26100.0).
  • --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).
  • --no-build - Sla het bouwen over en voer de bestaande build-uitvoer uit (evalueert nog steeds uitvoereigenschappen).
  • --no-restore - Sla het herstellen van het project over voordat u gaat bouwen.
  • -p, --property <Name=Value> - MSBuild property, doorgestuurd naar zowel de build als de evaluatie van de eigenschap. Herhaalbaar (bijvoorbeeld -p WindowsPackageType=None).

Build-uitvoer en uitgebreidheid: het project is gebouwd in twee stappen: een dotnet build waarvan de uitvoer live naar uw console streamt , gevolgd door een snelle evaluatie van eigenschappen. winapp drukt de exacte dotnet build … aanroep af vóór de uitvoer en streamt waarschuwingen zelfs bij een geslaagde build. Uitgebreidheid:

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

Ga onder --json of --quiet de aanroep- en build-uitvoer naar stderr, zodat stdout pure JSON/schoon blijft.

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

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

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

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

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

MSBuild-eigenschappen (NuGet-pakket):

Wanneer u het NuGet-pakket Microsoft.Windows.SDK.BuildTools.WinApp gebruikt, roept dotnet run automatisch winapp run aan. 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 false Starten via uitvoeringsalias in plaats van AUMID-activering
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 .exemap 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,WinAppRunUseExecutionAlias,WinAppRunDebugOutput,WinAppRunUnregisterOnExit
WinAppRunDetach WinAppRunNoLaunch,WinAppRunUseExecutionAlias,WinAppRunDebugOutput,WinAppRunUnregisterOnExit

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

Opties:

  • --manifest <path> - Pad naar Package.appxmanifest (standaard: automatisch detecteren vanuit de huidige map)
  • --force - Sla de installatielocatiemapcontrole over en hef de registratie op, zelfs als het pakket is geregistreerd vanuit een andere projectstructuur
  • --json - Uitvoer opmaken als JSON

Wat het doet:

  • Leest de pakketnaam uit het manifest
  • 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 de installatielocatie van het pakket zich onder de huidige mapstructuur bevindt (tenzij --force)
  • Registratie van overeenkomende pakketten ongedaan maken

Voorbeelden:

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

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

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

# JSON output for scripting
winapp unregister --json

cert

Ontwikkelingscertificaten genereren, inspecteren en installeren.

certificaat genereren

Ontwikkelcertificaten genereren voor pakketondertekening.

winapp cert generate [options]

Opties:

  • --manifest <Package.appxmanifest> - Uitgeversinformatie extraheren uit Package.appxmanifest
  • --publisher <name>- Publisher voor het certificaat. 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>
  • --output <path> - Pad naar uitvoercertificaatbestand (ondersteunt absolute en relatieve paden)
  • --password <password> - Certificaatwachtwoord (standaard: 'wachtwoord')
  • --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": "..."}).

certificaatgegevens

Geef certificaatdetails van een PFX-bestand weer. 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)

Opties:

  • --password <password> - Wachtwoord voor het PFX-bestand (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> [options]

Argumenten:

  • file-path - Pad naar MSIX-pakket of uitvoerbaar bestand om te ondertekenen

Opties:

  • --cert <path> - Pad naar handtekeningcertificaat
  • --cert-password <password> - Certificaatwachtwoord (standaard: 'wachtwoord')

Voorbeelden:

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

# Sign executable
winapp sign ./bin/MyApp.exe --cert ./mycert.pfx --cert-password mypassword

az-sign

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:

  1. winapp manifest generate --template sparse — Een sparse-manifest maken met AllowExternalContent
  2. winapp create-external-catalog ./bin — Genereer de code-integriteitscatalogus voor de uitvoerbare bestanden van uw app
  3. 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

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

find-ui

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]

Het corpus wordt opgehaald uit GitHub bij het eerste gebruik en in de cache opgeslagen per gebruiker, <global .winapp>/cache/find-uidus de eerste uitvoering vereist netwerktoegang. Volgende uitvoeringen worden uitgevoerd vanuit de lokale cache (maximaal elke 7 dagen vernieuwd of op aanvraag met --refresh).

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

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 automatisch wanneer u opdrachten uitvoert zoals init of restore.

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

gebruikersinterface

Inspecteer en communiceer met het uitvoeren van Windows app-API's met behulp van UI Automation (UIA).

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 (dialoogvensters voor automatisch vastleggen afzonderlijk)
  • record- Neem een venster-/elementregio op naar een H.264 MP4-video (Windows Graphics Capture + Media Foundation)
  • invoke - Element activeren (klik, wisselknop, uitvouwen)
  • 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

Opties:

  • -a, --app <app> - Doel-app (naam, titel of PID)
  • -w, --window <hwnd> - Doelvenster door HWND (stabiel)

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

Bekende beperking: het opnemen van een specifiek element in een pop-up die wordt weergegeven in een eigen venster op het hoogste niveau (WinUI/XAML flyout, onderwijstip, knopinfo) kan in plaats daarvan het onderliggende hoofdvenster vastleggen. Noteer het hele venster of gebruik ui screenshot --capture-screen deze voor pop-up stills. Bijgehouden in #646.

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

  • Last updated on