Aplicação do Windows Development CLI (winapp CLI)

Importante

O CLI de Desenvolvimento de Aplicações Windows encontra-se atualmente em pré-visualização pública. As funcionalidades e comandos podem mudar antes do lançamento final. Partilhe o seu feedback criando um problema.

Aplicação do Windows Development CLI (winapp CLI) é uma ferramenta de linha de comandos para construir aplicações Windows com o framework que escolher. Funciona a partir de um terminal, do editor que preferes ou de um agente de programação de IA.

• Aplicações WinUI: criar, executar, depurar, testar e empacotar aplicações WinUI sem abrir o Visual Studio.
• Frameworks multiplataforma e outros: traga funcionalidades do Windows para a sua aplicação existente Electron, Flutter, Tauri, Rust, .NET ou C++ sem alterar frameworks. A linha de comandos winapp configura o SDK de Aplicações Windows e o Windows SDK, atribui à sua aplicação uma identidade de pacote para que possa chamar APIs como notificações e IA no dispositivo, e empacota-a como MSIX para a Microsoft Store ou para a sua própria distribuição.

Principais benefícios do winapp CLI

Criar e executar aplicações WinUI a partir do terminal
winapp new cria uma aplicação WinUI a partir dos templates oficiais, incluindo blank, NavigationView, TabView e MVVM starters. winapp runconstrói o projeto, instala o Aplicação do Windows Runtime correspondente e lança a aplicação, quer esteja empacotada ou não empacotada.
Constrói a tua primeira aplicação WinUI

Depuração com identidade de pacote e diagnóstico de falhas
Execute a sua aplicação com identidade de pacote para poder testar notificações, IA no dispositivo e outras APIs que exijam identidade. Adicione --debug-output para capturar mensagens de depuração e crash dumps. Para crashes do WinUI, o winapp decodifica exceções armazenadas para te apontar para o handler de eventos XAML que falhou.
Depuração com identidade de pacote

Baseie agentes de codificação com IA em código WinUI real
winapp find-uiretorna XAML e C# funcionais da Galeria WinUI 3 e do Windows Community Toolkit. winapp find-apiinspeciona as APIs do Windows Runtime que o seu projeto referencia. Os agentes usam-nos para gerar código a partir de amostras reais e metadados em vez de adivinhar.
Utilizar a linha de comando do winapp com agentes de IA

Automatize e teste a interface da sua aplicação
winapp uiinspeciona e interage com aplicações em execução através do Automatização da Interface de Utilizador, e captura capturas de ecrã e gravações. Executa a tua aplicação no Windows Sandbox para a testar num ambiente limpo.
Automação de UI

Embalar, etiquetar e enviar
winapp pack constrói o teu projeto, empacota-o como MSIX e assina-o numa só etapa. Gerar certificados de desenvolvimento localmente, assinar compilações de release com Assinatura Confiável do Azure e instalar o winapp CLI em runners do GitHub Actions ou do Azure DevOps.
Empacote a sua aplicação

Trazer funcionalidades do Windows para qualquer framework
Adicione o SDK do Windows e o SDK de Aplicações Windows, a identidade do pacote e o empacotamento do MSIX às aplicações construídas com .NET, C++, Electron, Flutter, Rust ou Tauri, sem alterar o seu sistema de compilação.
Ver as estruturas suportadas

Introdução ao WinUI

Depois de instalar a CLI do Winapp e o SDK .NET, crie e execute uma aplicação WinUI:

winapp new --name MyWinUIApp --template winui-navview --use-defaults
cd MyWinUIApp
winapp run

Quando estiver pronto para testar um pacote localmente, gere um certificado de desenvolvimento e crie um pacote MSIX assinado:

winapp cert generate --manifest ./Package.appxmanifest
winapp pack ./MyWinUIApp.csproj -c Release --cert ./devcert.pfx

O certificado de desenvolvimento utiliza uma palavra-passe padrão e é apenas para testes locais. Antes de distribuir a sua aplicação, assine-a com um certificado de confiança, por exemplo com winapp az-sign. Para obter mais informações, consulte Security.

Para um guia passo a passo que inclui a configuração e a sua primeira alteração na interface, veja Construir a sua primeira aplicação WinUI. Para ver todos os modelos disponíveis, execute winapp new --list. Para o fluxo de trabalho completo, incluindo depuração, automação da interface e empacotamento, veja Usar a linha de comando winapp com WinUI.

Instalação

WinGet

A forma mais fácil de instalar a CLI é através do WinGet (Windows Gestor de Pacotes):

winget install Microsoft.winappcli --source winget

Se usares o módulo PowerShell do WinGet, executa Install-WinGetPackage Microsoft.winappcli em vez disso.

NPM

Em projetos Electron, instale via npm:

npm install @microsoft/winappcli --save-dev

GitHub Actions / Azure DevOps

Para pipelines CI/CD, usa a ação setup-WinAppCli para instalar automaticamente a CLI nos teus runners/agentes.

Transferência manual

