winapp CLI-Befehle für Setup, Verpacken und Signieren

Die winapp CLI bietet Befehle zum Einrichten, Packen, Signieren, Ausführen und Veröffentlichen moderner Windows Apps. Dieser Artikel ist eine vollständige Referenz für jeden Befehl, einschließlich der zugehörigen Argumente und Optionen.

Shellabschluss

Registerkartenabschluss für Befehle, Optionen und Werte aktivieren. Anweisungen zum Einrichten finden Sie im Shell-Abschlusshandbuch .

# 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

initialisieren

Initialisieren Sie ein Verzeichnis mit Windows SDK, Windows App SDK und erforderlichen Ressourcen für die moderne Windows-Entwicklung.

winapp init [base-directory] [options]

Argumente:

• base-directory - Basis-/Stammverzeichnis für die App/den Arbeitsbereich (Standard: aktuelles Verzeichnis)

Optionen:

• --config-dir <path> - Verzeichnis zum Lesen/Speichern (Standard: aktuelles Verzeichnis)
• --setup-sdks - SDK-Installationsmodus: 'stable' (Standard), 'preview', 'experimental' oder 'none' (SDK-Installation überspringen)
• --ignore-config, - --no-config Verwenden Sie keine Konfigurationsdatei für die Versionsverwaltung.
• --no-gitignore - Aktualisieren Sie die Gitignore-Datei nicht
• --use-defaults, - --no-prompt Nicht auffordern und Standard aller Eingabeaufforderungen verwenden
• --config-only – Behandeln von Konfigurationsdateivorgängen, Überspringen der Paketinstallation
• --exe <path> - Pfad zur ausführbaren Anwendung. Erfordert --sparse. Generiert ein Nur-Identitäts-Sparse-Manifest für die exe anstelle eines vollständigen Paket-/SDK-Setups.
• --sparse - Generieren Sie ein spärliches Identitätsmanifest (appxmanifest.xml) für eine vorhandene Desktop exe. Überspringt die SDK-/Paketinstallation. Verwendung mit --exe.
• --name <name> - Überschreiben Sie den Paketnamen (nur spärlich; Standard: abgeleitet von der exe)
• --publisher <CN> - Den Herausgeber CN außer Kraft setzen (nur spärlich; Standard: abgeleitet vom Firmennamen der Exe)
• --output-dir <path> - Verzeichnis zum Schreiben des Sparsemanifests und Assets/ (nur sparse; Standard: ein sparse/ Ordner im aktuellen Verzeichnis)
• --force - Überschreiben Sie ein vorhandenes appxmanifest.xml Im Zielverzeichnis (nur wenig). Ohne dies schlägt init fehl, anstatt ein vorhandenes Manifest/ressourcen zu ersetzen.
• --add-js-bindings (nur npm) – Zu package.json hinzufügen winapp.jsBindings und JS/TypeScript-Bindungen generieren, ohne dazu aufzufordern (nicht kompatibel mit --setup-sdks none)

Was es tut:

• Erstellt winapp.yaml Konfigurationsdatei (nur, wenn SDK-Pakete verwaltet werden; übersprungen mit --setup-sdks none)
• Herunterladen von Windows SDK- und Windows App SDK paketen
• Generiert C++/WinRT-Header und Binärdateien
• Erstellt Package.appxmanifest
• Richtet Buildtools ein und aktiviert den Entwicklermodus
• Aktualisiert gitignore so, dass generierte Dateien ausgeschlossen werden
• Speichert freigegebene Dateien im globalen Cacheverzeichnis.
• Generiert JS-Bindungen für Windows App SDK-APIs, wenn diese aktiviert sind (nur npm)

Automatische Projekterkennung:

Wenn init sie ohne Verzeichnisargument ausgeführt wird, führt sie eine breite erste Suche der aktuellen Verzeichnisstruktur aus, um kompatible Projekte (bis zu 10) zu finden. Unterstützte Projekttypen:

• Tauri – tauri.conf.json eine Ebene unterhalb des Verzeichnisses gefunden
• Electron – package.json mit electron Abhängigkeiten oder DevDependencies
• Flutter – pubspec.yaml im Projektstamm
• .NET – .csproj im Projektstamm
• Rost — Cargo.toml im Projektstamm
• C++ – CMakeLists.txt im Projektstamm

Die Suche überspringt häufig ignorierte Verzeichnisse (node_modules, bin, obj, GIT usw.). Wenn ein kompatibles Projekt gefunden wird, werden Unterverzeichnisse darunter nicht durchsucht.

• Wenn ein Verzeichnisargument bereitgestellt wird (z. B. winapp init . oder winapp init path/to/project), wird die Suche übersprungen und init überprüft nur das Verzeichnis für ein kompatibles Projekt.
• Wenn --use-defaults (oder --no-prompt) ohne Verzeichnisargument festgelegt ist, init überspringt die Suche und initialisiert das aktuelle Verzeichnis nicht interaktiv, warnung zuerst, wenn dort kein bekannter Projekttyp erkannt wird (z. B. winapp init --use-defaults)
• In nicht interaktiven Umgebungen (piped stdin, CI, umgeleitete Eingabe), init verwendet --use-defaults automatisch Verhalten und gibt eine Warnung aus: Non-interactive environment detected. Using default values.
• Wenn das aktuelle Verzeichnis ein kompatibles Projekt ist, init fahren Sie sofort fort.
• Wenn genau ein Projekt an anderer Stelle gefunden wird, werden Sie aufgefordert, dies zu bestätigen.
• Wenn mehrere Projekte gefunden werden, können Sie auswählen, welches zu initialisieren ist – das aktuelle Verzeichnis ist immer als Fallbackoption verfügbar.
• Wenn keine Projekte gefunden werden, werden Sie gewarnt und gefragt, ob der Vorgang trotzdem fortgesetzt werden soll.
• Wenn die Suche den Grenzwert von 10 Projekten erreicht, schlägt eine Warnung vor, ein Verzeichnisargument bereitzustellen.

Automatischer .NET Projektfluss:

Wenn eine .csproj-Datei im Zielverzeichnis gefunden wird, verwendet init einen optimierten .NET-spezifischen Fluss:

• Überprüft und aktualisiert den TargetFramework auf eine Windows kompatible TFM (z. B. net10.0-windows10.0.26100.0)
• Fügt Microsoft.WindowsAppSDK und Microsoft.Windows.SDK.BuildTools als NuGet-PackageReference-Einträge direkt in das .csproj hinzu.
• Generiert Package.appxmanifest, Ressourcen und ein Entwicklungszertifikat
• Erstellt keine winapp.yaml C++-Projektionen und lädt sie nicht herunter (für NuGet-Pakete verwendendotnet restore)

Spärlicher Identitätsmodus (--exe + --sparse):

Generiert ein Nur-Identitäts-Sparse-Paketmanifest für eine vorhandene ausführbare Desktopdatei – den ersten Schritt des spärlichen Paketworkflows. Im Gegensatz zum vollständigen init Ablauf überspringt dies alle SDK-/Paketinstallationen (geringe Identitätspakete haben keine SDK-Abhängigkeiten) und generiert nur ein Manifest- und Platzhalterobjekt.

• Leitet den Paketnamen, den Herausgeber, die Beschreibung und die Version von der exe über FileVersionInfo (außer Kraft setzen mit --name, --publisheroder interaktiv) ab.
• appxmanifest.xml Schreibt (mit dem exe-Namen ersetzt in Executable) plus einen Assets/ Ordner in einen sparse/ Ordner im aktuellen Verzeichnis (oder --output-dir)
• Wird --use-defaults/--no-prompt verwendet, um die interaktiven Überschreibungsaufforderungen zu überspringen (CI-freundlich)
• --exe ohne --sparse Fehler

Ressourcen sind extern. Der Geringe Ist-Wert .msix ist nur identitätsgeschützt: Die generierten Assets/ Dateien werden aus dem Installationsverzeichnis der App (dem externen Inhaltsspeicherort) zur Laufzeit aufgelöst, nicht gebündelt..msix Stellen Sie sie zusammen mit Ihrer Anwendung bereit.

Nächste Schritte nach winapp init --exe <exe> --sparse: winapp pack <appxmanifest.xml> zum Erstellen der Identität .msix, dann winapp embed-identity <exe>. Die vollständige exemplarische Vorgehensweise finden Sie im Handbuch für sparse Packaging .

Beispiele:

# 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

Tipp: Installieren von SDKs nach dem anfänglichen Setup

Wenn Sie mit init (oder übersprungener SDK-Installation) ausgeführt --setup-sdks none haben und später die SDKs benötigen:

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

Verwenden Oder --setup-sdks preview--setup-sdks experimental für Vorschau-/experimentelle SDK-Versionen.

neu

Erstellen Sie eine neue WinUI-App aus einer offiziellen Windows App SDK dotnet new Vorlage. Interaktiv standardmäßig; verwendet standardmäßige Standardeinstellungen in nicht interaktiven Umgebungen.

winapp new [options]

Optionen:

