CLI de Desenvolvimento do aplicativo do Windows (CLI do 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 aplicativo do Windows Development CLI (WinApp CLI) é uma ferramenta de linha de comando para criar aplicativos do 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 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 de WinUI, a CLI do WinApp decodifica exceções stowed 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 o Assinatura Confiável do Azure e instale a WinApp CLI no GitHub Actions ou em 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 os plug-ins do agente para dar ao seu agente habilidades para a CLI do WinApp e o WinUI:

  • winappcli: um agente e habilidades do WinApp para comandos da CLI, fluxos de trabalho e solução de problemas.
  • winui: habilidades para criar, empacotar e testar aplicativos WinUI 3.
# GitHub Copilot CLI
copilot plugin marketplace add microsoft/WinAppCli
copilot plugin install winappcli@winappcli
copilot plugin install winui@winappcli

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

# OpenAI Codex
codex plugin marketplace add microsoft/WinAppCli
codex plugin add winappcli@winappcli
codex plugin add winui@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
  • Aplicativos .NET baseados em arquivo: execute um único arquivo .cs com o identificador de pacote, nenhum arquivo de projeto ou manifesto necessário
  • 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
  • DevTools: inspecione um aplicativo WinUI 3 em execução, experimente alterações de propriedade ao vivo e deixe comentários para um agente (avançado)
  • 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, devtools, target
Utilitários tool, store, get-winapp-path, config, 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 .NET MAUI Windows projeto 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 está código aberto. Você pode encontrar o código-fonte, problemas de arquivo e contribuir com GitHub. Para obter ajuda, consulte Suporte.

  • Última atualização em