Empacotar o aplicativo usando o MSIX de projeto único
O MSIX de projeto único é um recurso que permite criar um aplicativo para desktop WinUI 3 empacotado sem a necessidade de um projeto de empacotamento separado. Um aplicativo WinUI 3 é aquele que usa a estrutura da Windows UI Library (WinUI) 3 para sua interface de usuário (UI) e usa o SDK do Aplicativo Windows. Para empacotar um aplicativo para desktop que não seja um aplicativo WinUI 3, confira Configurar seu aplicativo para desktop para empacotamento MSIX no Visual Studio.
O recurso MSIX de projeto único está disponível como uma extensão do Visual Studio que você pode utilizar para estes cenários:
- Criar um novo aplicativo para desktop WinUI 3 usando o modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na área de trabalho) do Visual Studio que acompanha o SDK do Aplicativo Windows. Esse projeto é configurado para compilar seu aplicativo em um pacote MSIX sem a necessidade de um projeto de empacotamento separado.
- Modifique um aplicativo para desktop WinUI 3 existente que usa um projeto de empacotamento separado. A modificação envolve a remoção do projeto de embalagem separada, como mostra a ilustração abaixo.
Visão geral
Esta seção apresenta alguns detalhes importantes sobre o recurso MSIX de projeto único.
Benefícios
Antes da introdução do recurso MSIX de projeto único, se você quisesse criar um aplicativo para desktop WinUI 3 empacotado, precisaria de dois projetos na solução: o projeto de aplicativo, além de um Projeto de Empacotamento de Aplicativos do Windows adicional (confira Configurar seu aplicativo para desktop para empacotamento MSIX no Visual Studio). O recurso MSIX de projeto único permite desenvolver e compilar um aplicativo usando apenas um projeto para ele. Isso proporciona uma estrutura de projeto mais limpa e uma experiência de desenvolvimento mais direta. Por exemplo, não é mais necessário selecionar o projeto de empacotamento separado como seu projeto de inicialização.
Tipos de projeto com suporte
O recurso MSIX de projeto único oferece suporte a modelos WinUI 3 no Visual Studio (C# e C++) para o SDK do Aplicativo Windows.
Limitações
O MSIX de projeto único oferece suporte apenas para um executável no pacote MSIX gerado. Se precisar combinar vários executáveis em um único pacote MSIX, você precisará continuar usando um Projeto de Empacotamento de Aplicativos do Windows na sua solução.
Instale as ferramentas de empacotamento MSIX de projeto único
As ferramentas de empacotamento MSIX de projeto único incluem modelos de projeto do Visual Studio que você pode usar para criar novos aplicativos para desktop WinUI 3 empacotados. Essas ferramentas estão incluídas na extensão do SDK do Aplicativo Windows para Visual Studio. Para obter instruções de instalação para o SDK do Aplicativo Windows, confira Instalar ferramentas para o SDK do Aplicativo Windows.
SDK do Aplicativo Windows 0.8 e versão C# do 1.0 Preview 3: as ferramentas de empacotamento MSIX de projeto único não estão incluídas na extensão do SDK do Aplicativo Windows para Visual Studio para SDK do Aplicativo Windows versão 0.8 ou para projetos C# com até e incluindo Preview 3 do SDK do Aplicativo Windows 1.0. Portanto, se estiver usando essas versões, talvez seja necessário instalar explicitamente as ferramentas de empacotamento MSIX de projeto único. Confira as informações a seguir:
Visual Studio 2022 versão 17.1 e posterior: a extensão Ferramentas de empacotamento MSIX de projeto único para Visual Studio 2022 VSIX é incorporada ao Visual Studio 2022 versão 17.1 e posterior.
Visual Studio 2022 anterior à versão 17.1: instale a extensão Ferramentas de empacotamento MSIX de projeto único para Visual Studio 2022 VSIX.
Visual Studio 2019: instale a extensão Ferramentas de empacotamento MSIX de projeto único para Visual Studio 2019 VSIX. A extensão requer o Visual Studio 2019 versão 16.10.x ou posterior.
Em seguida, no Visual Studio, você pode confirmar que tem a extensão instalada. Clique em Extensões>Gerenciar Extensões>Instaladas>Todas e confirme se a opção Ferramentas de empacotamento MSIX de projeto único está listada.
Crie um novo projeto
Se estiver usando o SDK do Aplicativo Windows 1.0 Preview 2 ou posterior, poderá criar um novo aplicativo baseado em WinUI 3 que inclua suporte a MSIX de projeto único simplesmente usando o modelo Aplicativo em branco, empacotado (WinUI 3 na Área de Trabalho). Para obter mais informações, confira Criar seu primeiro projeto WinUI 3.
Modificar um projeto existente
Siga as etapas nesta seção para modificar um aplicativo baseado em WinUI 3 existente que usa um projeto de empacotamento separado. As etapas incluem mover o manifesto do pacote (e outro suporte necessário para criar um pacote MSIX) para o projeto de aplicativo e depois remover o projeto de empacotamento separado.
Etapa 1: criar ou abrir um projeto de empacotamento existente
Se já tiver uma solução para um aplicativo para desktop WinUI 3 (confira Modelos WinUI 3 no Visual Studio) que inclui um Projeto de empacotamento de aplicativo do Windows (confira Configurar seu aplicativo para desktop para empacotamento MSIX no Visual Studio) e abra essa solução no Visual Studio agora.
Caso contrário, crie um novo aplicativo para desktop WinUI 3 no Visual Studio usando o modelo Aplicativo em branco, empacotado com Projeto de Empacotamento de Aplicativo do Windows (WinUI 3 no Desktop). Sua solução será semelhante à captura de tela abaixo.
Etapa 2: editar as configurações do projeto do aplicativo
Em seguida, edite algumas definições de configuração para usar o recurso MSIX de projeto único. Há instruções diferentes dependendo do tipo de projeto e da versão do Visual Studio.
No Gerenciador de Soluções, clique duas vezes no nó do projeto do seu aplicativo para abrir o arquivo .csproj no editor XML. Adicione o seguinte XML ao elemento <PropertyGroup> principal.
<EnableMsixTooling>true</EnableMsixTooling> <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>Quando você terminar, o elemento <PropertyGroup> deverá ser semelhante a este.
<Project Sdk="Microsoft.NET.Sdk"> <PropertyGroup> <OutputType>WinExe</OutputType> <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework> ... <UseWinUI>true</UseWinUI> <EnableMsixTooling>true</EnableMsixTooling> <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile> </PropertyGroup>Salve suas alterações e feche o arquivo .csproj.
Execute um dos procedimentos a seguir, dependendo da versão do Visual Studio.
Para o Visual Studio 2022 ou posterior:
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Propriedades no nó do projeto do aplicativo e selecione Adicionar>Novo Item....
Selecione Arquivo de texto, nomeie o novo arquivo como launchSettings.json e clique em Adicionar. Verifique se o novo arquivo está na pasta Propriedades do seu projeto de aplicativo.
Copie as seguintes configurações para o novo arquivo. Você pode alterar os valores conforme necessário para o seu cenário. O valor MyApp pode ser qualquer sequência, e não precisa corresponder ao nome do aplicativo.
{ "profiles": { "MyApp": { "commandName": "MsixPackage", "commandLineArgs": "", /* Command line arguments to pass to the app. */ "alwaysReinstallApp": false, /* Uninstall and then reinstall the app. All information about the app state is deleted. */ "remoteDebugEnabled": false, /* Indicates that the debugger should attach to a process on a remote machine. */ "allowLocalNetworkLoopbackProperty": true, /* Allow the app to make network calls to the device it is installed on. */ "authenticationMode": "Windows", /* The authentication scheme to use when connecting to the remote machine. */ "doNotLaunchApp": false, /* Do not launch the app, but debug my code when it starts. */ "remoteDebugMachine": "", /* The name of the remote machine. */ "nativeDebugging": false /* Enable debugging for managed and native code together, also known as mixed-mode debugging. */ } } }Salve e feche o arquivo launchSettings.json.
Para Visual Studio 2019:
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto do seu aplicativo e selecione Propriedades.
Selecione a guia Depurar e defina a propriedade Launch como MsixPackage. Talvez seja necessário selecionar isso duas vezes se for revertido na primeira tentativa.
Salve suas alterações.
Etapa 3: mover arquivos para o projeto de aplicativo
Em seguida, mova vários arquivos importantes para o projeto de aplicativo. Há instruções diferentes dependendo do tipo de projeto.
- No Explorador de Arquivos, mova o arquivo Package.appxmanifest e a pasta Imagens do projeto de empacotamento para o projeto de aplicativo. Coloque o arquivo e a pasta no nível superior da hierarquia de pastas do projeto de aplicativo.
- No Visual Studio, no Gerenciador de Soluções, selecione várias das imagens dentro da pasta Imagens. Na janela Propriedades, defina Criar Ação como Conteúdo.
- Remova o projeto de empacotamento da sua solução.
Etapa 4: habilitar a implementação no Configuration Manager
- Selecione Gerencie>Gerenciador de Configuração.
- No Configuration Manager, marque a caixa de seleção Implantar para cada combinação de configuração e plataforma (por exemplo, Depurar e x86, Depurar e arm64, Liberar e x64, entre outros).
Observação
Use os menus suspensos Configuração de solução ativa e Plataforma de solução ativa na parte superior em vez dos menus suspensos Configuração e Plataforma na mesma linha que a caixa de seleção Implantar.
Etapa 5: implantar o aplicativo
Compile e implante seu projeto de aplicativo. O Visual Studio criará o aplicativo em um pacote MSIX, instalará o pacote e executará o aplicativo.
Etapa 6: empacotar o aplicativo para publicação
Use o comando Publicar pacote no Visual Studio para empacotar seu aplicativo para publicá-lo na Microsoft Store.
Automatizar a criação e o empacotamento de seu aplicativo MSIX de projeto único
É possível usar msbuild para criar e empacotar seu aplicativo MSIX de projeto único, permitindo automatizar o fluxo de trabalho. A técnica para uma solução de projeto único e a linha de comando é apenas um pouco diferente do que você já pode estar fazendo se tem uma solução de dois projetos: uma que tenha um Projeto de Empacotamento de Aplicativos do Windows (confira Configurar seu aplicativo para desktop para empacotamento MSIX no Visual Studio).
A opção de compilação de comando importante para uma solução de projeto único é /p:GenerateAppxPackageOnBuild=true. Sem ela, o projeto será compilado, mas você não receberá um pacote MSIX. Inclua essa opção, e ela fará com que o pacote MSIX seja gerado.
Há um exemplo completo na forma de uma Ação do GitHub que cria uma solução de projeto único WinUI 3.
Observação
Atualmente, o MSIX de projeto único não oferece suporte à produção de pacotes MSIX (confira Agrupar pacotes MSIX). Ele produz apenas um MSIX. Porém, você pode agrupar arquivos .msix em um pacote MSIX usando a Ação do GitHub MSIX Bundler.
Como um aplicativo de desktop empacotado é executado no Windows
Para se aprofundar sobre o que acontece com arquivos e entradas do Registro quando você cria um pacote do aplicativo do Windows para seu aplicativo da área de trabalho, confira Noções básicas sobre como os aplicativos da área de trabalho empacotados são executados no Windows.
Enviar comentários
Para deixar comentários, denunciar problemas ou fazer perguntas sobre o recurso MSIX de projeto único, poste uma discussão ou problema no repositório GitHub do SDK do Aplicativo Windows.
Windows developer
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de