CLI-Dokumentation und -Verwendung

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

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

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.

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.

Hinweis

Für .NET Projekte, die mit winapp init initialisiert wurden, gibt es keine winapp.yaml. Verwenden Sie stattdessen dotnet restore, um NuGet-Pakete wiederherzustellen.

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.

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.

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 an die MSIX-Bundleversion verteilt, 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

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:

Platzhalter im Manifest

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

Platzhalter Gelöst in Beispiel
$targetnametoken$ Name der ausführbaren Datei ohne Erweiterung Executable="$targetnametoken$.exe" → Executable="MyApp.exe"
$targetentrypoint$ Windows.FullTrustApplication Immer automatisch gelöst

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.

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

Argumente:

  • input-folder - Verzeichnis, das die auszuführende App enthält (erforderlich)

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

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:

Eigentum Standard Beschreibung
EnableWinAppRunSupport true Aktivieren/Deaktivieren der Ausführungsunterstützungsfunktionalität
WinAppLaunchArgs (leer) Argumente, die beim Start an die App übergeben werden sollen
WinAppRunUseExecutionAlias false Starten über ausführungsalias anstelle der AUMID-Aktivierung
WinAppRunNoLaunch false Identität nur registrieren, ohne starten zu müssen
WinAppRunDebugOutput false Erfassen Sie OutputDebugString Nachrichten und Ausnahmen mit der ersten Chance. Es kann jeweils nur ein Debugger angefügt werden (verhindert VS/VS-Code). Verwenden Sie WinAppRunNoLaunch stattdessen, um einen anderen Debugger anzufügen. 
<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

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

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

Hinweis

Bindungen sind nur npm-only – sie erfordern Aufrufe über npx winapp (das @microsoft/winappcli npm-Paket); die eigenständige Winget CLI wird nicht angezeigt. Führen Sie winapp init interaktiv aus, oder verwenden Sie sie, bevor Sie diesen Befehl verwenden winapp init . --use-defaults --add-js-bindings, um Bindungen neu zu generieren. Wenn Sie bearbeitenwinapp.yaml, führen Sie vor npx winapp restore der Neugenerierung Windows Abhängigkeiten aus.

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

Von Bedeutung

Es gibt ein bekanntes Problem mit spärlichen Verpackungen von Electron-Anwendungen, die dazu führen, dass die App beim Start abstürzt oder den Webinhalt nicht rendert. Das Problem wurde in Windows behoben, wurde jedoch noch nicht an externe Windows Geräte weitergegeben. Wenn dieses Problem nach dem Aufrufen add-electron-debug-identityangezeigt wird, können Sie die Sandkastenfunktion in Ihrer Electron-App für Debugzwecke mit der --no-sandbox Kennzeichnung deaktivieren. Dieses Problem wirkt sich nicht auf die gesamte MSIX-Verpackung aus.

Um die Electron-Debug-Identität zurückzusetzen, verwenden Sie winapp node clear-electron-debug-identity.

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

Optionen:

Option Beschreibung
--manifest <path> Pfad zu benutzerdefiniertem Package.appxmanifest (Standard: Package.appxmanifest im aktuellen Verzeichnis)
--no-install Installieren oder ändern Sie keine Abhängigkeiten; konfigurieren Sie nur die Electron-Debugidentität
--keep-identity Beibehalten der Manifestidentität, so wie sie ist, ohne .debug an den Paketnamen und die Anwendungs-ID anzufügen.
--verbose Ausführliche Ausgabe aktivieren

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:

Option Beschreibung
--verbose Ausführliche Ausgabe aktivieren

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 das Zielfenster – oder den Bereich eines einzelnen Elements – in einem H.264 MP4-Video auf. Frames werden über Windows Graphics Capture (mit einem PrintWindow-Fallback) erfasst und inkrementell mit Media Foundation codiert, sodass lange Aufzeichnungen niemals im Arbeitsspeicher puffern.

# 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

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

Mit --json, emittiert einen UiRecordResult Umschlag einschließlich der Ausgabe path, , frames, width, height, , fileSizecodec ("h264") und mode — den tatsächlich verwendeten Aufnahmepfad (wgc, printwindow, oder screen).

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. Nachverfolgt in #646.

Vollständige Dokumentation finden Sie unter docs/ui-automation.md.

  • Last updated on