Criação de pacotes opcionais e conjunto relacionado

  • Artigo

Os pacotes opcionais contêm conteúdo que pode ser integrado com um pacote principal. Eles são úteis para conteúdo para download (DLC), dividindo um aplicativo grande para restrições de tamanho ou para enviar qualquer conteúdo adicional separado do seu aplicativo original. Para obter mais informações sobre pacotes opcionais, consulte Postagem de blog: estender seu aplicativo usando pacotes opcionais.

Os conjuntos relacionados são uma extensão dos pacotes opcionais. Os conjuntos relacionados permitem que você imponha um conjunto estrito de versões em pacotes principais e opcionais. Os conjuntos relacionados podem ter editores diferentes do aplicativo principal se ele for implantado fora da Loja. Para obter mais informações sobre conjuntos relacionados, consulte Postagem de blog: ferramentas para criar um conjunto relacionado.

Pacotes opcionais e conjuntos relacionados são executados dentro do contêiner MSIX do aplicativo principal.

Pré-requisitos

  • Visual Studio 2019 ou Visual Studio 2017 (versão 15.1 ou posterior)
  • Windows 10, versão 1703 ou posterior
  • Windows 10, versão 1703 SDK ou posterior

Para obter todas as ferramentas de desenvolvimento mais recentes, consulte Downloads e ferramentas para o Windows 10.

Observação

Para enviar um aplicativo que usa pacotes opcionais e/ou conjuntos relacionados para a Microsoft Store, você precisará de permissão. Pacotes opcionais e conjuntos relacionados podem ser usados para aplicativos de LOB (Linha de Negócios) ou corporativos sem permissão do Partner Center se não forem enviados à Store. Consulte Suporte ao desenvolvedor do Windows a fim de obter permissão para enviar um aplicativo que usa pacotes opcionais e conjuntos relacionados.

Exemplo de código

Enquanto você estiver lendo este artigo, é recomendável que você acompanhe o exemplo de código de pacote opcional no GitHub para obter uma compreensão prática de como pacotes opcionais e conjuntos relacionados funcionam no Visual Studio.

Pacotes opcionais

Para criar um pacote opcional no Visual Studio, você precisará:

  1. Verifique se a Versão Mínima da Plataforma de Destino do seu aplicativo está definida como: 10.0.15063.0 ou superior.
  2. No projeto do pacote principal, abra o Package.appxmanifest arquivo. Navegue até a guia "Embalagem" e anote o nome da família do seu pacote, que é tudo antes do caractere "_".
  3. No seu projeto de pacote opcional, clique com o botão direito do Package.appxmanifest mouse e selecione Abrir com > o Editor de XML (Texto).
  4. Localize o elemento <Dependencies> no arquivo. Adicione o seguinte e substitua [MainPackageDependency] pelo nome da família do pacote na Etapa 2. Isso especificará que seu pacote opcional depende do pacoteprincipal. 
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>

Observação

Se você quiser criar um pacote opcional de um editor diferente, será necessário especificar o editor do aplicativo principal se eles forem diferentes. Como assim <uap4:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Isso não funcionará se você estiver publicando na Loja.

Depois de configurar as dependências do pacote das etapas 1 a 4, você poderá continuar desenvolvendo normalmente. Para obter mais informações, consulte Postagem de blog: Criar seu primeiro pacote opcional.

O Visual Studio pode ser configurado para reimplantar seu pacote principal sempre que você implantar um pacote opcional. Para definir a dependência de compilação no Visual Studio, você deve:

  1. Clique com o botão direito do mouse no projeto de pacote opcional e selecione Construir dependências > do projeto...
  2. Verifique o projeto do pacote principal e selecione "OK".

Agora, sempre que você inserir F5 ou criar um projeto de pacote opcional, o Visual Studio criará o projeto de pacote principal primeiro. Isso garantirá que seu projeto principal e projetos opcionais estejam em sincronia.

