Guia de implantação do SDK do Aplicativo Windows para aplicativos empacotados dependentes da estrutura

  • Artigo

Este artigo fornece diretrizes sobre como implantar aplicativos empacotados dependentes de estrutura (consulte O que é MSIX?) que usam o SDK do Aplicativo Windows. O tópico equivalente para outras opções de empacotamento dependentes de estrutura é SDK do Aplicativo Windows guia de implantação para aplicativos dependentes de estrutura empacotados com local externo ou não empacotados.

Visão geral

Por padrão, quando você cria um projeto usando um dos modelos do WinUI 3 no Visual Studio, seu projeto é configurado para compilar o aplicativo em um pacote MSIX usando MSIX de projeto único (consulte Empacotar seu aplicativo usando MSIX de projeto único) ou um projeto de Empacotamento de Aplicativos do Windows (consulte Configurar seu aplicativo da área de trabalho para empacotamento MSIX no Visual Studio). Em seguida, você pode criar um pacote MSIX para seu aplicativo usando as instruções em Empacotar um aplicativo da área de trabalho ou UWP no Visual Studio. Depois de criar um pacote MSIX para seu aplicativo, você tem várias opções para gerenciar sua implantação MSIX.

Para saber mais sobre os pacotes que seu aplicativo empacotado pode precisar ao usar o SDK do Aplicativo Windows, consulte Arquitetura de implantação para o SDK do Aplicativo Windows. Isso inclui os pacotes Framework, Main e Singleton ; que são todos assinados e publicados pela Microsoft. Há dois requisitos principais para implantar um aplicativo empacotado:

  1. Implante o pacote de estrutura SDK do Aplicativo Windows.
  2. Chame a API de implantação.

Pré-requisitos

Implantar o pacote de estrutura SDK do Aplicativo Windows

O pacote de estrutura SDK do Aplicativo Windows contém os binários SDK do Aplicativo Windows usados em tempo de execução e é instalado com seu aplicativo. A estrutura tem diferentes requisitos de implantação para diferentes canais do SDK do Aplicativo Windows.

Versão estável

Quando você instala uma versão de versão estável (consulte Notas de versão do canal estável) do pacote NuGet SDK do Aplicativo Windows em seu computador de desenvolvimento e cria um projeto usando um dos modelos de projeto WinUI 3 fornecidos, o manifesto do pacote gerado contém um elemento PackageDependency que especifica uma dependência no pacote de estrutura.

No entanto, se você criar o pacote do aplicativo manualmente usando um Projeto de Empacotamento de Aplicativos do Windows separado, deverá declarar um PackageReference em seu Application (package).wapproj arquivo, como o seguinte:

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.0.1">
       <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 prévia

Quando você instala uma versão prévia (consulte Notas de versão do canal de visualização) do pacote NuGet SDK do Aplicativo Windows em seu computador de desenvolvimento, uma versão prévia do pacote de estrutura SDK do Aplicativo Windows é implantada durante o tempo de build como uma dependência do pacote NuGet.

Chamar a API de implantação

Consulte também Inicializar o SDK do Aplicativo Windows.

A API de Implantação é fornecida pelo pacote de estrutura SDK do Aplicativo Windows e está disponível no namespace Microsoft.Windows.ApplicationModel.WindowsAppRuntime . O modelo de aplicativo do Windows não dá suporte à declaração de uma dependência nos pacotes Main e Singleton. A API de implantação é, portanto, necessária por estes 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 Main, que permite atualizações automáticas para o pacote Framework da Microsoft Store.

Para aplicativos empacotados que não são distribuídos por meio da Loja, você, como desenvolvedor, é responsável por distribuir o pacote Framework. Recomendamos que você chame a API de Implantação para que todas as 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).

Importante

No SDK do Aplicativo Windows versão 1.0, somente aplicativos empacotados que são de confiança total ou que têm a funcionalidade restrita packageManagement têm permissão para usar a API de Implantação para instalar as dependências do pacote Main e Singleton. O suporte para aplicativos empacotados de confiança parcial virá em versões posteriores.

Você deve chamar a API de Implantação depois que o processo do aplicativo for inicializado, mas antes que seu aplicativo use SDK do Aplicativo Windows recursos de runtime que usam o pacote Singleton (por exemplo, notificações por push). Os principais métodos da API de Implantação são os métodos estáticos GetStatus e Initialize da classe DeploymentManager .

  • O método GetStatus retorna o status de implantação atual do runtime SDK do Aplicativo Windows que está carregado no momento. Use esse método para identificar se há trabalho necessário para instalar SDK do Aplicativo Windows pacotes de runtime antes que o aplicativo atual possa usar SDK do Aplicativo Windows recursos.
  • O método Initialize verifica se todos os pacotes necessários estão presentes em uma versão mínima necessária para o runtime SDK do Aplicativo Windows que está carregado no momento. Se alguma dependência de pacote estiver ausente, o método tentará registrar esses pacotes ausentes. A partir do SDK do Aplicativo Windows 1.1, o método Initialize também dá suporte à opção de forçar a implantação dos pacotes de runtime SDK do Aplicativo Windows. Isso desliga todos os processos para os pacotes de runtime Main e Singleton e, portanto, interrompe seus serviços (por exemplo, as notificações por push não entregarão notificações durante esse período).

Aplicativo de exemplo da API de implantação

Para obter diretrizes adicionais sobre como usar os métodos GetStatus e Initialize da classe DeploymentManager , explore o aplicativo de exemplo disponível.

Explorar o aplicativo de exemplo da API de implantação

Corrigir erros de instalação

Se a API de Implantação encontrar um erro durante a instalação dos pacotes de runtime SDK do Aplicativo Windows, ela retornará um código de erro que descreve o problema.

Por exemplo, se seu aplicativo não for confiança total ou não tiver a funcionalidade restrita packageManagement , você receberá um código de erro ACCESS_DENIED . Para examinar outros códigos de erro que você pode encontrar e suas possíveis causas, consulte Solução de problemas de empacotamento, implantação e consulta de aplicativos do 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 você encontrar erros que não consegue diagnosticar, registre um problema no repositório GitHub do WindowsAppSDK com o código de erro e os logs de eventos para que possamos investigar o problema.