CLI de Desenvolvimento de Aplicativos do Windows (CLI de WinApp)

Importante

A CLI de Desenvolvimento de Apps do Windows está atualmente em visão pública. Recursos e comandos podem ser alterados antes da versão final. Compartilhe seus comentários criando um problema.

A CLI de desenvolvimento de aplicativos para Windows (winapp CLI) é uma ferramenta de linha de comando para criar aplicativos para Windows usando o framework de sua preferência. Funciona a partir de um terminal, do editor de sua preferência ou de um agente de programação baseado em IA.

• Aplicativos WinUI: criar, executar, depurar, testar e empacotar aplicativos WinUI sem abrir Visual Studio.
• Frameworks multiplataforma e outros: leve recursos do Windows para seu aplicativo existente, seja ele desenvolvido em Electron, Flutter, Tauri, Rust, .NET ou C++, sem precisar mudar de framework. A CLI do winapp configura o SDK do Aplicativo Windows e o Windows SDK, fornece a identidade do pacote do aplicativo para que você possa chamar APIs como notificações e IA no dispositivo e o empacota como MSIX para a Microsoft Store ou sua própria distribuição.

Principais benefícios da CLI do winapp

Criar e executar aplicativos WinUI no terminal
winapp new cria um aplicativo WinUI a partir dos modelos oficiais, incluindo opções como um modelo em branco, NavigationView, TabView e modelos baseados em MVVM. winapp runcria o projeto, instala o runtime de aplicativo do Windows correspondente e inicia o aplicativo, seja ele empacotado ou desempacotado.
Crie seu primeiro aplicativo WinUI

Depurar com a identidade do pacote e o diagnóstico de falha
Execute seu aplicativo com a identidade do pacote para que você possa testar notificações, IA no dispositivo e outras APIs que exigem identidade. Adicione --debug-output para capturar mensagens de depuração e arquivos de despejo de falha. Para falhas do WinUI, o winapp decodifica exceções armazenadas para apontá-lo para o manipulador de eventos XAML que falhou.
Depuração usando a identidade do pacote

Basear agentes de codificação de IA em código WinUI real
winapp find-uiretorna XAML e C# funcionando da WinUI 3 Gallery e do Windows Community Toolkit. winapp find-api inspeciona as APIs do Windows Runtime que o seu projeto referencia. Os agentes os usam para gerar código com base em exemplos reais e metadados em vez de adivinhar.
Usar a CLI do winapp com agentes de IA

Automatize e teste a interface do usuário do seu aplicativo
winapp ui inspeciona e interage com aplicativos em execução por meio de Automação da Interface do Usuário e captura capturas de tela e gravações. Execute seu aplicativo no Windows Sandbox para testá-lo em um ambiente limpo.
Automação da interface do usuário

Empacotar, etiquetar e enviar
winapp pack compila seu projeto, empacota-o como MSIX e o assina em uma etapa. Gere certificados de desenvolvimento localmente, assine builds de versão com Assinatura Confiável do Azure e instale a CLI do winapp em GitHub Actions ou executores do Azure DevOps.
Empacote seu aplicativo

Traga recursos do Windows para qualquer framework
Adicione o Windows SDK e SDK do Aplicativo Windows, identidade do pacote e empacotamento MSIX a aplicativos criados com .NET, C++, Electron, Flutter, Rust ou Tauri, sem alterar o sistema de build.
Veja os frameworks compatíveis

Introdução ao WinUI

Depois de instalar a CLI do winapp e o SDK do .NET, crie e execute um aplicativo 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 usa uma senha padrão e destina-se apenas a testes locais. Antes de distribuir seu aplicativo, assine-o com um certificado confiável, por exemplo, com winapp az-sign. Para obter mais informações, consulte Segurança.

Para um guia passo a passo que inclui a configuração e a sua primeira alteração na interface do usuário, consulte Criar seu primeiro aplicativo WinUI. Para ver todos os modelos disponíveis, execute winapp new --list. Para obter o fluxo de trabalho completo, incluindo depuração, automação da interface do usuário e empacotamento, consulte Usando a CLI do winapp com WinUI.

Installation

WinGet

A maneira mais fácil de instalar a CLI é por meio do WinGet (Windows Gerenciador de Pacotes):

winget install Microsoft.winappcli --source winget

Se você usar o módulo Do WinGet PowerShell, execute Install-WinGetPackage Microsoft.winappcli em vez disso.

NPM

Para projetos do Electron, instale via npm:

npm install @microsoft/winappcli --save-dev

