NPM-pakket — Programmatische API

TypeScript/JavaScript-API-verwijzing voor @microsoft/winappcli. Elke CLI-opdracht is beschikbaar als een asynchrone functie die stdout/stderr vastlegt en een getypt resultaat retourneert. Helperhulpprogramma's voor MSIX-identiteit, Electron-foutopsporingsidentiteit en buildhulpprogramma's worden ook geëxporteerd.

Installatie

npm install @microsoft/winappcli

Snel starten

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

Algemene typen

Elke CLI-opdrachtwrapper accepteert een optiesobject dat CommonOptions uitbreidt en Promise<WinappResult> retourneert.

CommonOptions

Basisopties die worden gedeeld door de meeste opdrachten.

WinappResult

Resultaat geretourneerd door elke opdrachtwikkelaar.

CLI-opdracht-wrappers

Met deze functies worden systeemeigen winapp CLI-opdrachten verpakt. Alle accepteren CommonOptions (quiet, verbose, cwd).

certGenerate()

Maak alleen een zelfondertekend certificaat voor lokaal testen. Publisher moet overeenkomen met het manifest (automatisch afgeleid als --manifest is opgegeven of Package.appxmanifest zich in de werkmap bevindt). Uitvoer: devcert.pfx (standaardwachtwoord: 'wachtwoord'). Haal voor productie een certificaat op bij een vertrouwde CA. Gebruik 'certificaatinstallatie' om te vertrouwen op deze computer.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

certInfo()

Geef certificaatdetails weer (onderwerp, vingerafdruk, vervaldatum). Handig om te controleren of een certificaat overeenkomt met uw manifest voordat u zich ondertekent.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

certInstall()

Vertrouw een certificaat op deze computer (hiervoor is een beheerder vereist). Voer uit voordat u MSIX-pakketten installeert die zijn ondertekend met dev-certificaten. Voorbeeld: winapp cert install ./devcert.pfx. Slechts één keer per certificaat nodig.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

createDebugIdentity()

Schakel pakketidentiteit in voor foutopsporing zonder volledige MSIX te maken. Vereist voor het testen van Windows API's (pushmeldingen, sharedoel, enzovoort) tijdens de ontwikkeling. Voorbeeld: winapp create-debug-identity ./myapp.exe. Vereist Package.appxmanifest of appxmanifest.xml in de huidige map of doorgegeven via --manifest. Voer opnieuw uit nadat u het manifest of Assets hebt gewijzigd.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

createExternalCatalog()

Genereert een CodeIntegrityExternal.cat catalogusbestand met hashes van uitvoerbare bestanden uit opgegeven mappen. Wordt gebruikt met de vlag TrustedLaunch in MSIX-pakketmanifesten (AllowExternalContent) om uitvoering van externe bestanden toe te staan die niet in het pakket zijn opgenomen.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

getWinappPath()

Druk het pad af naar de map .winapp. Gebruik --global voor de locatie van de gedeelde cache of laat deze weg voor de map project-local .winapp. Handig voor het bouwen van scripts die moeten verwijzen naar geïnstalleerde pakketten.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

init()

Begin hier voor het initialiseren van een Windows-app met de vereiste installatie. Stelt alles in dat nodig is voor Windows app-ontwikkeling: maakt Package.appxmanifest met standaardassets, downloadt Windows SDK en Windows App SDK pakketten en genereert projecties. Wanneer SDK-pakketten worden beheerd (--setup-sdks stable/preview/experimenteel), wordt winapp.yaml ook aangemaakt om versies vast te zetten voor 'restore'/'update'; met --setup-sdks none (bijvoorbeeld voor Rust/Tauri-projecten die hun eigen SDK-bindingen gebruiken), wordt er geen winapp.yaml gemaakt. Standaard interactief (gebruik --use-defaults om prompts over te slaan). Gebruik in plaats daarvan 'restore' als u een opslagplaats hebt gekloond die al winapp.yaml heeft. Gebruik 'manifest genereren' als u alleen een manifest of certificaat genereren nodig hebt als u een ontwikkelingscertificaat nodig hebt voor het ondertekenen van programmacode.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

manifestAddAlias()

Voeg een uitvoeringsalias (uap5:AppExecutionAlias) toe aan een Package.appxmanifest. Hierdoor kan de verpakte app vanaf de command line worden gestart door de aliasnaam te typen. De alias wordt standaard afgeleid van het kenmerk Uitvoerbaar (bijvoorbeeld $targetnametoken$.exe wordt $targetnametoken$.exe alias).

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

manifestGenerate()

Maak Package.appxmanifest zonder volledige projectinstallatie. Gebruik wanneer u alleen een manifest en afbeeldingsassets nodig heeft (geen SDK's, geen certificaat). Gebruik in plaats daarvan 'init' voor volledige installatie. Sjablonen: 'verpakt' (volledige MSIX), 'spaarzaam' (desktopapplicatie die Windows API's nodig heeft).

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

