Pacote NPM — API Programática

Referência da API TypeScript/JavaScript para @microsoft/winappcli. Cada comando CLI está disponível como uma função assíncrona que captura stdout/stderr e devolve um resultado digitado. Também são exportados utilitários auxiliares para identidade MSIX, identidade de depuração Electron e ferramentas de compilação.

Instalação

npm install @microsoft/winappcli

Início rápido

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

Tipos comuns

Cada invólucro de comandos CLI aceita um objeto de opções que se estende CommonOptions e retorna Promise<WinappResult>.

CommonOptions

Opções base partilhadas pela maioria dos comandos.

WinappResult

Resultado devolvido por cada wrapper de comando.

Envoltórios de comandos CLI

Estas funções envolvem comandos nativos winapp da CLI. Todos aceitam CommonOptions (quiet, verbose, cwd).

certGenerate()

Crie um certificado auto-assinado apenas para testes locais. O Publisher deve corresponder ao manifest (automaticamente inferido se --manifest fornecido ou Package.appxmanifest estiver no diretório de trabalho). Saída: devcert.pfx (palavra-passe padrão: 'senha'). Para produção, obtenha um certificado de uma Autoridade Certificadora (CA) de confiança. Usa o 'cert install' para confiar nesta máquina.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

certInfo()

Mostrar detalhes do certificado (assunto, impressão digital, validade). Útil para verificar se um certificado corresponde ao seu manifesto antes de assinar.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

certInstall()

Confie num certificado nesta máquina (requer administrador). Executa antes de instalar pacotes MSIX assinados com certificados de desenvolvimento. Exemplo: instalação do certificado winapp ./devcert.pfx. Só é necessário uma vez por certificado.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

createDebugIdentity()

Ativar a identidade do pacote para depuração sem necessidade de criar um pacote MSIX completo. Necessário para testar APIs do Windows (notificações push, share target, etc.) durante o desenvolvimento. Exemplo: winapp create-debug-identity ./myapp.exe. Requer Package.appxmanifest ou appxmanifest.xml no diretório atual ou passado via --manifest. Reexecute depois de alterar o manifesto ou os Assets/.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

createExternalCatalog()

Gera um ficheiro de catálogo CodeIntegrityExternal.cat com hashes de ficheiros executáveis a partir de diretórios especificados. Usado com o sinalizador TrustedLaunch nos manifestos de pacotes esparsos MSIX (AllowExternalContent), permite a execução de ficheiros externos não incluídos no pacote.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

getWinappPath()

Imprime o caminho para a pasta .winapp. Use --global para a localização partilhada da cache, ou omita para a pasta .winapp do projeto local. Útil para scripts de build que precisam de referenciar pacotes instalados.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

init()

Comece aqui para inicializar uma aplicação Windows com a configuração necessária. Configura tudo o que é necessário para o desenvolvimento de aplicações Windows: cria o Package.appxmanifest com os recursos predefinidos, descarrega pacotes do Windows SDK e SDK de Aplicações Windows e gera projeções. Quando os pacotes SDK são geridos (--setup-sdks stable/preview/experimental), também é criado um ficheiro de configuração winapp.yaml para estabelecer versões de 'restauração'/'atualização'; com --setup-sdks none (por exemplo, para projetos Rust/Tauri que trazem as suas próprias integrações SDK), não é criado o ficheiro winapp.yaml. Interativo por padrão (use --use-defaults para saltar prompts). Usa 'restore' em vez disso se clonaste um repositório que já tenha winapp.yaml. Use 'manifest generate' se só precisar de manifesto, ou 'cert generate' se precisar de um certificado de desenvolvimento para assinatura de código.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

manifestAddAlias()

Adicione um alias de execução (uap5:AppExecutionAlias) a um Package.appxmanifest. Isto permite iniciar a aplicação empacotada a partir da linha de comandos, escrevendo o nome do alias. Por defeito, o alias é inferido a partir do atributo Executable (por exemplo, $targetnametoken$.exe torna-se $targetnametoken$.exe alias).

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

manifestGenerate()

