Distribuir um aplicativo WinUI 3 não empacotado

A distribuição não empacotada permite que você envie um aplicativo WinUI 3 sem MSIX — útil para cenários empresariais em que a implantação do MSIX não está disponível ou para desenvolvedores que preferem uma instalação tradicional baseada em pastas.

Importante

Examine essas limitações antes de começar. Aplicativos WinUI 3 não empacotados têm restrições que afetam sua estratégia de distribuição:

  • EXE de arquivo único — suporte PublishSingleFile a aplicativos WinUI 3 não empacotados e independentes (SDK do Aplicativo Windows 1,5 e posterior). Isso produz um único EXE distribuível; as dependências são extraídas para um diretório temporário na primeira inicialização. Propriedades específicas do MSBuild são necessárias – consulte o EXE de arquivo único abaixo. Aplicativos dependentes de estrutura e aplicativos empacotados não dão suporte a PublishSingleFile.
  • Dependência de tempo de execução — o runtime do SDK do Aplicativo Windows deve estar presente no computador do usuário. Você deve agrupar o instalador de runtime com seu aplicativo ou usar a implantação autocontida (o que aumenta significativamente o tamanho da saída). Consulte Implantação do tempo de execução do SDK do Aplicativo Windows abaixo.
  • No identidade do pacote — Sem um manifesto do pacote, seu aplicativo não pode usar recursos de Windows baseados em manifesto: nenhuma atualização automática por meio do Instalador de Aplicativo ou da Loja, nenhum registro de tarefa em segundo plano e nenhuma associação de tipo de arquivo ou personalização do bloco de menu Iniciar por meio do manifesto do pacote. (Mecanismos tradicionais do Win32, como entradas e atalhos de registro escritos pelo instalador, ainda funcionam.)
  • No MSIX/package-identity Store submissão — este modelo de distribuição não tem nenhuma identidade de pacote; ele não é qualificado para envio MSIX para a Microsoft Store. (Você pode enviar um instalador tradicional para a Loja por meio do caminho de envio do instalador MSI ou EXE, mas esse é um fluxo de trabalho separado do que este artigo descreve.)

Se essas restrições forem uma preocupação, considere empacotar seu aplicativo (recomendado para a maioria dos aplicativos) ou empacotar com localização externa para adicionar a identidade do pacote sem uma conversão MSIX completa.

Para obter detalhes sobre todas as opções de empacotamento, consulte Visão geral do empacotamento e da implantação de aplicativos do Windows.

Se você optar por desempacotar um aplicativo WinUI novo ou existente, siga estas etapas:

Em seu .csproj arquivo, localize o primeiro elemento PropertyGroup existente, que também contém OutputType, TargetFrameworke outras propriedades.

  • Adicione a propriedade do projeto WindowsPackageType a este elemento PropertyGroup. Defina seu valor como None.
<Project ...>
  ...
  <PropertyGroup>
    <WindowsPackageType>None</WindowsPackageType><!-- add this -->
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    ...
  </PropertyGroup> 
  ...
</Project>

Para iniciar o aplicativo Visual Studio (Debugging ou Without Debugging), selecione o perfil de inicialização Unpackaged na lista suspensa Start. Se o perfil Package estiver selecionado, você verá um erro de implantação no Visual Studio. Essa etapa não será necessária se você iniciar o aplicativo (.exe) na linha de comando ou no Explorador de Arquivos Windows.

Visual Studio – inicie a lista suspensa com o perfil de inicialização não empacotado do aplicativo C# realçado

"A API do 'bootstrapper'"

Definir a propriedade de projeto <WindowsPackageType>None</WindowsPackageType> faz com que o auto-initializer localize e carregue uma versão do SDK do Aplicativo Windows mais apropriada para seu aplicativo.

Se você tiver necessidades avançadas (como tratamento de erros personalizados ou carregar uma versão específica do SDK do Aplicativo Windows), poderá chamar explicitamente a API bootstrapper. Para obter mais informações, consulte Use o tempo de execução do SDK do Aplicativo Windows para aplicativos que estão empacotados com local externo ou não empacotados e Tutorial: use a API bootstrapper em um aplicativo que está empacotado com local externo ou não empacotado e que utiliza o SDK do Aplicativo Windows.

Para obter mais informações sobre o bootstrapper, consulte a arquitetura de implantação e a visão geral dos aplicativos dependentes da estrutura.

Implantando o runtime do SDK do Aplicativo Windows

Os aplicativos WinUI 3 não empacotados dependem do SDK do Aplicativo Windows runtime que está sendo instalado no computador do usuário. Você tem duas opções para garantir que o tempo de execução (runtime) esteja presente:

Option 1: SDK do Aplicativo Windows instalador de runtime (.exe) (recomendado)

