Pacchetto NPM - API programmatica

Informazioni di riferimento su TypeScript/API JavaScript per @microsoft/winappcli. Ogni comando dell'interfaccia della riga di comando è disponibile come funzione asincrona che acquisisce stdout/stderr e restituisce un risultato tipizzato. Vengono esportate anche utilità helper per identità MSIX, identità di debug Electron e strumenti di compilazione.

Installazione

npm install @microsoft/winappcli

Avvio rapido

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

Tipi comuni

Ogni wrapper di comando CLI accetta un oggetto opzioni che estende CommonOptions e restituisce Promise<WinappResult>.

CommonOptions

Opzioni di base condivise dalla maggior parte dei comandi.

WinappResult

Risultato restituito da ciascun wrapper di comando.

Wrapper dei comandi CLI

Queste funzioni avvolgono i comandi nativi winapp della CLI. Tutti accettano CommonOptions (quiet, verbose, cwd).

certGenerate()

Creare un certificato autofirmato solo per i test locali. Il publisher deve corrispondere al manifesto (automaticamente dedotto se --manifest è specificato o se Package.appxmanifest si trova nella directory di lavoro). Output: devcert.pfx (password predefinita: 'password'). Per la produzione, ottenere un certificato da una CA attendibile. Usare 'cert install' per considerare attendibile il computer.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

certInfo()

Visualizzare i dettagli del certificato (oggetto, identificazione personale, scadenza). Utile per verificare che un certificato corrisponda al manifesto prima della firma.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

certInstall()