• -t, --template <short-name>- Kurzname der Vorlage (z. B. winui, winui-navview, winui-mvvm, winui-lib). winui-unittest Wird zur Laufzeit anhand des installierten Pakets überprüft; ausführen winapp new --list , um alle anzuzeigen. Standard: winui (leere App).
• -n, --name <name> - Name für die neue App/das neue Projekt (Standard: abgeleitet von --output, else WinUIApp)
• -o, --output <path> - Verzeichnis zum Erstellen der App in (Standard: ./<name>)
• --use-defaults, - --no-prompt Keine Eingabeaufforderung; Verwenden Sie Standardwerte (leere Vorlage, Name von --output/--name, und behalten Sie das installierte Vorlagenpaket bei, anstatt es zu aktualisieren)
• --force - Gerüst auch dann, wenn das Ausgabeverzeichnis bereits Dateien enthält
• --template-version <latest|installed|version> - WinUI Template Pack-Version: latest installiert das neueste veröffentlichte Paket, behält alles, installed was bereits heruntergeladen wurde (kein Netzwerk) oder eine explizite Version wie 1.2.3. Standard: Installieren Sie das neueste, wenn kein Paket vorhanden ist, andernfalls werden Sie aufgefordert, ein veraltetes Paket zu aktualisieren (beibehalten as-is unter --use-defaults).
• --list – Auflisten der verfügbaren WinUI-Vorlagen und -Beendigung (installiert zuerst das neueste Paket, wenn keines installiert ist)
• --json - Formatieren der Ausgabe als JSON

Vorlagen:

Die Vorlagenliste wird live aus dem installierten Paket gelesen, sodass sie immer die version widerspiegelt, die Sie haben – ausführen winapp new --list , um den aktuellen Satz anzuzeigen. Allgemeine Vorlagen:

Der kanonische Kurzname jeder Vorlage ist die erste Aliasliste dotnet new dafür. Alle aufgelisteten Aliase (z. B. winui3, wasdk-single) werden ebenfalls akzeptiert. Wenn Sie innerhalb eines vorhandenen WinUI-Projekts ausgeführt werden, dotnet new werden auch Elementvorlagen (z. B. eine leere Seite) angezeigt, die winapp new dem aktuellen Projekt hinzugefügt wird, anstatt ein neues Projekt zu erstellen.

Versionsverwaltung für Vorlagenpakete:

winapp new Heftet keine bestimmte Vorlagenpaketversion mehr an. Wenn kein Paket installiert ist, wird das neueste installiert. Wenn ein älteres Paket bereits installiert ist, überprüft es den Feed und fordert, wenn ein neueres paket vorhanden ist, auf , ob aktualisiert werden soll , mit Ausnahme von nicht interaktiven/--use-defaults Ausgeführten, die das installierte Paket beibehalten. Wird verwendet --template-version latest , um immer das neueste ohne Aufforderung zu übernehmen oder --template-version installed das heruntergeladene Paket immer ohne Netzwerküberprüfung zu verwenden. Durch Übergeben einer expliziten Version (z. B. --template-version 1.2.3) wird immer genau diese Version installiert – auch wenn bereits ein neueres Paket vorhanden ist – Gerüst ist also auf allen Computern reproduzierbar.

Was es tut:

• Überprüft, ob das .NET SDK installiert ist (schlägt schnell mit Anleitungen fehl, wenn nicht vorhanden – winapp keine Toolkette installiert)
• Installiert oder aktualisiert das offizielle WinUI-Vorlagenpaket (Microsoft.WindowsAppSDK.WinUI.CSharp.Templates) bei Bedarf
• Listet die verfügbaren Vorlagen aus dem installierten Paket auf und stellvertretungsgerüst dotnet new <short-name>

WinUI-App-Vorlagen enthalten bereits Windows Verpackung und Identität (Package.appxmanifest), sodass kein separater winapp init Schritt erforderlich ist. Verwenden Sie winapp run für App-Vorlagen das Erstellen und Starten der App. Die winui-lib Vorlage erstellt eine Klassenbibliothek, auf die aus einem App-Projekt verwiesen werden soll (es hat kein App-Manifest). Die winui-unittest Vorlage ist eine verpackte MSTest-App, deren Tests ausgeführt werden, wenn die App gestartet wird (winapp run) und nicht über dotnet test. winapp newGerüste für das installierte .NET SDK-Zielframework und druckt den entsprechenden nächsten Schritt für die von Ihnen ausgewählte Vorlage.

Übergeben Sie das globale --verbose (-v) Flag, um jeden zugrunde liegenden dotnet Aufruf (Packabfrage, Updateüberprüfung, Installation, dotnet new listGerüst) zusammen mit seiner vollständigen Ausgabe zu echoen – nützlich für die Diagnose von Vorlagenpaket- oder Gerüstproblemen.

Beispiele:

# 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

wiederherstellen

Stellen Sie Pakete wieder her, und generieren Sie Dateien basierend auf der vorhandenen winapp.yaml Konfiguration neu.

winapp restore [options]

Optionen:

• --config-dir <path> - Verzeichnis mit winapp.yaml (Standard: aktuelles Verzeichnis)

Was es tut:

• Liest vorhandene winapp.yaml Konfiguration
• Herunterladen/Aktualisieren von SDK-Paketen in angegebene Versionen
• Generiert C++/WinRT-Header und Binärdateien
• Speichert freigegebene Dateien im globalen Cacheverzeichnis.

Beispiele:

# Restore from winapp.yaml in current directory
winapp restore

Aktualisierung

Aktualisieren Sie Pakete auf ihre neuesten Versionen, und aktualisieren Sie die Konfigurationsdatei.

winapp update [options]

Optionen:

• --setup-sdks <stable|preview|experimental|none>- SDK-Installationsmodus: stable (Standard), preview, oder experimentalnone(SDK-Installation überspringen)

Was es tut:

• Liest die vorhandene winapp.yaml Konfiguration im aktuellen Verzeichnis.
• Aktualisiert alle Pakete auf die neuesten verfügbaren Versionen
• Aktualisiert die winapp.yaml Datei mit neuen Versionsnummern.
• Generiert C++/WinRT-Header und Binärdateien

Beispiele:

# Update packages to latest versions
winapp update

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

pack

Erstellen Sie MSIX-Pakete aus vorbereiteten Anwendungsverzeichnissen. Erfordert, dass eine Manifestdatei (Package.appxmanifest bevorzugt, appxmanifest.xml auch unterstützt) im Zielverzeichnis, im aktuellen Verzeichnis vorhanden oder mit der --manifest Option übergeben wird. (Ausführen init oder manifest generate Erstellen eines Manifests)

Übergeben Sie mehrere Eingabeordner, um eine .msixbundle Verteilung mit mehreren Architekturen zu erstellen (siehe Pakete mit mehreren Architekturen unten).

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

Argumente:

• input-folder – Mindestens ein Verzeichnis, das die zu verpackenden Anwendungsdateien enthält. Übergeben Sie mehrere Ordner (z. B. ./publish/x64 ./publish/arm64), um ein MSIX-Bündel zu erstellen. Übergeben Sie für sparse Identity Packages eine sparse-Dateiappxmanifest.xml direkt anstelle eines Ordners (siehe Sparse Identity Packages unten).

Optionen:

• --output <filename> - Ausgabedateiname. Für einzelne Pakete: <name>_<version>_<arch>.msix (zurück auf <name>_<version>.msix, , <name>_<arch>.msixoder <name>.msix). Für Bundles: <name>_<version>_<arch1>_<arch2>.msixbundle.
• --name <name> - Paketname (Standard: aus Manifest)
• --manifest <path> - Pfad zur Manifestdatei (Package.appxmanifest bevorzugt, appxmanifest.xml auch unterstützt; Standard: automatische Erkennung)
• --cert <path> - Pfad zum Signieren des Zertifikats (aktiviert die automatische Signatur)
• --cert-password <password> - Zertifikatkennwort (Standard: "Kennwort")
• --generate-cert - Generieren eines neuen Entwicklungszertifikats
• --install-cert - Installieren des Zertifikats auf dem Computer
• --publisher <name>- Publisher für die Zertifikatgenerierung. Akzeptiert einen vollständigen X.500 Distinguished Name oder einen baren Namen (automatisch umschlossen als CN=<name>)
• --self-contained – Bundle Windows App SDK Runtime
• --skip-pri - Pri-Dateigenerierung überspringen
• --executable <path> - Pfad zur ausführbaren Datei relativ zum Eingabeordner (auch --exe). Wird verwendet, um $targetnametoken$-Platzhalter im Manifest aufzulösen.

Was es tut:

• Überprüft und verarbeitet Package.appxmanifest-Dateien
• $placeholder$ Löst Token im Manifest auf (siehe Manifestplatzhalter unten)
• Stellt die richtigen Frameworkabhängigkeiten sicher
• Aktualisiert parallele Manifeste mit Registrierungen
• Erkennt und bündelt automatisch alle Nicht-Image-Dateien, auf die im Manifest verwiesen wird (z. B. AppExtension manifest.json, Konfigurationsdateien) aus dem Manifestverzeichnis oder Eingabeordner, wenn sie beim Staging fehlen
• Erkennt WinRT-Komponenten von Drittanbietern automatisch und registriert ihre aktivierbaren Klassen (siehe WinRT-Komponentenermittlung unten)
• Behandelt eigenständige WinAppSDK-Bereitstellung
• Signiert das Paket, wenn das Zertifikat bereitgestellt wird.

