NPM-Paket – Programmgesteuerte API

TypeScript/JavaScript-API-Referenz für @microsoft/winappcli. Jeder CLI-Befehl ist als asynchrone Funktion verfügbar, die stdout/stderr erfasst und ein typiertes Ergebnis zurückgibt. Hilfsprogramme für MSIX-Identität, Electron-Debug-Identität und Build-Tools werden ebenfalls exportiert.

Installation

npm install @microsoft/winappcli

Schnellstart

import { init, packageApp, certGenerate } from '@microsoft/winappcli';

// Initialize a new project with defaults
await init({ useDefaults: true });

// Generate a dev certificate
await certGenerate({ install: true });

// Package the built app
await packageApp({ inputFolder: './dist', cert: './devcert.pfx' });

Allgemeine Typen

Jeder CLI-Befehlswrapper akzeptiert ein Optionsobjekt, das erweitert CommonOptions und zurückgegeben wird Promise<WinappResult>.

CommonOptions

Basisoptionen, die von den meisten Befehlen gemeinsam verwendet werden.

WinappResult

Von jedem Befehlswrapper zurückgegebenes Ergebnis.

CLI-Befehls-Wrapper

Diese Funktionen fassen native winapp CLI-Befehle zusammen. Alle akzeptieren CommonOptions (quiet, verbose, cwd).

certGenerate()

Erstellen Sie ein selbstsigniertes Zertifikat nur für lokale Tests. Der Herausgeber muss mit dem Manifest übereinstimmen (automatisch abgeleitet, wenn --manifest angegeben ist oder Package.appxmanifest im Arbeitsverzeichnis vorhanden ist). Ausgabe: devcert.pfx (Standardkennwort: 'password'). Erhalten Sie für die Produktion ein Zertifikat von einer vertrauenswürdigen Zertifizierungsstelle. Verwenden Sie 'cert install', um diesem Computer zu vertrauen.