Um conjunto relacionado consiste em um pacote principal e um pacote opcional que são fortemente acoplados por meio de metadados especificados no arquivo .appxbundle ou .msixbundle do pacote principal. Esses metadados vinculam o pacote principal ao pacote opcional (usando o nome do arquivo .appxbundle + versão) e o pacote opcional ao pacote principal (usando o nome independente da versão). Visual Studio ajuda você a obter os metadados corretos em seus arquivos.

O controle de versão de pacotes em um conjunto relacionado é sincronizado de uma forma que não permitirá que a versão mais recente de qualquer pacote seja usada até que todos os pacotes de conjunto relacionados (especificados por versão no pacote principal) sejam instalados. Os pacotes são atendidos de forma independente, mas os pacotes especificados no conjunto não podem ser usados até que todos eles tenham sido atualizados. Para obter mais informações sobre conjuntos relacionados, consulte Postagem de blog: ferramentas para criar um conjunto relacionado.

Para configurar a solução do aplicativo para conjuntos relacionados, use as seguintes etapas:

  1. Clique com o botão direito do mouse no projeto do pacote principal, selecione Adicionar > Novo Item...
  2. Na janela, procure ".txt" nos Modelos Instalados e adicione um novo arquivo de texto.

    Importante

    O novo arquivo de texto deve ser nomeado: Bundle.Mapping.txt.

  3. No arquivo, insira a Bundle.Mapping.txt cadeia de caracteres "[OptionalProjects]" seguida pelos caminhos relativos para seus projetos de pacote opcionais. Aqui está um arquivo de exemplo Bundle.Mapping.txt : 
    [OptionalProjects]
"..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
"..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"

Quando sua solução é configurada dessa maneira, o Visual Studio criará um manifesto de pacote chamado AppxBundleManifest.xml para o pacote principal com todos os metadados necessários para conjuntos relacionados.

Observe que, como pacotes opcionais, um Bundle.Mapping.txt arquivo para conjuntos relacionados só funcionará no Windows 10, versão 1703 ou superior. Além disso, a versão mínima da plataforma de destino do seu aplicativo deve ser definida como 10.0.15063.0 ou superior.

Removendo pacotes opcionais

Os usuários podem acessar o aplicativo Configurações e remover os pacotes opcionais. Da mesma forma, os desenvolvedores podem usar o RemoveOptionalPackageAsync para remover uma lista de pacotes opcionais.

PackageCatalog catalog = PackageCatalog.OpenForCurrentPackage();
List<string> optionalList = new List<string>();
optionalList.Add("FabrikamAgeAnalysis_kwpnjs8c36mz0");
    
// Warn user that application will be restarted. 
var result = await catalog.RemoveOptionalPackagesAsync(optionalList);
if (result.ExtendedError != null)
{
    throw removalResult.ExtendedError;
}

Observação

No caso de um conjunto relacionado, a plataforma precisará reiniciar o aplicativo principal para finalizar a remoção para evitar situações em que o aplicativo tenha conteúdo carregado do pacote que está sendo removido. Os aplicativos devem notificar os usuários de que o aplicativo precisará ser reiniciado antes que o aplicativo chame a API.

Se o pacote opcional for conteúdo somente então, o desenvolvedor deve dizer explicitamente à plataforma que o pacote que está prestes a remover não está em uso pelo aplicativo antes que o desenvolvedor remova o pacote opcional. Isso também permite que o desenvolvedor remova o pacote sem uma reinicialização.

Problemas conhecidos

A depuração de um projeto opcional de conjunto relacionado não tem suporte no momento no Visual Studio. Para contornar esse problema, você pode implantar e iniciar a ativação (Ctrl + F5) e anexar manualmente o depurador a um processo. Para anexar o depurador, vá ao menu "Depurar" no Visual Studio, selecione "Anexar ao processo..." e anexe o depurador ao processo principal do aplicativo.