Разработка дополнительных пакетов и связанных наборовOptional packages and related set authoring

Дополнительные пакеты включают в себя содержимое, которое можно интегрировать с главным пакетом.Optional packages contain content that can be integrated with a main package. Они полезны для загружаемого контента (DLC), так как позволяют поделить большое приложение при наличии ограничений на размер или доставить любое дополнительное содержимое отдельно от исходного приложения.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. Дополнительные сведения о дополнительных пакетах см. в записи блога: расширение возможностей приложения с помощью дополнительных пакетов.For more information about optional packages, see Blog post: Extend your application using optional packages.

Связанные наборы являются расширением дополнительных пакетов.Related sets are an extension of optional packages. Связанные наборы позволяют применять строгий набор версий для основных и дополнительных пакетов.Related sets allow you to enforce a strict set of versions across main and optional packages. Связанные наборы могут иметь разных издателей из основного приложения, если они развернуты за пределами магазина.Related sets can have different publishers from the main app if it is deployed outside of the Store. Дополнительные сведения о связанных наборах см. в записи блога: Инструментарий для создания связанного набора.For more information about related sets, see Blog post: Tooling to create a related set.

Необязательные пакеты и связанные наборы запускаются внутри контейнера MSIX основного приложения.Optional packages and related sets all run inside the main app's MSIX container.

Предварительные требованияPrerequisites

  • Visual Studio 2019 или Visual Studio 2017 (версия 15,1 или более поздняя)Visual Studio 2019 or Visual Studio 2017 (version 15.1 or later)
  • Windows 10 версии 1703 или более позднейWindows 10, version 1703 or later
  • Windows 10, пакет SDK для версии 1703 или более позднейWindows 10, version 1703 SDK or later

Чтобы скачать все самые последние средства для разработки, см. раздел Загружаемые файлы и инструменты для Windows 10.To get all of the latest development tools, see Downloads and tools for Windows 10.

Примечание

Чтобы отправить приложение, которое использует необязательные пакеты и/или связанные наборы для Microsoft Store, вам потребуется разрешение.To submit an app that uses optional packages and/or related sets to the Microsoft Store, you will need permission. Необязательные пакеты и связанные наборы можно использовать для бизнес-приложений или корпоративных приложения без разрешения центра партнеров, если они не отправлены в магазин.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. Для получения разрешения на отправку приложений, использующих дополнительные пакеты и связанные наборы, см. раздел Поддержка разработчиков для Windows.See Windows developer support to get permission to submit an app that uses optional packages and related sets.

Пример кодаCode sample

Во время чтения этой статьи рекомендуется следить за примером кода для дополнительного пакета на GitHub, чтобы получить практическое понимание работы дополнительных пакетов и связанных наборов в 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.

Дополнительные пакетыOptional packages

Чтобы создать дополнительный пакет в Visual Studio, необходимо выполнить следующее:To create an optional package in Visual Studio, you'll need to:

  1. Убедитесь, что для параметра Минимальная версия целевой платформы приложения задано значение 10.0.15063.0 или выше.Make sure your app's Target Platform Min Version is set to: 10.0.15063.0 or higher.
  2. Из проекта вашего главного пакета откройте файл Package.appxmanifest.From your main package project, open the Package.appxmanifest file. Перейдите на вкладку "Упаковка" и обратите внимание на имя семейства пакета, в которое входят все символы до символа "".Navigate to the "Packaging" tab and make a note of your package family name, which is everything before the "" character.
  3. Из проекта вашего дополнительного пакета щелкните правой кнопкой мыши файл Package.appxmanifest и выберите пункты Открыть с помощью > Редактор (текстовый) XML.From your optional package project, right click the Package.appxmanifest and select Open with > XML (Text) Editor.
  4. Найдите в этом файле элемент <Dependencies>.Locate the <Dependencies> element in the file. Добавьте следующее и замените [MainPackageDependency] именем семейства пакетов , которое было на шаге 2.Add the following, and replace [MainPackageDependency] with your package family name from Step 2. Эта строка будет указывать, что ваш дополнительный пакет зависит от главного пакета.This will specify that your optional package is dependent on your main package.
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>
    

После настройки зависимостей пакета из шагов с 1 по 4 можно продолжить разработку, как обычно.After you have your package dependencies set up from Steps 1 through 4, you can continue developing as you normally would. Дополнительные сведения см. в записи блога: создание первого необязательного пакета.For more information, see Blog post: Build your first optional package.

Visual Studio можно настроить для повторного развертывания главного пакета при каждом развертывании дополнительного пакета.Visual Studio can be configured to re-deploy your main package each time you deploy an optional package. Чтобы задать зависимости сборки в Visual Studio, выполните следующее:To set the build dependency in Visual Studio, you should:

  1. Щелкните правой кнопкой мыши проект дополнительного пакета и выберите пункты Зависимости сборки > Зависимости проекта...Right click the optional package project and select Build Dependencies > Project Dependencies...
  2. Выберите проект главного пакета и нажмите кнопку "ОК".Check the main package project and select "OK".

