Utilizar a CLI do WinApp com o WinUI

Este guia mostra como usar o winapp CLI em todo o ciclo de desenvolvimento interno de uma aplicação WinUI 3: criar um projeto a partir de um modelo oficial, construir e lançar com identidade de pacote, depurar crashes, encontrar controlos e APIs, automatizar a interface e produzir um pacote MSIX assinado. Cada passo corre a partir da linha de comandos, por isso funciona em qualquer editor, em CI e com agentes de codificação de IA.

Os modelos de projeto WinUI já incluem um Package.appxmanifest, por isso não precisa de correr winapp init para uma aplicação WinUI. Se estiver a adicionar identidade de pacote a uma aplicação .NET existente que não usa o WinUI, veja Usar a linha de comando do winapp com .NET em vez disso.

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 requerem o SDK .NET 10. A linha de comando winapp não instala cadeias de ferramentas, por isso winapp new e winapp run param e apresentam orientações se o SDK .NET estiver em falta.

  • winapp CLI:

    winget install Microsoft.winappcli --source winget

  • Modo de Programador, que o Windows exige para registar a aplicação a partir do resultado da compilação. Ative-o em Definições > Sistema > Para programadores. Para saber o que isto altera na sua máquina, veja Segurança.

Criar um aplicativo WinUI

winapp new cria a estrutura de uma aplicação WinUI a partir do pacote oficial Microsoft.WindowsAppSDK.WinUI.CSharp.Templates. Instala ou atualiza o pacote de templates a pedido e depois chama dotnet new por si.

# 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 templates no pacote instalado. O pacote inclui estes templates:

Template Description
winui Aplicação XAML mínima em branco (por defeito). Veja a captura de ecrã
winui-navview Aplicação XAML com um shell NavigationView. Ver a captura de ecrã
winui-tabview Aplicação XAML com shell TabView. Veja a captura de ecrã
winui-mvvm Aplicação XAML que utiliza o padrão MVVM com o CommunityToolkit.Mvvm. Consulte a captura de ecrã
winui-lib Biblioteca de classes WinUI
winui-unittest Projeto MSTest empacotado para testes unitários WinUI
reactor, reactor-mvu, reactor-navview, reactor-tabview Experimental. Aplicações WinUI escritas apenas em C#, sem XAML

Note

Os modelos do Reactor referem-se a pacotes de pré-lançamento Microsoft.UI.Reactor. As suas APIs podem mudar ou ser removidas numa versão futura.

Para cada opção, veja a newreferência de comando.

Compilar e executar com identidade

A partir da pasta do projeto, winapp run constrói o projeto, instala o runtime do SDK de Aplicações Windows que corresponde à tua arquitetura caso esteja em falta, regista a aplicação com a identidade do pacote e lança-a.

cd MyApp
winapp run

winapp run aceita um ficheiro de projeto, um ficheiro de solução, uma pasta que contenha 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

O winapp CLI lê a propriedade do WindowsPackageType projeto para decidir como o lançar. Um projeto empacotado é executado com identidade de pacote. Um projeto que define WindowsPackageType como None é executado como uma aplicação não empacotada sem identidade. Para executar um projeto empacotado como não empacotado, passe a propriedade na linha de comandos:

winapp run -p WindowsPackageType=None

Outras opções úteis incluem --clean remover o registo anterior e os dados guardados da aplicação (LocalState e definições) para uma nova primeira execução, --no-launch registar sem iniciar a aplicação, e --detach --json devolver o ID do processo e sair para que scripts e agentes possam continuar a funcionar enquanto a aplicação corre. Para a lista completa, veja modo de projeto (projetos do SDK do .NET).

Utilize dotnet run em vez disso

Se preferires dotnet run, usa o Microsoft.Windows.SDK.BuildTools.WinApp pacote NuGet. O pacote interceta dotnet run para chamar winapp run e lançar a aplicação com identidade. Os projetos que crias com winapp new já referenciam o pacote, por isso dotnet run funciona sem configuração extra. Para outros projetos, adicione primeiro o pacote:

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

Podes passar winapp run opções como WinAppRun* propriedades do MSBuild, por exemplo dotnet run -p:WinAppRunDebugOutput=true. Para desligar a integração, defina EnableWinAppRunSupport para false no ficheiro do projeto. Para detalhes, veja suporte do dotnet run.

Depuração de falhas

Adicione --debug-output para capturar mensagens OutputDebugString e exceções de primeira oportunidade enquanto a aplicação está a funcionar. Quando uma aplicação WinUI falha com uma stowed exception, a CLI do winapp analisa o crash dump e imprime o erro original e a pilha de chamadas em vez de um código genérico de falha.