Spärliche Identitätspakete

Wenn es sich bei der Eingabe um eine spärliche appxmanifest.xml Datei (eine unter ) anstelle eines Ordners handelt <uap10:AllowExternalContent>true</uap10:AllowExternalContent><Properties>, winapp pack wird nur eine Identität.msix erstellt – sie verpackt nur das Manifest, ohne Anwendungsbinärdateien oder Ressourcen. Dies ist Schritt 2 des spärlichen Paketworkflows.

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

• Die Ausgabe ist <PackageName>.identity.msix standardmäßig im aktuellen Verzeichnis (Außerkraftsetzung mit --output).
• Das Signieren erfolgt nur, wenn --cert (oder --generate-cert) angegeben wird.
• Wenn Sie stattdessen einen Ordner übergeben, dessen Manifest deklariert wird, gilt das vorhandene Verhalten für das Packen AllowExternalContentvon Ordnern, warnt jedochwinapp pack, wenn objekte (.ico/.jpg/.png) oder Binärdateien (.exe.dll//.so) gefunden werden – für sparse Pakete, die an dem externen Speicherort gehören, nicht innerhalb der ..msix

Führen Sie nach dem Packen das Paket in Ihrem Installationsprogramm aus winapp embed-identity <exe> , und registrieren Sie es bei Add-AppxPackage -Path <msix> -ExternalLocation <install-dir>. Weitere Informationen finden Sie im Handbuch für sparsame Verpackungen.

WinRT-Komponentenermittlung

Beim Verpacken überprüft automatisch NuGet-Pakete, winapp pack die in den winapp.yaml*.csproj WinRT-Komponenten von Drittanbietern (z. B. Win2D) definiert sind. Es analysiert .winmd Dateien, um aktivierbare Klassennamen zu extrahieren und ihre Implementierungs-DLLs zu suchen. Die ermittelten Einträge werden wie folgt registriert:

• Frameworkabhängige (Standard): Aktivierbare Klassen werden als <InProcessServer> Einträge in der Package.appxmanifest
• Eigenständige (--self-contained): Aktivierbare Klassen werden in SxS-Manifeste (Side-by-Side, SxS) innerhalb der ausführbaren Datei eingebettet.

Platzhalterauflösung während der Verpackung:

Wenn das Manifest im $targetnametoken$ Attribut enthalten istExecutable:

1. Wenn --executable angegeben wird (Pfad relativ zum Eingabeordner), wird der Platzhalter durch den angegebenen Wert ersetzt.
2. winapp pack Andernfalls wird der Stamm des Eingabeordners auf .exe Dateien überprüft – wenn genau eins gefunden wird, wird er automatisch verwendet.
3. Wenn null oder mehrere .exe Dateien gefunden werden, wird ein Fehler angezeigt, in dem Sie aufgefordert werden, anzugeben. --executable

Beispiele:

# 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

Multi-Architecture Bundles

Wenn mehrere Eingabeordner übergeben werden, winapp pack wird ein .msixbundle enthaltende .msix Ordner pro Architektur erstellt:

# 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

Der Befehl erkennt die Architektur der einzelnen Ordner automatisch aus dem PE-Header der primären ausführbaren Datei, überprüft die Konsistenz über Segmente (Identität, Funktionen, Abhängigkeiten) und erzeugt eine <Name>_<Version>_<arch1>_<arch2>.msixbundle.

Manifestauflösung für Bündel:

Jedes Segment im Bundle benötigt ein Manifest. Der Befehl löst Manifeste in dieser Reihenfolge auf:

1. --manifest <path> — Wenn angegeben, wird dieses einzelne Manifest für alle Segmente verwendet. Die ProcessorArchitecture Aktualisierung erfolgt automatisch pro Segment, um der erkannten Architektur zu entsprechen.

2. Manifest pro Ordner – Wenn jeder Eingabeordner ein Package.appxmanifest (oder appxmanifest.xml) enthält, wird das Manifest dieses Ordners für das Segment verwendet.

3. Aktuelles Verzeichnis-Fallback – Wenn ein Ordner kein Manifest aufweist, sucht Package.appxmanifest der Befehl im aktuellen Arbeitsverzeichnis und verwendet ihn (mit automatischer Architektur).

In allen Fällen wird das Manifest automatisch aktualisiert: Platzhalter werden aufgelöst, Abhängigkeiten werden eingefügt und die ProcessorArchitecture erkannte Architektur wird erzwungen. Nach der Auflösung stellt eine datenübergreifende Überprüfung sicher, dass Identität (Name, Version, Publisher), Funktionen und Abhängigkeiten in allen Segmenten konsistent sind – nur ProcessorArchitecture unterschiedlich sein. Die in den Segmenten definierte Paketversion wird der MSIX-Bundleversion zugeordnet, außer wenn dies der Fall ist 0.0.0.0, wird automatisch eine zeitstempelbasierte Version generiert.

# 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

Erstellen Sie app-Identität für das Debuggen mithilfe von sparsamen Verpackungen. Die exe bleibt an ihrem ursprünglichen Ort - Windows ordnet ihr die Identität über Add-AppxPackage -ExternalLocation zu.

Wann dies vs winapp run: Verwenden Sie create-debug-identity , wenn die Exe von Ihrem App-Code getrennt ist (z. B. Electron-Apps, in denen electron.exe sich befindet node_modules), oder wenn Sie speziell das Verhalten des sparse Pakets testen. Verwenden Sie winapp run stattdessen für die meisten Frameworks, in denen sich die Exe-Datei in Ihrem Buildausgabeordner befindet– ein vollständiges loses Layoutpaket und startet die App. Einen vollständigen Vergleich finden Sie im Debughandbuch .

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

Argumente:

• entrypoint - Pfad zu ausführbarer Datei (.exe) oder Skript, das Identität benötigt

Optionen:

• --manifest <path> - Pfad zur App-Manifestdatei, entweder Package.appxmanifest oder appxmanifest.xml (Standard: automatische Erkennung Package.appxmanifest oder appxmanifest.xml im aktuellen Verzeichnis)
• --no-install – Installieren Sie das Paket nach der Erstellung nicht
• --keep-identity- Die Manifestidentität as-isbeibehalten, ohne an den Paketnamen und die Anwendungs-ID anzufügen .debug

Was es tut:

• Ändert das Side-by-Side-Manifest der ausführbaren Datei.
• Registriert ein Sparse-Paket für Identität
• Ermöglicht das Debuggen von identitätsrelevanten APIs.

Beispiele:

# 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

Einbettungsidentität

Verbinden Sie eine Desktopanwendung mit ihrem geringen Identitätspaket , indem Sie das <msix> Element in das Nebeneinander-Manifest (Fusion) der App einbetten. Dies ist Schritt 3 des spärlichen Paketworkflows – es teilt Windows, zu welchem Identitätspaket die ausgeführte exe gehört.

winapp embed-identity <target> [options]

Argumente:

• target – Die datei, die aktualisiert werden soll. Automatisch durch Erweiterung erkannt:
  • .exe(EXE-Modus) - Bettet das <msix> Element direkt in das parallele Manifest der Exe ein.mt.exe
  • .xml / .manifest (XML-Modus) – Fügt das <msix> Element in eine externe SxS-Manifestdatei ein (sofern nicht vorhanden). Erstellen Sie ihre App anschließend neu, damit das aktualisierte Manifest in die Binärdatei eingebettet ist.

Optionen:

• --manifest <path> - Pfad zum sparse appxmanifest.xml to read identity (packageName, publisher, applicationId) from. Wenn sie weggelassen wird, durchsucht der Befehl zuerst einen sparse/ Ordner neben dem Ziel, dann im aktuellen Verzeichnis, dann im Verzeichnis des Ziels und im aktuellen Verzeichnis nach appxmanifest.xml.

Beispiele:

# 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

Dieser Befehl ist idempotent: Durch erneutes Ausführen wird jedes vorhandene <msix> Element ersetzt, anstatt es zu duplizieren.

Manifest

Generieren und Verwalten von Package.appxmanifest-Dateien.

Manifest generieren

Generieren Sie "Package.appxmanifest" aus Vorlagen.

winapp manifest generate [directory] [options]

Argumente:

• directory - Verzeichnis zum Generieren des Manifests in (Standard: aktuelles Verzeichnis)

Optionen:

• --package-name <name> - Paketname (Standard: Ordnername)
• --publisher-name <name>- Publisher distinguished name (Standard: CN=<current user>). Akzeptiert alle gültigen X.500 DN; Bare Namen werden automatisch als CN=<Name> umschlossen.
• --version <version> - Version (Standard: "1.0.0.0").
• --description <text> - Beschreibung (Standard: "Meine Anwendung")
• --entrypoint <path> - Einstiegspunkt ausführbare Datei oder Skript
• --template <type> - Vorlagentyp: packaged (Standard) oder sparse
• --logo-path <path> - Pfad zur Logobilddatei
• --if-exists <Error|Overwrite|Skip> - Verhalten, wenn die Manifestdatei bereits am Zielpfad vorhanden ist (Standard: Error)

Vorlagen:

• packaged - Standardmäßiges App-Manifest
• sparse - App-Manifest mit sparse/external location packaging

Platzhalter im Manifest

Generierte Manifeste verwenden $placeholder$ Token (durch Dollarzeichen getrennt), die beim Verpacken automatisch aufgelöst werden:

Dies folgt der gleichen Konvention, die von Visual Studio Projektvorlagen verwendet wird, sodass Manifeste über toolsübergreifend portierbar sind.

Wie Platzhalter aufgelöst werden:

• winapp pack — Während des Verpackens $targetnametoken$ wird die --executable Option oder die automatische Erkennung des einzelnen .exe im Eingabeordner aufgelöst. Wenn mehrere (oder null) .exe Dateien gefunden und --executable nicht angegeben werden, wird ein Fehler angezeigt.
• winapp create-debug-identity — Wenn ein Einstiegspunktargument angegeben wird, $targetnametoken$ wird es aufgelöst. Ohne Einen Eintragspunkt muss der ausführbare Platzhalter bereits im Manifest aufgelöst werden.
• winapp manifest generate --executable — Bei --executable Angabe werden Manifestmetadaten (Version, Beschreibung) und Symbole aus der ausführbaren Datei extrahiert, das generierte Manifest wird jedoch weiterhin verwendet $targetnametoken$.exe; dieser Platzhalter wird später aufgelöst (z. B. winapp pack oder winapp create-debug-identity).

PS: Beibehalten von $targetnametoken$ in Ihrem eingecheckten Manifest vermeidet das Hartcodieren ausführbarer Namen und funktioniert sowohl mit winapp pack als auch mit Visual Studio Builds.

Beispiele:

# 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

Fügen Sie einem Package.appxmanifest einen Ausführungsalias (uap5:AppExecutionAlias) hinzu. Dies ermöglicht das Starten der verpackten App über die Befehlszeile, indem Sie den Aliasnamen eingeben.

winapp manifest add-alias [options]

Optionen:

• --name <alias> - Aliasname (z. B. myapp.exe). Standard: abgeleitet vom Executable Attribut im Manifest.
• --manifest <path> - Pfad zu Package.appxmanifest (Standard: aktuelles Verzeichnis durchsuchen)
• --app-id <id> - Anwendungs-ID zum Hinzufügen des Alias zu (Standard: erstes Anwendungselement)

Was es tut:

• Liest das Manifest und leitet den Alias aus dem Executable Attribut ab (wobei Platzhalter beibehalten werden, z $targetnametoken$.exe. B. )
• Fügt die uap5 Namespacedeklaration hinzu, wenn sie noch nicht vorhanden ist
• Fügt einen <Extensions> Block im <uap5:AppExecutionAlias> Zielanwendungselement hinzu.
• Wenn der Alias bereits vorhanden ist, meldet es und beendet ihn erfolgreich.

Beispiele:

# 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

Manifestaktualisierungsressourcen

Generieren Sie alle erforderlichen MSIX-Bildressourcen aus einem einzelnen Quellimage.

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

Argumente:

• image-path - Pfad zur Quellbilddatei (PNG, JPG, SVG, ICO, GIF, BMP usw.)

Optionen:

• --manifest <path> - Pfad zur Datei "Package.appxmanifest" (Standard: aktuelles Verzeichnis durchsuchen)
• --light-image <path> - Pfad zu einem separaten Quellbild für helle Designvarianten

Beschreibung:

Verwendet ein einzelnes Quellbild und generiert einen umfassenden Satz von MSIX-Bildressourcen basierend auf den Ressourcenverweise des Manifests:

Für jede Ressource, auf die im Manifest verwiesen wird:

• 5 Skalierungsvarianten — Basis (kein Suffix), .scale-125, .scale-150, , .scale-200.scale-400

Für das App-Symbol (Square44x44Logo / AppList, 44×44 Base):

• 14 platte Zielvarianten — .targetsize-{16,20,24,30,32,36,40,48,60,64,72,80,96,256}
• 14 unplated targetsize variants — .targetsize-{size}_altform-unplated

Additionally:

• app.ico – Multiauflösungs-ICO-Datei (16, 24, 32, 48, 256) für die Shellintegration. Wenn eine vorhandene .ico Datei im Ressourcenverzeichnis (z. B. AppIcon.ico aus einer Projektvorlage) gefunden wird, wird sie anstelle eines Duplikats ersetzt.

Mit --light-image:

• Helles Design zielt auf Varianten ab – .targetsize-{size}_altform-lightunplated (App-Symbol)
• Varianten der hellen Designskala – .scale-{factor}_altform-colorful_theme-light (Kacheln, Logo speichern)

SVG-Unterstützung: SVG-Dateien werden vollständig als Quellimages unterstützt. Sie werden direkt in jeder Zielgröße als Vektoren gerendert und erzeugen pixelgenaue Ergebnisse bei allen Auflösungen.

Der Befehl skaliert Bilder proportional, während das Seitenverhältnis beibehalten wird und bei Bedarf mit transparenten Hintergründen zentriert wird. Objekte werden relativ zur Position des Manifests im Assets Verzeichnis gespeichert.

Beispiele:

# 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

ausführen

Erstellen Sie ein loses Layoutpaket aus einem Buildausgabeordner, registrieren Sie es mit Windows mithilfe der Windows.Management.Deployment.PackageManager-API, und starten Sie die Anwendung, und simulieren Sie eine vollständige MSIX-Installation zum Debuggen. Gibt die Prozess-ID für die Debuggeranlage zurück.

winapp run arbeitet in einem von zwei Modi, die automatisch aus der Eingabe ausgewählt werden:

• Ordnermodus – die Eingabe ist ein Buildausgabeordner (enthält ein Package.appxmanifest/AppxManifest.xml).
• Project Modus – die Eingabe ist eine .csproj, eine .sln/.slnx Lösung oder ein Verzeichnis, das einen enthält. winapp run erstellt das Projekt und startet es und unterstützt sowohl verpackte als auch entpackte WinUI-Apps. Siehe Project Modus unten.

Dies ist der bevorzugte Befehl zum Debuggen mit Paketidentität für die meisten Frameworks (.NET, C++, Rust, Flutter, Tauri). Anders als create-debug-identity bei der Registrierung eines sparse-Pakets für eine einzelne exe registriert wird, winapp run registriert der gesamte Ordner wie ein loses Layoutpaket wie eine echte MSIX-Installation. Im Debughandbuch finden Sie allgemeine Debugworkflows.

winapp run [<input>] [options]

Argumente:

• input - Die auszuführende App: ein Buildausgabeordner (Ordnermodus), ein .csproj Projekt, eine .sln/.slnx Projektmappe oder ein Verzeichnis, das eines der Auf der obersten Ebene enthält (Projektmodus; das Verzeichnis wird nicht rekursiv durchsucht). Wird . verwendet, um das Projekt im aktuellen Verzeichnis zu erstellen/auszuführen. Optional – Standardeinstellung für das aktuelle Verzeichnis, wenn es weggelassen wird (Übereinstimmungen dotnet run).

Optionen:

• --manifest <path> - Pfad zu "Package.appxmanifest" (Standard: auto-detect from input folder or current directory)
• --output-appx-directory <path> - Ausgabeverzeichnis für das lose Layoutpaket (Standard: AppX innerhalb des Eingabeordnerverzeichnisses)
• --args <string> - Befehlszeilenargumente, die an die Anwendung übergeben werden sollen. Alternativ können Sie gefolgt von Argumenten verwenden -- , um die Flucht zu vermeiden (z. B winapp run . -- --flag value. ).
• --no-launch – Erstellen Sie nur die Debugidentität, und registrieren Sie das Paket, ohne die Anwendung zu starten.
• --with-alias – Starten Sie die App mit ihrem Ausführungsalias anstelle der AUMID-Aktivierung. Die App wird im aktuellen Terminal mit geerbtem stdin/stdout/stderr ausgeführt. Erfordert ein uap5:ExecutionAlias Im Manifest (zum winapp manifest add-alias Hinzufügen eines). Kann nicht mit --no-launch. Kann nicht mit --json.
• --debug-output – Erfassen Sie OutputDebugString Nachrichten und Ausnahmen von der gestarteten Anwendung mit der ersten Chance. Framework-Rauschen (WinUI, COM, DirectX) wird aus der Konsolenausgabe gefiltert; Die vollständige Protokolldatei erfasst alles. Wenn die App abstürzt, wird automatisch ein Minidump erfasst und analysiert, um den Ausnahmetyp, die Nachricht und die Stapelüberwachung mit Quelldatei:Zeilennummern anzuzeigen (aufgelöst von PDBs im Buildausgabeordner). Verwaltete (.NET) Abstürze werden sofort ohne externe Tools analysiert. Systemeigene Abstürze (C++/WinRT) zeigen Modulnamen und Offsets an. Wenn es sich bei der abgestürzten App um eine WinUI 3-App handelt (Microsoft.UI.Xaml.dll wird geladen), wird automatisch ein extra gestapelter Ausnahme-Triagedurchlauf ausgeführt, um das ursprüngliche HRESULT, seine ErrorContext-Kette und den vollständigen nativen XAML-Verteilerstapel anzuzeigen. Die erforderlichen Debuggerkomponenten werden bei der ersten Verwendung heruntergeladen (siehe Debuggen, überschreibbar über die WINAPP_DBGTOOLS_DIR Umgebungsvariable). Es kann jeweils nur ein Debugger an einen Prozess angefügt werden, sodass andere Debugger (Visual Studio, VS-Code) nicht gleichzeitig verwendet werden können. Verwenden Sie --no-launch stattdessen, wenn Sie einen anderen Debugger anfügen müssen. Kann nicht mit --no-launch. Kann nicht mit --json.
• --symbols – Laden Sie PDB-Symbole von Microsoft Symbolserver herunter, um eine umfassendere systemeigene Absturzanalyse mit aufgelösten Funktionsnamen zu erhalten. Nur mit --debug-output verwendet. Wenn nicht angegeben und ein systemeigener Absturz auftritt, schlägt die Ausgabe das Hinzufügen dieses Flags vor. Dieses Flag verbessert auch den WinUI-Triagestapel für WinUI 3-Apps mit Ausnahme.This flag also improves the WinUI stowed-exception triage stack for WinUI 3 apps. Führen Sie zuerst Downloads-Symbole aus und speichert sie lokal zwischen; bei nachfolgenden Ausführungen wird der Cache verwendet.
• --unregister-on-exit – Heben Sie die Registrierung des Entwicklungspakets auf, nachdem die Anwendung beendet wurde. Entfernt nur Pakete, die im Entwicklungsmodus registriert sind. Kann nicht mit --no-launch.
• --detach – Starten Sie die Anwendung, und kehren Sie sofort zurück, ohne darauf zu warten, dass sie beendet wird. Nützlich für CI/Automatisierung, bei der Sie nach dem Start mit der App interagieren müssen. Druckt die PID in Stdout (oder in JSON mit --json). Kann nicht mit --no-launch, --debug-output, , --with-aliasoder --unregister-on-exit.
• --clean – Entfernen Sie die Anwendungsdaten des vorhandenen Pakets (LocalState, Einstellungen usw.), bevor Sie es erneut bereitstellen. Standardmäßig werden Anwendungsdaten bei allen erneuten Bereitstellungen beibehalten.
• --json - Formatieren Sie die Ausgabe als JSON für den programmgesteuerten Verbrauch (z. B. CI/Automation). Nützlich bei --detach der Erfassung der PID. Kann nicht mit --with-alias oder --debug-output kombiniert werden.

Persistenz von Anwendungsdaten:

Behält die Daten Ihrer Anwendung bei der erneuten Bereitstellung standardmäßig winapp run bei (LocalState, RoamingState, Settingsusw.) bei. Wenn Ihre App Daten in ApplicationData.Current.LocalFolder oder Environment.GetFolderPath(SpecialFolder.LocalApplicationData) innerhalb des Paketkontexts schreibt, bleiben diese Daten über winapp run Aufrufe hinweg bestehen.

Verwenden Sie diese Einstellung --clean , wenn Sie einen Neustart benötigen (z. B. um beschädigten Zustand zurückzusetzen oder das Verhalten der ersten Ausführung zu testen).

Was es tut:

• Sucht oder generiert das Package.appxmanifest
• Erstellt und registriert eine Debugidentität mithilfe eines lose Layoutpakets.
• Berechnet die Anwendungsbenutzermodell-ID (Application User Model ID, AUMID)
• Startet die Anwendung mit der registrierten Identität (sofern nicht --no-launch angegeben)
• Druckt die Prozess-ID (PID) für die Debuggeranlage.

Beispiele:

# 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-Projekte)

Wenn es sich bei der Eingabe um eine .csproj, eine.slnx/.sln Lösung oder ein Verzeichnis handelt, das einen enthält (einschließlich .),winapp run erstellt das Projekt mit dotnet build und startet es dann. Sie unterstützt sowohl verpackte als auch entpackte WinUI-Apps und installiert die passende Architektur Windows-App Runtime, die die App vor dem Start benötigt.

Lösungseingabe: Zeigen winapp run Sie auf ein/.slnx.sln(oder ein Verzeichnis, das ein Verzeichnis enthält – eine Lösung wird bevorzugt gegenüber lose .csproj Dateien) und löst das runnbare App-Projekt auf, erstellt es dann mit $(SolutionDir) und den definierten gleichgeordneten Solution* Eigenschaften, sodass Projekte, die von ihnen abhängig sind, wie in Visual Studio erstellt werden. Lösungsregeln:

• Testprojekte werden bei der automatischen Auswahl übersprungen, sodass eine Lösung, die eine App sowie die zugehörigen Tests enthält, für die App ohne --project Bedarf aufgelöst wird. (Ein WinUI-Testprojekt ist selbst eine verpackte App, sodass der Ausgabetyp allein nicht unterschieden werden kann.)
• Wenn das einzige ausgeführte Projekt ein Testprojekt ist, wird es ausgeführt.
• Wenn mehr als ein ausgeführtes App-Projekt vorhanden ist, winapp run erraten Sie kein Startprojekt– sie führt die Kandidaten auf. Verwenden Sie --project <name> diese Option, um auszuwählen, welche immer berücksichtigt wird, einschließlich der Auswahl eines Testprojekts.

Verpackt und entpackt wird automatisch aus der effektiven WindowsPackageType MSBuild-Eigenschaft des Projekts erkannt (nie aus Manifestpräsenz):

• Verpackt (WindowsPackageType=MSIX, der WinUI-Paketstandard) – Erstellt und registriert dann die Buildausgabe als Lose-Layout-Paket und startet über AUMID (die gleiche Pipeline wie der Ordnermodus).
• Entpackt (WindowsPackageType=None) - Builds, stellt sicher, dass das frameworkabhängige Windows-App Runtime installiert ist, und startet dann die integrierte .exe direkt. Erzwingen Sie dies für ein verpacktes Projekt mit -p WindowsPackageType=None.

Project Modus erfordert das .NET SDK 8.0.100 oder höher (für MSBuild--getProperty).

optionen für den Project modus (im Ordnermodus ignoriert):

• -c, --configuration <name> – Buildkonfiguration. Standardwert: Debug.
• --arch <x64|arm64|x86> - Zielarchitektur. Standard: die aktuelle Prozessarchitektur. Bestimmt sowohl den Build RID als auch die Architektur der Windows-App Runtime, die installiert wird.
• -r, --runtime <rid>- Ziel-.NET Laufzeit-ID (z. B. win-x64). Project Modus verwendet nur die RID-Architektur, erstellt immer die kanonische win-<arch>und lehnt nicht-Windows RIDs (z. B. linux-x64) ab. Seine Architektur setzt außer Kraft --arch.
• -f, --framework <tfm> - Zielrahmenmoniker für multi-gezielte Projekte (z. B. net10.0-windows10.0.26100.0).
• --project <name-or-path> – Wenn es sich bei der Eingabe um eine Lösung (.sln/.slnx) oder ein Verzeichnis mit mehreren runnierbaren App-Projekten handelt, wird ausgewählt, welches Projekt gestartet werden soll (nach Projektname oder Pfad).
• --no-build - Überspringen Sie die Erstellung, und führen Sie die vorhandene Buildausgabe aus (wertet weiterhin Ausgabeeigenschaften aus).
• --no-restore – Überspringen Sie die Wiederherstellung des Projekts vor dem Erstellen.
• -p, --property <Name=Value> - MSBuild-Eigenschaft, weitergeleitet an den Build und die Eigenschaftsauswertung. Wiederholbar (z. B. -p WindowsPackageType=None).

Buildausgabe und Ausführlichkeit: Das Projekt ist in zwei Schritten integriert – einer dotnet build , deren Ausgabestreams in Ihrer Konsole gespeichert sind, gefolgt von einem schnellen Eigenschaftsauswertungsdurchlauf. winapp druckt den genauen dotnet build … Aufruf vor der Ausgabe und streamt Warnungen sogar bei einem erfolgreichen Build. Ausführlichkeit:

Unter --json oder --quiet dem Aufruf und der Buildausgabe wechseln Sie zu stderr, sodass stdout reines JSON /clean bleibt.

Option applicability: the identity/loose-layout options (--manifest, --output-appx-directory, , --with-alias--no-launch, --unregister-on-exit, --clean) --executableapply to packaged apps only. Sie werden mit einem klaren Fehler für entpackte Apps abgelehnt (die kein MSIX-Paket aufweisen). Start-/Debugoptionen (--args/--, --detach, --debug-output, --json--symbols) funktionieren in beiden.

Beispiele für den 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-Eigenschaften (NuGet-Paket):

Bei Verwendung des Microsoft.Windows.SDK.BuildTools.WinApp NuGet-Pakets ruft dotnet run automatisch winapp run auf. Die folgenden MSBuild-Eigenschaften können in Ihrem .csproj Verhalten festgelegt werden, um das Verhalten zu steuern:

Sich gegenseitig ausschließende Einstellungen. WinAppRunNoLaunch und WinAppRunDetach jeder beschreibt ein anderes Startverhalten, sodass sie mit den anderen Starteigenschaften und miteinander in Konflikt stehen. Das Festlegen eines konfliktierenden Paares schlägt bei der Ausführung mit --X and --Y cannot be used together:

WinAppRunUseExecutionAlias, WinAppRunDebugOutputund WinAppRunUnregisterOnExit kann miteinander kombiniert werden. WinAppRunClean, WinAppRunSymbols, WinAppRunExecutableund WinAppLaunchArgs haben keine Einschränkungen. WinAppRunArgs fügt keine eigene Einschränkung hinzu, aber ein Durchgang wird wie jeder andere überprüft, sodass WinAppRunArgs="--detach" es immer noch in Konflikt steht WinAppRunNoLaunch.

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

Registrierung

Heben Sie die Registrierung eines quergeladenen Entwicklungspakets auf. Entfernt nur Pakete, die im Entwicklungsmodus registriert wurden (z. B. via winapp run oder create-debug-identity). Vom Store installierte oder MSIX-installierte Pakete werden nie entfernt.

winapp unregister [options]

Optionen:

• --manifest <path> - Pfad zu "Package.appxmanifest" (Standard: automatische Erkennung aus dem aktuellen Verzeichnis)
• --force – Die Verzeichnisüberprüfung des Installationsspeicherorts überspringen und die Registrierung aufheben, auch wenn das Paket aus einer anderen Projektstruktur registriert wurde
• --json - Formatieren der Ausgabe als JSON

Was es tut:

• Liest den Paketnamen aus dem Manifest.
• Sucht sowohl nach Paketen als {name} auch {name}.debug nach Paketen (die Debugvariante wird von create-debug-identity)
• Überprüft, ob jedes Paket im Entwicklungsmodus registriert wurde (IsDevelopmentMode == true)
• Überprüft, ob sich der Installationsspeicherort des Pakets unter der aktuellen Verzeichnisstruktur befindet (es sei denn --force,
• Aufheben der Registrierung übereinstimmener Pakete

Beispiele:

# 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

Generieren, Prüfen und Installieren von Entwicklungszertifikaten.

Zertifikat erzeugen

Generieren Sie Entwicklungszertifikate für die Paketsignierung.

winapp cert generate [options]

Optionen:

• --manifest <Package.appxmanifest> - Extrahieren von Herausgeberinformationen aus Package.appxmanifest
• --publisher <name>- Publisher für das Zertifikat. Akzeptiert einen vollständigen X.500-Distinguished-Namen (z. B. CN=Contoso, O=Contoso Ltd, C=US) oder einen offenen Namen, der automatisch umschlossen wird CN=<name>
• --output <path> - Ausgabezertifikatdateipfad (unterstützt absolute und relative Pfade)
• --password <password> - Zertifikatkennwort (Standard: "Kennwort")
• --valid-days <valid-days> - Anzahl der Tage, an der das Zertifikat gültig ist (Standard: 365)
• --install – Installieren des Zertifikats im lokalen Computerspeicher nach der Generation
• --if-exists <Error|Overwrite|Skip> - Verhalten festlegen, wenn die Zertifikatdatei bereits vorhanden ist (Standard: Fehler)
• --export-cer - Exportieren Einer .cer Datei (nur öffentlicher Schlüssel) neben dem .pfx. Nützlich für die separate Verteilung des öffentlichen Zertifikats für die Installation der Vertrauensstellung.
• --json - Formatieren Sie die Ausgabe als JSON für den programmgesteuerten Verbrauch. Fehler werden auch als JSON ({"error": "..."}) zurückgegeben.

Cert-Informationen

Zeigen Sie Zertifikatdetails aus einer PFX-Datei an. Hilfreich für die Überprüfung eines Zertifikats mit Ihrem Manifest vor der Signierung.

winapp cert info <cert-path> [options]

Argumente:

• cert-path - Pfad zur Zertifikatdatei (PFX)

Optionen:

• --password <password> - Kennwort für die PFX-Datei (Standard: "Kennwort")
• --json - Formatieren der Ausgabe als JSON

Zertifikat installieren

Installieren Sie das Zertifikat im Zertifikatspeicher des Computers.

winapp cert install <cert-path> [options]

Argumente:

• cert-path – Pfad zur zu installierenden Zertifikatdatei

Beispiele:

# 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

sign

Signieren Sie MSIX-Pakete und ausführbare Dateien mit Zertifikaten.

winapp sign <file-path> [options]

Argumente:

• file-path - Pfad zu MSIX-Paket oder ausführbarer Datei zum Signieren

Optionen:

• --cert <path> - Pfad zum Signieren des Zertifikats
• --cert-password <password> - Zertifikatkennwort (Standard: "Kennwort")

Beispiele:

# 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

Codesignieren einer Datei (exe, MSIX oder MSIX Bundle) mit Azure Artifact Signing – einer cloudverwalteten Signaturidentität, sodass kein privater Schlüssel (PFX) auf dem lokalen Computer vorhanden ist.

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

Argumente:

• file-path - Pfad zur Zu signierenden Datei (exe, msix oder msixbundle)

Optionen:

• --subscription, -s - Azure zu verwendende Abonnement-ID. Wenn nicht angegeben und mehrere Abonnements vorhanden sind, werden Sie aufgefordert.
• --resource-group, – -r Ressourcengruppe zum Einschränken von Signaturkonten
• --account - Kontoname signieren. Muss mit --resource-group
• --profile, - -p Zertifikatprofilname. Muss mit --account
• --metadata-file, - -m Pfad zu einem vorhandenen metadata.json. Überspringt die Ressourcenermittlung und Die Auswahlaufforderungen für Konto/Profil und signiert sie direkt. Eine nicht interaktive Azure Anmeldeinformationen sollten bereits verfügbar sein. Andernfalls kann die CLI auf eine interaktive Mandantenaufforderung oder az login-aufforderung zurückgreifen, die programmgesteuerte npm-API ist jedoch immer nicht interaktiv und schlägt fehl, anstatt dazu aufzufordern.

Authentifizierung:

az-signverwendet Azure Standardanmeldeinformationskette (DefaultAzureCredential). Für CI/CD, set AZURE_TENANT_ID, AZURE_CLIENT_IDund AZURE_CLIENT_SECRET (oder verwenden Sie GitHub Actions OIDC / verwaltete Identität). Eine vorhandene Azure CLI-Sitzung (az logineinschließlich der azure/login GitHub Aktion) wird auch in jeder Umgebung berücksichtigt. Nur wenn keine Anmeldeinformationen gefunden werden und die Sitzung interaktiv ist, wird az-sign für Sie gestartet az login .

Voraussetzungen:

• Ein Artefaktsignierungskonto und ein Zertifikatprofil (erstellt im Azure-Portal nach der Identitätsüberprüfung) sowie die Rolle "Artifact Signing Certificate Signer", die Ihrer Identität zugewiesen ist. Weitere Anleitungen finden Sie in der Schnellstartanleitung zur Azure Artefaktsignierung.
• Eine computerweite x64-.NET 8 (oder höher) Laufzeit installiert. Die Azure Signierclientbibliothek ist eine verwaltete Assembly, die signtool.exe in einem separaten Prozess geladen wird. Die eigene eigenständige Runtime von winapp erfüllt sie nicht. Installieren Sie sie auf der .NET-Downloadseite, wenn die Signatur mit einem Laufzeitladefehler fehlschlägt.
• Die Microsoft Visual C++ Redistributable (x64). Die Azure Signierclientbibliothek hängt von der VC++-Laufzeit ab, und da winapp das unformatierte NuGet-Paket anstelle des offiziellen Installationsprogramms für Clienttools herunterlädt, wird diese Abhängigkeit nicht automatisch installiert. Ein sauberer Computer kann sogar mit .NET und SignTool geladen werden. Installieren Sie die neueste x64-Weiterverteilerversion , wenn die Signatur mit einer 0xc000007b, "Die Anwendung konnte nicht ordnungsgemäß gestartet werden kann" oder fehler fehlende DLL-Fehler aus der Dlib fehlschlägt.

CI mit geringsten Rechten: Die automatische Erkennung (Auflisten von Abonnements, Ressourcengruppen, Konten und Profilen) benötigt Lesezugriff auf übergeordneten Bereich. Um jeden Auflistungsauflistungsaufruf zu vermeiden, übergeben Sie alle vier --subscriptionvon , --resource-group, --accountund --profile: az-sign überprüft dann das Konto und Profil mit direkten Ressourcenlesevorgängen (ein GET für jede benannte Ressource), anstatt die übergeordnete Auflistung aufzuzählen, sodass ein Prinzipal, das nur für dieses Konto und dieses Profil gilt, ausreichend ist. Wenn sie einen von ihnen weglassen, wird ein Eintragsaufruf erneut eingeführt , z. B. führt az-sign das Auslassen --subscription der Liste der Abonnements aus, auf die Ihre Identität zugreifen kann – was ein schmaler Prinzipal möglicherweise nicht tun darf. Ein Prinzipal, der nur auf ein einzelnes Zertifikatprofil festgelegt ist, kann die Überprüfung vollständig überspringen, indem ein vorab generierter --metadata-file Wert übergeben wird (der den Kontoendpunkt und das Profil direkt angibt).

Beispiele:

# 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

Generieren Sie eine CodeIntegrityExternal.cat Katalogdatei, die Hashes von ausführbaren Dateien aus angegebenen Verzeichnissen enthält. Dieser Katalog wird mit dem TrustedLaunch-Flag in MSIX sparse package manifests (AllowExternalContent) verwendet, um die Ausführung externer Dateien zu ermöglichen, die nicht im Paket selbst enthalten sind.

Dies ähnelt der Erstellung signtool.exeAppxMetadata\CodeIntegrity.cat beim Signieren eines MSIX-Pakets, generiert aber einen externen Katalog für die Verwendung mit wenig/externem Speicherortpaket.

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

Argumente:

• input-folder – Mindestens ein Verzeichnis, das ausführbare Dateien enthält, die verarbeitet werden sollen. Trennen mehrerer Verzeichnisse durch Semikolons (z. B. "dir1;dir2")

Optionen:

• --recursive, - -r Einschließen von Dateien aus Unterverzeichnissen
• --use-page-hashes - Seitenhashes beim Generieren des Katalogs einschließen (erzeugt einen größeren Katalog mit Hashdaten pro Seite)
• --compute-flat-hashes - Einfügen von Flat File-Hashes beim Generieren des Katalogs
• --if-exists <Error|Overwrite|Skip> - Verhalten, wenn die Ausgabedatei bereits vorhanden ist (Standard: Error)
• --output, - -o Ausgabekatalogdateipfad. Wenn nicht angegeben, CodeIntegrityExternal.cat wird im aktuellen Verzeichnis erstellt. Wenn ein Verzeichnis angegeben ist, wird der Standarddateiname angefügt.

Was es tut:

• Überprüft die angegebenen Verzeichnisse auf ausführbare Dateien (PE-Binärdateien mit Codeabschnitten)
• Generiert eine Katalogdefinitionsdatei (Catalog Definition File, CDF) mit Hashes aller gefundenen ausführbaren Dateien.
• Verwendet Windows CryptoCAT-APIs zum Erstellen der .cat-Katalogdatei
• Nicht ausführbare Dateien (z. B. .txtohne .dll Codeabschnitte) werden automatisch übersprungen.

Beispiele:

# 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

Verwendungsbedingungen:

Verwenden Sie diesen Befehl beim Erstellen eines sparsamen MSIX-Pakets, das TrustedLaunch verwendet, um externe ausführbare Dateien zu überprüfen. Der typische Workflow lautet:

1. winapp manifest generate --template sparse — Erstellen eines Sparsemanifests mit AllowExternalContent
2. winapp create-external-catalog ./bin – Generieren des Codeintegritätskatalogs für die ausführbaren Dateien Ihrer App
3. winapp pack — Packen des Manifests, der Objekte und des Katalogs in einem MSIX

Werkzeug

Greifen Sie direkt auf Windows SDK-Tools zu. Verwendet Tools, die in Microsoft.Windows verfügbar sind. SDK. BuildTools

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

Verfügbare Tools:

• makeappx – Erstellen und Bearbeiten von App-Paketen
• signtool - Signieren von Dateien und Überprüfen von Signaturen
• mt - Manifesttool für parallele Assemblys
• Und andere Windows SDK-Tools aus Microsoft.Windows. SDK. BuildTools

Beispiele:

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

store

Führen Sie einen Befehl der Microsoft Store Developer CLI aus. Dieser Befehl lädt die Microsoft Store Developer CLI herunter, wenn sie noch nicht heruntergeladen wurde. Erfahren Sie mehr über die Microsoft Store Developer CLI.

winapp store [args...]

Argumente:

• args... – Argumente, die direkt an die msstore CLI übergeben werden sollen. Informationen zu verfügbaren Befehlen und Optionen finden Sie in der MSStore CLI-Dokumentation .

Was es tut:

• Stellt sicher, dass die Microsoft Store Developer CLI (msstore) heruntergeladen und auf Ihrem System verfügbar ist.
• Leitet alle Argumente an die msstore CLI weiter.
• Führt den Befehl aus, der die Ausgabe direkt in Ihrem Terminal anzeigt.

Beispiele:

# 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

Abrufen der Pfade zu den installierten Windows SDK-Komponenten.

winapp get-winapp-path [options]

Was sie zurückgibt:

• Pfade zum .winapp Arbeitsbereichsverzeichnis
• Paketinstallationsverzeichnisse
• Generierte Headerspeicherorte

Find-Ui

Durchsuchen von WinUI-Steuerelementen und Beispielen für ein funktionierendes Codebeispiel. Nur WinUI: Der Korpus ist der WinUI 3-Katalog und das Windows Community Toolkit (sowie einige kuratierte Kernmuster) – es deckt nicht WPF, WinForms oder andere UI-Frameworks ab. Eine dritte Quelle, der Microsoft-UI-Reaktor ReaktorGallery, ist opt-in: Sie wird von einer normalen Suche ausgeschlossen und nur durchsucht, wenn Sie übergeben --source reactor (die C#-only deklarativen Beispiele fügen nicht in eine Standard-XAML-App ein, also erreichen Sie sie nur beim Erstellen eines Reaktor-/MVU-Projekts).

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

Der Korpus wird von GitHub bei der ersten Verwendung abgerufen und pro Benutzer <global .winapp>/cache/find-uizwischengespeichert, sodass für die erste Ausführung Netzwerkzugriff erforderlich ist. Nachfolgende Ausführungen werden aus dem lokalen Cache (höchstens alle 7 Tage oder bei Bedarf --refreshaktualisiert) bereitgestellt.

Optionen:

• --id <id> - Abrufen des Codes (Gallery/Toolkit gibt XAML und/oder C# zurück; Reaktor ist nur C#-only) plus Voraussetzungshinweise für eine oder mehrere Szenario-IDs aus einer vorherigen Suche (z. B. gallery-tabview-1). Wiederholbar. Bei IDs wird die Groß-/Kleinschreibung nicht beachtet . GALLERY-TABVIEW-1gallery-tabview-1
• --list - Listet jede auffindbare Steuerelement-/Beispiel-ID anstelle der Suche auf (Gallery + Toolkit + Core; die Opt-In-Reaktorquelle ist ausgeschlossen).
• --source <gallery|toolkit|reactor|core> – Einschränken von Suchergebnissen auf eine einzelne Quelle. (Nur Suche – nicht gültig mit --list/--id.) Reaktor ist opt-in - es wird von einer normalen Suche ausgeschlossen, also --source reactor ist die einzige Möglichkeit, sie zu durchsuchen.
• --max <N> - Maximale Anzahl übereinstimmender Steuerelemente, die zurückgegeben werden sollen (Standard: 3). Gilt nur für die Suche; ignoriert mit --list/--id.
• --refresh- Umgehen Sie den lokalen Cache, und rufen Sie den WinUI-Korpus aus GitHub erneut ab.
• --json - Emitt structured JSON (agent-friendly). Bei der Suche enthält sourcejede Übereinstimmung ein Array, descriptioncontrolscenariosscoredessen Einträge die einzelnen Szenarien id enthalten, und header; für --idvollständigen Code. Unter --jsonjedem Fehler , einschließlich Argument-/Parserfehlern wie z. B. einer nicht ganzzahligen Zahl --max , wird als flaches {"error": "..."} Objekt auf stdout mit einem Nicht-Null-Ausgangscode ausgegeben, sodass die Ausgabe maschinenlesbar bleibt.

Workflow: Suchen Sie kompakt, um das richtige Steuerelement und die zugehörigen Szenario-IDs zu finden, und rufen Sie dann den vollständigen Code für die beste Übereinstimmung mit --id.

Beispiele:

# Find a control by intent (compact results with scenario ids)
winapp find-ui "tabbed layout"

# Restrict to the Windows Community Toolkit
winapp find-ui "settings card" --source toolkit

# Restrict to Reactor (opt-in; C#-only declarative WinUI — Reactor projects only)
winapp find-ui "flex layout" --source reactor

# Fetch the full XAML + C# for a specific scenario
winapp find-ui --id gallery-tabview-1

# Agent-friendly structured output
winapp find-ui "color picker" --json

# Browse everything, or force a corpus refresh
winapp find-ui --list
winapp find-ui "navigation view" --refresh

node generate-bindings

(Nur im NPM-Paket verfügbar) Generieren Sie JS-Bindungen für Windows App SDK-APIs. Die Bindungen werden von einem "winapp": { "jsBindings": {...} } Namespace package.json in und geschrieben in .winapp/bindings/.

npx winapp node generate-bindings [options]

Optionen:

• --verbose, - -v Ausführliche Pro-Datei-Codegen-Ausgabe aktivieren
• --quiet, - -q Status und Informationsausgabe unterdrücken

Was es tut:

• Liest den winapp.jsBindings Block und package.json den winmds.lock.json vom letzten winapp restoregeschriebenen Block und gibt dann typierte .js + .d.ts Bindungen in .winapp/bindings/
• Ändert sich nicht – es handelt sich um package.json einen passiven Regenerator. Das Hinzufügen des winapp.jsBindings Blocks und die @microsoft/dynwinrt Laufzeitabhängigkeit erfolgt während winapp init der Aktivierung von JS-Bindungen. Dieser Befehl schlägt schnell fehl, wenn der Block nicht vorhanden ist.
• Warnt (aber nicht schreiben), wenn @microsoft/dynwinrt ihre Abhängigkeiten fehlen – ausführen npm install , nachdem init sie hinzugefügt wurde

Beispiele:

# 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

Weitere Informationen finden Sie in der JS-Bindungsanleitung für den End-to-End-Workflow und die winapp.jsBindings Konfigurationsoptionen.

node create-addon

(Nur im NPM-Paket verfügbar) Generieren sie systemeigene C++- oder C#-Addonvorlagen mit Windows SDK und Windows App SDK Integration.

npx winapp node create-addon [options]

Optionen:

• --name <name> - Addonname (Standard: "nativeWindowsAddon")
• --template - Select type of addon. Optionen sind cs oder cpp (Standard: cpp)
• --verbose - Ausführliche Ausgabe aktivieren

Was es tut:

• Erstellt ein Addonverzeichnis mit Vorlagendateien.
• Generiert binding.gyp und addon.cc mit Windows SDK-Beispielen
• Installiert erforderliche npm-Abhängigkeiten (nan, node-addon-api, node-gyp)
• Fügt ein Buildskript zur package.json hinzu.

Beispiele:

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

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

node add-electron-debug-identity

(Nur im NPM-Paket verfügbar) Fügen Sie app-Identität zum Elektronenentwicklungsprozess hinzu, indem Sie sparsame Verpackungen verwenden. Erfordert ein Package.appxmanifest (erstellen Sie eins mit winapp init oder winapp manifest generate wenn Sie keins haben).

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

Optionen:

Was es tut:

• Registriert die Debugidentität für electron.exe Prozess.
• Ermöglicht das Testen von Identitätsanforderungs-APIs in der Elektronenentwicklung
• Verwendet vorhandene Package.appxmanifest für die Identitätskonfiguration.

Beispiele:

# 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

node clear-electron-debug-identity (Befehl zur Bereinigung der Electron-Debug-Identität)

(Nur im NPM-Paket verfügbar) Entfernen Sie die Paketidentität aus dem Electron-Debugprozess, indem Sie die ursprüngliche electron.exe aus der Sicherung wiederherstellen.

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

Optionen:

Was es tut:

• Stellt electron.exe aus der sicherung wieder her, die von add-electron-debug-identity
• Entfernt die Sicherungsdateien nach der Wiederherstellung.
• Gibt Electron in seinen ursprünglichen Zustand ohne Paketidentität zurück.

Beispiele:

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

Globale Optionen

Alle Befehle unterstützen diese globalen Optionen:

• --verbose, – -v Ausführliche Ausgabe für detaillierte Protokollierung aktivieren
• --quiet, - -q Statusmeldungen unterdrücken
• --help, - -h Befehlshilfe anzeigen

Globales Cacheverzeichnis

Winapp erstellt ein Verzeichnis zum Zwischenspeichern von Dateien, die zwischen mehreren Projekten freigegeben werden können.

Standardmäßig erstellt winapp ein Verzeichnis $UserProfile/.winapp als globales Cacheverzeichnis.

Wenn Sie einen anderen Speicherort verwenden möchten, legen Sie die WINAPP_CLI_CACHE_DIRECTORY Umgebungsvariable fest.

In cmd:

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

In PowerShell und pwsh:

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

Winapp erstellt dieses Verzeichnis automatisch, wenn Sie Befehle wie init oder restore.

Updateüberprüfungen

Die winapp CLI sucht regelmäßig nach neuen Versionen und zeigt eine einzeilige Benachrichtigung an, wenn ein Update verfügbar ist. Diese Überprüfung wird im Hintergrund ausgeführt und fügt befehle keine Latenz hinzu.

Updateprüfungen werden in CI-Umgebungen automatisch deaktiviert (GitHub Actions, Azure Pipelines usw.).

Um Updateprüfungen manuell zu deaktivieren, legen Sie die WINAPP_CLI_UPDATE_CHECK Umgebungsvariable auf 0.

In cmd:

set WINAPP_CLI_UPDATE_CHECK=0

In PowerShell und pwsh:

$env:WINAPP_CLI_UPDATE_CHECK = "0"

So machen Sie dies dauerhaft:

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

ui

Überprüfen und interagieren Sie mit der Ausführung von Windows App-UIs mithilfe von Benutzeroberflächenautomatisierung (UIA).

winapp ui [command] [options]

Befehle:

• status – Herstellen einer Verbindung mit der App und Anzeigen von Informationen
• inspect - Elementstruktur anzeigen
• search - Suchen von Elementen nach Auswahl
• get-property - Elementeigenschaften lesen
• get-text / get-value - Wert/Text aus Element lesen (TextPattern, ValuePattern oder Name)
• screenshot - Fenster/Element als PNG erfassen (Dialogfelder werden separat erfasst)
• record- Aufzeichnen eines Fenster-/Elementbereichs in einem H.264 MP4-Video (Windows Grafikaufnahme + Media Foundation)
• invoke - Activate-Element (Klicken, Umschalten, Erweitern)
• click - Click-Element über Maussimulation (für Steuerelemente, die den Aufruf nicht unterstützen)
• hover - Maus zum Element bewegen, um QuickInfos, Flyouts und Hoverzustände auszulösen (Standardeinstellung: 800 ms)
• drag - Ziehen Sie die Maus von einem Punkt an einen anderen, nach Elementmarkierer oder Bildschirmkoordinaten x,y (Neuanordnung, Größe ändern, Schieberegler, Ziehen und Ablegen)
• touch- Einfügen synthetischer Touchgesten (Tippen, Doppeltippen, Lange drücken, Wischen, Zusammendrücken, Strecken) an einer Elementmitte oder Bildschirmkoordinaten x,y
• pen - Einfügen synthetischer Zeichen-/Eingabestifte – Tippen und Freihandstriche mit konfigurierbaren Druck-, Kipp- und Radierermodus
• send-keys - Senden von synthetischen Tastatureingaben (benannte Tasten, Kombinationen, unformatierter vk=0xNN oder Literaltext) an ein Fenster
• set-value - Wert für bearbeitbares Element festlegen (Text, Zahl); zurück auf LegacyIAccessible put_accValue für Nur-TextPattern-Rich-Edit-Steuerelemente
• focus - Tastaturfokus verschieben
• scroll-into-view - Bildlaufelement sichtbar
• wait-for - Auf Elementstatus warten
• list-windows – Auflisten aller Fenster für eine App
• get-focused - Melden des aktuell fokussierten Elements

Optionen:

• -a, --app <app> - Ziel-App (Name, Titel oder PID)
• -w, --window <hwnd> - Zielfenster von HWND (stabil)

Ui-Datensatz

Zeichnen Sie ein Fenster oder einen Elementbereich in einem H.264 MP4 auf.

# 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

Datensatzoptionen:

• --duration-sec <n> - Aufzeichnungslänge in Sekunden. 0 datensätze bis STRG+C (Standard 0).
• --fps <n> - Frames pro Sekunde zum Erfassen (Standardeinstellung 15).
• --max-edge <px> - Abwärtsskalen, sodass die längste Kante höchstens diese anzahl Pixel beträgt (0 = keine Abwärtsskalen).
• --capture-screen - Aufnahme über den Bildschirm, sodass Überlagerungen/Popups enthalten sind (kann Fenster erfassen).
• -o, --output <path> - Ausgabepfad .mp4 (Standardwert: recording-<timestamp>-<guid>.mp4).
• --frames - Schreiben sie zeitstempelte JPEGs, frames.ndjsonund manifest.json in <output-name>.frames. Unterstützt 1-30 fps und --max-edge 64-4096 (Standard 1280), mit einer GiB-Frame-Datenkappe.

Mit --jsondiesem Ergebnis enthält das Endergebnis den Ausgabepfad, Dimensionen, Codec, Aufnahmemodus, Häufigkeit, Stoppgrund, optional frameArtifactsund Warnungen.

Bekannte Einschränkung: Das Aufzeichnen eines bestimmten Elements innerhalb eines Popups, das in einem eigenen Fenster der obersten Ebene (WinUI/XAML-Flyout, Lehrtipp, QuickInfo) gerendert wird, kann stattdessen das zugrunde liegende Hauptfenster erfassen. Zeichnen Sie das gesamte Fenster auf, oder verwenden Sie ui screenshot --capture-screen popup-Stills. In Problem Nr. 646 nachverfolgt.

Eine vollständige Dokumentation finden Sie in der Referenz zur Benutzeroberflächenautomatisierung.