Guia de implementação do Windows App SDK 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 Windows App SDK. O tópico equivalente para outras opções de empacotamento dependentes do framework é Windows App SDK guia de implementação para aplicações dependentes do framework com localização externa ou não empacotadas.

Overview

Por defeito, quando cria um projeto usando um dos modelos WinUI 3 em Visual Studio, o seu projeto está configurado para compilar a aplicação num pacote MSIX utilizando o MSIX de projeto único (ver Empacote a sua aplicação com MSIX de projeto único) ou um projeto de Empacotamento de Aplicações Windows (ver Configure a sua aplicação desktop 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 Windows App SDK, consulte Deployment architecture para o Windows App SDK. 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 Windows App SDK.
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 Windows App SDK

O pacote de framework do Windows App SDK contém os binários do Windows App SDK 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 Windows App SDK.

Versão estável

Quando instala uma versão estável do pacote NuGet Windows App SDK 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 Windows App SDK no seu computador de desenvolvimento, uma versão pré-visualizada do pacote framework do Windows App SDK é implementada durante a compilação como uma dependência do pacote NuGet.

Chamar a API de implantação

Veja também Inicialize o Windows App SDK.

A API de Implementação é fornecida pelo pacote framework Windows App SDK 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 Windows App SDK 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 Windows App SDK runtime que está atualmente carregado. Use este método para identificar se é necessário trabalho para instalar pacotes de runtime do Windows App SDK antes de a aplicação atual poder usar as funcionalidades do Windows App SDK.
• 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 Windows App SDK atualmente carregado. Se alguma dependência de pacote estiver faltando, o método tentará registrar esses pacotes ausentes. A partir de Windows App SDK 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 Windows App SDK. 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 Windows App SDK, devolve um código de erro que descreve o problema.

Por exemplo, se a sua aplicação não for totalmente confiável, ou não tiver a capacidade restrita packageManagement , então receberá um código de erro ACCESS_DENIED . Para rever outros códigos de erro que possa encontrar e as suas possíveis causas, consulte Resolução de problemas de empacotamento, implementação e consulta de aplicações Windows.

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

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 Windows App SDK
• Guia de Implementação do Windows App SDK 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