winapp run --debug-output

Adicione --symbols para descarregar símbolos para nomes completos de funções nativas. Como --debug-output anexa o WINAPP CLI como depurador, não se pode associar o Visual Studio ou outro depurador ao mesmo processo. Para depurar com o seu IDE, veja Depuração com winapp CLI. Para detalhes sobre a análise de exceções armazenadas, veja Triagem de exceções armazenadas do WinUI.

Encontrar controlos e APIs

winapp find-uipesquisa amostras de XAML e C# na WinUI Gallery e no Windows Community Toolkit por intenção, e devolve o código para o cenário que escolher. winapp find-api pesquisa na superfície da API do Windows e WinRT que o seu projeto referencia, como os tipos, membros e enums do SDK de Aplicações Windows e 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 suportam --json, pelo que os agentes de codificação de IA podem usá-los para escolher controlos e verificar nomes de APIs. Para mais informações, consulte as referências find-ui e find-api.

Automatizar e verificar a interface de utilizador

winapp uiControla uma aplicação em execução através da Automatização da IU da Microsoft. Usa-o para inspecionar a árvore de elementos, invocar controlos, esperar por alterações de estado e tirar capturas de ecrã. Os agentes podem usar os mesmos comandos para verificar as 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 PART_PaneToggleButton seletor dirige-se ao botão do menu no winui-navview template/modelo. Para os seus próprios elementos da IU, copie um seletor da saída de winapp ui inspect ou winapp ui search.

Para correr a aplicação no Windows Sandbox em vez de no seu ambiente de trabalho, adicione --on sandbox a winapp run e winapp ui. Para mais informações, consulte Automação da IU e execução em isolamento.

Empacotar e assinar

Quando estiver pronto para testar um pacote localmente, gere um certificado de desenvolvimento cujo publicador corresponda ao seu manifesto e depois construa e empacote o projeto num só passo:

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

winapp pack compila o projeto e produz um .msix assinado. Para combinar builds de várias arquiteturas numa só .msixbundle, veja Bundles multi-arquitetura. O projeto tem de ser empacotado, por isso um projeto que define WindowsPackageType como None não pode ser empacotado. Para projetos WinUI, a build do SDK de Aplicações Windows detém o manifesto, o ponto de entrada e a geração de recursos, por isso --manifest, --executable, e --skip-pri não são aceites.

O certificado de desenvolvimento é apenas para testes locais e usa uma palavra-passe predefinida. Antes de distribuir a sua aplicação, assine-a com um certificado de confiança, por exemplo, com winapp az-sign e o Assinatura Confiável do Azure. Para mais informações, consulte Empacotamento direto de um projeto e Segurança.

Projetos WinUI existentes

O winapp CLI funciona com projetos WinUI que criaste no Visual Studio. Aponte winapp run para o ficheiro do projeto, para o ficheiro de solução ou para a pasta que o contém. Para winapp pack, transfira o .csproj. Podes continuar a construir e a depurar no Visual Studio e usar winapp CLI para scripts, CI e fluxos de trabalho de agentes.

WinUI com C++

winapp runtambém constrói e inicia projetos WinUI em C++/WinRT (.vcxproj) que criou a partir do modelo WinUI Blank App (Packaged) do Visual Studio. Constrói o projeto com o MSBuild do Visual Studio, regista a aplicação com a identidade do pacote e lança-a:

winapp run .\MyApp.vcxproj

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

Os projetos em C++ precisam do Visual Studio ou Build Tools para Visual Studio, com a carga de trabalho de desenvolvimento de Desktop com C++ e as ferramentas de desenvolvimento de aplicações WinUI em C++. winapp packnão compila .vcxproj projetos, por isso cria o pacote MSIX no Visual Studio. Para pré-requisitos e opções, veja projetos C++ (.vcxproj). Para aplicações C++ que não usam WinUI, veja Usar a linha de comando winapp com C++.

Samples

  • winui-app: uma aplicação WinUI empacotada com controlos configurados para winapp ui automação
  • winui-unpackaged-app: uma aplicação WinUI que corre sem identidade de pacote
  • winui-solution: uma solução multi-projeto que mostra como winapp run escolhe o projeto da aplicação
  • cpp-winui-app: uma aplicação WinUI em C++/WinRT empacotada (Visual Studio .vcxproj com XAML) que corre comwinapp run

Passos seguintes

  • Última atualização a