Empacote a sua aplicação usando MSIX de projeto único

MSIX de projeto único é um recurso que permite criar uma aplicação WinUI 3 desktop empacotada sem 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 do Aplicativo Windows. Para embalar uma aplicação da área de trabalho que não é uma aplicação WinUI 3, consulte Configurar a sua aplicação da área de trabalho 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 usar para estes cenários:

Crie um novo aplicativo de área de trabalho WinUI 3 usando o modelo de projeto Aplicativo em Branco, Empacotado (WinUI 3 na Área de Trabalho) Visual Studio que vem com o SDK de Aplicativo do Windows. Esse projeto é configurado para criar seu aplicativo em um pacote MSIX sem precisar de um projeto de empacotamento separado.
Modifique um aplicativo de desktop WinUI 3 existente que usa um projeto de empacotamento separado. A modificação envolve a remoção do projeto de embalagem separado, como mostrado na 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 de área de trabalho WinUI 3 empacotado, precisava de dois projetos em sua solução — seu projeto de aplicativo, além de um adicional Projeto de Empacotamento de Aplicativos do Windows (consulte Configurar seu aplicativo de área de trabalho para empacotamento MSIX no Visual Studio). O recurso MSIX de projeto único permite que você desenvolva e crie seu aplicativo usando apenas um projeto para seu aplicativo. Isso proporciona uma estrutura de projeto mais limpa e uma experiência de desenvolvimento mais direta. Por exemplo, você não precisa mais selecionar o projeto de empacotamento separado como seu projeto de inicialização.

Tipos de projetos suportados