Теперь каждый раз при нажатии клавиши F5 или сборке проекта дополнительного пакета программа Visual Studio будет создавать сначала проект главного пакета.Now, every time you enter F5 or build an optional package project, Visual Studio will build the main package project first. Это гарантирует синхронизацию главного и дополнительного проектов.This will ensure that your main project and optional projects are in sync.

Связанный набор состоит из основного пакета и необязательного пакета, который тесно связан с помощью метаданных, указанных в файле. appxbundle или. msixbundle основного пакета.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. Эти метаданные связывают основной пакет с дополнительным пакетом (используя имя appxbundle-файла и версию) и дополнительный пакет для основного пакета (с использованием независимого от версии имени).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). Visual Studio помогает вам получить правильные метаданные в ваших файлах.Visual Studio helps you get the correct metadata in your files.

Управление версиями пакетов в связанном наборе синхронизируется таким образом, что не позволит использовать последнюю версию любого пакета до тех пор, пока не будут установлены все связанные пакеты набора (указанные версией в основном пакете).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. Пакеты обслуживаются независимо, но пакеты, указанные в наборе, могут не использоваться до тех пор, пока не будут обновлены все.Packages are serviced independently, but packages specified in the set may not be used until all of them have been updated. Дополнительные сведения о связанных наборах см. в записи блога: Инструментарий для создания связанного набора.For more information about related sets, see Blog post: Tooling to create a related set.

Чтобы настроить решение для связанных наборов для вашего приложения, выполните следующие действия:To configure your app's solution for related sets, use the following steps:

  1. Щелкните правой кнопкой мыши проект главного пакета и выберите пункты Добавить > Новый элемент...Right click the main package project, select Add > New Item...
  2. Из этого окна выполните поиск установленных шаблонов для ".txt" и добавьте новый текстовый файл.From the window, search the Installed Templates for ".txt" and add a new text file.

    Важно!

    Новый текстовый файл должен называться Bundle.Mapping.txt.The new text file must be named: Bundle.Mapping.txt.

  3. В Bundle.Mapping.txt файле введите строку "[оптионалпрожектс]", а затем относительные пути к необязательным проектам пакета.In the Bundle.Mapping.txt file enter the string "[OptionalProjects]" followed by the relative paths to your optional package projects. Ниже приведен пример файла Bundle.Mapping.txt:Here is an example Bundle.Mapping.txt file:
    [OptionalProjects]
    "..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
    "..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"
    

Если решение настроено таким образом, Visual Studio создаст манифест пакета с именем AppxBundleManifest.xml для основного пакета со всеми необходимыми метаданными для связанных наборов.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.

Обратите внимание, что, как и в случае с дополнительными пакетами, Bundle.Mapping.txt файл для связанных наборов будет работать только в Windows 10, версии 1703 или более поздней.Note that like optional packages, a Bundle.Mapping.txt file for related sets will only work on Windows 10, version 1703 or higher. Кроме того, минимальная версия целевой платформы приложения должна быть равна 10.0.15063.0 или выше.Additionally, your app's Target Platform Min Version should be set to 10.0.15063.0 or higher.

Удаление дополнительных пакетовRemoving Optional Packages

Пользователи могут войти в приложение параметров и удалить необязательные пакеты.Users can go into their Settings app and remove the optional packages. Аналогичным образом разработчики могут использовать ремовеоптионалпаккажеасинк для удаления списка дополнительных пакетов.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;
}

Примечание

В случае связанного набора платформа должна перезапустить основное приложение, чтобы завершить удаление, чтобы избежать ситуаций, в которых приложение имеет содержимое, загруженное из удаляемого пакета.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. Приложения должны уведомлять пользователей о том, что приложение потребуется перезапустить, прежде чем приложение вызовет API.The apps must notify the users that the application will need to be restarted before the app calls the API.

Если дополнительный пакет является содержимым, то разработчик должен явно сообщить платформе, что удаляемый пакет не используется приложением, прежде чем разработчик удалит дополнительный пакет.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. Это также позволяет разработчику удалить пакет без перезагрузки.This also allows the developer to remove the package without a restart.

Известные проблемыKnown issues

В настоящее время в Visual Studio не поддерживается отладка дополнительного проекта связанного набора.Debugging a related set optional project is not currently supported in Visual Studio. Чтобы обойти эту проблему, можно развернуть и запустить активацию (Ctrl+F5) и вручную подключить отладчик к процессу.To work around this issue, you can deploy and launch the activation (Ctrl + F5) and manually attach the debugger to a process. Чтобы подключить отладчик, перейдите в Visual Studio в меню "Отладка", выберите пункт "Присоединиться к процессу..." и подключите отладчик к процессу основного приложения.To attach the debugger, go the "Debug" menu in Visual Studio, select "Attach to Process...", and attach the debugger to the main app process.