GitHub Actions/Azure DevOps

Para pipelines de CI/CD, use a ação setup-WinAppCli para instalar automaticamente a CLI em seus executores/agentes.

Download manual

Baixe o build mais recente do GitHub Releases.

Verifique a instalação

Depois de instalado, verifique a instalação chamando a CLI:

winapp --help

Ou se estiver usando o Electron/Node.js:

npx winapp --help

Usar a CLI do winapp com agentes de IA

A CLI do winapp foi projetada para funcionar bem com agentes de codificação de IA. Comandos como find-ui e find-api retornam saída legível por computador com --json, portanto, um agente pode pesquisar exemplos reais do WinUI e APIs do Windows Runtime antes de escrever código.

Instale o plug-in do winapp para dar ao seu agente habilidades para o fluxo de trabalho da 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 você trabalha em Visual Studio Code, a extensão winapp vs code executa comandos da CLI do winapp do editor e inicia seu aplicativo com a identidade do pacote quando você pressiona F5. Instale-o pelo Visual Studio Marketplace.

Estruturas com suporte

A CLI do winapp funciona com WinUI e outras estruturas de aplicativo:

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

Guias adicionais:

• Empacotando um EXE/CLI: guia passo a passo para empacotar um EXE/CLI existente como MSIX
• Empacotamento esparso: atribui uma identidade a um pacote de aplicativo não empacotado com um MSIX (esparso) contendo apenas a identidade e conteúdo externo
• Conclusão do shell: habilitar a conclusão da guia para comandos, opções e valores no PowerShell, bash, zsh e fish
• Diretrizes de segurança: o que os certificados de desenvolvimento e o Modo de Desenvolvedor alteram no seu computador, como lidar com devcert.pfx e como assinar para produção

Visão geral de comandos

Categoria	Comandos
Criar e configurar	novo, iniciar, restaurar, atualizar
Executar & depurar	run, create-debug-identity, inbed-identity, unregister
Embalagem	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 por agentes	find-ui, find-api
Automação da interface do usuário e Sandbox	ui, destino
Utilitários	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 obter a referência completa da CLI, consulte a referência da CLI.

Samples

A pasta de exemplos no GitHub contém um projeto executável para cada framework compatível:

Sample	Description
Aplicativo WinUI	Aplicativo WinUI empacotado registrado e iniciado com winapp run
Aplicativo não empacotado do WinUI	Aplicativo WinUI não empacotado iniciado com winapp run
Solução WinUI	Solução de vários projetos (aplicativo e projeto de teste) que mostra como winapp run seleciona o projeto do aplicativo
Aplicativo WinUI do C++	Janela WinUI desenvolvida em C++ com CMake, sem XAML ou MSBuild
aplicativo WPF	Aplicativo da área de trabalho do WPF
aplicativo .NET MAUI	projeto Windows do .NET MAUI empacotado e assinado com a CLI do winapp
app C++	Aplicativo nativo C++ Win32 criado com CMake
Electron	Aplicativo Electron Forge com um manifesto, ativos e complementos C++ e C# nativos
Aplicativo Rust	Aplicativo Rust que chama APIs de Windows
Aplicativo Tauri	Aplicativo Tauri com um back-end do Rust
Aplicativo Flutter	Aplicativo de área de trabalho flutter com a identidade do pacote e o SDK do Aplicativo Windows
Aplicativo Sparse	WPF aplicativo com empacotamento esparso (MSIX somente identidade) e um instalador

Por que a identidade do pacote?

Muitas APIs Windows exigem que seu aplicativo tenha a identidade do pacote. Com a identidade, seu aplicativo ganha access a recursos como notificações, integração do sistema operacional e IA no dispositivo. Os modelos de aplicativo WinUI incluem um manifesto de pacote, portanto winapp run lhes confere identidade por padrão. Para obter uma lista completa do que a identidade do pacote desbloqueia e ajudar a escolher o modelo de empacotamento correto, consulte a visão geral do empacotamento.

Código aberto

A CLI do winapp é código aberto. Você pode encontrar o código-fonte, problemas de arquivo e contribuir com GitHub. Para obter ajuda, consulte Suporte.

Tópicos relacionados

• Crie seu primeiro aplicativo WinUI
• Visão geral do WinUI
• Referência da CLI
• Depuração usando a identidade do pacote
• Diretrizes de segurança
• Automação da interface do usuário
• Execução do Windows Sandbox
• API programática do NPM
• Guias de Framework
• Documentação do SDK do Aplicativo Windows
• Documentação do empacotamento MSIX