Criar o Package.appxmanifest sem configurar todo o projeto. Use quando só precisa de um manifesto e recursos de imagem (sem SDKs, sem certificado). Para configuração completa, usa 'init' em vez disso. Modelos: 'packaged' (MSIX completo), 'sparse' (aplicação desktop que precisa de APIs do Windows).

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

manifestUpdateAssets()

Gerar novos assets para imagens referenciadas num Package.appxmanifest a partir de uma única imagem de origem. A imagem de origem deve ter pelo menos 400x400 píxeis.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

packageApp()

Crie o instalador MSIX a partir da sua aplicação construída. Execute depois de criar a sua aplicação. Um manifesto (Package.appxmanifest ou appxmanifest.xml) é necessário para empacotamento – deve estar no diretório de trabalho atual, passado como --manifest ou estar na pasta de entrada. Usa --cert devcert.pfx para fazer a assinatura para fins de teste. Exemplo: winapp package ./dist --manifest Package.appxmanifest --cert ./devcert.pfx

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

restore()

Use depois de clonar um repositório ou quando falta a pasta .winapp/. Reinstala pacotes do SDK a partir do winapp.yaml existente sem mudar de versão. Requer o winapp.yaml (criado pelo 'init'). Para verificar versões mais recentes do SDK, use 'update' em vez disso.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

run()

Cria o layout empacotado, regista a Aplicação e lança a aplicação empacotada.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

sign()

Assinar digitalmente um pacote MSIX ou executável. Exemplo: sinal winapp ./app.msix ./devcert.pfx. Use --timestamp para que as versões de produção permaneçam válidas após o certificado expirar. O comando 'package' pode assinar automaticamente com --cert.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

store()

Executa um comando CLI do Microsoft Store Developer. Este comando irá descarregar a CLI do Microsoft Store Developer se ainda não estiver descarregada. Saiba mais sobre o CLI de Desenvolvedores Microsoft Store aqui: https://aka.ms/msstoredevcli

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

tool()

Executa diretamente as ferramentas do Windows SDK (makeappx, signtool, makepri, etc.). Descarrega automaticamente as ferramentas de construção se necessário. Para a maioria das tarefas, prefira comandos de nível superior como 'pacotejar' ou 'assinar'. Exemplo: winapp tool makeappx pack /d ./folder /p ./out.msix

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiClick()

Clique num elemento através do slug ou pesquisa de texto usando simulação de mouse. Funciona em elementos que não suportam InvokePattern (por exemplo, cabeçalhos de colunas, itens de lista). Utilize --double para duplo clique, --right para clique com o botão direito.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiFocus()

Mover o foco do teclado para o elemento especificado usando o UIA SetFocus.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiGetFocused()

Mostra o elemento que atualmente tem foco do teclado na aplicação alvo.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiGetProperty()

Leia os valores das propriedades UIA a partir de um elemento. Especifique --property para uma única propriedade ou omita para todas.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiGetValue()

Leia o valor atual de um elemento. Tenta TextPattern (RichEditBox, Document), ValuePattern (TextBox, ComboBox, Slider), depois Name (labels). Utilização: winapp ui get-value <selector> -a <app>

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiInspect()

Veja a árvore de elementos da interface com rótulos semânticos, tipos de elementos, nomes e limites.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiInvoke()

Ativa um elemento por slug ou pesquisa de texto. Tenta InvokePattern, TogglePattern, SelectionItemPattern e ExpandCollapsePattern numa sequência definida.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiListWindows()

Liste todas as janelas visíveis com o seu HWND, título, processo e tamanho. Use -a para filtrar por nome da aplicação. Usa o HWND com -w para direcionar uma janela específica.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiScreenshot()

Captura a janela ou elemento alvo como uma imagem PNG. Quando existem várias janelas (por exemplo, diálogos), captura cada uma num ficheiro separado. Com --json, devolve o caminho do ficheiro e as dimensões. Utiliza --capture-screen para sobreposições popup.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiScroll()

Desloca um elemento de contentor usando o ScrollPattern. Usa --direction para deslocar-te incrementalmente, ou --para saltar para cima/baixo.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiScrollIntoView()

Desloca o elemento especificado para a área visível usando UIA ScrollItemPattern.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiSearch()

Pesquise na árvore de elementos por elementos que correspondam a uma consulta de texto. Devolve todas as correspondências com slugs semânticos.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiSetValue()

