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: das ausgewählte Projektverzeichnis oder das aktuelle Verzeichnis, wenn kein Projekt erkannt wird)
• --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>- Vorlagenname (z. B. , , , winui-mvvm, winui-lib, winui-unittestoder eine experimentelle Reaktorvorlage, zreactor. B. winuioder reactor-mvu). winui-navview Wird zur Laufzeit anhand des installierten Pakets überprüft; ausführen winapp new --list , um alle anzuzeigen. Standard: winui (leere XAML-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:

Das Paket enthält zwei Stile der WinUI-App. XAML-Vorlagen definieren die Benutzeroberfläche im Markup mit einem C#-CodeBehind. Reaktorvorlagen sind reines C# ohne XAML, wobei ein MVU-Muster (Model-View-Update) verwendet wird. 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:

Reaktorvorlagen sind experimentell. Sie verweisen auf die Vorabversionspakete Microsoft.UI.Reactor , deren APIs in einer zukünftigen Version geändert oder entfernt werden können. winapp newmarkiert sie (Experimental) in --list und in der interaktiven Auswahl, legt ein --json"Experimental": true und druckt eine Warnung nach dem Gerüst. Sie werden niemals als Standardvorlage ausgewählt. Der Reaktor erfordert auch das .NET 10 SDK oder neuer. Bei einem älteren SDK winapp new tritt ein Fehler vor der benötigten Version auf, anstatt ein Projekt zu erstellen, das Sie nicht erstellen können.

Der kanonische Kurzname jeder Vorlage ist die erste Aliasliste dotnet new dafür. Alle aufgelisteten Aliase (z. B. winui3, wasdk-single, winui-reactor) 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.

Eine erste Ausführung kann länger dauern: Das Installieren oder Aktualisieren des Vorlagenpakets oder das Wiederherstellen fehlender Windows App SDK NuGet-Pakete, die von der ausgewählten Vorlage verwendet werden, können zusätzliche Downloads erfordern. Dies kann auch geschehen, nachdem eine neue Windows App SDK Version veröffentlicht wurde. Wenn das Gerüst nach 10 Sekunden noch ausgeführt wird, wird die Statusmeldung aktualisiert, winapp new um anzugeben, dass Pakete möglicherweise heruntergeladen oder wiederhergestellt werden.

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

# Experimental Reactor app (pure C#, no XAML) — requires the .NET 10 SDK
winapp new --name MyApp --template reactor-mvu

# Always use the newest template pack, no prompts
winapp new --name MyApp --template-version latest --use-defaults

# Show the underlying dotnet commands and their output
winapp new --name MyApp --verbose

# Non-interactive (agent) with machine-readable output
winapp new --use-defaults --name MyApp --json

wiederherstellen

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

winapp restore [base-directory] [options]

Argumente:

• base-directory - Verzeichnis, das wiederhergestellt werden soll (Standard: aktuelles Verzeichnis). Wählt auch aus, wo sie nuget.config gelesen werden, winapp.yaml es sei denn--config-dir, es wird außer Kraft gesetzt.

Optionen:

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

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

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

Benutzerdefinierte und private NuGet-Feeds:

winapp init, restoreund update laden Sie das Windows SDK und Windows App SDK Pakete über NuGet herunter, um Ihre Standardhierarchie nuget.config zu berücksichtigen. Private Feeds und Spiegelungen, Feedanmeldeinformationen (einschließlich Anmeldeinformationsanbietern) und eine benutzerdefinierte globalPackagesFolder Arbeit funktionieren wie für dotnet restoresie. Um ausschließlich aus Ihrem eigenen Spiegel wiederherzustellen, <clear /> fügen Sie die geerbten Quellen hinzu, und fügen Sie nur Ihre hinzu:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="contoso" value="https://pkgs.dev.azure.com/contoso/_packaging/winsdk-mirror/nuget/v3/index.json" />
  </packageSources>
</configuration>

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 einem Projekt oder 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 einen einzelnen.csproj, um das Projekt zu erstellen und die Ausgabe in einem Schritt zu verpacken (siehe Projektmodus, siehe Packen eines Projekts direkt unten). Ü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 – Ein Einzelner .csproj zum Erstellen und Verpacken (Projektmodus) oder ein oder mehrere Verzeichnisse, die die zu verpackenden Anwendungsdateien enthalten. Ü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
• --no-sign – Übermitteln Sie das Paket ohne Vorzeichen, und überschreiben Sie alle Projektsignierungskonfigurationen (z. B. für die Store-Übermittlung oder eine externe Signaturpipeline). Kann nicht mit --cert oder --generate-cert kombiniert werden.
• --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.

Project-Modus-Optionen (eingabe erforderlich.csproj; für Ordner-/Bundle-/Manifesteingaben abgelehnt):

• --configuration <name> (-c) - Buildkonfiguration (Standard: Release)
• --arch <arch> - Zielarchitektur: x64, , arm64oder x86 (Standard: die aktuelle Prozessarchitektur)
• --framework <tfm> (-f) - Zielrahmenmoniker für multiorientierte Projekte
• --no-build – Packen der vorhandenen Buildausgabe ohne Neuerstellung
• --no-restore - Das Wiederherstellen des Projekts vor dem Erstellen überspringen
• --property <name=value> (-p) - MSBuild-Eigenschaft, weitergeleitet an Build und Auswertung (wiederholbar)

Hinweis: Für einen WinUI / EnableMsixTooling.csproj (MSIX-Tooling-Projektmodus) besitzt die Windows App SDK das Manifest, den Einstiegspunkt und die PRI-Generierung, also --manifest, --executableund --skip-pri werden abgelehnt – konfigurieren<AppxManifest>, den Einstiegspunkt des Projekts und dessen Ressourcenbuild im Projekt selbst. Diese drei Optionen gelten weiterhin für Ordnereingaben und für den generischen (nicht-MSIX-tooling) .csproj -Projektmodus.

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.

Direktes Packen eines Projekts

Wenn es sich bei der Eingabe um einen einzelnen .csprojhandelt, winapp pack erstellt das Projekt (mithilfe der oben genannten Optionen) und packt die resultierende Ausgabe – sie müssen nicht separat erstellt oder zuerst den Ausgabeordner suchen. Dadurch wird der Projektmodus gespiegelt winapp run.

# Build MyApp in Release for arm64 and package + sign it in one step
winapp pack ./MyApp.csproj -c Release --arch arm64 --cert ./devcert.pfx

# Package an existing build output without rebuilding
winapp pack ./MyApp.csproj --no-build

# Select the target architecture with an exact RID instead of --arch
winapp pack ./MyApp.csproj -p RuntimeIdentifier=win-x64

Die Zielarchitektur stammt von --archoder von einem Einzelnen -p RuntimeIdentifier=<rid> , wenn Sie nicht übergeben --arch werden (die genaue RID wird beibehalten und steuert den Build). Das Übergeben von beiden --arch und -p RuntimeIdentifier ist ein Konflikt und wird abgelehnt.

Das Projekt muss als verpackte App (EnableMsixTooling=true mit einem Package.appxmanifest) erstellen; ein Projekt, das als entpackte App (WindowsPackageType=None) erstellt wird, verfügt über kein MSIX-Manifest zum Packen und winapp pack meldet einen Fehler mit Aktionen. Ordner-, Bundle- und Sparse-Manifesteingaben bleiben unverändert.

Project Modus erzeugt einen einzelnen .msix oder einen reinen Architekturmodus .msixbundle (siehe Multi-Architecture Bundles). Es erzeugt keine Store-Upload-Archive oder Ressourcenteilungspakete (Sprache/Skalierung): ein explizites -p UapAppxPackageBuildMode=StoreUpload Oder -p AppxBundleAutoResourcePackageQualifiers=... wird mit einer Notiz abgelehnt, um den systemeigenen SDK-Paketbefehl direkt für diese Flüsse auszuführen.

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

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 einen X.500 DN mit einzelwertigen, durch Trennzeichen getrennten Komponenten (mehrwertige + RDNs und umgekehrte Schrägstriche werden nicht unterstützt). Bare Namen werden automatisch als CN=<Name> eingeschlossen.
• --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. Die Datei muss ihre eigene Größe entweder durch ein viewBox oder absolute width Und height Attribute deklarieren; eine Prozentbreite ohne viewBox Beschreibt keine bestimmte Größe. Eine Quelle, die keines deklariert, wird nicht mit SVG image has no usable dimensions leeren Ressourcen, sondern abgelehnt.

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 drei 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.
• Einzeldateimodus – die Eingabe ist eine .cs.NET dateibasierte App. winapp run erstellt es, generiert ein Manifest aus seinen #:property Direktiven und startet es mit paketidentität.

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), eine .cs .NET dateibasierte App (Einzeldateimodus), ein .csproj Projekt, eine .sln/.slnx Lösung oder ein Verzeichnis, das eine der Dateien auf oberster 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 Layout (Standard: AppX innerhalb des Eingabeordners). Das Standardlayout entfernt Dateien nicht mehr im Build. Ein benutzerdefiniertes Verzeichnis behält zusätzliche Dateien bei. Verwenden Sie ein neues benutzerdefiniertes Verzeichnis, wenn Sie ein sauberes Layout benötigen.
• --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. Selten erforderlich: Eine App, die OutputType=Exe bereits auf diese Weise gestartet wird, wird standardmäßig gestartet. winapp fügt dem Manifest, uap5:ExecutionAlias das es phasenweise im AppX-Layout, hinzu. Daher ist keine Änderung des eingecheckten Manifests erforderlich. Ein Alias, der von der App deklariert wird, wird as-isverwendet. Kann nicht mit --no-launch, --detach, , --without-aliasoder --json.
• --without-alias – Erzwingen der AUMID-Aktivierung für eine App, die andernfalls über einen Ausführungsalias gestartet würde. Eine Konsolen-App wird dann ohne Konsole ausgeführt und druckt nichts an diesem Terminal. Kann nicht mit --with-alias.
• --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. Lokale Ausführung druckt die PID; Das Ziel wird ausgeführt, um das bereichsbezogene UI-Ziel zu drucken. JSON enthält den PID- und Zielbereich. 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.
• --on <target> – Erstellen Sie auf dem Host, registrieren Sie den Host, und führen Sie sie im Ziel aus. Unterstützt sandboxderzeit , ohne Fallback auf die lokale Ausführung. Verwenden Sie --detach vor der Nachverfolgung von UI-Befehlen. Sandkasten --debug-output erfordert eine verpackte App. Weitere Informationen finden Sie unter Windows Sandkastenausführung für Setup, Laufzeitunterstützung und Lebensdauer von getrennten Apps.

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