Autorizzare un certificato su questo computer (richiede l'amministratore di sistema). Eseguire prima di installare i pacchetti MSIX firmati con i certificati di sviluppo. Esempio: winapp cert install ./devcert.pfx. È necessaria una sola volta per ogni certificato.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

createDebugIdentity()

Abilitare l'identità del pacchetto per il debug senza creare MSIX completo. Obbligatorio per il test Windows API (notifiche push, destinazione di condivisione e così via) durante lo sviluppo. Esempio: winapp create-debug-identity ./myapp.exe. Richiede Package.appxmanifest o appxmanifest.xml nella directory corrente o passato tramite --manifest. Rieseguire dopo aver modificato il manifest o la cartella Assets/.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

createExternalCatalog()

Genera un file di catalogo CodeIntegrityExternal.cat con hash di file eseguibili dalle directory specificate. Usato con il flag TrustedLaunch nei manifesti del pacchetto sparse MSIX (AllowExternalContent) per consentire l'esecuzione di file esterni non inclusi nel pacchetto.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

getWinappPath()

Stampare il percorso della directory .winapp. Usare --global per il percorso della cache condivisa o omettere per la cartella project-local .winapp. Utile per gli script di compilazione che devono fare riferimento ai pacchetti installati.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

init()

Iniziare da qui per inizializzare un'app Windows con la configurazione richiesta. Configura tutti gli elementi necessari per lo sviluppo di app Windows: crea Package.appxmanifest con asset predefiniti, scarica Windows SDK e pacchetti SDK per app di Windows e genera proiezioni. Quando i pacchetti SDK sono gestiti (--setup-sdks stable/preview/experimental), crea anche winapp.yaml per aggiungere versioni per 'restore'/'update'; con --setup-sdks none (ad esempio, per i progetti Rust/Tauri che portano i propri binding SDK), non viene creato alcun file winapp.yaml. Interattivo per impostazione predefinita (usare --use-defaults per ignorare le richieste). Usare invece 'restore' se è stato clonato un repository che dispone già di winapp.yaml. Usare 'manifest generate' se è necessario un manifesto o 'cert generate' se è necessario un certificato di sviluppo per la firma del codice.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

manifestAddAlias()

Aggiungere un alias di esecuzione (uap5:AppExecutionAlias) a Package.appxmanifest. Ciò consente di avviare l'app in pacchetto dalla riga di comando digitando il nome dell'alias. Per impostazione predefinita, l'alias viene dedotto dall'attributo Executable (ad esempio, $targetnametoken$.exe diventa $targetnametoken$.exe alias).

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

manifestGenerate()

Creare Package.appxmanifest senza la configurazione completa del progetto. Usare quando sono necessari solo un manifesto e asset di immagine (senza SDK, nessun certificato). Per la configurazione completa, usare invece 'init'. Modelli: 'packaged' (MSIX completo), 'sparse' (app desktop che necessita di API Windows).

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

manifestUpdateAssets()

Generare nuovi asset per le immagini a cui si fa riferimento in un package.appxmanifest da una singola immagine di origine. L'immagine di origine deve essere di almeno 400x400 pixel.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

packageApp()

Crea un programma di installazione MSIX dalla tua app costruita. Avviare dopo la creazione dell'app. Per la creazione del pacchetto è necessario un manifesto (Package.appxmanifest o appxmanifest.xml), che deve trovarsi nella directory di lavoro corrente, passato come --manifest o nella cartella di input. Usare --cert devcert.pfx per firmare per i test. Esempio: pacchetto winapp ./dist --manifest Package.appxmanifest --cert ./devcert.pfx

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

restore()

Usare dopo la clonazione di un repository o quando manca la cartella .winapp/. Reinstalla i pacchetti SDK da winapp.yaml esistente senza modificare le versioni. Richiede winapp.yaml (creato da 'init'). Per verificare la disponibilità di versioni più recenti dell'SDK, usare invece 'update'.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

run()

Crea il layout in pacchetto, registra l'applicazione e avvia l'applicazione in pacchetto.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

sign()

Firmare il codice di un pacchetto MSIX o un eseguibile. Esempio: winapp sign ./app.msix ./devcert.pfx. Usare --timestamp per le compilazioni di produzione per rimanere valide dopo la scadenza del certificato. Il comando 'package' può firmare automaticamente con --cert.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

store()

Eseguire un comando di Microsoft Store Developer CLI. Questo comando scaricherà la CLI per sviluppatori del Microsoft Store se non è già stata scaricata. Altre informazioni sull'interfaccia della riga di comando per sviluppatori di Microsoft Store sono disponibili qui: https://aka.ms/msstoredevcli

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

tool()

Eseguire direttamente gli strumenti SDK di Windows (makeappx, signtool, makepri, ecc.). Scarica automaticamente Gli strumenti di compilazione, se necessario. Per la maggior parte delle attività, preferire comandi di livello superiore, ad esempio 'package' o 'sign'. Esempio: strumento winapp makeappx pack /d ./cartella /p ./out.msix

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiClick()

Fare clic su un elemento tramite lo slug o la ricerca di testo utilizzando la simulazione del clic del mouse. Funziona su elementi che non supportano InvokePattern (ad esempio, intestazioni di colonna, voci di elenco). Usare --double per fare doppio clic, --right per fare clic con il pulsante destro del mouse.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiFocus()

Usando UIA SetFocus, spostare lo stato attivo della tastiera sull'elemento specificato.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiGetFocused()

Mostra l'elemento che attualmente ha il focus della tastiera nell'app di destinazione.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiGetProperty()

Leggere i valori delle proprietà UIA da un elemento. Specificare --property per una singola proprietà o omettere per tutte le proprietà.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiGetValue()

Leggere il valore corrente da un elemento . Prova TextPattern (RichEditBox, Document), ValuePattern (TextBox, ComboBox, Slider), quindi Nome (etichette). Utilizzo: winapp ui get-value <selettore> -a <app>

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiInspect()

Visualizzare l'albero degli elementi dell'interfaccia utente con slug semantici, tipi di elemento, nomi e limiti.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiInvoke()

Attivare un elemento tramite slug o ricerca di testo. Prova InvokePattern, TogglePattern, SelectionItemPattern ed ExpandCollapsePattern nell'ordine specificato.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiListWindows()

Elencare tutte le finestre visibili con HWND, titolo, processo e dimensioni. Usare -a per filtrare in base al nome dell'app. Usare HWND con -w per specificare come destinazione una finestra specifica.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiScreenshot()

Acquisire come immagine PNG la finestra o l'elemento di destinazione. Quando esistono più finestre (ad esempio, finestre di dialogo), acquisisce ognuna in un file separato. Con --json, restituisce il percorso e le dimensioni del file. Usare --capture-screen per le sovrapposizioni pop-up.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiScroll()

Scorrere un elemento contenitore usando ScrollPattern. Usare --direction per scorrere in modo incrementale o --to per passare subito all'inizio o alla fine.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiScrollIntoView()

Scorrere l'elemento specificato nell'area visibile usando UIA ScrollItemPattern.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiSearch()

Cercare gli elementi corrispondenti a una query di testo nell'albero degli elementi. Restituisce tutte le corrispondenze con slug semantici.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiSetValue()

Impostare un valore su un elemento usando UIA ValuePattern. Funziona per TextBox, ComboBox, Slider e altri controlli modificabili. Utilizzo: winapp ui set-value <selettore><valore> -a <app>

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiStatus()

Connettersi a un'app di destinazione e visualizzare le informazioni di connessione.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

uiWaitFor()

Attendere che un elemento venga visualizzato, scompaia o che una proprietà raggiunga un valore di destinazione. Esegue il polling a intervalli di 100 ms fino a quando la condizione è soddisfatta o si verifica il timeout.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

unregister()

Cancella la registrazione di un pacchetto di sviluppo sideloaded. Rimuove solo i pacchetti registrati in modalità di sviluppo (ad esempio, tramite 'winapp run' o 'create-debug-identity').

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

update()

Verificare la presenza e installare le versioni più recenti dell'SDK. Aggiorna winapp.yaml con le versioni più recenti e reinstalla i pacchetti. Richiede winapp.yaml esistente (creato da 'init'). Usare l'anteprima di --setup-sdks per gli SDK di anteprima. Per reinstallare le versioni correnti senza aggiornare, usare invece 'restore'.

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

Opzioni:

Accetta anche CommonOptions (quiet, verbose, cwd).

Funzioni di utilità

execWithBuildTools()

Esegui un comando con il percorso bin di BuildTools aggiunto all'ambiente del PATH

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

Parametri:

Restituisce: Output di execSync

addMsixIdentityToExe()

Aggiunge informazioni sull'identità del pacchetto da un file appxmanifest.xml al manifesto incorporato di un eseguibile

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

Parametri:

addElectronDebugIdentity()

Aggiunge l'identità del pacchetto al processo di debug Electron

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

Parametri:

clearElectronDebugIdentity()

Cancella/rimuove l'identità del pacchetto dal processo di debug di Electron ripristinando dal backup

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

Parametri:

getGlobalWinappPath()

Ottieni il percorso della directory globale .winapp

function getGlobalWinappPath(): string

Restituisce: Il percorso completo alla directory globale .winapp

getLocalWinappPath()

Ottieni il percorso della directory locale .winapp

function getLocalWinappPath(): string

Restituisce: Il percorso completo alla directory locale .winapp

comandi dell'interfaccia della riga di comando di Node.js

Questi comandi sono disponibili esclusivamente tramite npx winapp node <subcommand> e non vengono esportati come funzioni a livello di codice.

node create-addon

Generare file di addon nativi per un progetto Electron. Supporta i modelli C++ (node-gyp) e C# (node-api-dotnet).

npx winapp node create-addon [options]

Opzioni:

Nota: Deve essere eseguito dalla radice di un progetto Electron (directory contenente package.json).

Esempi:

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

Aggiungere l'identità del pacchetto al processo di debug Electron usando il packaging sparso. Crea un backup di electron.exe, genera un manifesto MSIX sparse, aggiunge l'identità all'eseguibile e registra il pacchetto sparse. Richiede un oggetto Package.appxmanifest (crearne uno con winapp init o winapp manifest generate).

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

Opzioni:

Nota: Deve essere eseguito dalla radice di un progetto Electron (directory contenente node_modules/electron). Per annullare, usare npx winapp node clear-electron-debug-identity.

Esempi:

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

node clear-electron-debug-identity

Rimuovere l'identità del pacchetto dal processo di debug Electron. electron.exe Ripristina dal backup creato da add-electron-debug-identity e rimuove i file di backup.

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

Opzioni:

Nota: Deve essere eseguito dalla radice di un progetto Electron (directory contenente node_modules/electron).

Esempi:

npx winapp node clear-electron-debug-identity

Informazioni di riferimento per i tipi

ExecSyncOptions

Eseguire nuovamente l'esportazione da Node.js per praticità. Vedere Node.js documentazione.

MsixIdentityOptions

MsixIdentityResult

ElectronDebugIdentityResult

ClearElectronDebugIdentityResult

CallWinappCliOptions

CallWinappCliResult

CallWinappCliCaptureOptions

CallWinappCliCaptureResult

GenerateCppAddonOptions

GenerateCppAddonResult

GenerateCsAddonOptions

GenerateCsAddonResult

IfExists

Valori di IfExists.

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

SdkInstallMode

Valori SdkInstallMode.

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

ManifestTemplates

Valori ManifestTemplates.

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