Criação de pacotes opcionais e conjunto relacionadoOptional packages and related set authoring

Os pacotes opcionais contêm conteúdo que pode ser integrado com um pacote principal.Optional packages contain content that can be integrated with a main package. 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.These are useful for downloadable content (DLC), dividing a large app for size restraints, or for shipping any additional content separate from your original app. Para obter mais informações sobre pacotes opcionais, consulte postagem de blog: estender seu aplicativo usando pacotes opcionais.For more information about optional packages, see Blog post: Extend your application using optional packages.

Os conjuntos relacionados são uma extensão de pacotes opcionais.Related sets are an extension of optional packages. Os conjuntos relacionados permitem que você aplique um conjunto estrito de versões em pacotes principais e opcionais.Related sets allow you to enforce a strict set of versions across main and optional packages. Os conjuntos relacionados podem ter editores diferentes do aplicativo principal se ele for implantado fora do repositório.Related sets can have different publishers from the main app if it is deployed outside of the Store. Para obter mais informações sobre conjuntos relacionados, consulte postagem no blog: ferramentas para criar um conjunto relacionado.For more information about related sets, see Blog post: Tooling to create a related set.

Pacotes opcionais e conjuntos relacionados todos são executados dentro do contêiner MSIX do aplicativo principal.Optional packages and related sets all run inside the main app's MSIX container.

Pré-requisitosPrerequisites

  • Visual Studio 2019 ou Visual Studio 2017 (versão 15,1 ou posterior)Visual Studio 2019 or Visual Studio 2017 (version 15.1 or later)
  • Windows 10, versão 1703 ou posteriorWindows 10, version 1703 or later
  • Windows 10, versão 1703 SDK ou posteriorWindows 10, version 1703 SDK or later

Para obter todas as ferramentas de desenvolvimento mais recentes, consulte Downloads e ferramentas para Windows 10.To get all of the latest development tools, see Downloads and tools for Windows 10.

Observação

Para enviar um aplicativo que usa pacotes opcionais e/ou conjuntos relacionados para o Microsoft Store, você precisará de permissão.To submit an app that uses optional packages and/or related sets to the Microsoft Store, you will need permission. Os pacotes opcionais e os conjuntos relacionados podem ser usados para LOB (linha de negócios) ou aplicativos empresariais sem a permissão do Partner Center se não forem enviados para a loja.Optional packages and related sets can be used for Line of Business (LOB) or enterprise apps without Partner Center permission if they are not submitted to the Store. Consulte Suporte do desenvolvedor Windows para obter permissão para enviar um aplicativo que usa pacotes opcionais e conjuntos relacionados.See Windows developer support to get permission to submit an app that uses optional packages and related sets.

Exemplo de códigoCode sample

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.While you're reading this article, it's recommended that you follow along with the optional package code sample on GitHub for a hands-on understanding of how optional packages and related sets work within Visual Studio.

Pacotes opcionaisOptional packages

Para criar um pacote opcional no Visual Studio, você precisará:To create an optional package in Visual Studio, you'll need to:

  1. Verifique se a versão mínima da plataforma de destino do aplicativo está definida como: 10.0.15063.0 ou superior.Make sure your app's Target Platform Min Version is set to: 10.0.15063.0 or higher.
  2. Em seu projeto pacote principal, abra o arquivo Package.appxmanifest.From your main package project, open the Package.appxmanifest file. Navegue até a guia "Pacotes" e anote seu nome de família do pacote, que é tudo antes do caractere "".Navigate to the "Packaging" tab and make a note of your package family name, which is everything before the "" character.
  3. Em seu projeto pacote opcional, clique com botão direito em Package.appxmanifest e selecione Abrir com > Editor XML (texto).From your optional package project, right click the Package.appxmanifest and select Open with > XML (Text) Editor.
  4. Localize o elemento <Dependencies> no arquivo.Locate the <Dependencies> element in the file. Adicione o seguinte e substitua [MainPackageDependency] pelo nome da família de pacotes da etapa 2.Add the following, and replace [MainPackageDependency] with your package family name from Step 2. Isso especifica que seu pacote opcional depende seu pacote principal.This will specify that your optional package is dependent on your main package.
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>
    

Depois de ter suas dependências de pacote configuradas das etapas 1 a 4, você pode continuar desenvolvendo como faria normalmente.After you have your package dependencies set up from Steps 1 through 4, you can continue developing as you normally would. Para obter mais informações, consulte postagem no blog: criar seu primeiro pacote opcional.For more information, see Blog post: Build your first optional package.

O Visual Studio pode ser configurado para implementar novamente seu pacote principal sempre que você implantar um pacote opcional.Visual Studio can be configured to re-deploy your main package each time you deploy an optional package. Para definir a dependência de compilação no Visual Studio, você deve:To set the build dependency in Visual Studio, you should:

  1. Clique com o botão direito no projeto de pacote opcional e selecione Dependências da compilação > Dependências do projeto...Right click the optional package project and select Build Dependencies > Project Dependencies...
  2. Verifique se o projeto do pacote principal e selecione "OK".Check the main package project and select "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.Now, every time you enter F5 or build an optional package project, Visual Studio will build the main package project first. Isso garante que seu projeto principal e projetos opcionais estejam em sincronia.This will ensure that your main project and optional projects are in sync.