Defina um valor num elemento usando o UIA ValuePattern. Funciona para TextBox, ComboBox, Slider e outros controlos editáveis. Utilização: winapp set-value UI <selector><valor> -a <app>

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiStatus()

Liga-te a uma aplicação alvo e mostra as informações de ligação.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

uiWaitFor()

Espere que um elemento apareça, desapareça ou que uma propriedade atinja um valor-alvo. Interroga a intervalos de 100ms até que a condição seja cumprida ou o limite de tempo.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

unregister()

Desregista um pacote de desenvolvimento carregado manualmente. Apenas remove pacotes registados em modo de desenvolvimento (por exemplo, via 'winapp run' ou 'create-debug-identity').

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

update()

Verifique e instale versões mais recentes do SDK. Atualiza o winapp.yaml com as versões mais recentes e reinstala os pacotes. Requer um winapp.yaml existente (criado por 'init'). Utilize --setup-sdks preview para SDKs em pré-visualização. Para reinstalar as versões atuais sem atualizar, use 'restaurar' em vez disso.

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

Opções:

Também aceita CommonOptions (quiet, verbose, cwd).

Funções utilitárias

execWithBuildTools()

Executar um comando com o caminho do diretório bin do BuildTools adicionado à variável de ambiente PATH

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

Parâmetros:

Resultado: A saída do execSync

addMsixIdentityToExe()

Adiciona informação de identidade de pacote a partir de um ficheiro appxmanifest.xml ao manifesto embutido de um executável

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

Parâmetros:

addElectronDebugIdentity()

Adiciona identidade de pacote ao processo de depuração do Electron

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

Parâmetros:

clearElectronDebugIdentity()

Limpa/remove a identidade do pacote do processo de depuração do Electron ao restaurar a partir de backup

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

Parâmetros:

getGlobalWinappPath()

Obtenha o caminho para o diretório global .winapp

function getGlobalWinappPath(): string

Retornos: O caminho completo para o diretório .winapp global

getLocalWinappPath()

Obtenha o caminho para o diretório local .winapp

function getLocalWinappPath(): string

Retornos: O caminho completo para o diretório .winapp local

Node.js comandos CLI

Estes comandos estão disponíveis exclusivamente através npx winapp node <subcommand> e não são exportados como funções programáticas.

node create-addon

Gerar ficheiros de addons nativos para um projeto Electron. Suporta templates C++ (node-gyp) e C# (node-api-dotnet).

npx winapp node create-addon [options]

Opções:

Nota: Deve ser executado a partir da raiz de um projeto Electron (diretório contendo package.json).

Exemplos:

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

Adicionar identidade de pacote ao processo de depuração do Electron usando empacotamento esparso. Cria uma cópia de segurança de electron.exe, gera um manifesto MSIX esparso, adiciona identidade ao executável e regista o pacote esparso. Requer um Package.appxmanifest (criar um com winapp init ou winapp manifest generate).

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

Opções:

Nota: Deve ser executado a partir da raiz de um projeto Electron (diretório contendo node_modules/electron). Para desfazer, use npx winapp node clear-electron-debug-identity.

Exemplos:

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

node clear-electron-debug-identity

Remover a identidade do pacote do processo de depuração no Electron. Restaura electron.exe a partir do backup criado por add-electron-debug-identity e remove os ficheiros de backup.

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

Opções:

Nota: Deve ser executado a partir da raiz de um projeto Electron (diretório contendo node_modules/electron).

Exemplos:

npx winapp node clear-electron-debug-identity

Referência de tipos

ExecSyncOptions

Reexportado de Node.js por conveniência. Consulta Node.js documentos.

MsixIdentityOptions

MsixIdentityResult

ElectronDebugIdentityResult

ClearElectronDebugIdentityResult

CallWinappCliOptions

CallWinappCliResult

CallWinappCliCaptureOptions

CallWinappCliCaptureResult

GenerateCppAddonOptions

GenerateCppAddonResult

GenerateCsAddonOptions

GenerateCsAddonResult

IfExists

Valores de IfExists.

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

SdkInstallMode

Valores do SdkInstallMode.

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

ManifestTemplates

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