Descarregue a versão mais recente de GitHub Releases.

Verificar a instalação

Depois de instalado, verifique a instalação chamando a linha de código:

winapp --help

Ou, se estiver a usar Electron/Node.js:

npx winapp --help

Utilizar o CLI do winapp com agentes de IA

winapp CLI foi concebida para funcionar bem com agentes de codificação de IA. Comandos como find-ui e find-api retornam uma saída legível por máquina com --json, para que um agente possa consultar exemplos reais do WinUI e APIs do Windows Runtime antes de escrever código.

Instale o plugin winapp para dar ao seu agente competências para o fluxo de trabalho de CLI do winapp:

# GitHub Copilot CLI
copilot plugin install microsoft/WinAppCli

# Claude Code
claude plugin marketplace add microsoft/WinAppCli
claude plugin install winappcli@winappcli

Se trabalhas no Visual Studio Code, a extensão WinApp VS Code executa comandos de CLI winapp a partir do editor e lança a tua aplicação com a identidade do pacote quando carregas em F5. Instale-o a partir do Visual Studio Marketplace.

Estruturas suportadas

O winapp CLI funciona com o WinUI e outros frameworks de aplicações:

Framework	Guide
WinUI	Introdução ao WinUI
.NET / WPF / WinForms	Introdução ao .NET
.NET MAUI	Introdução ao .NET MAUI
C++ (CMake)	Comece a usar C++
Elétron	Inicie com o Electron
Ferrugem	Comece com Rust
Tauri	Começar com o Tauri
Flutter	Comece com o Flutter

Guias adicionais:

• Empacotamento de um EXE/CLI: guia passo a passo para embalar um EXE/CLI existente como MSIX
• Empacotamento esparso: atribua a uma aplicação não empacotada uma identidade de pacote com um MSIX só de identidade (esparso) e conteúdo externo
• Shell Completion: ativar a conclusão de tabulação para comandos, opções e valores no PowerShell, bash, zsh e fish
• Orientações de segurança: o que os certificados de desenvolvimento e o Modo de Programador alteram na sua máquina, como lidar com devcert.pfx, e como assinar para produção

Visão geral dos comandos

Categoria	Comandos
Criar e configurar	new, init, restore, update
Executar e depurar	run, create-debug-identity, embed-identity, unregister
Empacotamento	pack
Manifestos	manifest generate, manifest update-assets, manifest add-alias
Certificados e Assinatura	cert generate, cert install, sign, az-sign, create-external-catalog
Pesquisa de código para agentes	find-ui, find-api
Automação de UI & Sandbox	ui, target
Utilities	tool, store, get-winapp-path, complete
Node.js/Electron	node create-addon, node generate-bindings, node add-electron-debug-identity, node clear-electron-debug-identity

Para a referência completa de CLI, veja referência de CLI.

Samples

A pasta samples no GitHub tem um projeto executável para cada framework suportado:

Sample	Description
WinUI app	A aplicação WinUI incluída foi registada e lançada com winapp run
WinUI unpackaged app	Aplicação WinUI não empacotada lançada com winapp run
WinUI solution	Solução multi-projeto (app e projeto de teste) que mostra como winapp run seleciona o projeto da app
C++ WinUI app	Janela WinUI construída em C++ com CMake, sem XAML ou MSBuild
WPF app	Aplicação de computador WPF
.NET MAUI app	projeto Windows .NET MAUI empacotado e assinado com o winapp CLI
C++ app	Aplicação Win32 nativa em C++ construída com CMake
Electron	Aplicação Electron Forge com manifesto, assets e addons nativos em C++ e C#
Rust app	Aplicação Rust que chama APIs do Windows
Tauri app	Aplicação Tauri com backend Rust
Flutter app	Aplicação de desktop Flutter com identidade de pacote e o SDK de Aplicações Windows
Sparse app	Aplicação WPF com embalagem esparsa (MSIX apenas de identidade) e um instalador

Porquê a identidade do pacote?

Muitas APIs do Windows exigem que a sua aplicação tenha identidade de pacote. Com a identidade, a sua aplicação ganha acesso a funcionalidades como notificações, integração com o sistema operativo e IA no dispositivo. Os modelos de aplicações WinUI incluem um manifesto de pacote, por isso winapp run dá-lhes identidade por defeito. Para uma lista completa do que a identidade da embalagem desbloqueia e ajuda na escolha do modelo de embalagem certo, consulte Visão Geral da Embalagem.

Código aberto

O winapp CLI é open source. Podes encontrar o código-fonte, problemas de ficheiros e contribuir em GitHub. Para obter ajuda, consulte o Suporte.

Tópicos relacionados

• Constrói a tua primeira aplicação WinUI
• Visão geral do WinUI
• Referência CLI
• Depuração com identidade de pacote
• Orientação de segurança
• Automação de UI
• Execução no Windows Sandbox
• API programática NPM
• Guias de Framework
• SDK de Aplicações Windows documentação
• Documentação de embalagem do MSIX