O recurso MSIX de projeto único oferece suporte a modelos WinUI 3 no Visual Studio (C# e C++) para o SDK de Aplicativo do Windows.

Limitações

O MSIX de projeto único suporta apenas um único executável no pacote MSIX gerado. Se você precisar combinar vários executáveis em um único pacote MSIX, precisará continuar usando um projeto de empacotamento de aplicativos do Windows em sua solução.

Instale as ferramentas de empacotamento MSIX de um único projeto

As ferramentas de empacotamento MSIX para um único projeto incluem modelos de projeto do Visual Studio que pode usar para criar novos aplicativos de área de trabalho empacotados WinUI 3. Essas ferramentas estão incluídas na extensão do SDK de aplicativos Windows para Visual Studio. Para obter instruções de instalação para o SDK de Aplicativo Windows, consulte Ferramentas de instalação para o SDK de Aplicativo Windows.

Windows App SDK 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 de Aplicativo do Windows para Visual Studio para SDK de Aplicativo Windows versão 0.8 ou para projetos em C# com até e incluindo a Visualização 3 do SDK de Aplicativo do Windows 1.0. Portanto, se você estiver usando essas versões, talvez precise instalar explicitamente as ferramentas de empacotamento MSIX de projeto único. Veja as informações abaixo:

Visual Studio 2022 versão 17.1 e posterior: A extensão VSIX das Ferramentas de Empacotamento MSIX para um único projeto no Visual Studio 2022 está incorporada ao Visual Studio 2022 versão 17.1 e posterior.
Visual Studio 2022 antes da versão 17.1: Instale o Single-Project MSIX Packaging Tools for Visual Studio 2022 VSIX extension.

Para confirmar que você tem a extensão instalada, clique em Extensões>Gerenciar extensões>instaladas>todas e verifique se Ferramentas de empacotamento MSIX de projeto único está listado.

Criar um novo projeto

Se estiver a usar o Windows App SDK 1.0 Preview 2 ou posterior, pode criar uma nova aplicação baseada em WinUI 3 que inclua suporte de projeto único MSIX simplesmente usando o modelo Aplicativo em Branco, Empacotado (WinUI 3 no Desktop). Para obter mais informações, consulte 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, em seguida, remover o projeto de empacotamento separado.

Etapa 1: Criar ou abrir um projeto de empacotamento existente

Se já tiveres uma solução para uma aplicação de ambiente de trabalho WinUI 3 (consulta modelos WinUI 3 no Visual Studio) que inclua um Projeto de Empacotagem de Aplicação do Windows (consulta Configurar a tua aplicação de ambiente de trabalho para empacotagem MSIX no Visual Studio), deves abrir essa solução no Visual Studio agora.

Caso contrário, crie uma nova aplicação de ambiente de trabalho WinUI 3 no Visual Studio, utilizando o modelo Aplicação em Branco, empacotada com o Windows Application Packaging Project (WinUI 3 na Área de Trabalho). Sua solução será semelhante à captura de tela abaixo.

Uma solução usando o projeto de embalagem

Etapa 2: Editar as configurações do projeto de 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 da sua aplicação para abrir o arquivo .csproj no editor XML. Adicione o seguinte XML ao elemento principal <PropertyGroup>.

<EnableMsixTooling>true</EnableMsixTooling>
<PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>

Quando terminar, o elemento <PropertyGroup> deverá ser semelhante a isto.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
    <PublishProfile>Properties\PublishProfiles\win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>

Guarde as suas alterações e feche o ficheiro de .csproj.

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

Para 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 para a aplicação e selecione Adicionar>Novo Item....
Selecione Arquivo de texto, nomeie o novo arquivo launchSettings.jsone 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ê é livre para alterar os valores conforme necessário para o seu cenário. O valor de MyApp pode ser qualquer cadeia de caracteres; ele não precisa corresponder ao nome da sua aplicação.

{
    "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 .

No Gerenciador de Soluções , clique com o botão direito do mouse no nó do projeto do seu aplicativo e selecione Descarregar projeto.
Clique com o botão direito do mouse no nó do projeto novamente e selecione Editar .vcxproj de nome do projeto para abrir o arquivo .vcxproj no editor XML.

Faça as seguintes alterações no XML no arquivo .vcxproj :

Adicione <EnableMsixTooling>true</EnableMsixTooling> ao elemento principal <PropertyGroup> .
Altere o valor de <AppxPackage> para true.

Quando terminar, o conteúdo do arquivo .vcxproj deverá ser semelhante a este.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Label="Globals">
    ...
    <MinimumVisualStudioVersion>16.0</MinimumVisualStudioVersion>
    <AppContainerApplication>false</AppContainerApplication>
    <AppxPackage>true</AppxPackage>
    <ApplicationType>Windows Store</ApplicationType>
    <ApplicationTypeRevision>10.0</ApplicationTypeRevision>
    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
    <WindowsTargetPlatformMinVersion>10.0.17763.0</WindowsTargetPlatformMinVersion>
    <UseWinUI>true</UseWinUI>
    <EnableMsixTooling>true</EnableMsixTooling>
  </PropertyGroup>

Salve e feche o arquivo .vcxproj .
No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Recarregar Projeto.

Etapa 3: Mover arquivos para o projeto de aplicativo

Em seguida, mova vários arquivos importantes para o projeto de aplicativo. Existem instruções diferentes, dependendo do seu tipo de projeto.

No Explorador de Arquivos, mova o ficheiro Package.appxmanifest e a pasta Imagens do seu projeto de empacotamento para o seu projeto de aplicação. Coloque esse arquivo e pasta no nível superior da hierarquia de pastas do projeto de aplicativo.
No Visual Studio, no Explorador de Soluções , selecione todas as imagens dentro da pasta Imagens. Na janela Propriedades, configure Ação de Compilação para Conteúdo.
Remova o projeto de empacotamento da sua solução.

principal do aplicativo

Etapa 4: Habilitar a implantação no Configuration Manager

Selecione Compilação>Gestor de Configurações.
No Configuration Manager, clique na opção Desenvolver para cada combinação de configuração e plataforma (por exemplo, Depuração e x86, Depuração e arm64, Release e x64, entre outros).

Observação

Certifique-se de usar as listas pendentes de configuração de solução ativa e plataforma de solução ativa na parte superior, em vez das listas pendentes Configuration e Platform na mesma linha da caixa de seleção Deploy.

Etapa 5: implantar seu aplicativo

Crie e implante seu projeto de aplicativo. Visual Studio irá compilar seu aplicativo em um pacote MSIX, instalar o pacote e, em seguida, executar seu aplicativo.

Etapa 6: empacotar seu aplicativo para publicação

Use o comando Package & Publish no Visual Studio para empacotar seu aplicativo para publicá-lo na Microsoft Store.

Automatize a criação e o empacotamento de seu aplicativo MSIX de projeto único

Você pode usar msbuild para criar e empacotar seu aplicativo MSIX de projeto único, permitindo assim automatizar o fluxo de trabalho. A técnica para uma solução de projeto único e a linha de comando é apenas ligeiramente diferente do que já pode estar a fazer se tiver uma solução de dois projetos — uma que tenha um Projeto de Empacotamento de Aplicativos do Windows (consulte Configurar o seu aplicativo de área de trabalho para empacotamento MSIX no Visual Studio).

A opção de comando build importante para uma solução de projeto único é /p:GenerateAppxPackageOnBuild=true. Sem essa opção, o projeto será construído, mas você não receberá um pacote MSIX. Inclua essa opção e isso 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 suporta a produção de pacotes MSIX (consulte Agrupando pacotes MSIX). Produz apenas um único MSIX. Mas você pode agrupar .msix arquivos em um pacote MSIX usando o MSIX Bundler GitHub Action.

Como uma aplicação de ambiente de trabalho embalada é executada no Windows

Para obter um mergulho mais profundo sobre o que acontece com arquivos e entradas do Registro quando você cria um pacote de aplicativo do Windows para seu aplicativo da área de trabalho, consulte Noções básicas sobre como os aplicativos da área de trabalho empacotados são executados no Windows.

Fornecer comentários

Para nos enviar seus comentários, relatar problemas ou fazer perguntas sobre o recurso MSIX de projeto único, publique uma discussão ou problema no repositório GitHub do SDK de Aplicativo Windows.

Feedback

Esta página foi útil?

Last updated on 2025-07-14