function certGenerate(options?: CertGenerateOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

certInfo()

Anzeigen von Zertifikatdetails (Betreff, Fingerabdruck, Ablauf). Hilfreich, um zu überprüfen, ob ein Zertifikat mit Ihrem Manifest übereinstimmt, bevor es signiert wird.

function certInfo(options: CertInfoOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

certInstall()

Vertrauen Sie einem Zertifikat auf diesem Computer (erfordert Administrator). Führen Sie dies aus, bevor Sie MSIX-Pakete installieren, die mit Entwicklerzertifikaten signiert sind. Beispiel: winapp cert install ./devcert.pfx. Nur einmal pro Zertifikat erforderlich.

function certInstall(options: CertInstallOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

createDebugIdentity()

Aktivieren Sie die Paketidentität für das Debuggen, ohne vollständige MSIX zu erstellen. Erforderlich zum Testen von Windows-APIs, wie Push-Benachrichtigungen und Freigabebereich, während der Entwicklung. Beispiel: winapp create-debug-identity ./myapp.exe. Erfordert Package.appxmanifest oder appxmanifest.xml im aktuellen Verzeichnis oder dass über --manifest übergeben wird. Führen Sie den Vorgang nach dem Ändern des Manifests oder der Assets/ erneut aus.

function createDebugIdentity(options?: CreateDebugIdentityOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

createExternalCatalog()

Generiert eine CodeIntegrityExternal.cat Katalogdatei mit Hashes von ausführbaren Dateien aus angegebenen Verzeichnissen. Wird mit dem TrustedLaunch-Flag in MSIX sparse package manifests (AllowExternalContent) verwendet, um die Ausführung externer Dateien zuzulassen, die nicht im Paket enthalten sind.

function createExternalCatalog(options: CreateExternalCatalogOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

getWinappPath()

Drucken Sie den Pfad zum WINAPP-Verzeichnis. Verwenden Sie "-global" für den freigegebenen Cachespeicherort, oder lassen Sie den ordner ".winapp" des Projekts aus. Nützlich für Buildskripts, die auf installierte Pakete verweisen müssen.

function getWinappPath(options?: GetWinappPathOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

init()

Beginnen Sie hier, um eine Windows-App mit erforderlichem Setup zu initialisieren. Richtet alles ein, was für Windows App-Entwicklung erforderlich ist: Erstellt Package.appxmanifest mit Standardressourcen, lädt Windows SDK- und Windows App SDK-Pakete herunter und generiert Projektionen. Wenn SDK-Pakete verwaltet werden (--setup-sdks stable/preview/experimental), erstellt auch winapp.yaml, um Versionen für "restore"/"update" anzuheften; mit --setup-sdks none (z.B. für Rust/Tauri-Projekte, die eigene SDK-Bindungen mitbringen), wird keine winapp.yaml erstellt. Interaktiv (verwenden Sie standardmäßig "--use-defaults", um Eingabeaufforderungen zu überspringen). Verwenden Sie stattdessen "Wiederherstellen", wenn Sie ein Repository geklont haben, das bereits "winapp.yaml" enthält. Verwenden Sie "Manifest generieren", wenn Sie nur ein Manifest oder "Zertifikat generieren" benötigen, wenn Sie ein Entwicklungszertifikat für die Codesignierung benötigen.

function init(options?: InitOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

manifestAddAlias()

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. Standardmäßig wird der Alias aus dem Attribut 'Ausführbar' abgeleitet (z. B. $targetnametoken$.exe wird zum $targetnametoken$.exe-Alias).

function manifestAddAlias(options?: ManifestAddAliasOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

manifestGenerate()

Erstellen Sie Package.appxmanifest ohne vollständiges Projektsetup. Wird verwendet, wenn Sie nur ein Manifest- und Bildressourcen benötigen (keine SDKs, kein Zertifikat). Verwenden Sie für die vollständige Einrichtung stattdessen "init". Vorlagen: "packaged" (full MSIX), "sparse" (Desktop-App, die Windows APIs benötigt).

function manifestGenerate(options?: ManifestGenerateOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

manifestUpdateAssets()

Generieren Sie neue Ressourcen für Bilder, auf die in einem Package.appxmanifest verwiesen wird, aus einem einzigen Quellimage. Das Quellbild sollte mindestens 400 x 400 Pixel groß sein.

function manifestUpdateAssets(options: ManifestUpdateAssetsOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

packageApp()

Erstellen Sie das MSIX-Installationsprogramm aus Ihrer integrierten App. Führen Sie die Ausführung nach dem Erstellen Ihrer App aus. Ein Manifest (Package.appxmanifest oder appxmanifest.xml) ist für das Packen erforderlich – es muss sich im aktuellen Arbeitsverzeichnis befinden, als --manifest übergeben oder sich im Eingabeordner befinden. Verwenden Sie "-cert devcert.pfx", um sich zum Testen zu signieren. Beispiel: winapp package ./dist --manifest Package.appxmanifest --cert ./devcert.pfx

function packageApp(options: PackageOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

restore()

Verwenden Sie nach dem Klonen eines Repositorys oder beim Fehlen eines WINAPP/-Ordners. Installiert SDK-Pakete aus vorhandenen winapp.yaml neu, ohne Versionen zu ändern. Erfordert winapp.yaml (erstellt von 'init'). Verwenden Sie stattdessen "Update", um nach neueren SDK-Versionen zu suchen.

function restore(options?: RestoreOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

run()

Erstellt ein paketiertes Layout, registriert die Anwendung und startet die verpackte Anwendung.

function run(options: RunOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

sign()

Signieren Sie ein MSIX-Paket oder eine ausführbare Datei. Beispiel: winapp sign ./app.msix ./devcert.pfx. Verwenden Sie --timestamp bei Produktionsbuilds, damit sie auch nach Ablauf des Zertifikats gültig bleiben. Der Befehl 'package' kann sich automatisch mit --cert signieren.

function sign(options: SignOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

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. Weitere Informationen zur Microsoft Store Developer CLI finden Sie hier: https://aka.ms/msstoredevcli

function store(options?: StoreOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

tool()

Führen Sie Windows SDK-Tools direkt aus (makeappx, signtool, makepri usw.). Lädt build tools bei Bedarf automatisch herunter. Bevorzugen Sie für die meisten Aufgaben Befehle auf höherer Ebene wie "package" oder "sign". Beispiel: winapp-Tool makeappx pack /d ./folder /p ./out.msix

function tool(options?: ToolOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiClick()

Klicken Sie mithilfe der Maussimulation auf ein Element, indem Sie eine Strich- oder Textsuche verwenden. Funktioniert für Elemente, die InvokePattern nicht unterstützen (z. B. Spaltenüberschriften, Listenelemente). Verwenden Sie --double für Doppelklick, --right für Rechtsklick.

function uiClick(options?: UiClickOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiFocus()

Setzen Sie den Tastaturfokus mithilfe von UIA SetFocus auf das angegebene Element.

function uiFocus(options?: UiFocusOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiGetFocused()

Zeigen Sie das Element an, das derzeit den Tastaturfokus in der Ziel-App hat.

function uiGetFocused(options?: UiGetFocusedOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiGetProperty()

Lesen von UIA-Eigenschaftswerten aus einem Element. Geben Sie --Eigenschaft für eine einzelne Eigenschaft an, oder lassen Sie sie für alle aus.

function uiGetProperty(options?: UiGetPropertyOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiGetValue()

Lesen Sie den aktuellen Wert aus einem Element. Versucht TextPattern (RichEditBox, Dokument), ValuePattern (TextBox, ComboBox, Slider), dann Name (Bezeichner). Verwendung: winapp ui get-value <selector> -a <app>

function uiGetValue(options?: UiGetValueOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiInspect()

Zeigen Sie die Ui-Elementstruktur mit semantischen Schrägstrichen, Elementtypen, Namen und Grenzen an.

function uiInspect(options?: UiInspectOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiInvoke()

Aktivieren Sie ein Element über Slug oder Textsuche. Tries InvokePattern, TogglePattern, SelectionItemPattern und ExpandCollapsePattern in der Reihenfolge.

function uiInvoke(options?: UiInvokeOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiListWindows()

Listet alle sichtbaren Fenster mit deren HWND, Titel, Prozess und Größe auf. Verwenden Sie -a, um nach App-Namen zu filtern. Verwenden Sie den HWND mit -w, um auf ein bestimmtes Fenster zu abzielen.

function uiListWindows(options?: UiListWindowsOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiScreenshot()

Erfassen Sie das Zielfenster oder -Element als PNG-Bild. Wenn mehrere Fenster vorhanden sind (z. B. Dialogfelder), werden die einzelnen Fenster in einer separaten Datei erfasst. Gibt mit --json Dateipfad und Dimensionen zurück. Verwenden Sie "-capture-screen" für Popupüberlagerungen.

function uiScreenshot(options?: UiScreenshotOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiScroll()

Scrollen Sie mithilfe von ScrollPattern in einem Containerelement. Verwenden Sie --direction, um schrittweise zu scrollen, oder --to, um nach oben/unten zu springen.

function uiScroll(options?: UiScrollOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiScrollIntoView()

Scrollen Sie das angegebene Element mithilfe von UIA ScrollItemPattern in den sichtbaren Bereich.

function uiScrollIntoView(options?: UiScrollIntoViewOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiSearch()

Durchsuchen Sie die Elementstruktur nach Elementen, die einer Textabfrage entsprechen. Gibt alle Übereinstimmungen mit semantisch relevanten Slugs zurück.

function uiSearch(options?: UiSearchOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiSetValue()

Legen Sie einen Wert für ein Element mithilfe von UIA ValuePattern fest. Funktioniert für TextBox-, ComboBox-, Slider- und andere bearbeitbare Steuerelemente. Verwendung: winapp ui set-value <selector><value> -a <app>

function uiSetValue(options?: UiSetValueOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiStatus()

Stellen Sie eine Verbindung mit einer Ziel-App her, und zeigen Sie Verbindungsinformationen an.

function uiStatus(options?: UiStatusOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

uiWaitFor()

Warten Sie, bis ein Element angezeigt, ausgeblendet wird oder eine Eigenschaft einen Zielwert erreicht. Fragt in 100 ms-Intervallen ab, bis die Bedingung erfüllt oder timeout ist.

function uiWaitFor(options?: UiWaitForOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

unregister()

Hebt die Registrierung eines seitengeladenen Entwicklungspakets auf. Entfernt nur Pakete, die im Entwicklungsmodus registriert sind (z. B. über "winapp run" oder "create-debug-identity").

function unregister(options?: UnregisterOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

update()

Suchen und installieren Sie neuere SDK-Versionen. Aktualisiert winapp.yaml mit den neuesten Versionen und installiert Pakete neu. Erfordert eine vorhandene winapp.yaml, erstellt von 'init'. Verwenden Sie --setup-sdks preview für Vorschau-SDKs. Wenn Sie die aktuellen Versionen ohne Aktualisierung erneut installieren möchten, verwenden Sie stattdessen "Wiederherstellen".

function update(options?: UpdateOptions): Promise<WinappResult>

Optionen:

Akzeptiert auch CommonOptions (quiet, verbose, cwd).

Hilfsprogrammfunktionen

execWithBuildTools()

Ausführen eines Befehls mit dem Bin-Pfad "BuildTools", der der PATH-Umgebung hinzugefügt wurde

function execWithBuildTools(command: string, options?: ExecSyncOptions): string | Buffer<ArrayBufferLike>

Parameter:

Gibt zurück: Die Ausgabe von execSync

addMsixIdentityToExe()

Fügt Paketidentitätsinformationen aus einer appxmanifest.xml-Datei zum eingebetteten Manifest einer ausführbaren Datei hinzu.

function addMsixIdentityToExe(exePath: string, appxManifestPath?: string | undefined, options?: MsixIdentityOptions): Promise<MsixIdentityResult>

Parameter:

addElectronDebugIdentity()

Fügt dem Electron-Debugprozess die Paketidentität hinzu.

function addElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ElectronDebugIdentityResult>

Parameter:

clearElectronDebugIdentity()

Löscht/entfernt die Paketidentität aus dem Electron-Debugprozess, indem sie aus der Sicherung wiederhergestellt wird.

function clearElectronDebugIdentity(options?: MsixIdentityOptions): Promise<ClearElectronDebugIdentityResult>

Parameter:

getGlobalWinappPath()

Abrufen des Pfads zum globalen .winapp-Verzeichnis

function getGlobalWinappPath(): string

Liefert: Der vollständige Pfad zum globalen .winapp-Verzeichnis

getLocalWinappPath()

Abrufen des Pfads zum lokalen .winapp-Verzeichnis

function getLocalWinappPath(): string

Rückgabewert: Der vollständige Pfad zum lokalen .winapp-Verzeichnis

Node.js CLI-Befehle

Diese Befehle sind ausschließlich über npx winapp node <subcommand> verfügbar und werden nicht als programmatische Funktionen exportiert.

node create-addon

Generieren Sie systemeigene Addondateien für ein Electron-Projekt. Unterstützt C++-Vorlagen (Node-gyp) und C# (node-api-dotnet).

npx winapp node create-addon [options]

Optionen:

Hinweis: Muss vom Stamm eines Electron-Projekts (Verzeichnis mit package.json) ausgeführt werden.

Beispiele:

npx winapp node create-addon
npx winapp node create-addon --name myAddon
npx winapp node create-addon --template cs --name MyCsAddon

node add-electron-debug-identity

Fügen Sie dem Electron-Debugprozess paketidentitäten mithilfe von sparsamen Verpackungen hinzu. Erstellt eine Sicherung von electron.exe, generiert ein Sparse-MSIX-Manifest, fügt der ausführbaren Datei eine Identität hinzu und registriert das Sparse-Paket. Erfordert ein (erstellen Sie eins Package.appxmanifest mit winapp init oder winapp manifest generate).

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

Optionen:

Hinweis: Muss vom Stamm eines Electron-Projekts (Verzeichnis mit node_modules/electron) ausgeführt werden. Verwenden Sie npx winapp node clear-electron-debug-identityzum Rückgängigmachen .

Beispiele:

npx winapp node add-electron-debug-identity
npx winapp node add-electron-debug-identity --manifest ./custom/Package.appxmanifest

node clear-electron-debug-identity

Entfernen Sie die Paketidentität aus dem Electron-Debugprozess. Stellt electron.exe aus der von add-electron-debug-identity erstellten Sicherung wieder her und entfernt die Sicherungsdateien.

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

Optionen:

Hinweis: Muss vom Stamm eines Electron-Projekts (Verzeichnis mit node_modules/electron) ausgeführt werden.

Beispiele:

npx winapp node clear-electron-debug-identity

Typenreferenz

ExecSyncOptions

Aus Node.js aus Gründen des Komforts erneut exportiert. Siehe Node.js Dokumente.

MsixIdentityOptions

MsixIdentityResult

ElectronDebugIdentityResult

ClearElectronDebugIdentityResult

CallWinappCliOptions

CallWinappCliResult

CallWinappCliCaptureOptions

CallWinappCliCaptureResult

GenerateCppAddonOptions

GenerateCppAddonResult

GenerateCsAddonOptions

GenerateCsAddonResult

IfExists

IfExists-Werte.

type IfExists = "error" | "overwrite" | "skip"

SdkInstallMode

SdkInstallMode-Werte.

type SdkInstallMode = "stable" | "preview" | "experimental" | "none"

ManifestTemplates

ManifestTemplates-Werte.

type ManifestTemplates = "packaged" | "sparse"

CertGenerateOptions

CertInfoOptions

CertInstallOptions

CreateDebugIdentityOptions

CreateExternalCatalogOptions

GetWinappPathOptions

InitOptions

ManifestAddAliasOptions

ManifestGenerateOptions

ManifestUpdateAssetsOptions

PackageOptions

RestoreOptions

RunOptions

SignOptions

StoreOptions

ToolOptions

UiClickOptions

UiFocusOptions

UiGetFocusedOptions

UiGetPropertyOptions

UiGetValueOptions

UiInspectOptions

UiInvokeOptions

UiListWindowsOptions

UiScreenshotOptions

UiScrollOptions

UiScrollIntoViewOptions

UiSearchOptions

UiSetValueOptions

UiStatusOptions

UiWaitForOptions

UnregisterOptions

UpdateOptions