Native AOT: Fügen Sie diese Eigenschaftengruppe innerhalb des Elements der project Datei <Project> hinzu, und fügen Sie dann Folgendes hinzu--aot:

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

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

--aotunterstützt x64- und ARM64-Projekte und erfordert das .NET SDK 8.0.300 oder höher. Sie wird mit der AOT-Konfiguration des Projekts ausgeführt dotnet publish und startet diese Ausgabe. Verwenden Sie -p PublishAot=true sie für eine einmalige Außerkraftsetzung. Es führt keine separate Laufzeitzertifizierung durch und kann nicht mit --no-build oder --manifestkombiniert werden.

Für Apps, die die Paketidentität ohne generiertes MSIX-Layout verwenden, schließen Sie Package.appxmanifest die Veröffentlichungsausgabe des Projekts ein oder appxmanifest.xml aus. Winapp stellt die veröffentlichten Dateien mit diesem Manifest auf. Wenn beide Namen vorhanden sind, stoppt winapp, anstatt eines auszuwählen. Entfernen Sie das veraltete Manifest, und konfigurieren Sie das Projekt so, dass nur das beabsichtigte Manifest veröffentlicht wird.

Project-Modus-Optionen (im Ordnermodus ignoriert, sofern nicht angegeben):

• -c, --configuration <name> – Buildkonfiguration. Standardwert: Debug. (Auch im Einzeldateimodus berücksichtigt.)
• --arch <x64|arm64|x86> - Zielarchitektur. Standard: die aktuelle Prozessarchitektur. Bestimmt die Build-RID- und Windows-App Runtime-Architektur und wählt ein passendes plattformabhängiges Veröffentlichungsprofil aus, wenn dies für den effektiven Build erforderlich ist. (Auch im Einzeldateimodus berücksichtigt.)
• -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. Die Architektur setzt außer Kraft --arch und kann das erforderliche Veröffentlichungsprofil auswählen. (Wird auch im Einzeldateimodus berücksichtigt, wobei eine #:property RuntimeIdentifier von der Datei deklarierte Außerkraftsetzung erfolgt.)
• -f, --framework <tfm> - Zielrahmenmoniker für multi-gezielte Projekte (z. B. net10.0-windows10.0.26100.0). (Abgelehnt im Einzeldateimodus – Verwenden Sie #:property TargetFramework=....)
• --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). (Im Einzeldateimodus abgelehnt – eine .cs dateibasierte App ist selbst das Projekt.)
• --no-build - Überspringen Sie die Erstellung, und führen Sie die vorhandene Buildausgabe aus (wertet weiterhin Ausgabeeigenschaften aus). (Auch im Einzeldateimodus berücksichtigt.)
• --no-restore – Überspringen Sie die Wiederherstellung vor dem Erstellen oder der nativen AOT-Veröffentlichung. (Auch im Einzeldateimodus berücksichtigt.)
• --aot– Führen Sie die konfigurierte .NET native AOT-Veröffentlichung des Projekts aus. Erfordert eine effektive PublishAot=true. In Ordner- und Einzeldateimodi abgelehnt.
• -p, --property <Name=Value> - MSBuild-Eigenschaft, weitergeleitet an den Build und die Eigenschaftsauswertung. Wiederholen Sie diesen Vorgang -p für mehrere Eigenschaften; verwenden %3B Sie %2C ein Literal-Semikolon oder Komma in einem Wert. (Wird auch im Einzeldateimodus berücksichtigt, wo es die einzige Möglichkeit zum Festlegen TargetFrameworkvon .)

Buildausgabe und Ausführlichkeit: Eine normale Projektausführung verwendet dotnet buildund wertet dann die integrierte Ausgabe aus. Wiederherstellen und Erstellen des Ausgabedatenstroms live mit Anmeldeinformationen aus authentifizierten Feed-URLs. Mit --aot, winapp verwendet dotnet publish; --verbose zeigt den Veröffentlichungsbefehl und aufgelöste Pfade an. Verwenden Sie die nachstehenden Ausführlichkeitsoptionen, um zu steuern, was angezeigt wird:

Native AOT veröffentlicht Ausgabedatenströme, sobald es eingeht. Under --json, restore/build invocations and child output go to stderr so stdout stays pure JSON. Unter --quiet"Aufrufe" werden unterdrückt, und die ruheige Wiederherstellungs-/Buildausgabe von dotnet wird an stderr weitergeleitet, sodass stdout sauber bleibt. Die native AOT-Veröffentlichungsausgabe wechselt auch unter beiden Optionen zu Stderr.

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

# Publish and run the Release configuration with Native AOT
winapp run . --aot -c Release

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

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

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

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

Einzeldateimodus (.NET dateibasierte Apps)

mit .NET 10 können Sie eine einzelne .cs Datei ohne Projektdatei ausführen und sie mit #: Direktiven oben konfigurieren. Zeigen winapp run Sie auf diese Datei, und sie erstellt die App, generiert dafür ein appxmanifest und startet sie mit der Paketidentität . Dies funktioniert also Windows.ApplicationModel.Package.Current , die App erhält eine echte AUMID und einen Startmenüeintrag, und die APIs, die einfach Identitäten (App-Benachrichtigungen, ApplicationData, on-Device AI) erfordern, funktionieren.

Shellintegrationen wie Protokollhandler, Dateizuordnungen, Freigabeziele und Startaufgaben benötigen einen deklarierten <Extensions> Eintrag, der vom generierten Manifest nicht enthalten ist. Um eins hinzuzufügen, erstellen Sie Ihr eigenes Manifest – siehe "Eigenes Manifest mitbringen " weiter unten.

winapp run counter.cs

Oder führen Sie sie mit einfachem dotnet run Format aus – siehe "Ausführen mit dotnet run unten".

Sie erstellen kein Manifest. Beschreiben Sie stattdessen das Paket mit #:property Direktiven:

#:package Microsoft.UI.Reactor@0.1.0-preview.13
#:property OutputType=WinExe
#:property TargetFramework=net10.0-windows10.0.22621.0
#:property UseWinUI=true
#:property RuntimeIdentifier=win-x64

#:property WinAppPackageName=com.contoso.counter
#:property WinAppDisplayName=Contoso Counter
#:property WinAppDescription=Counts things, one click at a time
#:property Version=1.2.3

using static Microsoft.UI.Reactor.Factories;
ReactorApp.Run<MyApp>("Hello");

Manifesteigenschaften. Alle sind optional; jeder fall back to a sensible default:

Version. Eine Paketversion muss genau vier Zahlen sein, jeweils 0 bis 65535. WinAppVersion (oder, wenn Sie sie nicht festlegen, wird die Standardeigenschaft Version so normalisiert, dass sie wie folgt -preview/-rc passt: Suffix wird gelöscht, und fehlende Komponenten werden mit Nullen gefüllt, sodass #:property Version=1.2.3-preview.4 die Assemblyversion und die Paketversion zusammen festgelegt werden 1.2.3.0 . Ein Wert, der nicht angepasst werden kann – eine Komponente über 65535 oder mehr als vier Komponenten – wird mit einem Fehler abgelehnt , anstatt im Hintergrund geändert zu werden.

Capabilities

Ihre App wird voll vertrauenswürdig mit Identität ausgeführt, was APIs erfüllt, die nur eine verpackte App erfordern. Einige APIs werden jedoch unabhängig von einer deklarierten Funktion bereitgestellt – die Windows AI-APIs sind die gängigen Fälle. (Shell-Integrationen wie Protokollhandler und Dateizuordnungen sind ein dritter Fall: Diese benötigen verfasste <Extensions> Einträge, keine Funktion, verwenden Sie also Ihr eigenes Manifest für sie.)

#:property WinAppCapabilities=systemAIModels

Das sind alle Phi-Silikadikate und die anderen On-Device-Modell-APIs, die aus dem Manifest benötigt werden. Deklarieren Sie mehrere, indem Sie sie trennen:

#:property WinAppCapabilities=systemAIModels;internetClient;microphone

winapp schreibt jeden in den Element- und XML-Namespace, den er tatsächlich benötigt, deklariert diesen Namespace und löst aus MaxVersionTested , wenn die Funktion eine neuere benötigt. Dies ist mehr wichtig als es klingt: Funktionen sind auf mehrere verschiedene Elemente verteilt, und die gleiche Liste oben wird zu drei verschiedenen Formen –

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

Namen winapp weiß, sind für Sie geschrieben. Für alles andere – der eingeschränkte Satz wächst im Laufe der Zeit – qualifizieren sie sich selbst mit dem Namespacepräfix:

#:property WinAppCapabilities=rescap:broadFileSystemAccess

Ein unbekannter bare Name wird mit einem Fehler abgelehnt, bei dem diese Präfixe benannt werden, anstatt zu erraten – eine im falschen Namespace ausgegebene Funktion erzeugt ein Manifest, Windows sich entweder weigert, sich zu registrieren oder zu akzeptieren, während sie im Hintergrund nicht gewährt wird.

Bringen Sie Ihr eigenes Manifest mit

Wenn Sie etwas benötigen, das die Eigenschaften nicht abdecken – einen Protokollhandler, eine Dateizuordnung, einen Ausführungsalias – erstellen Sie ein Manifest und winapp run verwenden sie verbatim, anstatt eines zu generieren. Es wird in der Reihenfolge abgeholt:

1. --manifest <path> auf der Befehlszeile.
2. #:property WinAppManifestPath=<path> in der .cs Datei.
3. Ein Manifest, das neben der .cs Datei sitzt ( <filename>.appxmanifest z. B counter.appxmanifest . neben counter.cs).

Nur dieser Dateiname wird automatisch aufgenommen. A Package.appxmanifest oder appxmanifest.xml im selben Ordner wird absichtlich ignoriert – mehrere .cs Dateien können einen Ordner freigeben, und das Übernehmen eines freigegebenen Namens führt eine App automatisch unter der Identität eines anderen aus. Um ein Manifest für mehrere Dateien zu verwenden, benennen Sie es explizit mit --manifest oder WinAppManifestPath.

Andernfalls wird ein Package.appxmanifest Objekt in der Buildausgabe zusammen mit den Standardimageressourcen generiert und bei jeder Ausführung aktualisiert.

Options. Jede Ordnermodusoption funktioniert: --no-launch, , --with-alias, --without-alias, --detach, , --clean, --debug-output, --symbols, --unregister-on-exit, --args--/, , --json, --output-appx-directory--executable-c/--configuration--no-build--manifest--no-restoreund .-p/--property

winapp run counter.cs

#:property WinAppRunUseExecutionAlias=false

Der Alias winapp declares is named after the package family name, with a winapp- prefix — so com.contoso.counter published by CN=You get winapp-com.contoso.counter_gspb8g6x97k2t.exe. Dieser nachfolgende Teil ist der Herausgeberhash Windows abgeleitet, sodass zwei Apps, die einen Namen unter verschiedenen Herausgebern teilen, immer noch unterschiedliche Aliase erhalten. Das Präfix behält den Namen der echten Befehle klar: Eine App in python.cs erhält einen winapp-… Alias, niemals python.exe. Wenn Sie Ihr eigenes Manifest erstellen, wird der alias, den Sie deklarieren, as-is verwendet, und winapp fügt nichts hinzu.

Dies gilt nur für den Alias. Die Registrierung selbst wird auf den Paketnamen festgelegt, sodass das Ausführen einer zweiten App, die dasselbe WinAppPackageName unter einem anderen Herausgeber deklariert, die erste Registrierung ersetzt, anstatt daran zu sitzen. Weisen Sie jeder App einen eigenen Namen zu, wenn beide gleichzeitig registriert werden sollen.

winapp run druckt den registrierten Alias, sodass Sie den Hash nicht berechnen müssen, um ihn zu finden.

Der Alias ist ein Befehl in Ihrem PATH, der dauert, solange das Paket registriert bleibt. Wenn ein anderes Paket bereits den Namen besitzt, sagt winapp dies. Wenn der Alias für Sie stattdessen über AUMID gestartet wird, anstatt die falsche App zu starten; wenn Sie nach einem expliziten – mit --with-alias oder #:property WinAppRunUseExecutionAlias=true – gefragt haben, schlägt dies fehl, anstatt etwas anderes ruhig zu tun.

Zwei Projektmodusoptionen gelten nicht , da eine dateibasierte App sich selbst konfiguriert. Sie werden mit einer Nachricht abgelehnt, die die zu verwendende Direktive benennt:

--arch und -r/--runtime funktionieren wie im Projektmodus. Wenn Sie beides nicht übergeben, erstellen Winapp-Builds für die Architektur Ihres Computers – was eine eigenständige Windows App SDK App benötigt, da ohne sie die SDK-Builds erstellt AnyCPU und fehlschlägt.WindowsAppSDKSelfContained requires a supported Windows architecture A #:property RuntimeIdentifier=win-arm64 in der Datei wird beachtet; eine explizite --arch/--runtime Außerkraftsetzung.

Verpackte und entpackte Arbeiten, erkannt vom effektiven WindowsPackageType genau wie im Projektmodus: Der Standard registriert ein loses Layout und startet es mit Identität, während #:property WindowsPackageType=None die App erstellt, die passende Windows-App Runtime installiert und die .exe direkt startet. (Eine verpackte App wird über ihren Ausführungsalias oder über die AUMID-Aktivierung gestartet– siehe oben die Konsolennotiz. Diese Auswahl unterscheidet sich von der Gepackten.) Die Identitätsoptionen (--no-launch, --with-alias, --without-alias, --clean--unregister-on-exit, , --manifest, , --output-appx-directory) gelten nur für verpackte Apps.

Ausführen mit dotnet run

Sie müssen überhaupt nicht eingeben winapp . Verweisen Sie auf das Microsoft.Windows.SDK.BuildTools.WinApp Paket aus der Datei, und nur gibt dotnet run Ihnen den gleichen paketierten Start:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

System.Console.WriteLine(Windows.ApplicationModel.Package.Current.Id.FamilyName);

dotnet run counter.cs

Die MSBuild-Ziele des Pakets leiten die Ausführung auf winapp um, die pakete, registriert und startet die soeben erstellte App dotnet run – sie wird nicht neu erstellt. Die Manifestbehandlung ist unverändert: winapp löst sie genau wie für winapp runsie aus, also #:property WinAppManifestPath=… und eine <filename>.appxmanifest neben den .cs beiden geehrten (siehe Bring your own manifest), a directory wide Package.appxmanifest is still ignored, and otherwise one is generated from your #:property directives and refreshed every run.

Für die Umleitung müssen zwei Bedingungen gehalten werden:

Durch das Hinzufügen #:property WindowsPackageType=None wird auch die Datei allein gelassen: dotnet run Führt dann die .exe direkte Ausführung ohne Identität aus. Wird für den entpackten Pfad verwendetwinapp run, wenn zuerst der entsprechende Windows-App Runtime installiert werden soll.

Legen Sie #:property EnableWinAppRunSupport=false fest, dass die Umleitung vollständig abgemeldet wird, und die WinAppRun* unter "Konfiguration " beschriebenen Eigenschaften, um den Start zu gestalten , z. B.:

#:property WinAppRunUnregisterOnExit=true

Wenn dotnet run die App beim Erwarteten der Identität entpackt wird, fragen Sie MSBuild warum. Verwenden Sie dotnet buildnicht dotnet msbuild – synthetisiert nur dotnet build das virtuelle Projekt, über das eine dateibasierte App kompiliert wird:

dotnet build counter.cs -t:WinAppRunSupportInfo

Der Einzeldateimodus erfordert das .NET SDK 10.0.300 oder höher.

Die Registrierung überlebt den Lauf. winapp run counter.cs lässt das Paket nach dem Beenden der App registriert, genau wie Ordner und Projektmodus – bleibt also LocalState erhalten, und die gleiche Datei wird dieselbe Identität wiederverwendet, anstatt Registrierungen aufzufüllen. winapp sagt, dass sie eine App zum ersten Mal registriert und winapp unregister sich selbst .cs übernimmt:

# Remove the registration (resolves the same identity `winapp run` registered)
winapp unregister counter.cs

# Or remove it as soon as the app exits
winapp run counter.cs --unregister-on-exit

winapp unregister counter.cs benötigt keinen Manifestpfad: Er wertet die Werte der Datei #:property auf die gleiche Weise run aus und entfernt nur ein Paket, das aus der Buildausgabe dieser Datei registriert ist. Eine aus einem anderen Ordner registrierte app mit demselben Namen wird verweigert, es sei denn, Sie übergeben --force. Wenn die Ausführung eine Option verwendet hat, die die Identität oder das Layout gestaltet, übergeben Sie dasselbe an unregister:

winapp run counter.cs -p WinAppPackageName=com.contoso.alt
winapp unregister counter.cs -p WinAppPackageName=com.contoso.alt

winapp run counter.cs -c Release --arch arm64
winapp unregister counter.cs -c Release --arch arm64

-p setzt die eigenen Direktiven der Datei außer Kraft, und eine Directory.Build.props neben dem .cs Schlüssel aus WinAppPackageName$(Configuration) oder $(RuntimeIdentifier) – so kann jeder dieser Elemente ändern, welches Paket registriert wird.

Nachdem die temporäre Ausgabe des SDK bereinigt wurde, winapp unregister counter.cs kann die Registrierung nicht mehr von dieser Datei bestätigt werden und überspringt sie . Verwenden Sie dies winapp unregister --prune zum Löschen von Registrierungen, deren Dateien nicht mehr vorhanden sind, oder --force um eine bestimmte Datei trotzdem zu entfernen. Wenn die verwendete Ausführung verwendet wird --output-appx-directory, übergeben Sie dasselbe Verzeichnis, unregister damit es das Layout erkennen kann.

Das gleiche gilt für einen benutzerdefinierten Ausgabepfad: Der Besitz wird vom Standardlayout <root>\bin\<configuration> des SDK bestätigt, sodass eine integrierte Ausführung nicht -p OutputPath=<somewhere-else> mit der Quelldatei abgeglichen werden kann. unregister überspringt es, anstatt es in einem breiteren Verzeichnis zu erraten – nennen Sie das Layout mit --output-appx-directory, oder verwenden Sie --force.

Beispiele für einzelne Dateien:

# Build and run a file-based app with package identity
winapp run counter.cs

# Register identity without launching (e.g. to attach Visual Studio)
winapp run counter.cs --no-launch

# Release build, detached, printing the PID as JSON
winapp run counter.cs -c Release --detach --json

# Capture OutputDebugString output and crash diagnostics
winapp run counter.cs --debug-output

# Forward arguments to the app
winapp run counter.cs -- --verbose --input data.json

# Wipe the app's LocalState and start fresh
winapp run counter.cs --clean

# Remove the package it registered
winapp unregister counter.cs

MSBuild-Eigenschaften (NuGet-Paket):

Bei Verwendung des Microsoft.Windows.SDK.BuildTools.WinApp NuGet-Pakets ruft dotnet run automatisch winapp run auf.

Alles, was nach dotnet run der Übergabe an Ihre Anwendung geschrieben wurde, genau so, wie es ohne das Paket wäre. Konfigurieren Sie das Startfeld mit den folgenden MSBuild-Eigenschaften:

# Goes to your app. `--` is optional here, but required when the flag is also a
# `dotnet run` option (--configuration, --framework, --project, -c, -f, -r, ...),
# otherwise the SDK claims it and your app never sees it.
dotnet run --devtools
dotnet run -- --devtools
dotnet run -- --configuration Release

# Configures WinApp; --devtools still reaches your app
dotnet run -p:WinAppRunDetach=true --devtools

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 ist bewusst nicht in dieser Liste, in beide Richtungen. false fordert die AUMID-Aktivierung auf, die nicht gestartet und bereits ablöst; true wird einfach nicht angewendet, wenn beides festgelegt ist, da ein Ausführungsalias einen nachverfolgten, ausgeführten Prozess benötigt. Daher wird ein Projekt, das nach wie vor sauber dotnet run -p:WinAppRunDetach=trueeingecheckt <WinAppRunUseExecutionAlias>true</WinAppRunUseExecutionAlias> wird, gestartet über AUMID statt fehlschlagen.

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

Argumente:

• input– Pfad zu einer dateibasierten .NET-App (ein einzelner.cs), dessen Paket nicht registriert werden soll. Seine Identität wird auf die gleiche Weise winapp run aufgelöst – aus einem autorierten Manifest, wenn die App einen hat, andernfalls aus ihren #:property Werten , sodass kein Manifestpfad erforderlich ist. Lassen Sie die Verwendung --manifest oder automatische Erkennung eines Manifests im aktuellen Verzeichnis aus. Kann nicht kombiniert werden, mit --manifestdem das Paket anders benannt wird und in ein anderes aufgelöst werden kann.

Optionen:

• --manifest <path> - Pfad zu "Package.appxmanifest" (Standard: automatische Erkennung aus dem aktuellen Verzeichnis)
• --force – Überspringen Sie bei der lokalen Registrierung nur die Verzeichnisüberprüfung des Installationsspeicherorts, und heben Sie die Registrierung auf, auch wenn das Paket aus einer anderen Projektstruktur registriert wurde. Sie wird mit --on; Zielbesitzprüfungen können nicht umgangen werden.
• --on <target> - Entfernen Sie die entsprechende winapp-eigene Entwicklungsregistrierung von , nicht von sandboxdiesem Computer. Erfordert ein Manifest und unterstützt --forcenicht . Siehe Sandkasten-App-Bereinigung.
• --prune - Entfernen Sie jede Registrierung im Entwicklungsmodus, deren Dateien nicht mehr vorhanden sind. Kann nicht mit einer Eingabe, --manifest, , --property, --configuration, , --arch, oder --output-appx-directory--runtime.
• -p, --property <Name=Value> – MSBuild-Eigenschaft, die beim Auflösen der Identität einer .cs dateibasierten App verwendet wird. Wiederholbar. Übergeben Sie dieselben identitätsrelevanten Eigenschaften, die die Ausführung verwendet (z. B. -p WinAppPackageName=...), da eine Befehlszeileneigenschaft die eigenen #:property Direktiven der Datei außer Kraft setzt. Gilt nur für eine .cs Eingabe.
• -c, --configuration <name> – Buildkonfiguration, die beim Auflösen der Identität einer .cs dateibasierten App verwendet wird. Standardwert: Debug. Übergeben Sie dieselbe Konfiguration wie die verwendete Ausführung: eine Directory.Build.props neben der .cs kann festgelegt WinAppPackageName oder WinAppManifestPath bedingt aktiviert $(Configuration)werden. Gilt nur für eine .cs Eingabe.
• --arch <x64|arm64|x86> – Zielarchitektur, die beim Auflösen der Identität einer .cs dateibasierten App verwendet wird. Standard: die aktuelle Prozessarchitektur. Übergeben Sie dieselbe Architektur wie die verwendete Ausführung, da die Identität auch entschlüsselt $(RuntimeIdentifier)werden kann. Gilt nur für eine .cs Eingabe.
• -r, --runtime <rid>– Ziel-.NET Laufzeit-ID (z. B.win-x64), die beim Auflösen der Identität einer .cs dateibasierten App verwendet wird. Nur seine Architektur wird verwendet, und es überschreibt --arch. Gilt nur für eine .cs Eingabe.
• --output-appx-directory <path> – Das AppX-Layoutverzeichnis, aus dem das Paket registriert wurde. Nur erforderlich, wenn die Ausführung verwendet wird --output-appx-directory, da nichts in den Paketdatensätzen, die die Ausführungsoption ausführen, das Layout erzeugt hat.
• --json - Formatieren der Ausgabe als JSON

Was es tut:

• Bestimmt den Paketnamen – aus der aufgelösten Identität der .cs Datei oder durch Lesen des Manifests
• 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 das Paket zu der App gehört, die Sie benannt haben (es sei denn --force), der Installationsspeicherort muss sich unter einem verzeichnis befinden, das Sie identifiziert haben: die .cs eigene Buildausgabe der Datei, das Verzeichnis des Manifests, das aktuelle Verzeichnis oder ein explizites --output-appx-directoryVerzeichnis. Ein Paket, dessen Installationsspeicherort nicht aufgelöst werden kann (seine Dateien wurden gelöscht), wird übersprungen, da Identität allein kein Besitznachweis ist: zwei Apps, die beide die gleiche Identität aus verschiedenen Ordnern festlegen #:property WinAppPackageName=counter . Dient --prune zum Löschen von Registrierungen, deren Dateien nicht mehr vorhanden sind.
• Aufheben der Registrierung übereinstimmener Pakete

Bereinigen von toten Registrierungen (--prune):

Eine Registrierung überlebt ihre Dateien. Löschen Sie eine Buildausgabe, projektstruktur oder (für eine dateibasierte App), damit Windows sauber %LOCALAPPDATA%\Tempbleibt, und das Paket bleibt registriert: Windows behält die Identität und den Startmenüeintrag bei, aber die Aktivierung führt im Hintergrund nichts aus. Diese sammeln sich unsichtbar an.

# List dev registrations whose files are gone, then confirm before removing
winapp unregister --prune

# Skip the prompt (required for non-interactive/CI use)
winapp unregister --prune --force

Es werden nur Registrierungen im Entwicklungsmodus berücksichtigt, und jede wird durch den vollständigen Paketnamen entfernt, sodass ein weiterhin mit demselben Namen installiertes Paket von einem Livespeicherort unberührt bleibt. Die Eingabeaufforderung ist vorhanden, da ein fehlender Installationsspeicherort in der Regel ein gelöschter Ordner ist, aber auch ein Paket beschreibt, das von einer getrennten Netzwerkfreigabe oder einem Wechseldatenträger registriert ist. Überprüfen Sie die Liste, bevor Sie dies bestätigen.

Beispiele:

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

# Unregister a .NET file-based app by its source file
winapp unregister counter.cs

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

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

# Remove every dev registration whose files are gone
winapp unregister --prune

# JSON output for scripting
winapp unregister --json

cert

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 Sie das Zertifikat publisher aus dem ManifestIdentity/@Publisher. Nur der Herausgeber ist erforderlich, sodass ein teilweise vollständiges Manifest weiterhin funktioniert. Wenn das Manifest keinen verwendbaren Herausgeber hat, schlägt der Befehl fehl, anstatt einen Standardwert zu ersetzen, sodass das Zertifikat niemals im Hintergrund mit dem Manifest übereinstimmt.
• --publisher <name>- Publisher für das Zertifikat. Beim Generieren eines Zertifikats hat diese Option Vorrang --manifest; ein explizit leerer Wert schlägt fehl, anstatt den Manifestherausgeber zu verwenden. Akzeptiert einen vollständigen X.500 Distinguished Name (z. B. CN=Contoso, O=Contoso Ltd, C=US) oder einen baren Namen, der automatisch umschlossen CN=<name>wird. Komponenten müssen einwertig und kommagetrennt sein; Mehrwertige RDNs (CN=Foo+OU=Bar) und umgekehrte Schrägstriche werden nicht unterstützt, da der MSIX-Manifestherausgeber sie nicht darstellen kann. Ein falsch formatierter distinguished Name (z. B. CN= oder CN=A,,O=B) wird mit einem Nicht-Null-Exit abgelehnt und ein Fehler beim Benennen des Problems, anstatt ein Zertifikat zu erstellen, das niemals mit dem Manifestherausgeber übereinstimmen kann.
• --output <path> - Ausgabezertifikatdateipfad (unterstützt absolute und relative Pfade)
• --password <password> - Zertifikatkennwort (Standard: password, öffentlich bekannt – siehe JSON-Ausgabe und Sicherheit)
• --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.

JSON-Ausgabe:

{
  "certificatePath": "C:\\app\\devcert.pfx",
  "password": "password",
  "defaultPasswordIsPublic": true,
  "publisher": "Contoso",
  "subjectName": "CN=Contoso",
  "warnings": [
    "Protected with the default password ('password'), which is public. Treat this certificate as development-only: anyone who obtains the .pfx can sign as you. Pass --password to choose your own, and use a CA-issued certificate or Azure Trusted Signing to ship."
  ]
}

publisher ist der Anzeigename und subjectName der vollständige distinguishe Name, für den das Zertifikat ausgestellt wurde. defaultPasswordIsPublic ist immer vorhanden. Wenn es .pfx sich um trueein Kennwort handelt, kann jeder erraten, daher muss das Zertifikat nur Builds signieren, die auf Ihren eigenen Computern verbleiben – überprüfen Sie es, bevor ein Skript das Zertifikat an alles andere übergibt. warnings enthält dieselbe Offenlegung wie Text und wird weggelassen, wenn nichts zu melden ist. publicCertificatePath wird nur mit --export-cer.

Cert-Informationen

Zeigen Sie Zertifikatdetails aus einer PFX- oder CER-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 oder CER)

Optionen:

• --password <password> - Kennwort für die PFX-Datei, für eine öffentliche CER ignoriert (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> <cert-path> [options]

Argumente:

• file-path - Pfad zu MSIX-Paket oder ausführbarer Datei zum Signieren
• cert-path - Pfad zum Signaturzertifikat (PFX)

Optionen:

• --password <password> - Zertifikatkennwort (Standard: "Kennwort")
• --timestamp <url> - RFC 3161-Zeitstempelserver-URL

Beispiele:

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

# Sign executable with a non-default certificate password
winapp sign ./bin/MyApp.exe ./mycert.pfx --password mypassword

az-sign

Codesignieren einer Datei (exe, MSIX oder MSIX Bundle) mit Azure Trusted 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 Azure Codesignaturkonto und ein Zertifikatprofil (erstellt im Azure-Portal nach der Identitätsüberprüfung) sowie die Rolle "Signierer für das Codesignaturzertifikat", die Ihrer Identität zugewiesen ist. Weitere Anleitungen finden Sie in Azure Schnellstartdokumenten zur 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, https://dotnet.microsoft.com/download 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 https://aka.ms/vs/17/release/vc_redist.x64.exe die Signatur mit einer 0xc000007b, "Die Anwendung konnte nicht ordnungsgemäß gestartet werden kann" fehlschlägt, oder fehlende DLL-Fehler von der Dlib.

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

Signaturüberprüfung

Buildtools werden von NuGet heruntergeladen und dann ausgeführt. Daher überprüft winapp jedes element auf eine gültige Microsoft Authenticode-Signatur unmittelbar vor dem Ausführen. Das Zertifikat muss Microsoft Corporation als Signierorganisation benennen. Dies gilt für jeden Befehl, der für ein SDK-Tool bereitgestellt wird, einschließlich tool, packageund sign. Ein Tool, bei dem die Überprüfung fehlschlägt, wird nicht ausgeführt:

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

Ein Fehler hier bedeutet, dass die Datei auf dem Datenträger nicht das ist, was Microsoft veröffentlicht wird – meistens ein beschädigter oder teilweiser Download. Löschen Sie das Paket aus dem NuGet-Cache, und führen Sie den Befehl erneut aus, damit winapp es erneut herunterlädt.

winapp hält das Tool dann so lange geöffnet, wie es ausgeführt wird, sodass die datei, die sie überprüft hat, die Datei ist, Windows geladen wird. Wenn das Tool nicht vorhanden ist, wird es nicht ausgeführt:

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

Schließen Sie alles, was die Datei verwendet – eine Antivirenüberprüfung oder ein geöffneter Editor ist die übliche Ursache – und führen Sie den Befehl erneut aus. Wenn das Tool nicht mehr verwendet wird, löschen Sie das Paket aus dem NuGet-Cache, damit winapp es erneut herunterlädt.

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

target

Führen Sie Befehle aus, kopieren Sie Dateien, prüfen Sie den Zustand, oder erfassen Sie den gesamten Gastdesktop.

Jedes Verb nimmt sandbox als erstes Argument an. Mit Ausnahme dieser snapshotBefehle können diese Befehle den Sandkasten vorbereiten oder starten. Siehe Windows Sandkastenausführung für Voraussetzungen, Berechtigungen, Lebenszyklus und Wiederherstellung.

target exec

Führen Sie einen Befehl als Gastbenutzer aus.

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

Argumente nach -- beibehaltung ihrer Grenzen. Standarddatenströme und der Ausgangscode des Gastprozesses werden weitergeleitet. dies ist kein vollständiges Terminal. --json formatiert Winapp-Fehler auf Stderr, ohne die Stdout des untergeordneten Befehls zu ändern. Verwenden Sie die strukturierte Struktur error.code , um einen Zielfehler vom eigenen Beendigungsstatus einer Anwendung zu unterscheiden.

Eine explizite WINAPP_UI_WORKFLOW_ID Gruppierung von Gastbenutzeroberflächenaufrufen durch den Befehl; siehe Sandkasten-UI-Koordination.

Ziel-Push- und Ziel-Pull

Kopieren Sie eine Datei oder ein Verzeichnis in die vom Verb benannte Richtung.

winapp target push <target> <host-source> <target-destination> [--json]
winapp target pull <target> <target-source> <host-destination> [--json]
winapp target push sandbox .\setup.ps1 Setup\setup.ps1
winapp target pull sandbox Results .\results

Zielpfade sind relativ zum verwalteten Arbeitsbereich des Ziels; Absolute, roote und UNC-Zielpfade werden abgelehnt. Ein Dateiziel enthält seinen Dateinamen. Informationen zum Ausführen von Befehlen und Kopieren von Dateien für das Verzeichnislayout, die Verknüpfungsverarbeitung und das Ausführen eines kopierten Skripts finden Sie unter "Ausführen von Befehlen".

Zielmomentaufnahme

Melden Sie Bereitschaft, Bereitstellungen und Gastfenster, ohne einen Sandkasten zu starten.

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

Ein Client wird nicht wiederhergestellt oder ein Agent repariert. Kein ausgeführter Sandkasten ist ein erfolgreiches Ergebnis, kein Fehler. Weitere Informationen finden Sie unter "Inspecting the Sandbox for interpreting readiness and process IDs".

Screenshot des Ziels

Erfassen Sie den Gastdesktop in seiner nativen Pixelgröße als Host-PNG ohne App-Selektor oder Hostfensterrahmen. --json meldet den Ursprung der Gastkoordinate.

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

Verwenden Sie ui screenshot --on sandbox -a <app> stattdessen für ein App-Fenster. Screenshots und Aufzeichnungen für Clientanforderungen, Fokusbeschränkungen und Ausgabebehandlung finden Sie unter Screenshots und Aufzeichnungen .

Zieldatensatz

Notieren Sie den Gastdesktop auf H.264 MP4. Hosten von Video- und Framedateien, die nach Abschluss der Aufzeichnung eingehen; JSON und das Framemanifest beschreiben alle Skalierungen oder Abstände.

winapp target record <target> [-o <host-path>] [--duration-sec <n>] [--fps <n>] [--max-edge <px>] [--frames] [--overwrite] [--json]
winapp target record sandbox -o .\sandbox.mp4 --duration-sec 20 --fps 15

Verwendet die Optionen "Dauer", "Frame", "Überschreiben" und "Ergebnis" von ui record, erfasst jedoch den Desktop anstelle einer App. Bevorzugen Sie eine positive --duration-sec Für unbeaufsichtigte CLI-Verwendung; das npm-Hilfsprogramm erfordert durationSec. Siehe Sandkastenerfassung für teilweise Nachweise und Erfassungsbereitschaftsfehler.

Find-Ui

Agent-first. find-ui wird in erster Linie für KI-Codierungs-Agents erstellt – sie ermöglicht es einem Agent, winUI-Markup aus den Versandkatalogen zu kompilieren, anstatt es zu erfinden, und --json macht jedes Ergebnis (und jedes Fehler) maschinenlesbar. Es funktioniert genauso gut von Hand eingegeben.

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]

Das Gallery-, Toolkit- und Reaktorkorpora-Schiff innerhalb der CLI funktioniert daher find-ui ohne Netzwerkzugriff – auch bei einer ersten Ausführung in einer Agent-Sandbox oder hinter einem Unternehmensproxy, der blockiert raw.githubusercontent.comwird. Wenn GitHub erreichbar ist, aktualisiert sich die CLI von ihr und speichert das Ergebnis pro Benutzer unter <global .winapp>/cache/find-ui; der integrierte Korpus ist nur ein Boden, niemals eine Decke. Zwischengespeicherte Daten werden höchstens alle 24 Stunden oder bei Bedarf aktualisiert --refresh.

Der integrierte Korpus wird jedes Mal, wenn eine stabile Version erstellt wird, von GitHub erneut abgerufen, und eine Aktualisierung, die den Releasebuild nicht mehr reagiert, anstatt ältere Daten ruhig zu versenden – der Baker ruft denselben Codepfad --refresh ab, sodass ein Fehler dort bedeutet, dass die Liveaktualisierung ebenfalls unterbrochen wird und sich lohnt, vor dem Versand zu untersuchen. Eine Freigabe kann weiterhin gegen den zuvor zugesicherten Korpus, aber nur als explizite Außerkraftsetzung gekürzt werden. Wenn Ergebnisse aus der integrierten Kopie der Gallery/Toolkit/Reactor Corpora bereitgestellt werden, find-ui sagt dies bei Stderr und --json Ausgabe ( "corpus": "embedded" andere Werte: "network" für einen frischen Abruf, "cache" für den lokalen Cache). Eine nur kerngeschützte Anforderung – --source coreoder ein --id Satz, der alle Kernmuster ist – berichtet "embedded" auch, da die kuratierten Kernmuster in die CLI kompiliert und nie abgerufen werden; es druckt keine Veraltetheitshinweise, da --refresh sie nicht geändert werden können. Das corpus Feld wird immer dann gemeldet, wenn ergebnisse bedient wurden; es fehlt nur, wenn kein Korpus überhaupt geladen werden konnte.

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

Verwandt:find-ui durchsucht WinUI-Beispiele; wird find-api verwendet, um die API-Oberfläche (Typen, Member, Enumerationen) eines Projekts zu durchsuchen und winapp ui search die UI-Struktur einer ausgeführten App zu durchsuchen.

find-api

Agent-first. find-api wird hauptsächlich für KI-Codierungs-Agents erstellt – es wird generierter Code in der API-Oberfläche erstellt, ein Projekt verweist tatsächlich auf die Erinnerung des Modells, und --json plus Nicht-Null-Ausgangscodes auf fehlenden Symbolen ermöglichen es einem Agent-Gate Codegen auf der Antwort. Es funktioniert genauso gut von Hand eingegeben.

Suchen und prüfen Sie die Windows/WinRT-API-Oberfläche (Typen, Member, Enumerationen, Namespaces), die für ein Projekt verfügbar sind, aufgelöst aus den referenzierten .winmd/.dll Metadaten. Das bloße Formular durchsucht; Unterverben führen einen Drilldown in einen bestimmten Typ, einen Namespace oder den Index selbst durch.

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

Der Index basiert auf den wiederhergestellten NuGet/SDK-Paketen des Projekts (über project.assets.json) bei der ersten Verwendung und automatisch aktualisiert, wenn das Projekt wiederhergestellt wird. Es lebt unter dem globalen .winapp Cache (cache/find-api/) und wird für alle Projekte freigegeben. Wiederherstellen des Projekts zuerst (winapp restore oder dotnet restore).

Jede Übereinstimmung wird unter dem Namespace mit dem Paket aufgeführt, das sie enthält, und eine einzeilige Zusammenfassung dessen, was sie tut, sodass ein Ergebnis ohne einen zweiten members Aufruf verwendet werden kann:

[40] Microsoft.UI.Xaml.Media
    Class Microsoft.UI.Xaml.Media.AcrylicBrush  [Microsoft.WindowsAppSDK.WinUI 1.8.260224000]
        Paints an area with a semi-transparent material that uses multiple effects including blur and a noise texture.

Fügen Sie --verbose hinzu, um auch die Cachedatei auf dem Datenträger zu drucken, die jeden Namespace sichert, was hilfreich ist, wenn sie einen veralteten oder unerwarteten Index diagnostizieren.

Die Ausführung winapp find-api ohne Abfrage überhaupt druckt eine kurze Verwendungszusammenfassung und beendet – 0 es handelt sich um eine Hilfeanforderung, keine Suche, die nichts gefunden hat.

Bereiche. Jede Antwort stammt aus genau einem Bereich, der wie scope in --json und als Notiz in der Textausgabe gemeldet wird:

• project - das Projekt im aktuellen Verzeichnis (oder --project / --project-dir). Deckt das Windows SDK, die Windows App SDK und die eigenen NuGet-Pakete des Projekts ab. Bei den Windows App SDK Metadaten handelt es sich um die Version der Projektverweise: Wenn auf dem Computer eine neuere Windows-App Runtime installiert ist, warnt und verlässt sie, anstatt die Typen zu bestätigen, find-api für die das Projekt nicht kompiliert werden kann.
• sdk– das computerweite Windows SDK + Windows App SDK Metadaten, die automatisch verwendet werden, wenn das aktuelle Verzeichnis kein Projekt und keine Lösung enthält. Dadurch können find-api APIs untersucht werden, bevor ein Projekt vorhanden ist und kein Netzwerkzugriff erforderlich ist. Es enthält absichtlich keine NuGet-Pakete von Drittanbietern, daher wird in diesem Bereich kein Typ aus dem Community-Toolkit gefunden (angenommen).

Eine Abfrage aus einem Verzeichnis ohne Projekt und keine Lösung wird immer vom sdk Bereich beantwortet – niemals durch das Projekt, das im freigegebenen Cache indiziert wird – sodass die Ergebnisse niemals von einem nicht verknüpften globalen Zustand abhängen. Übergeben Sie --project sdk den SDK-Bereich explizit innerhalb eines Projekts, und winapp find-api refresh --project sdk erstellen Sie ihn nach der Installation eines neuen Windows SDK neu.

Lösungsverzeichnisse. Aus einem Verzeichnis, das eine .sln/.slnx Projektdatei ohne Projektdatei enthält, werden die Projekte, die die Lösung erstellt Antwort statt des sdk Bereichs – sie werden bei Bedarf indiziert, sodass ihre NuGet-Pakete enthalten sind. Wenn die Lösung mehrere indizierte Projekte erstellt, listet die Abfrage sie auf und fordert --project <name> sie auf, anstatt ein Projekt zu wählen.

Befehle:

• (bare)find-api "<query>" ["<query>"...] - Suchtyp- und Membernamen, zurück zu den dokumentierten Zusammenfassungen, gruppiert nach Namespace
• members <type> [<type>...] [--filter <text>] – Auflisten der Eigenschaften, Ereignisse und Methoden eines Typs (deklarierte Member mit Signaturen, geerbte Member, zusammengefasst durch Deklarieren des Typs)
• check-property <type> <property> [<property>...] - Überprüfen sie, ob Eigenschaften für einen Typ vorhanden sind (beendet nicht null, falls vorhanden). Eine schreibgeschützte Eigenschaft wird mit ⚠" und "schreibgeschützt, kann nicht zugewiesen werden" anstelle einer einfachen ✅, sodass eine Eigenschaft, z ActualWidth . B. nicht für etwas, das Sie festlegen können, falsch ist. Bei Eigenschaftsnamen wird die Groß-/Kleinschreibung beachtet, da C# und XAML folgendes sind: check-property Button background beendet Nicht-Null und bietet Background eine nahe Übereinstimmung, anstatt einen Namen zu melden, den Sie nicht tatsächlich schreiben können.
• enums <type> [<type>...] [--filter <text>] - Listet die Werte einer Enumeration auf (beendet nicht null, wenn der Typ keine Enumeration ist)
• packages – Auflisten der indizierten Metadatenpakete mit anzahl pro Pakettyp/Element
• stats - Aggregierte Indexstatistiken anzeigen (Pakete, Namespaces, Typen, Member, .winmd Dateien)
• refresh [--scan] - Erstellen Sie den Index für ein Projekt neu (--scan indiziert jedes Projekt unter dem Verzeichnis). Bei --project <name>einem Namen, der keinem einzelnen indizierten Projekt entspricht, tritt ein Fehler auf, anstatt das aktuelle Verzeichnis indizieren zu müssen.

Batching.search, members, , enumsund check-property akzeptieren Sie mehrere Themen in einem Aufruf. Für einen KI-Agenten ist dies der einzige größte Kostenhebel: Die Marginalkosten eines Nachschlagevorgangs werden von der Roundtrip dominiert (jeder Anruf sendet die gesamte Unterhaltung), nicht durch die Größe der Nutzlast, so dass ein Anruf, der zehn Fragen beantwortet, viel billiger als zehn Anrufe ist.

• Ein einzelner Betreff gibt genau das Nutzlast-Shape zurück, das es immer hat, sowohl im Text als --jsonauch im .
• Zwei oder mehr Themen geben einen Umschlag zurück – { "count": N, "results": [ ... ] } in , wobei --jsonjedes Element die normale Einzelbetreffnutzlast ist; check-property fügt hinzu missingCount. Die Textausgabe rendert jeden Betreff in Sequenz unter einem Bereichsheader.
• check-property batches properties on one type: The first argument is the type, every argument after it is a property. Im Batchmodus wird eine Eigenschaft, die vorhanden ist, eine einzelne ✅ Zeile gedruckt. Vollständige Nahfehlerdetails werden nur für diejenigen gedruckt, die nicht.
• Ein Batch wird nur beendet 0 , wenn jedes Thema aufgelöst und gefunden wurde . Daher ist ein Batch weiterhin sicher, um Codegen zu toren.

Suchbewertung. Eine Abfrage, die genau mit einem Typnamen übereinstimmt, wird vor partiellen Übereinstimmungen bewertet, und wenn ein kurzer Name von mehreren Namespaces gemeinsam genutzt wird, werden nur die Exaktnamenkonflikte als mehrdeutig aufgeführt – eine Abfrage wie NavigationView meldet die Handvoll Namespaces, die diesen genauen Typ definieren, anstatt jeden Namespace, der ein ähnlich benanntes Symbol enthält. Die Mehrdeutigkeitsliste --maxgehorcht, und normale Ergebnisse werden weiterhin darunter gedruckt.

Geben Sie Namen einmembers, check-propertyund enums akzeptieren Sie einen Kurznamen (NavigationView) oder einen vollqualifizierten (Microsoft.UI.Xaml.Controls.NavigationView). Wenn ein kurzer Name von einem modernen Microsoft.* Typ und seinem älteren Windows.* UWP-Zwilling geteilt wird, werden die Microsoft.* Typantworten , d. h. die Projektion, die eine Windows App SDK-App verwendet, und der aufgelöste vollqualifizierte Name wird immer angezeigt. Alle anderen Kollisionen beenden Nicht-Null und listen die Kandidaten auf, anstatt zu erraten.

Methodensignaturen. Eine Signatur wird so gedruckt, wie Sie den Aufruf schreiben würden: eine Methode, die Sie für den Typ aufrufen, anstatt für eine Instanz, wird mit staticdem Schlüsselwort angezeigt, das sie tatsächlich benötigt out– , , inoder ref. Liest Boolean TryGetValue(String key, out String value)alsoTryGetValue, was wie geschrieben kompiliert wird.

Optionen:

• --max <n> - Maximale Anzahl von namespacegegruppierten Suchergebnissen (Standard 5; nur Suche). Überschreibt auch die Mehrdeutigkeitsliste, sodass eine kurze Abfrage, die in vielen Namespaces kollidiert, lesbar bleibt.
• --filter <text> - Eingrenzen einer Auflistung auf members und enums: Eine Übereinstimmung zwischen Teilzeichenfolgen mit Berücksichtigung der Groß-/Kleinschreibung für den Element-/Wertnamen. Wird am besten für Typen mit Hunderten von Mitgliedern verwendet. Die meisten Enumerationen sind klein genug, um ganze (auch Symboldie größte in WinUI bei 197 Werten) zu dumpen, sodass das Filtern in der Regel mehr kostet, als es spart, sobald Sie einen zweiten Schätzwert berücksichtigen. Führen Sie niemals denselben Befehl mit unterschiedlichen Filtertexten erneut aus– Dump einmal, und lesen Sie ihn.
• --all members- Auflisten der vollständigen Oberfläche: vollständige Signaturen für geerbte Member sowie Statische der Abhängigkeitseigenschafts-ID und Beschreibungen pro Element, von denen eine nicht gefilterte Auflistung weggelassen wird (siehe Eintragsgröße unten). --verbose impliziert es; verwenden --all Sie auch, wenn Sie möchten --json, die nicht mit --verbose.
• --scan - Rekursiv jedes Projekt unter dem Verzeichnis ermitteln und indizieren (refresh nur)
• --project <name>- Project abfrage (entspricht dem .csproj/.vcxproj Namen) oder sdk um den computerweiten Windows SDK-Bereich abzufragen
• --project-dir <path>- Project Verzeichnis abfragt (Standardeinstellung für das aktuelle Verzeichnis). Ein Pfad, der nicht vorhanden ist, ist ein Fehler – er wird nie im Hintergrund vom sdk Bereich beantwortet.
• --json - Emittieren Sie eine maschinenlesbare Nutzlast auf stdout (unterstützt von jedem Verb). Abfragenutzlasten identifizieren den Index, der über ( oder ) beantwortet wurde und projectDir (für den SDK-Bereich nicht vorhanden) – Projektnamen sind nicht in Verzeichnissen eindeutig, also projectDir die zuverlässige Identität. projectNamesdkprojectscope 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.

Beispiele:

# Search
winapp find-api "acrylic brush"
winapp find-api NavigationView --max 10

# Inspect and validate
winapp find-api members Microsoft.UI.Xaml.Controls.NavigationView
winapp find-api check-property Button Background
winapp find-api enums Symbol

# Batch — one call instead of one per subject
winapp find-api check-property InfoBar Severity IsOpen Message Title
winapp find-api members InfoBar TeachingTip ContentDialog
winapp find-api enums InfoBarSeverity Visibility
winapp find-api "acrylic brush" "teaching tip" --max 5

# Narrow a large type instead of dumping it and grepping
winapp find-api members Button --filter background

# Full member surface: inherited signatures, dependency-property statics, descriptions
winapp find-api members Button --all

# Manage the index
winapp find-api refresh

# Explore the Windows SDK with no project at all (e.g. before scaffolding an app)
winapp find-api "acrylic brush"          # from an empty directory -> scope: sdk
winapp find-api members Button --project sdk

Wenn --filter sie angewendet wird, meldet die Ausgabe weiterhin die ungefilterte Summe (totalValuesoder totalProperties/totalMethods/totalEventsin--json), sodass eine schmale Ansicht nie für eine kleine API verwechselt wird. Ein Filter, der mit nichts übereinstimmt, wird immer noch beendet 0 und sagt so explizit , dass "nichts mit Ihrem Filter übereinstimmt", nicht "kein solcher Typ".

Eintragsgröße. Eine nicht gefilterte members Auflistung ist die eine teure Form – members Button umfasst 288 Member, von denen 280 von 6 Basistypen geerbt werden. Ein ungefilterter Aufruf ist eine Ausrichtungsabfrage ("Was ist dieser Typ, ungefähr was kann er tun?"), sodass er antwortet und die Teile ausgelassen, aus denen nichts geschrieben wird:

• Geerbte Membersignaturen – geerbte Mitglieder werden nach Typ deklarieren und nur nach Namen aufgelistet, sodass die Form der geerbten Oberfläche weiterhin ohne vollständige Signaturen von 280 sichtbar ist.
• Dependency-Property Identifier statics (BackgroundProperty) – 28% der Eigenschaften eines typischen WinUI-Steuerelements. Sie sind vorhanden, um an , nicht zugewiesen zu GetValue/SetValuewerden.
• Beschreibungen pro Element – die XML-Doc-Prose, etwa 16% der Nutzlast.
• Felder, die durch ihre Umgebung impliziert werden in --json: kind (impliziert durch das enthaltende/eventspropertiesmethods/ Array), returnType (das führende Token von signature) und inherited wenn falsch (impliziert durch ).declaringType

Was nicht angegeben wurde, wird immer gemeldet (hiddenDependencyProperties, descriptionsOmittedund ein hint In --json; eine "Omitted:"-Zeile im Text), und Summen beschreiben weiterhin den gesamten Typ. Sowohl als --all auch --filter die vollständige Oberfläche mit vollständigen Signaturen und Beschreibungen finden Sie den members Button --filter BackgroundProperty Bezeichner members Button --filter Click und gibt weiterhin die geerbte Signatur zurückClick. Gemessen am samples/winui-app, dies nimmt members Button --json von 91.954 bis 10.567 Zeichen (−88,5%) bei Verlassen --filter und --all Byte identisch.

Wie eine Abfrage abgeglichen wird. winapp find-api "language model" rangiert über Übereinstimmungen LanguageModel , deren Wörter über Namespaces und Member verteilt sind, einschließlich außerhalb eines Projekts, wenn der Typ indiziert wird. Die Suche ist lexikalisch, nicht semantisch: Sie stimmt mit ganzen Bezeichnerwörtern und nicht mit einer Zeichenfolge von Buchstaben überein, findet IImageLLMAdapterSession aber llm nichtScrollMode. Wenn eine Abfrage mit keinem Namen übereinstimmt, wird sie anhand der dokumentierten Zusammenfassungen von Typen und Elementen versucht, was die Suche IRandomAccessStreamermöglicht"random-access stream". Beschreibungen rangieren unter jeder Namenszustimmung, und nur zusammenfassungen, die tatsächlich gelieferten Pakete sind durchsuchbar – ein Paket ohne XML-Dokumentation trägt keinen Beschreibungstext bei.

Projekte ohne MSBuild-Projektdatei. Eine Electron-App (oder eine andere nicht .NET App, die von winapp.yaml) gesteuert wird, hat keine .csproj und daher keine project.assets.json. find-api indiziert sie aus dem .winapp/winmds.lock.json Schreibvorgang winapp restore , der dasselbe aufzeichnet: jedes aufgelöste Paket, seine Version und die Dateien, die .winmd er beiträgt. Ein solches Projekt wird nach seinem Verzeichnis benannt und sein Index wird veraltet, wenn die Sperrdatei neu geschrieben wird. Ein Verzeichnis, das sowohl ein .csproj als auch ein winapp.yaml Verzeichnis enthält, wird aus dem .csprojverzeichnis indiziert. Dies ist die genauere Beschreibung dessen, wofür das Projekt kompiliert wird.

Negative Antworten werden qualifiziert, wenn der Index unvollständig ist. Wenn die Metadaten eines Pakets nicht gelesen werden konnten, sehen "kein solcher Typ" und "dieses Paket wurde nie indiziert" identisch aus – und das erste, wenn es wirklich der zweite generiert Code für eine VON Ihnen mitgeteilte API generiert, ist nicht vorhanden. Jede negative Antwort, einschließlich einer search , die null Ergebnisse zurückgibt, trägt also eine Notiz, dass der Index teilweise und punktiert winapp find-api refreshist. Positive Antworten sind nicht betroffen.

Generische Typnamen. Metadaten speichern generische Typen mit einem Aheitssuffix (IAsyncOperation`1), was nicht deren Schreibweise ist. members, enumsund check-property akzeptieren Sie jedes Formular: IAsyncOperation, IAsyncOperation<StorageFile>, und IAsyncOperation`1 alle auflösen in denselben Typ. Ein barer Name stimmt mit jeder Arität überein; eine angegebene Arität (in beiden Schreibweisen) muss übereinstimmen, sodass Holder<A, B> sie nicht in einen einzelnen Parameter Holder<T>aufgelöst wird.

--json Die Nutzlasten lassen die Diagnose aus. Cachedateipfade werden nur unter --verbose (übereinstimmende Textausgabe, wo sie bereits ausführlich waren) angezeigt, und leere Vorschlagsarrays werden ausgelassen, anstatt als serialisiert zu []werden.

Ausgangscodes:search ohne Treffer, check-property auf einer fehlenden Eigenschaft und enums auf einem Nicht-Enumerationstyp alle Exit-Nicht-Null-Typen – Generierung von Gatecode und CI-Überprüfungen. Ein Batchaufruf beendet nicht null, wenn ein Betreff fehlschlägt. Eine schreibgeschützte Eigenschaft ist kein Fehler – sie ist vorhanden, sodass check-property sie in der Ausgabe (writable: false in --json) beendet 0 und gekennzeichnet wird. Eine init Eigenschaft meldet writable: false aus demselben Grund: Sie kann in einem Objektinitialisierer festgelegt werden, und seine Signatur sagt { get; init; }, aber das Zuweisen danach wird nicht kompiliert.

Verwandt:find-api antwort "Ist diese API vorhanden und was sind ihre Mitglieder?"; wird find-ui verwendet, um ein funktionierendes WinUI-Beispiel für ein Steuerelement zu finden.

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

Benutzeroberflächenworkflowidentität

winapp ui Befehle, die den physischen Desktop steuern, nehmen immer kooperative Wendungen, sodass zwei gleichzeitig ausgeführte Workflows nicht den Fokus der anderen stehlen oder die Menüs der anderen schließen können. Diese Vermittlung benötigt kein Setup und kann nicht ausgeschaltet werden.

Was optional ist, ist Kontinuität. Standardmäßig ist jeder Befehl ein eigenständiger Einschuss, der den Desktop freigibt, sobald er abgeschlossen ist. Um den Desktop über mehrere Befehle hinweg zu halten, weisen Sie ihnen alle die gleiche Workflow-ID zu:

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

Verwenden Sie denselben Wert für die Zusammenarbeit von Prozessen (z. B. eine Aufzeichnung und die Klicks, die erfasst werden sollen) und unterschiedliche Werte für unabhängige Workflows. Jeder Befehl ohne ID ist ein eigener Einschussworkflow, auch wenn mehrere von einer Shell gestartet werden, sodass Hosts, die eine neue Shell pro Befehl starten, denselben expliziten Wert in jedes Element einfügen müssen. Der Wert ist undurchsichtig, wird nie als Anmeldeinformationen behandelt und wird nur als SHA-256-Hash beibehalten. Siehe Benutzeroberflächenautomatisierung → Koordinieren gleichzeitiger UI-Workflows.

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 - Aufnahmefenster/Element als PNG (mehrere Fenster bilden eine zusammengesetzte PNG-Datei; siehe Aufnahmebereich)
• 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
• yield - Freigeben der Benutzeroberfläche des aktuellen Workflows; erfordert WINAPP_UI_WORKFLOW_ID

Optionen:

• -a, --app <app> - Ziel-App (Name, Titel oder PID)
• -w, --window <hwnd> - Zielfenster von HWND (stabil)
• --on <target> - Führen Sie ein beliebiges ui Verb in sandbox; Namen, PIDs und Fensterziehpunkte auf den Gast aus. Ausgaben werden an den Host übermittelt. Siehe Sandkasten-Benutzeroberflächenautomatisierung für Setup, Workflowkoordination und Clientanforderungen.

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 evidence.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).
• --overwrite - Vorhandene Aufzeichnungsausgaben nach Abschluss der neuen Aufnahme ersetzen; Vorhandene Ausgaben werden standardmäßig abgelehnt. Frühere Framebundle werden beibehalten. Siehe Aufzeichnungsausgabewiederherstellung.
• --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 folgen Sie dem Screenshot-Überlagerungsworkflow für Popup-Stills. Nachverfolgt in #646.

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