manifestUpdateAssets()

Genereer nieuwe assets voor afbeeldingen waarnaar wordt verwezen in een Package.appxmanifest op basis van één bronafbeelding. De bronafbeelding moet ten minste 400x400 pixels zijn.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

packageApp()

Maak een MSIX-installatieprogramma op basis van uw ingebouwde app. Voer uit na het bouwen van uw app. Er is een manifest (Package.appxmanifest of appxmanifest.xml) vereist voor de verpakking. Het moet zich in de huidige werkmap bevinden, als --manifest worden doorgegeven of zich in de invoermap bevinden. Gebruik --cert devcert.pfx om te ondertekenen voor testen. Voorbeeld: winapp-pakket ./dist --manifest Package.appxmanifest --cert ./devcert.pfx

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

restore()

Gebruik na het klonen van een opslagplaats of wanneer de map .winapp/ontbreekt. Installeert SDK-pakketten opnieuw van bestaande winapp.yaml zonder versies te wijzigen. Vereist het bestand winapp.yaml (gemaakt door 'init'). Als u wilt controleren op nieuwere SDK-versies, gebruikt u in plaats daarvan 'update'.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

run()

Hiermee maakt u een verpakte indeling, registreert u de toepassing en start u de verpakte toepassing.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

sign()

Een MSIX-pakket of uitvoerbaar bestand met code ondertekenen. Voorbeeld: winapp sign ./app.msix ./devcert.pfx. Voeg --timestamp toe aan productie-builds zodat ze geldig blijven nadat een certificaat is verlopen. De opdracht 'package' kan automatisch worden ondertekend met --cert.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

store()

Voer een Microsoft Store Developer CLI-opdracht uit. Met deze opdracht wordt de Microsoft Store Developer CLI gedownload als deze nog niet is gedownload. Meer informatie over de Microsoft Store Developer CLI vindt u hier: https://aka.ms/msstoredevcli

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

tool()

Voer Windows SDK-hulpprogramma's rechtstreeks uit (makeappx, signtool, makepri, enzovoort). Automatisch buildhulpprogramma's downloaden, indien nodig. Voor de meeste taken geeft u de voorkeur aan opdrachten op een hoger niveau, zoals 'package' of 'sign'. Voorbeeld: Gebruik de tool 'winapp' om makeappx pack /d ./folder /p ./out.msix uit te voeren.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiClick()

Selecteer een element door te zoeken op slug of tekst, met behulp van muissimulatie. Werkt op elementen die geen ondersteuning bieden voor InvokePattern (bijvoorbeeld kolomkoppen, lijstitems). Gebruik --double voor dubbelklikken, --rechts om met de rechtermuisknop te klikken.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiFocus()

Verplaats de toetsenbordfocus naar het opgegeven element met behulp van UIA SetFocus.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiGetFocused()

Het element weergeven dat momenteel de toetsenbordfocus heeft in de doel-app.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiGetProperty()

UIA-eigenschapswaarden van een element lezen. Geef --eigenschap op voor één eigenschap of laat deze weg voor alle.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiGetValue()

Lees de huidige waarde van een element. Probeert TextPattern (RichEditBox, Document), ValuePattern (Tekstvak, ComboBox, Schuifregelaar) en vervolgens Naam (labels). Gebruik: winapp ui get-value <selector> -a <app>

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiInspect()

Bekijk de elementstructuur van de gebruikersinterface met semantische slugs, elementtypen, namen en grenzen.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiInvoke()

Activeer een element via een slug of een tekstzoekopdracht. Probeert InvokePattern, TogglePattern, SelectionItemPattern en ExpandCollapsePattern achtereenvolgens.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiListWindows()

Geef alle zichtbare vensters weer met hun HWND, titel, proces en grootte. Gebruik -a om te filteren op app-naam. Gebruik de HWND met -w om een specifiek venster te richten.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiScreenshot()

Leg het doelvenster of het doelelement vast als png-afbeelding. Wanneer er meerdere vensters bestaan (bijvoorbeeld dialoogvensters), wordt elk venster vastgelegd in een afzonderlijk bestand. Met --json retourneert u het bestandspad en de dimensies. Gebruik --capture-screen voor pop-up-overlays.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiScroll()

Schuif door een containerelement met behulp van ScrollPattern. Gebruik --direction om stapsgewijs te schuiven of om naar boven/onder te springen.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiScrollIntoView()

Schuif het opgegeven element naar het zichtbare gebied met behulp van UIA ScrollItemPattern.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiSearch()

Zoek in de elementstructuur naar elementen die overeenkomen met een tekstquery. Retourneert alle resultaten met semantische slugs.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiSetValue()

