Guia de Implantação do SDK do Aplicativo Windows para Aplicativos Empacotados Dependentes de Framework

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

Overview

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

Para saber mais sobre os pacotes de que seu aplicativo empacotado pode precisar ao utilizar o SDK do Aplicativo Windows, consulte Arquitetura de implantação do SDK do Aplicativo Windows. Eles incluem 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 framework do SDK do Aplicativo Windows.
2. Chamar a API de implantação.

Prerequisites

• Para aplicativos empacotados, é necessário ter o pacote da estrutura VCLibs como requisito. Para obter mais informações, consulte pacotes de estrutura de tempo de execução do C++ para a Ponte Desktop.
• C#. .NET 6 ou posterior é necessário. Para obter mais informações, consulte .NET Downloads.

Implantar o pacote de estrutura de SDK do Aplicativo Windows

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

Versão estável

Quando você instala uma versão estável do pacote NuGet SDK do Aplicativo Windows no computador de desenvolvimento e cria um projeto com um dos modelos de projeto WinUI 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 seu pacote de aplicativos manualmente usando um projeto de empacotamento de aplicativos Windows separado, deverá declarar um PackageReference no arquivo Application (package).wapproj, como o seguinte:

<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 é implantado em outro computador.

Versão de visualização

Quando você instala uma versão prévia do pacote NuGet do SDK do Aplicativo Windows no computador de desenvolvimento, uma versão prévia do pacote de estrutura do SDK do Aplicativo Windows é implantada durante a compilação como uma dependência do pacote NuGet.

Chamar a API de Implantação

Consulte também Initializar o SDK do Aplicativo Windows.

A API de Implantação é fornecida pelo pacote da estrutura SDK do Aplicativo Windows e está disponível no Microsoft.Windows. ApplicationModel.WindowsAppRuntime namespace. O modelo de aplicativo Windows não dá suporte à declaração de uma dependência nos pacotes Main e Singleton. Portanto, a API de Implantação é necessária para 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 Principal, que permite atualizações automáticas para o pacote Framework na 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 do Framework. Recomendamos que você chame a API de Implantação para que todas as atualizações de manutenção críticas 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).

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

• O método GetStatus retorna o status de implantação atual do runtime SDK do Aplicativo Windows carregado no momento. Use este método para identificar se há necessidade de trabalho para instalar os pacotes de runtime do SDK do Aplicativo Windows antes que o aplicativo atual possa usar os recursos do SDK do Aplicativo Windows.
• 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 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 fornecerão notificações durante esse tempo). Você deve chamar Inicializar apenas uma vez. Você não precisa chamar Initialize para aplicativos implantados por meio dos comandos Start Without Debugging e Start Debugging no Visual Studio.

App de exemplo de API de implantação

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

Solucionar erros de instalação

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

A tabela a seguir lista códigos de erro comuns da API de Implantação e 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 logs de eventos estão localizados em Visualizador de Eventos em Logs de Aplicativos e Serviços>Microsoft>Windows>AppxDeployment-Server.

Se você encontrar erros que não pode diagnosticar, registre um problema no WindowsAppSDK GitHub repositório com o código de erro e os logs de eventos para que possamos investigar o problema.

Tópicos relacionados

• arquitetura de implantação para o SDK do Aplicativo Windows
• Guia de implantação do SDK do Aplicativo Windows para apps dependentes de framework empacotados com local externo ou desempacotados
• Canais de lançamento
• Empacotar seu aplicativo usando projeto único MSIX
• O que é MSIX?
• Solução de problemas no empacotamento, implantação e consulta de aplicativos Windows
• Empacote um aplicativo da área de trabalho ou UWP no Visual Studio
• Gerencie sua implantação de MSIX