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

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.

Automatische Erkennung eines .NET-Projekts:

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 --setup-sdks none (oder übersprungener SDK-Installation) ausgeführt init 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.

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 noneexperimental(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)

winapp pack <input-folder> [options]

Argumente:

• input-folder - Verzeichnis, das die zu verpackenden Anwendungsdateien enthält

Optionen:

• --output <filename> - Ausgabe-MSIX-Dateiname (Standard: <name>_<version>_<arch>.msix, Rückfall auf <name>_<version>.msix, <name>_<arch>.msixoder <name>.msix wenn Version/Bogen nicht bestimmt werden kann)
• --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 Name für die Zertifikatgenerierung
• --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 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 *.csprojwinapp.yaml 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 Executable Attribut enthalten ist$targetnametoken$:

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

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 CN (Standard: CN=<current user>)
• --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.

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

<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}.debug auch {name} 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 Name des Zertifikats
• --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 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.

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)
• invoke - Activate-Element (Klicken, Umschalten, Erweitern)
• click - Click-Element über Maussimulation (für Steuerelemente, die den Aufruf nicht unterstützen)
• set-value - Festlegen des Werts für bearbeitbares Element (Text, Zahl)
• 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)

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