Stel een waarde in voor een element met behulp van UIA ValuePattern. Werkt voor TextBox, ComboBox, Slider en andere bewerkbare besturingselementen. Gebruik: winapp ui set-value <selector><value> -a <app>

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiStatus()

Maak verbinding met een doel-app en geef verbindingsgegevens weer.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

uiWaitFor()

Wacht tot een element wordt weergegeven, verdwijnt of heeft een eigenschap een doelwaarde bereikt. Pollt met intervallen van 100 ms totdat aan de voorwaarde is voldaan of er een time-out optreedt.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

unregister()

Registratie van een sideloaded ontwikkelingspakket ongedaan maken. Verwijdert alleen pakketten die zijn geregistreerd in de ontwikkelingsmodus (bijvoorbeeld via 'winapp run' of 'create-debug-identity').

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

update()

Controleer op nieuwere SDK-versies en installeer deze. Werkt winapp.yaml bij met de nieuwste versies en installeert pakketten opnieuw. Vereist bestaande winapp.yaml (gemaakt door 'init'). Gebruik --setup-sdks preview voor preview-SDK's. Als u de huidige versies opnieuw wilt installeren zonder bij te werken, gebruikt u in plaats daarvan 'herstellen'.

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

Opties:

Accepteert ook CommonOptions (quiet, verbose, cwd).

Hulpprogrammafuncties

execWithBuildTools()

Voer een opdracht uit waarbij het bin-pad van BuildTools aan de PATH-omgeving is toegevoegd.

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

Parameters:

Retourneert: De uitvoer van execSync

addMsixIdentityToExe()

Voegt pakketidentiteitsgegevens uit een appxmanifest.xml-bestand toe aan het ingesloten manifest van een uitvoerbaar bestand

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

Parameters:

addElectronDebugIdentity()

Voegt pakketidentiteit toe aan het Electron-foutopsporingsproces

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

Parameters:

clearElectronDebugIdentity()

Door de pakketidentiteit uit het Electron-foutopsporingsproces te wissen/verwijderen, wordt deze hersteld van een back-up.

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

Parameters:

getGlobalWinappPath()

Het pad naar de globale .winapp-map verkrijgen

function getGlobalWinappPath(): string

Retourneert: Het volledige pad naar de globale .winapp-directory

getLocalWinappPath()

Het pad naar de lokale .winapp-map krijgen

function getLocalWinappPath(): string

Retourneert: Het volledige pad naar de lokale .winapp-map

Node.js CLI-opdrachten

Deze opdrachten zijn exclusief beschikbaar via npx winapp node <subcommand> en worden niet geëxporteerd als programmatische functies.

node create-addon

Genereer systeemeigen addon-bestanden voor een Electron-project. Ondersteunt C++-sjablonen (node-gyp) en C# (node-api-dotnet).

npx winapp node create-addon [options]

Opties:

Opmerking: Moet worden uitgevoerd vanuit de hoofdmap van een Electron-project (map met package.json).

Voorbeelden:

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

Voeg pakketidentiteit toe aan het Electron-debugproces met behulp van spaarzame verpakkingen. Hiermee maakt u een back-up van electron.exe, genereert u een sparse MSIX-manifest, voegt u de identiteit toe aan het uitvoerbare bestand en registreert u het sparse-pakket. Vereist een creatie Package.appxmanifest (creëer er een met winapp init of winapp manifest generate).

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

Opties:

Opmerking: Moet worden uitgevoerd vanuit de root map van een Electron-project (map met node_modules/electron). Als u het ongedaan wilt maken, gebruikt u npx winapp node clear-electron-debug-identity.

Voorbeelden:

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

node clear-electron-debug-identity

Verwijder pakketidentiteit uit het electron-foutopsporingsproces. Herstelt electron.exe vanuit de back-up die is gemaakt door add-electron-debug-identity en verwijdert de back-upbestanden.

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

Opties:

Opmerking: Moet worden uitgevoerd vanuit de hoofdmap van een Electron-project (de directory die node_modules/electron bevat).

Voorbeelden:

npx winapp node clear-electron-debug-identity

Typenreferentie

ExecSyncOptions

Opnieuw geëxporteerd uit Node.js voor het gemak. Zie Node.js documenten.

MsixIdentityOptions

MsixIdentityResult

ElectronDebugIdentityResult

ClearElectronDebugIdentityResult

CallWinappCliOptions

CallWinappCliResult

CallWinappCliCaptureOptions

CallWinappCliCaptureResult

GenerateCppAddonOptions

GenerateCppAddonResult

GenerateCsAddonOptions

GenerateCsAddonResult

IfExists

IfExists-waarden.

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

SdkInstallMode

SdkInstallMode-waarden.

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

ManifestTemplates

ManifestTemplates-waarden.

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