Criação de pacotes opcionais e conjunto relacionado

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

Conjuntos relacionados são uma extensão de pacotes opcionais. Conjuntos relacionados permitem impor um conjunto estrito de versões entre pacotes principais e opcionais. Os conjuntos relacionados poderão ter publicores diferentes do aplicativo principal se ele for implantado fora da Store. Para obter mais informações sobre conjuntos relacionados, consulte Postagem no 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 Windows 10.

Observação

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

Exemplo de código

Enquanto você está lendo este artigo, recomenda-se que você acompanhe o exemplo de código do pacote opcional no GitHub para obter um conhecimento prático de como os pacotes opcionais e conjuntos relacionados funcionam no Visual Studio.

Pacotes opcionais

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

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

Observação

Se você quiser criar um pacote opcional de um publicador diferente, precisará especificar o editor do aplicativo principal se eles são diferentes. Assim como <uap4:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Isso não funcionará se você estiver publicando na Store.

Depois de configurar suas dependências de pacote das Etapas 1 a 4, você pode continuar desenvolvendo como faria normalmente. Para obter mais informações, consulte Postagem no blog: Criar seu primeiro pacote opcional.

O Visual Studio pode ser configurado para implementar novamente 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 no projeto de pacote opcional e selecione Dependências da compilação > Dependências do projeto...
  2. Verifique se o projeto do pacote principal e selecione "OK".

Agora, toda vez que você pressionar F5 ou criar um projeto de pacote opcional, o Visual Studio irá construir o projeto do pacote principal primeiro. Isso garante 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 firmemente aloados 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 para o pacote principal (usando o nome independente da versão). O Visual Studio ajuda você a obter os metadados corretos em seus arquivos.

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

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

  1. Clique com botão direito do projeto do pacote principal, selecione Adicionar > Novo Item...
  2. Na janela, pesquise os modelos instalados para ". txt" e adicione um novo arquivo de texto.

    Importante

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

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

Quando sua solução estiver configurada dessa forma, 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, assim como os pacotes opcionais, um arquivo para conjuntos relacionados só funcionará Bundle.Mapping.txt Windows 10, versão 1703 ou superior. Além disso, a Versão Mínima da Plataforma de Destino do aplicativo deve ser definida como 10.0.15063.0 ou superior.

Removendo pacotes opcionais

Os usuários podem entrar no aplicativo Configurações e remover os pacotes opcionais. Da mesma forma, os desenvolvedores podem usar 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 chama a API.

Se o pacote opcional for somente conteúdo, o desenvolvedor deverá explicitamente dizer à plataforma que o pacote que está prestes a ser removido é 'não em uso' pelo aplicativo antes de o desenvolvedor remover 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 é atualmente suportada no Visual Studio. Para resolver este problema, você pode implantar e iniciar a ativação (Ctrl + F5) e anexar manualmente o depurador a um processo. Para anexar o depurador, vá no menu "Depurar" no Visual Studio, selecione "Anexar ao Processo ..." e anexe o depurador ao processo principal do aplicativo.