NPM-paket – Programmatiskt API

TypeScript/JavaScript API referens för @microsoft/winappcli. Varje CLI-kommando är tillgängligt som en asynkron funktion som samlar in stdout/stderr och returnerar ett skrivet resultat. Hjälpverktyg för MSIX-identitet, Electron-felsökningsidentitet och byggverktyg exporteras också.

Installation

npm install @microsoft/winappcli

Snabbstart

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

Vanliga typer

Varje CLI-kommandoomslutning accepterar ett alternativobjekt som utökar CommonOptions och returnerar Promise<WinappResult>.

CommonOptions

Grundläggande alternativ som delas av de flesta kommandon.

WinappResult

Resultatet som genereras av varje kommandoinneslutning.

CLI-kommandoomslutning

Dessa funktioner omsluter interna winapp CLI-kommandon. Alla accepterar CommonOptions (quiet, verbose, cwd).

certGenerate()

Skapa endast ett självsignerat certifikat för lokal testning. Förläggaren måste matcha manifestet (antas automatiskt om --manifest anges eller Package.appxmanifest finns i arbetskatalogen). Utdata: devcert.pfx (standardlösenord: "lösenord"). För produktion hämtar du ett certifikat från en betrodd certifikatutfärdare. Använd "cert install" för att lita på den här datorn.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

certInfo()

Visa certifikatinformation (ämne, tumavtryck, förfallodatum). Användbart för att verifiera att ett certifikat matchar manifestet innan du loggar in.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

certInstall()

Lita på ett certifikat på den här datorn (kräver administratör). Kör innan du installerar MSIX-paket som är signerade med utvecklingscertifikat. Exempel: winapp cert install ./devcert.pfx. Behövs bara en gång per certifikat.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

createDebugIdentity()

Aktivera paketidentitet för felsökning utan att skapa fullständig MSIX. Krävs för att testa Windows API:er (push-meddelanden, dela mål osv.) under utveckling. Exempel: winapp create-debug-identity ./myapp.exe. Kräver Package.appxmanifest eller appxmanifest.xml i den aktuella katalogen eller skickas via --manifest. Kör igen när du har ändrat manifestet eller Tillgångar/.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

createExternalCatalog()

Genererar en CodeIntegrityExternal.cat katalogfil med hashvärden av körbara filer från angivna kataloger. Används med flaggan TrustedLaunch i MSIX sparse-paketmanifest (AllowExternalContent) för att tillåta körning av externa filer som inte ingår i paketet.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

getWinappPath()

Skriv ut sökvägen till .winapp-katalogen. Använd --global för den delade cacheplatsen eller utelämna för mappen project-local .winapp. Användbart för byggskript som behöver referera till installerade paket.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

init()

Börja här för att initiera en Windows app med nödvändig konfiguration. Konfigurerar allt som behövs för Windows apputveckling: skapar Package.appxmanifest med standardtillgångar, laddar ned Windows SDK och Windows App SDK paket och genererar prognoser. När SDK-paket hanteras (--setup-sdks stable/preview/experimental) skapar även winapp.yaml för att fästa versioner för "restore"/"update"; med --setup-sdks none (t.ex. för Rust/Tauri-projekt som tar med sina egna SDK-bindningar) skapas ingen winapp.yaml. Interaktiv som standard (använd --use-defaults för att hoppa över prompter). Använd "restore" i stället om du klonade en lagringsplats som redan har winapp.yaml. Använd "manifestgenerering" om du bara behöver ett manifest eller "cert generate" om du behöver ett utvecklingscertifikat för kodsignering.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

manifestAddAlias()

Lägg till ett körningsalias (uap5:AppExecutionAlias) i en Package.appxmanifest. På så sätt kan du starta den paketerade appen från kommandoraden genom att skriva aliasnamnet. Som standard härleds aliaset från attributet Körbar (t.ex. $targetnametoken$.exe blir $targetnametoken$.exe alias).

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

manifestGenerate()

Skapa Package.appxmanifest utan fullständig projektkonfiguration. Använd när du bara behöver ett manifest och avbildningstillgångar (inga SDK:er, inget certifikat). För fullständig installation använder du "init" i stället. Mallar: "packaged" (full MSIX), "sparse" (skrivbordsapp som behöver Windows API:er).

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

