Distribuir uma aplicação WinUI 3 não embalada

A distribuição não empacotada permite-lhe lançar uma aplicação WinUI 3 sem MSIX — útil para cenários empresariais onde a implementação MSIX não está disponível, ou para programadores que preferem uma instalação tradicional baseada em pastas.

Importante

Reveja estas limitações antes de começar. As aplicações WinUI 3 não empacotadas têm restrições que afetam a sua estratégia de distribuição:

  • EXE de ficheiro único — Suporte PublishSingleFile a aplicações WinUI 3 não embaladas e autónomas (SDK de Aplicações Windows 1.5 e posteriores). Isto produz um único EXE distribuível; as dependências são extraídas para um diretório temporário no primeiro lançamento. São necessárias propriedades específicas do MSBuild — ver Single-file EXE abaixo. Aplicações dependentes do framework e aplicações empacotadas não suportam PublishSingleFile.
  • Dependência de tempo de execução — O tempo de execução do SDK de Aplicações Windows deve estar presente na máquina do utilizador. Deve incluir o instalador de runtime com a sua aplicação ou usar uma implementação autónoma (que aumenta significativamente o tamanho do output). Veja Deploying the SDK de Aplicações Windows runtime abaixo.
  • Sem identidade de pacote — Sem um manifesto de pacote, a sua aplicação não pode usar funcionalidades de Windows baseadas em manifestos: não há atualizações automáticas via App Installer ou Loja, não há registo de tarefas em segundo plano, nem associações de tipos de ficheiro ou personalização de tiles do menu Iniciar via manifesto de pacote. (Mecanismos tradicionais do Win32, como entradas de registo escritas pelo instalador e atalhos, ainda funcionam.)
  • Nenhuma submissão de identidade de pacote MSIX/para a Loja — Este modelo de distribuição não tem identidade de pacote; não é elegível como submissão MSIX para a Microsoft Store. (Pode submeter um instalador tradicional à Store através do caminho de submissão do instalador MSI ou EXE, mas esse é um fluxo de trabalho separado do que este artigo descreve.)

Se estas restrições forem uma preocupação, considere empacotar a sua aplicação (recomendada para a maioria das aplicações) ou empacotar com localização externa para adicionar identidade de pacote sem uma conversão completa em MSIX.

Para obter detalhes sobre todas as opções de empacotamento, consulte Descrição geral sobre como empacotar e implementar aplicações do Windows.

Se optar por desempacotar uma aplicação WinUI nova ou existente, siga estes passos:

No seu .csproj ficheiro, encontre o primeiro elemento PropertyGroup existente, que também contém OutputType, TargetFramework, e outras propriedades.

  • Adicione a propriedade WindowsPackageType projeto 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 a aplicação a partir de Visual Studio (seja Debugging ou Without Debugging), selecione o perfil de lançamento Unpackaged no menu suspenso Start. Se o perfil Package estiver selecionado, então verá um erro de implementação em Visual Studio. Este passo não é necessário se iniciar a aplicação (.exe) a partir da linha de comandos ou Windows Explorador de Ficheiros.

Visual Studio - Menu suspenso inicial com perfil de lançamento da aplicação C# não empacotado destacado

A API Bootstrapper

Definir a propriedade de projeto <WindowsPackageType>None</WindowsPackageType> faz com que o autoinicializador localize e carregue uma versão do SDK de Aplicações Windows mais adequada para a sua aplicação.

Se tiver necessidades avançadas (como gestão personalizada de erros ou carregar uma versão específica do SDK de Aplicações Windows), então pode chamar explicitamente a API do bootstrapper. Para obter mais informações, consulte Use o runtime do SDK de Aplicações Windows para aplicações empacotadas com localização externa ou não empacotadas, e Tutorial: Use a API de bootstrapper numa aplicação empacotada com localização externa ou não empacotada que usa o SDK de Aplicações Windows.

Para mais informações sobre o bootstrapper, consulte Arquitetura de implementação e visão geral para aplicações dependentes do framework.

Implementação do runtime do SDK de Aplicações Windows

As aplicações WinUI 3 não embaladas dependem do tempo de execução do SDK de Aplicações Windows estar instalado na máquina do utilizador. Tem duas opções para garantir que o tempo de execução está presente:

Opção 1: instalador de tempo de execução SDK de Aplicações Windows (.exe) (recomendado)

