Compartilhar via


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 WinUI 3 para sua interface do usuário (UI) e usa o SDK de Aplicativo do 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.

Comparar o projeto de embalagem com um único projeto

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.

Uma solução usando o projeto de empacotamento

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.

  1. 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>
    
  2. Salve suas alterações e feche o arquivo .csproj.

  3. Execute um dos procedimentos a seguir, dependendo da versão do Visual Studio.

    Para o Visual Studio 2022 ou posterior:

    1. 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....

    2. 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.

    3. 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. */
              }
          }
      }
      
    4. Salve e feche o arquivo launchSettings.json.

    Para Visual Studio 2019:

    1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto do seu aplicativo e selecione Propriedades.

    2. 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.

      Ativar a opção MsixProject

    3. 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.

  1. 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.
  2. 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.
  3. Remova o projeto de empacotamento da sua solução.

Ilustração de arquivos sendo movidos para o aplicativo principal

Etapa 4: habilitar a implementação no Configuration Manager

  1. Selecione Gerencie>Gerenciador de Configuração.
  2. 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.

Habilitando a Implantação no Configuration Manager

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.