Inclua o instalador do runtime do SDK do Aplicativo Windows junto com o seu aplicativo. O instalador de runtime é um .exe redistribuível que instala os pacotes de runtime SDK do Aplicativo Windows necessários. Baixe-o na página de versões do SDK do Aplicativo Windows e agrupe-o com seu próprio instalador e script de instalação. Para obter orientação completa, consulte Utilize o runtime do SDK do Aplicativo Windows para aplicativos empacotados com local externo ou não empacotados.

Os usuários devem executar o instalador de runtime uma vez. As atualizações subsequentes do aplicativo não exigem a reinstalação do tempo de execução, a menos que a versão necessária do SDK do Aplicativo Windows mude.

Opção 2: implantação autossuficiente

Defina <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> no arquivo de projeto para agrupar o runtime SDK do Aplicativo Windows diretamente na pasta de saída do aplicativo. Isso remove a dependência de runtime – os usuários não precisam instalar nada separadamente.

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

A compensação: sua pasta de saída é significativamente maior (o runtime completo está incluído) e cada atualização de aplicativo carrega o conteúdo de tempo de execução completo. Use essa opção para cenários de distribuição simples ou quando não é possível controlar o que está instalado no computador de destino.

Implante aplicativos não empacotados que usam o SDK do Aplicativo Windows para a referência completa de implantação do tempo de execução.

EXE em arquivo único

A partir do SDK do Aplicativo Windows 1.5, aplicativos WinUI 3 não empacotados e independentes dão suporte ao modelo de implantação .NETPublishSingleFile. Isso produz um único arquivo EXE distribuível – todas as dependências são agrupadas no EXE e extraídas para um diretório temporário no início.

Importante

PublishSingleFile não é compatível com aplicativos empacotados (MSIX ou empacotados com local externo) nem com aplicativos dependentes de framework. Ambas as condições — sem empacotamento e autocontidas — são necessárias.

Propriedades necessárias do MSBuild

O SDK do Aplicativo Windows inclui um destino de validação em tempo de compilação (WindowsAppSDKSingleFileVerifyConfiguration) que verifica a configuração do seu projeto quando PublishSingleFile estiver definido. As seguintes propriedades são necessárias:

<PropertyGroup>
  <WindowsPackageType>None</WindowsPackageType>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
  <SelfContained>true</SelfContained>
  <EnableMsixTooling>true</EnableMsixTooling>
  <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
  <PublishSingleFile>true</PublishSingleFile>
</PropertyGroup>

O build emitirá erros se EnableMsixTooling, WindowsPackageType=Noneou IncludeAllContentForSelfExtract estiverem ausentes, e avisos se WindowsAppSDKSelfContained estiverem ausentes ou SelfContained ausentes.

Note

Comportamento de extração:IncludeAllContentForSelfExtract=true significa que as dependências são extraídas para um diretório temporário no computador do usuário no início – o aplicativo não é um binário de extração zero. O EXE único é conveniente de distribuir, mas os arquivos extraídos devem estar presentes para serem executados. O auto-inicializador WindowsAppSdkUndockedRegFreeWinRTInitialize é responsável por localizar o runtime extraído; se você optar por não usá-lo, deverá definir a variável de ambiente MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY como AppContext.BaseDirectory antes do início do programa.

Alternativas se a extração de arquivo único não for aceitável

Se você precisar de um binário único de extração zero ou se o comportamento de extração não for aceitável em seu ambiente de implantação, considere:

  • Use o MSIX para empacotamento – os usuários obtêm uma única experiência de instalador (o Instalador de Aplicativo manipula todos os arquivos) e você obtém elegibilidade para a Loja, a identidade do pacote e atualizações integradas
  • Usar um instalador tradicional (WiX, Instalação Inno) – encapsular a pasta de saída em um único instalador EXE que extrai e instala todos os arquivos necessários de forma transparente
  • Use um framework diferente — os aplicativos WPF e WinForms oferecem suporte a PublishSingleFile com um conjunto mais amplo de configurações

Considerações de distribuição para aplicativos não empacotados

Os aplicativos WinUI 3 não empacotados não têm identidade de pacote, o que significa que eles não podem acessar determinados recursos de Windows:

  • Nenhuma atualização automática por meio do Instalador de Aplicativos ou da Windows Store
  • Sem registro de tarefa em segundo plano no manifesto do pacote
  • Nenhuma associação de tipo de arquivo ou manipuladores de protocolo no manifesto do pacote
  • Sem personalização do bloco do menu Iniciar por meio do manifesto do pacote

Se você precisar desses recursos, considere o empacotamento com localização externa como um caminho intermediário que adiciona a identidade do pacote sem a necessidade de conversão completa do MSIX.

→ Publish seu primeiro aplicativo Windows para obter uma visão geral completa das opções de distribuição para o WinUI 3 e outras estruturas de aplicativos Windows.

  • Last updated on