Inclua o instalador de runtime do SDK de Aplicações Windows ao lado da sua aplicação. O instalador em tempo de execução é um .exe redistribuível que instala os pacotes de SDK de Aplicações Windows de execução necessários. Descarrega-o da página de lançamentos SDK de Aplicações Windows e inclua-o com o teu próprio instalador ou script de configuração. Para orientações completas, veja Use o tempo de execução SDK de Aplicações Windows para aplicações empacotadas com localização externa ou não empacotadas.

Os utilizadores devem executar o instalador do runtime uma única vez. As atualizações subsequentes da aplicação não requerem a reinstalação do runtime, a menos que a versão necessária do SDK de Aplicações Windows mude.

Opção 2: Implantação autónoma

Define <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained> no ficheiro do teu projeto para agrupar o runtime SDK de Aplicações Windows diretamente na pasta de saída da tua app. Isto elimina a dependência do tempo de execução — os utilizadores não precisam de instalar nada separadamente.

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

A contrapartida: a tua pasta de saída é significativamente maior (o tempo de execução completo está incluído), e cada atualização da aplicação transporta toda a carga útil do tempo de execução. Use esta opção para cenários simples de distribuição ou quando não pode controlar o que está instalado na máquina alvo.

→ Implante aplicações não empacotadas que usem o SDK de Aplicações Windows para a referência completa de implementação em tempo de execução.

EXE em ficheiro único

A partir do SDK de Aplicações Windows 1.5, as aplicações WinUI 3 não embaladas e autónomas suportam o modelo de implementação .NETPublishSingleFile. Isto produz um único ficheiro EXE distribuível — todas as dependências são agrupadas no EXE e extraídas para um diretório temporário no primeiro lançamento.

Importante

PublishSingleFile não é suportado para aplicações empacotadas (MSIX ou empacotadas com localização externa) nem para aplicações dependentes do framework. Ambas as condições — não embaladas e autónomas — são necessárias.

Propriedades obrigatórias do MSBuild

O SDK de Aplicações 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>

A build emite erros se EnableMsixTooling, WindowsPackageType=None, ou IncludeAllContentForSelfExtract estiverem em falta, e avisos se WindowsAppSDKSelfContained ou SelfContained estiverem ausentes.

Note

Comportamento de extração:IncludeAllContentForSelfExtract=true significa que as dependências são extraídas para um diretório temporário na máquina do utilizador no primeiro lançamento — a aplicação não é um binário de extração zero. O EXE único é conveniente de distribuir, mas os ficheiros extraídos devem estar presentes para serem executados. O WindowsAppSdkUndockedRegFreeWinRTInitialize inicializador automático trata da localização do tempo de execução extraído; se optar por não o usar, deve definir a MICROSOFT_WINDOWSAPPRUNTIME_BASE_DIRECTORY variável ambiente para AppContext.BaseDirectory antes da entrada do programa.

Alternativas se a extração em ficheiro único não for aceitável

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

  • Use o pacote MSIX — os utilizadores têm uma experiência de instalador único (o App Installer trata de todos os ficheiros), e obtêm elegibilidade para a Loja, identidade do pacote e atualizações integradas
  • Use um instalador tradicional (WiX, Inno Setup) — envolva a pasta de saída num único instalador EXE que extraia e instale todos os ficheiros necessários de forma transparente
  • Use um framework diferente — as aplicações WPF e WinForms suportam PublishSingleFile um conjunto mais amplo de configurações

Considerações de distribuição para aplicações não embaladas

As aplicações WinUI 3 não integradas não têm identidade de pacote, o que significa que não podem aceder a certas funcionalidades do Windows:

  • Sem atualização automática via App Installer ou Windows Store
  • Sem registo de tarefas em segundo plano via manifesto de pacote
  • Sem associações de tipos de ficheiro ou manipuladores de protocolo via manifesto de pacote
  • Sem personalização de blocos do menu Iniciar através de manifesto de pacote

Se precisar destas funcionalidades, considere o empacotamento com localização externa como um caminho intermédio que adiciona identidade ao pacote sem exigir conversão completa em MSIX.

→ Publique a sua primeira Windows app para uma visão geral completa das opções de distribuição para o WinUI 3 e outros frameworks de Windows app.

  • Last updated on