Usando a CLI do WinApp com WinUI

Este guia mostra como usar a CLI do WinApp em todo o loop interno de um aplicativo WinUI 3: criar um projeto a partir de um modelo oficial, compilar e iniciá-lo com identidade de pacote, depurar falhas, localizar controles e APIs, automatizar a interface do usuário e produzir um pacote MSIX assinado. Cada etapa é executada na linha de comando, portanto, ela funciona em qualquer editor, em CI e com agentes de codificação de IA.

Os modelos de projeto do WinUI já incluem um Package.appxmanifest, portanto, você não precisa executar winapp init para um aplicativo WinUI. Se você estiver adicionando a identidade do pacote a um aplicativo .NET existente que não usa WinUI, consulte Como usar a CLI do WinApp com .NET.

Prerequisites

  • Windows 10 versão 1809 ou posterior ou Windows 11.

  • O SDK .NET, versão 8.0.100 ou posterior. Os modelos experimentais do Reactor exigem o SDK .NET 10. A CLI do WinApp não instala as cadeias de ferramentas, portanto winapp run e winapp new param com orientações se o SDK do .NET estiver ausente.

  • CLI do WinApp:

    winget install Microsoft.winappcli --source winget

  • Modo de Desenvolvedor, que o Windows requer para registrar o aplicativo a partir da saída da compilação. Ative-o em Configurações > Sistema > Para desenvolvedores. Para saber o que isso muda em seu computador, consulte Segurança.

Criar um aplicativo WinUI

winapp new gera a estrutura de um aplicativo WinUI a partir do pacote oficial Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Ele instala ou atualiza o pacote de modelos sob demanda e, em seguida, chama dotnet new para você.

# Pick a template and a name interactively
winapp new

# Or create a NavigationView app without prompts
winapp new --name MyApp --template winui-navview --use-defaults

Execute winapp new --list para ver os modelos no pacote instalado. O pacote inclui estes modelos:

Template Description
winui Aplicativo XAML em branco mínimo (padrão). Veja a captura de tela
winui-navview Aplicativo XAML com um shell NavigationView. Veja a captura de tela
winui-tabview Aplicativo XAML com um shell TabView. Veja a captura de tela
winui-mvvm Aplicativo XAML que usa o padrão MVVM com CommunityToolkit.Mvvm. Veja a captura de tela
winui-lib Biblioteca de classes WinUI
winui-unittest Projeto mstest empacotado para testes de unidade WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Experimental. Somente aplicativos WinUI escritos em C#, sem XAML

Note

Os modelos do Reactor fazem referência a pacotes Microsoft.UI.Reactor de pré-lançamento. Suas APIs podem ser alteradas ou removidas em uma versão futura.

Para cada opção, consulte a referência de comandos new.

Compilar e executar usando identidade

Na pasta do projeto, winapp run compila o projeto, instala o runtime do SDK do Aplicativo Windows correspondente à sua arquitetura, caso esteja ausente, registra o aplicativo com a identidade do pacote e o inicia.

cd MyApp
winapp run

winapp run aceita um arquivo de projeto, um arquivo de solução, uma pasta que contém um deles ou uma pasta de saída de build:

# A specific project and configuration
winapp run .\MyApp.csproj -c Release --arch arm64

# A solution: WinApp CLI finds the single app project and skips libraries and tests
winapp run .\MySolution.sln

# A solution with more than one app project
winapp run .\MySolution.sln --project MyApp

# Build output that you produced yourself
winapp run .\bin\x64\Debug\net10.0-windows10.0.26100.0\win-x64

A CLI do WinApp lê a propriedade WindowsPackageType do projeto para decidir como iniciá-lo. Um projeto empacotado é executado com a identidade do pacote. Um projeto que define WindowsPackageType como None é executado como um aplicativo não empacotado sem identidade. Para executar um projeto empacotado como não empacotado, passe a propriedade na linha de comando:

winapp run -p WindowsPackageType=None

Outras opções úteis incluem --clean remover o registro anterior e os dados salvos do aplicativo (LocalState e configurações) para uma nova primeira execução, --no-launch registrar sem iniciar o aplicativo e --detach --json retornar a ID do processo e sair para que scripts e agentes possam continuar funcionando enquanto o aplicativo é executado. Para obter a lista completa, consulte modo de projeto (projetos do SDK .NET).

Use dotnet run em vez disso

Se preferir dotnet run, use o Microsoft.Windows.SDK.BuildTools.WinApp pacote NuGet. O pacote intercepta dotnet run de modo que ele chame winapp run e inicie o aplicativo com uma identidade. Os projetos que você cria com o winapp new já fazem referência ao pacote, portanto, o dotnet run funciona sem configuração adicional. Para outros projetos, adicione o pacote primeiro:

dotnet add package Microsoft.Windows.SDK.BuildTools.WinApp --prerelease
dotnet run

Você pode passar winapp run opções como WinAppRun* propriedades do MSBuild, por exemplo dotnet run -p:WinAppRunDebugOutput=true. Para desativar a integração, defina EnableWinAppRunSupport como false no arquivo de projeto. Para obter detalhes, consulte o suporte ao dotnet run.

Depurar falhas

Adicione --debug-output para capturar mensagens OutputDebugString e exceções de primeira chance enquanto o aplicativo estiver em execução. Quando um aplicativo WinUI falha com uma stowed exception, a CLI do WinApp analisa o despejo de falhas e imprime o erro original e a pilha de chamadas em vez de um código de falha genérico.

