オプション パッケージと関連セットの作成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 Version 1703 以降Windows 10, version 1703 or later
  • Windows 10 バージョン 1703 SDK 以降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. オプションのパッケージと関連するセットは、パートナーセンターのアクセス許可を持たない基幹業務 (LOB) またはエンタープライズアプリに対して、ストアに送信されていない場合に使用できます。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. メイン パッケージ プロジェクトを確認し、[OK] を選択します。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. 同様に、開発者はRemoveOptionalPackageAsyncを使用してオプションのパッケージの一覧を削除できます。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.