manifestUpdateAssets()

Generera nya resurser för bilder som refereras i en Package.appxmanifest från en enda källbild. Källbilden ska vara minst 400 x 400 bildpunkter.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

packageApp()

Skapa MSIX-installationsprogrammet från din skapade app. Kör efter att ha byggt din app. Ett manifest (Package.appxmanifest eller appxmanifest.xml) krävs för paketering – det måste finnas i den aktuella arbetskatalogen, skickas som --manifest eller finnas i indatamappen. Använd --cert devcert.pfx för att signera för testning. Exempel: winapp-paketet ./dist --manifest Package.appxmanifest --cert ./devcert.pfx

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

restore()

Använd efter kloning av en lagringsplats eller när .winapp/-mappen saknas. Installerar om SDK-paket från befintliga winapp.yaml utan att ändra versioner. Kräver winapp.yaml (skapad av "init"). Om du vill söka efter nyare SDK-versioner använder du "update" i stället.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

run()

Skapar paketerad layout, registrerar programmet och startar det paketerade programmet.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

sign()

Signera koden i ett MSIX-paket eller körbar fil. Exempel: winapp sign ./app.msix ./devcert.pfx. Använd --timestamp för att produktionsversioner ska förbli giltiga när certifikatet har upphört att gälla. Kommandot "package" kan signeras automatiskt med --cert.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

store()

Kör ett CLI-kommando för Microsoft Store Developer. Det här kommandot laddar ned Microsoft Store Developer CLI om det inte redan har laddats ned. Läs mer om Microsoft Store Developer CLI här: https://aka.ms/msstoredevcli

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

tool()

Kör Windows SDK-verktyg direkt (makeappx, signtool, makepri osv.). Hämtar build-verktyg automatiskt om det behövs. För de flesta uppgifter föredrar du kommandon på högre nivå som "paket" eller "sign". Exempel: winapp tool makeappx pack /d ./folder /p ./out.msix

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiClick()

Klicka på ett element genom att använda slug- eller textsökning med hjälp av mussimulering. Fungerar på element som inte stöder InvokePattern (t.ex. kolumnrubriker, listobjekt). Använd --double för dubbelklick, --right för högerklick.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiFocus()

Flytta tangentbordsfokus till det angivna elementet med UIA SetFocus.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiGetFocused()

Visa elementet som för närvarande har tangentbordsfokus i målappen.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiGetProperty()

Läs UIA-egenskapsvärden från ett element. Ange --property för en enskild egenskap eller utelämna för alla.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiGetValue()

Läs det aktuella värdet från ett element. Testar TextPattern (RichEditBox, Document), ValuePattern (TextBox, ComboBox, Slider), sedan Namn (etiketter). Användning: winapp ui get-value <selector> -a <app>

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiInspect()

Visa UI-elementträdet med semantiska sniglar, elementtyper, namn och gränser.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiInvoke()

Aktivera ett element genom slugg- eller textsökning. Försöker använda InvokePattern, TogglePattern, SelectionItemPattern och ExpandCollapsePattern i ordning.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiListWindows()

Visa en lista över alla synliga fönster med deras HWND, rubrik, process och storlek. Använd -a för att filtrera efter appnamn. Använd HWND med -w för att rikta in dig på ett visst fönster.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiScreenshot()

Avbilda målfönstret eller -elementet som en PNG-avbildning. När det finns flera fönster (t.ex. dialogrutor) avbildas var och en till en separat fil. Med hjälp av --json returneras filsökväg och dimensioner. Använd --capture-screen för popup-överlägg.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiScroll()

Rulla ett containerelement med Hjälp av ScrollPattern. Använd --direction för att rulla inkrementellt, eller --to för att hoppa upp/ned.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiScrollIntoView()

Rulla det angivna elementet till det synliga området med UIA ScrollItemPattern.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiSearch()

Sök i elementträdet efter element som matchar en textfråga. Returnerar alla matchningar med semantiska sniglar.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiSetValue()

Ange ett värde för ett element med UIA ValuePattern. Fungerar för textruta, kombinationsruta, skjutreglage och andra redigerbara kontroller. Användning: winapp ui set-value <selector><value> -a <app>

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiStatus()