winapp run --debug-output

Adicione --symbols para fazer download de símbolos para nomes completos de funções nativas. Como --debug-output anexa a CLI do WinApp como depurador, você não pode anexar Visual Studio ou outro depurador ao mesmo processo. Para depurar com seu IDE, consulte Depuração com a CLI do WinApp. Para obter detalhes sobre a análise de exceção stowed, consulte triagem de stowed-exception do WinUI.

Localizar controles e APIs

winapp find-ui pesquisa exemplos em XAML e C# na WinUI Gallery e no Kit de Ferramentas da Comunidade Windows com base na intenção, e retorna o código referente a um cenário que você escolher. winapp find-apipesquisa a superfície da API do Windows e do WinRT às quais seu projeto faz referência, como tipos, membros e enumerações do SDK do Aplicativo Windows e do Windows SDK.

# Find a control by what you want to build
winapp find-ui "tabbed layout"

# Get the XAML and C# for one of the returned scenarios
winapp find-ui --id gallery-tabview-1

# Look up an API
winapp find-api NavigationView

Ambos os comandos dão suporte --json, portanto, os agentes de codificação de IA podem usá-los para escolher controles e verificar nomes de API. Para obter mais informações, consulte as referências find-api e find-ui.

Automatizar e verificar a interface do usuário

winapp ui controla um aplicativo em execução por meio de Microsoft Automação da Interface do Usuário. Use-a para inspecionar a árvore de elementos, invocar controles, aguardar as alterações de estado e fazer capturas de tela. Os agentes podem usar os mesmos comandos para verificar suas próprias alterações.

winapp run --detach
winapp ui inspect -a MyApp
winapp ui search Button -a MyApp
winapp ui invoke PART_PaneToggleButton -a MyApp
winapp ui screenshot -a MyApp

O seletor PART_PaneToggleButton tem como alvo o botão de menu no modelo winui-navview. Para seus próprios controles, copie um seletor da saída de winapp ui inspect ou winapp ui search.

Para executar o aplicativo no Windows Sandbox em vez de na sua área de trabalho, adicione --on sandbox a winapp run e winapp ui. Para obter mais informações, consulte automação da interface do usuário e execução da área restrita.

Empacotar e assinar

Quando estiver pronto para testar um pacote localmente, gere um certificado de desenvolvimento cujo publicador corresponda ao manifesto e, em seguida, compile e empacote o projeto em uma etapa:

winapp cert generate --manifest .\Package.appxmanifest
winapp pack .\MyApp.csproj -c Release --arch x64 --cert .\devcert.pfx

winapp pack compila o projeto e gera um .msix assinado. Para combinar builds de várias arquiteturas em um único pacote .msixbundle, consulte Pacotes de múltiplas arquiteturas. O projeto deve ser empacotado, portanto, um projeto que define WindowsPackageType como None não pode ser empacotado. Para projetos WinUI, o build do SDK do Aplicativo Windows é responsável pelo manifesto, pelo ponto de entrada e pela geração de recursos, portanto, --manifest, --executable e --skip-pri não são aceitos.

O certificado de desenvolvimento destina-se apenas a testes locais e usa uma senha padrão. Antes de distribuir seu aplicativo, assine-o com um certificado confiável, por exemplo, com winapp az-sign e Assinatura Confiável do Azure. Para obter mais informações, consulte Empacotar um projeto diretamente e Segurança.

Projetos WinUI existentes

A CLI do WinApp funciona com projetos WinUI criados em Visual Studio. Aponte winapp run para o arquivo de projeto, o arquivo de solução ou a pasta que contenha um deles. Para winapp pack, passe o .csproj. Você pode continuar criando e depurando em Visual Studio e usar a CLI do WinApp para scripts, CI e fluxos de trabalho do agente.

WinUI com C++

winapp runtambém compila e inicia projetos WinUI do C++/WinRT (.vcxproj) que você criou com base no modelo do Visual Studio WinUI Blank App (Empacotado). Ele cria o projeto com o MSBuild do Visual Studio, registra o aplicativo com a identidade do pacote e o inicia:

winapp run .\MyApp.vcxproj

# Or from the folder that contains the project
winapp run .

Os projetos de C++ precisam do Visual Studio ou do Build Tools para Visual Studio com a workload Desktop development with C++ e ferramentas de desenvolvimento de aplicativos WinUI para C++. Você também pode compilar, empacotar e assinar um .vcxproj com winapp pack:

winapp pack .\MyApp.vcxproj -c Release --arch x64 --cert .\devcert.pfx

Para obter opções de empacotamento, consulte Empacotar um projeto diretamente. Para obter pré-requisitos e opções de build, consulte projetos C++ (.vcxproj). Para aplicativos C++ que não usam WinUI, consulte Usando a CLI do WinApp com C++.

Samples

  • winui-app: um aplicativo WinUI empacotado com controles configurados para automação com winapp ui
  • winui-unpackaged-app: um aplicativo WinUI que é executado sem a identidade do pacote
  • winui-solution: uma solução de vários projetos que mostra como winapp run escolhe o projeto de aplicativo
  • cpp-winui-app: um aplicativo C++/WinRT WinUI empacotado (Visual Studio .vcxproj com XAML) que é executado comwinapp run

Próximas Etapas 

  • Última atualização em