Um conjunto relacionado consiste em um pacote principal e um pacote opcional que são rigidamente acoplados por meio de metadados que são especificados no arquivo. appxbundle ou. msixbundle do pacote principal.A related set consists of a main package and an optional package that are tightly coupled via metadata that is specified in the .appxbundle or .msixbundle file of the main package. 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).This metadata links the main package to the optional package (using the name of the .appxbundle file + version), and the optional package to the main package (using the version independent name). O Visual Studio ajuda você a obter os metadados corretos em seus arquivos.Visual Studio helps you get the correct metadata in your files.

O controle de versão 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 do conjunto relacionado (especificados pela versão no pacote principal) estejam instalados.The versioning of packages in a related set is synchronized in a way that won't allow the latest version of any package to be used until all of the related set packages (specified by version in the main package) are installed. Os pacotes são atendidos de forma independente, mas os pacotes especificados no conjunto podem não ser usados até que todos tenham sido atualizados.Packages are serviced independently, but packages specified in the set may not be used until all of them have been updated. Para obter mais informações sobre conjuntos relacionados, consulte postagem no blog: ferramentas para criar um conjunto relacionado.For more information about related sets, see Blog post: Tooling to create a related set.

Para configurar a solução do seu aplicativo para conjuntos relacionados, use as seguintes etapas:To configure your app's solution for related sets, use the following steps:

  1. Clique com botão direito do projeto do pacote principal, selecione Adicionar > Novo Item...Right click the main package project, select Add > New Item...
  2. Na janela, pesquise os modelos instalados para ". txt" e adicione um novo arquivo de texto.From the window, search the Installed Templates for ".txt" and add a new text file.

    Importante

    O novo arquivo de texto deve ser nomeado: Bundle.Mapping.txt.The new text file must be named: 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.In the Bundle.Mapping.txt file enter the string "[OptionalProjects]" followed by the relative paths to your optional package projects. Veja aqui um exemplo de arquivo Bundle.Mapping.txt:Here is an example Bundle.Mapping.txt file:
    [OptionalProjects]
    "..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
    "..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"
    

Quando sua solução estiver configurada dessa forma, o Visual Studio criará um manifesto de pacote chamado AppxBundleManifest.xml para o pacote principal com todos os metadados necessários para conjuntos relacionados.When your solution is configured this way, Visual Studio will create a bundle manifest named AppxBundleManifest.xml for the main package with all of the required metadata for related sets.

Observe que, assim como os pacotes opcionais, um Bundle.Mapping.txt arquivo para conjuntos relacionados só funcionará no Windows 10, versão 1703 ou superior.Note that like optional packages, a Bundle.Mapping.txt file for related sets will only work on Windows 10, version 1703 or higher. 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.Additionally, your app's Target Platform Min Version should be set to 10.0.15063.0 or higher.

Removendo pacotes opcionaisRemoving Optional Packages

Os usuários podem acessar seu aplicativo de configurações e remover os pacotes opcionais.Users can go into their Settings app and remove the optional packages. Da mesma forma, os desenvolvedores podem usar o RemoveOptionalPackageAsync para remover uma lista de pacotes opcionais.Similarly, developers can use the RemoveOptionalPackageAsync to remove a list of optional packages.

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 tem conteúdo carregado do pacote que está sendo removido.In the case of a related set the platform will need to restart the main application to finalize the removal to avoid situations where the app has content that is loaded from the package that is being removed. Os aplicativos devem notificar os usuários de que o aplicativo precisará ser reiniciado antes que o aplicativo chame a API.The apps must notify the users that the application will need to be restarted before the app calls the API.

Se o pacote opcional for somente conteúdo, o desenvolvedor deverá informar 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.If the optional package is content only then, the developer should explicitly tell the platform that the package that is about to remove is 'not in use' by the application before the developer removes the optional package. Isso também permite que o desenvolvedor remova o pacote sem uma reinicialização.This also allows the developer to remove the package without a restart.

Problemas conhecidosKnown issues

A depuração de um projeto opcional de conjunto relacionado não é atualmente suportada no Visual Studio.Debugging a related set optional project is not currently supported in Visual Studio. Para resolver este problema, você pode implantar e iniciar a ativação (Ctrl + F5) e anexar manualmente o depurador a um processo.To work around this issue, you can deploy and launch the activation (Ctrl + F5) and manually attach the debugger to a process. Para anexar o depurador, vá no menu "Depurar" no Visual Studio, selecione "Anexar ao Processo ..." e anexe o depurador ao processo principal do aplicativo.To attach the debugger, go the "Debug" menu in Visual Studio, select "Attach to Process...", and attach the debugger to the main app process.