Anslut till en målapp och visa anslutningsinformation.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

uiWaitFor()

Vänta tills ett element visas, försvinner eller har en egenskap som når ett målvärde. Avsöker med 100 ms intervall tills villkoret uppfylls eller tidsgränsen uppnås.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

unregister()

Avregistrerar ett sidoladdat utvecklingspaket. Tar endast bort paket som registrerats i utvecklingsläge (t.ex. via "winapp run" eller "create-debug-identity").

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

update()

Sök efter och installera nyare SDK-versioner. Uppdaterar winapp.yaml med de senaste versionerna och installerar om paket. Kräver befintlig winapp.yaml (skapad av "init"). Använd förhandsversionen av --setup-sdks för förhandsversions-SDK:er. Om du vill installera om aktuella versioner utan att uppdatera använder du "restore" i stället.

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

Alternativ:

Accepterar även CommonOptions (quiet, verbose, cwd).

Hjälpfunktioner

execWithBuildTools()

Kör ett kommando med BuildTools bin-sökväg som har lagts till i PATH-miljövariabeln

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

Parameters:

Returnerar: Utdata från execSync

addMsixIdentityToExe()

Lägger till paketidentitetsinformation från en appxmanifest.xml-fil till en körbar inbäddad manifest

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

Parameters:

addElectronDebugIdentity()

Lägger till paketidentitet i Electron-felsökningsprocessen

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

Parameters:

clearElectronDebugIdentity()

Rensar/tar bort paketidentiteten från electron-felsökningsprocessen genom att återställa från säkerhetskopian

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

Parameters:

getGlobalWinappPath()

Hämta sökvägen till den globala .winapp-katalogen

function getGlobalWinappPath(): string

Returnerar: Den fullständiga sökvägen till den globala .winapp-katalogen

getLocalWinappPath()

Hämta sökvägen till den lokala .winapp-katalogen

function getLocalWinappPath(): string

Returnerar: Den fullständiga sökvägen till den lokala .winapp-mappen

Node.js CLI-kommandon

Dessa kommandon är endast tillgängliga via npx winapp node <subcommand> och exporteras inte som programmatiska funktioner.

node create-addon

Generera interna tilläggsfiler för ett Electron-projekt. Stöder mallar för C++ (node-gyp) och C# (node-api-dotnet).

npx winapp node create-addon [options]

Alternativ:

Observera: Måste köras från roten för ett Elektron-projekt (katalog som innehåller package.json).

Exempel:

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

Lägg till paketidentitet i Electron-felsökningsprocessen med hjälp av gles paketering. Skapar en säkerhetskopia av electron.exe, genererar ett gles MSIX-manifest, lägger till identitet i den körbara filen och registrerar det glesa paketet. Kräver en Package.appxmanifest (skapa en med winapp init eller winapp manifest generate).

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

Alternativ:

Observera: Måste köras från roten för ett Elektron-projekt (katalog som innehåller node_modules/electron). Om du vill ångra använder du npx winapp node clear-electron-debug-identity.

Exempel:

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

node clear-electron-debug-identity

Ta bort paketidentiteten från electron-felsökningsprocessen. Återställer electron.exe från säkerhetskopian som skapats av add-electron-debug-identity och tar bort säkerhetskopieringsfilerna.

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

Alternativ:

Observera: Måste köras från roten för ett Elektron-projekt (katalog som innehåller node_modules/electron).

Exempel:

npx winapp node clear-electron-debug-identity

Referens för typer

ExecSyncOptions

Exporteras på nytt från Node.js för enkelhetens skull. Se Node.js dokument.

MsixIdentityOptions

MsixIdentityResult

ElectronDebugIdentityResult

ClearElectronDebugIdentityResult

CallWinappCliOptions

CallWinappCliResult

CallWinappCliCaptureOptions

CallWinappCliCaptureResult

GenerateCppAddonOptions

GenerateCppAddonResult

GenerateCsAddonOptions

GenerateCsAddonResult

IfExists

IfExists-värdena.

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

SdkInstallMode

SdkInstallMode-värden.

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

ManifestTemplates

ManifestTemplates-värden.

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