Guia de implementação do SDK de Aplicações Windows para aplicações empacotadas dependentes do framework

Este artigo fornece orientações sobre a implementação de aplicações empacotadas dependentes do framework (ver O que é MSIX?) que utilizam o SDK de Aplicações Windows. O tópico equivalente para outras opções de empacotamento dependentes do framework é SDK de Aplicações Windows guia de implementação para aplicações dependentes do framework com localização externa ou não empacotadas.

Overview

Por predefinição, quando cria um projeto com um dos modelos WinUI 3 no Visual Studio, o seu projeto é configurado para compilar a aplicação para um pacote MSIX, utilizando o MSIX de projeto único (consulte Empacotar a sua aplicação utilizando o MSIX de projeto único) ou um projeto de empacotamento de aplicações do Windows (consulte Configurar a sua aplicação de ambiente de trabalho para empacotamento MSIX no Visual Studio). Pode então construir um pacote MSIX para a sua aplicação usando as instruções em Package uma aplicação desktop ou UWP em Visual Studio. Depois de criar um pacote MSIX para seu aplicativo, você tem várias opções para Gerenciar sua implantação do MSIX.

Para saber mais sobre os pacotes que a sua aplicação empacotada pode precisar ao usar o SDK de Aplicações Windows, consulte Deployment architecture para o SDK de Aplicações Windows. Estes incluem os pacotes Framework, Main e Singleton ; todas assinadas e publicadas pela Microsoft. Há dois requisitos principais para implantar um aplicativo empacotado:

1. Implementar o pacote framework SDK de Aplicações Windows.
2. Chame a API de implantação.

Prerequisites

• Para aplicações empacotadas, a dependência no pacote de estrutura VCLibs é obrigatória. Para obter mais informações, consulte pacotes de framework Runtime C++ para Desktop Bridge.
• C#. .NET 6 ou posterior é obrigatório. Para mais informações, consulte .NET Downloads.

Implementar o pacote framework do SDK de Aplicações Windows

O pacote de framework do SDK de Aplicações Windows contém os binários do SDK de Aplicações Windows usados em tempo de execução e é instalado com a sua aplicação. A framework tem requisitos de implementação diferentes para diferentes canais do SDK de Aplicações Windows.

Versão estável

Quando instala uma versão estável do pacote NuGet SDK de Aplicações Windows no seu computador de desenvolvimento, e cria um projeto usando um dos modelos de projeto WinUI fornecidos, o manifesto do pacote gerado contém um elemento PackageDependency que especifica uma dependência no pacote framework.

No entanto, se construir manualmente o seu pacote de aplicação usando um Windows Application Packaging Project separado, então deve declarar um PackageReference no seu ficheiro Application (package).wapproj, como segue:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

Essa dependência de pacote garante que o pacote Framework seja instalado quando seu aplicativo for implantado em outro computador.

Versão de pré-visualização

Quando instala uma versão de pré-visualização do pacote NuGet do SDK de Aplicações Windows no seu computador de desenvolvimento, uma versão pré-visualizada do pacote framework do SDK de Aplicações Windows é implementada durante a compilação como uma dependência do pacote NuGet.

Chamar a API de implantação

Veja também Inicialize o SDK de Aplicações Windows.

A API de Implementação é fornecida pelo pacote framework SDK de Aplicações Windows e está disponível no Microsoft.Windows. ApplicationModel.WindowsAppRuntime namespace. O modelo de aplicação Windows não suporta declarar uma dependência dos pacotes Main e Singleton. A API de implantação é, portanto, necessária pelos seguintes motivos:

1. Para implantar o pacote Singleton para recursos que não estão no pacote Framework (por exemplo, notificações por push).
2. Para implantar o pacote Principal, que permite atualizações automáticas para o pacote Framework a partir da Microsoft Store.

Para aplicações empacotadas que não são distribuídas através da Loja, você, enquanto programador, é responsável por distribuir o pacote Framework. Recomendamos que ligue para a API de Implementação para que quaisquer atualizações críticas de manutenção sejam entregues. Observe que, para usar recursos fora do pacote Framework (por exemplo, notificações por push), o pacote Singleton deve ser implantado (isso pode ser feito com a API de implantação ou redistribuindo os pacotes MSIX usando seu próprio método de instalação).

Deve ligar para a API de Implementação depois de o processo da sua aplicação ser inicializado, mas antes de a sua aplicação usar funcionalidades de runtime do SDK de Aplicações Windows que utilizam o pacote Singleton (por exemplo, notificações push). Os principais métodos da API de Deployment são os métodos estáticos GetStatus e Initialize da classe DeploymentManager .

• O método GetStatus devolve o estado atual de implementação do SDK de Aplicações Windows runtime que está atualmente carregado. Use este método para identificar se é necessário trabalho para instalar pacotes de runtime do SDK de Aplicações Windows antes de a aplicação atual poder usar as funcionalidades do SDK de Aplicações Windows.
• O método Initialize verifica se todos os pacotes necessários estão presentes para uma versão mínima exigida pelo tempo de execução SDK de Aplicações Windows atualmente carregado. Se alguma dependência de pacote estiver faltando, o método tentará registrar esses pacotes ausentes. A partir de SDK de Aplicações Windows 1.1, o método Initialize também suporta a opção de forçar a implantação dos pacotes de tempo de execução do SDK de Aplicações Windows. Isso encerra quaisquer processos para os pacotes de execução Main e Singleton, pelo que interrompe os seus serviços (por exemplo, notificações push não serão entregues durante esse tempo). Deve chamar Initialize apenas uma vez. Não precisa de chamar Initialize para aplicações implementadas através dos comandos Start Without Debugging e Start Debuggging em Visual Studio.

Aplicativo de exemplo da API de implantação

Para orientações adicionais sobre como usar os métodos GetStatus e Initialize da classe DeploymentManager , explore a aplicação de exemplo disponível.

Corrigir erros de instalação

Se a API de Implementação encontrar um erro durante a instalação dos pacotes de runtime do SDK de Aplicações Windows, devolve um código de erro que descreve o problema.

A tabela seguinte lista os códigos de erro comuns da API de Implementação e as suas causas típicas:

Se o código de erro não fornecer informações suficientes, você poderá encontrar mais informações de diagnóstico nos logs de eventos detalhados (consulte Obter informações de diagnóstico). Os registos de eventos localizam-se no Visualizador de Eventos em Registos de Aplicações e Serviços>Microsoft>Windows>AppxDeployment-Server.

Se encontrar erros que não consiga diagnosticar, então arquive um problema no WindowsAppSDK GitHub repositório com o código de erro e os registos de eventos para que possamos investigar o problema.

Tópicos relacionados

• Arquitetura de implementação para o SDK de Aplicações Windows
• Guia de Implementação do SDK de Aplicações Windows para Apps Dependentes de Framework, Empacotadas com Localização Externa ou Não Empacotadas
• Canais de lançamento
• Embalar o seu aplicativo usando MSIX num único projeto
• O que é o MSIX?
• Solução de problemas de empacotamento, implantação e consulta de aplicativos do Windows
• Empacotar uma aplicação desktop ou UWP no Visual Studio
• Gerencie a sua implantação do MSIX