パッケージ レイアウトを使ったパッケージの作成Package creation with the packaging layout

アセット パッケージの導入により、開発者はより多くのパッケージの種類だけでなく、より多くのパッケージをビルドするためのツールを利用できるようになりました。With the introduction of asset packages, developers now have the tools to build more packages in addition to more package types. アプリが大規模で複雑になるにつれて、構成されるパッケージが多くなり、それらのパッケージを管理するのが難しくなるのはよくあることです (特に、Visual Studio 外でビルドする場合やマッピング ファイルを使う場合)。As an app gets larger and more complex, it will often be comprised of more packages, and the difficulty of managing these packages will increase (especially if you are building outside of Visual Studio and using mapping files). アプリのパッケージ化構造の管理を簡略化するには、MakeAppx.exe でサポートされているパッケージ レイアウトを使うことができます。To simplify the management of an app’s packaging structure, you can use the packaging layout supported by MakeAppx.exe.

パッケージ レイアウトは、アプリのパッケージ構造を記述する 1 つの XML ドキュメントです。The packaging layout is a single XML document that describes packaging structure of the app. アプリのバンドル (プライマリおよびオプション)、バンドル内のパッケージ、パッケージ内のファイルを指定します。It specifies the bundles of an app (primary and optional), the packages in the bundles, and the files in the packages. ファイルは、さまざまなフォルダー、ドライブ、ネットワークの場所から選択することができます。Files can be selected from different folders, drives, and network locations. ワイルドカードを使って、ファイルを選択または除外することができます。Wildcards can be used to select or exclude files.

アプリのパッケージ レイアウトがセットアップされると、1 回のコマンド ライン呼び出しでアプリのパッケージをすべて作成するため MakeAppx.exe と共に使用されます。After the packaging layout for an app has been set up, it's used with MakeAppx.exe to create all of the packages for an app in a single command line call. 展開のニーズに合わせて、パッケージ レイアウトを編集してパッケージ構造を変更できます。The packaging layout can be edited to alter the package structure to fit your deployment needs.

シンプルなパッケージ レイアウトの例Simple packaging layout example

シンプルなパッケージ レイアウトの例を次に示します。Here's an example of what a simple packaging layout looks like:

<PackagingLayout xmlns="http://schemas.microsoft.com/appx/makeappx/2017">
  <PackageFamily ID="MyGame" FlatBundle="true" ManifestPath="C:\mygame\appxmanifest.xml" ResourceManager="false">
    
    <!-- x64 code package-->
    <Package ID="x64" ProcessorArchitecture="x64">
      <Files>
        <File DestinationPath="*" SourcePath="C:\mygame\*"/>
        <File ExcludePath="*C:\mygame\*.txt"/>
      </Files>
    </Package>
    
    <!-- Media asset package -->
    <AssetPackage ID="Media" AllowExecution="false">
      <Files>
        <File DestinationPath="Media\**" SourcePath="C:\mygame\media\**"/>
      </Files>
    </AssetPackage>

  </PackageFamily>
</PackagingLayout>

この例を分割してそのしくみを理解してみましょう。Let's break this example down to understand how it works.

PackageFamilyPackageFamily

このパッケージレイアウトでは、x64 アーキテクチャパッケージと "メディア" 資産パッケージを含む単一のフラットなアプリバンドルファイルを作成します。This packaging layout will create a single flat app bundle file with an x64 architecture package and a “Media” asset package.

アプリ バンドルの定義には PackageFamily 要素が使用されます。The PackageFamily element is used to define an app bundle. バンドルの AppxManifest を指定するには ManifestPath 属性を使う必要があります。AppxManifest は、バンドルのアーキテクチャ パッケージの AppxManifest に対応している必要があります。You must use the ManifestPath attribute to provide an AppxManifest for the bundle, the AppxManifest should correspond to the AppxManifest for the architecture package of the bundle. ID 属性も指定されている必要があります。The ID attribute must also be provided. これは、必要な場合はこのパッケージのみを作成できるように、パッケージの作成時に MakeAppx.exe と共に使用されます。また、結果として作成されるパッケージのファイル名になります。This is used with MakeAppx.exe during package creation so that you can create just this package if you want to, and this will be the file name of the resulting package. FlatBundle 属性は、作成するバンドルの種類を説明するために使用されます。フラット バンドル (詳しくはここで説明します) の場合は true、クラシック バンドルの場合は false です。The FlatBundle attribute is used to describe what type of bundle you want to create, true for a flat bundle (which you can read more about here), and false for a classic bundle. ResourceManager 属性は、このバンドル内のリソース パッケージがファイルにアクセスするために MRT を使うかどうかを指定するために使用されます。The ResourceManager attribute is used to specify if the resource packages within this bundle will use MRT in order to access the files. これは既定では true ですが、Windows 10 バージョン 1803 の時点ではまだ準備できていないため、この属性は false に設定する必要があります。This is by default true, but as of Windows 10, version 1803, this is not yet ready, so this attribute must be set to false.

Package と AssetPackagePackage and AssetPackage

PackageFamily 内では、アプリ バンドルに含まれるかアプリ バンドルが参照するパッケージが定義されます。Within the PackageFamily, the packages that the app bundle contains or references are defined. ここでは、アーキテクチャ パッケージ (メイン パッケージとも呼ばれます) が Package 要素を使って定義され、アセット パッケージが AssetPackage 要素を使って定義されます。Here, the architecture package (also called the main package) is defined with the Package element, and the asset package is defined with the AssetPackage element. アーキテクチャ パッケージは、パッケージの対象アーキテクチャ ("x64"、"x86"、"arm"、"neutral" のいずれか) を指定する必要があります。The architecture package must specify which architecture the package is for, either “x64”, “x86”, “arm”, or “neutral”. ManifestPath 属性をもう一度使って、このパッケージ専用に AppxManifest を直接指定することもできます (オプション)。You can also (optionally) directly provide an AppxManifest specifically for this package by using the ManifestPath attribute again. AppxManifest が指定されない場合、PackageFamily に指定された AppxManifest から自動的に生成されます。If an AppxManifest is not provided, one will be automatically generated from the AppxManifest provided for the PackageFamily.

既定では、AppxManifest はバンドル内のすべてのパッケージに生成されます。By default and AppxManifest will be generated for every package within the bundle. アセット パッケージでは、AllowExecution 属性を設定することもできます。For the asset package, you can also set the AllowExecution attribute. これを false に設定すると (既定)、実行する必要のないパッケージがウイルス スキャンに公開プロセスをブロックさせることがなくなるため、アプリの公開にかかる時間が短縮されます (これについて詳しくは「アセット パッケージの概要)」をご覧ください)。Setting this to false (the default), will help decrease the publishing time for your app since packages that don’t need to execute won’t have their virus scan block the publishing process (you can learn more about this at Introduction to asset packages).

ファイルFiles

各パッケージ定義内では、File 要素を使ってこのパッケージに含めるファイルを選ぶことができます。Within each package definition, you can use the File element to select files to be included in this package. SourcePath 属性は、ファイルが存在するローカルの場所です。The SourcePath attribute is where the files are locally. ファイルは、さまざまなフォルダー (相対パスを指定)、さまざまなドライブ (絶対パスを指定)、さらにはネットワーク共有 (\\myshare\myapp\* のように指定) から選ぶことができます。You can select files from different folders (by providing relative paths), different drives (by providing absolute paths), or even network shares (by providing something like \\myshare\myapp\*). DestinationPath は、ファイルが最終的に配置されるパッケージ内の場所 (パッケージのルートを基準) です。The DestinationPath is where the files will end up within the package, relative to the package root. ExcludePath を使うと (他の 2 つの属性の代わりに)、同じパッケージ内にある他の File 要素の SourcePath 属性によって選択されたファイルから除外するファイルを選ぶことができます。ExcludePath can be used (instead of the other two attributes) to select files to be excluded from the ones selected by other File elements’ SourcePath attributes within the same package.

File 要素を使うと、ワイルドカードを使って複数のファイルを選ぶことができます。Each File element can be used to select multiple files by using wildcards. 通常、単一ワイルドカード (*) はパス内の任意の場所で何回でも使うことができます。In general, single wildcard (*) can be used anywhere within the path any number of times. ただし、単一ワイルドカードが一致するのはフォルダー内のファイルのみであり、サブフォルダーには一致しません。However, a single wildcard will only match the files within a folder and not any subfolders. たとえば、SourcePathC:\MyGame\*\* を使って C:\MyGame\Audios\UI.mp3 ファイルと C:\MyGame\Videos\intro.mp4 ファイルを選ぶことはできますが、C:\MyGame\Audios\Level1\warp.mp3 を選ぶことはできません。For example, C:\MyGame\*\* can be used in the SourcePath to select the files C:\MyGame\Audios\UI.mp3 and C:\MyGame\Videos\intro.mp4, but it cannot select C:\MyGame\Audios\Level1\warp.mp3. 二重ワイルドカード (**) は、フォルダーまたはファイル名として使って再帰的に一致させることができます (ただし、名前の一部で使うことはできません)。The double wildcard (**) can also be used in place of folder or file names to match anything recursively (but it cannot be next to partial names). たとえば、C:\MyGame\**\Level1\** を使うと C:\MyGame\Audios\Level1\warp.mp3C:\MyGame\Videos\Bonus\Level1\DLC1\intro.mp4 を選ぶことができます。For example, C:\MyGame\**\Level1\** can select C:\MyGame\Audios\Level1\warp.mp3 and C:\MyGame\Videos\Bonus\Level1\DLC1\intro.mp4. 移動元と移動先の異なる場所でワイルドカードを使う場合、ワイルドカードを使ってパッケージ化プロセスの一部としてファイル名を直接変更することもできます。Wildcards can also be used to directly change file names as part of the packaging process if the wildcards are used in different places between the source and destination. たとえば、SourcePathC:\MyGame\Audios\*DestinationPathSound\copy_* を使うと、C:\MyGame\Audios\UI.mp3 を選んでパッケージに Sound\copy_UI.mp3 として表示することができます。For example, having C:\MyGame\Audios\* for SourcePath and Sound\copy_* for DestinationPath can select C:\MyGame\Audios\UI.mp3 and have it appear in the package as Sound\copy_UI.mp3. 通常、単一ワイルドカードおよび二重ワイルドカードの数は単一の File 要素の SourcePath および DestinationPath と同じでなければなりません。In general, the number of single wildcards and double wildcards must be the same for the SourcePath and DestinationPath of a single File element.

高度なパッケージ レイアウトの例Advanced packaging layout example

より複雑なパッケージ レイアウトの例を次に示します。Here's an example of a more complicated packaging layout:

<PackagingLayout xmlns="http://schemas.microsoft.com/appx/makeappx/2017">
  <!-- Main game -->
  <PackageFamily ID="MyGame" FlatBundle="true" ManifestPath="C:\mygame\appxmanifest.xml" ResourceManager="false">
    
    <!-- x64 code package-->
    <Package ID="x64" ProcessorArchitecture="x64">
      <Files>
        <File DestinationPath="*" SourcePath="C:\mygame\*"/>
        <File ExcludePath="*C:\mygame\*.txt"/>
      </Files>
    </Package>

    <!-- Media asset package -->
    <AssetPackage ID="Media" AllowExecution="false">
      <Files>
        <File DestinationPath="Media\**" SourcePath="C:\mygame\media\**"/>
      </Files>
    </AssetPackage>
    
    <!-- English resource package -->
    <ResourcePackage ID="en">
      <Files>
        <File DestinationPath="english\**" SourcePath="C:\mygame\english\**"/>
      </Files>
      <Resources Default="true">
        <Resource Language="en"/>
      </Resources>
    </ResourcePackage>

    <!-- French resource package -->
    <ResourcePackage ID="fr">
      <Files>
        <File DestinationPath="french\**" SourcePath="C:\mygame\french\**"/>
      </Files>
      <Resources>
        <Resource Language="fr"/>
      </Resources>
    </ResourcePackage>
  </PackageFamily>

  <!-- DLC in the related set -->
  <PackageFamily ID="DLC" Optional="true" ManifestPath="C:\DLC\appxmanifest.xml">
    <Package ID="DLC.x86" Architecture="x86">
      <Files>
        <File DestinationPath="**" SourcePath="C:\DLC\**"/>
      </Files>
    </Package>
  </PackageFamily>

  <!-- DLC not part of the related set -->
  <PackageFamily ID="Themes" Optional="true" RelatedSet="false" ManifestPath="C:\themes\appxmanifest.xml">
    <Package ID="Themes.main" Architecture="neutral">
      <Files>
        <File DestinationPath="**" SourcePath="C:\themes\**"/>
      </Files>
    </Package>
  </PackageFamily>

  <!-- Existing packages that need to be included/referenced in the bundle -->
  <PrebuiltPackage Path="C:\prebuilt\DLC2.appxbundle" />

</PackagingLayout>

この例は、ResourcePackage 要素と Optional 要素が追加されている点がシンプルな例と異なります。This example differs from the simple example with the addition of ResourcePackage and Optional elements.

リソース パッケージは、ResourcePackage 要素を使って指定することができます。Resource packages can be specified with the ResourcePackage element. ResourcePackage 内では、Resources 要素を使ってリソース パックのリソース修飾子を指定する必要があります。Within the ResourcePackage, the Resources element must be used to specify the resource qualifiers of the resource pack. リソース修飾子は、リソース パックによってサポートされているリソースです。ここには、2 つのリソース パッケージが定義されており、それぞれ英語とフランス語に固有のファイルが含まれていることがわかります。The resource qualifiers are the resources that are supported by the resource pack, here, we can see that there are two resource packs defined and they each contain the English and French specific files. リソース パックには、Resources 内に別の Resource 要素を追加することで複数の修飾子を付けることができます。A resource pack can have more than one qualifier, this can be done by adding another Resource element within Resources. ディメンションが存在する場合は (ディメンションは language、scale、dxfl)、リソース ディメンションの既定のリソースも指定する必要があります。A default resource for the resource dimension must also be specified if the dimension exists (dimensions being language, scale, dxfl). ここでは、英語が既定の言語であることがわかります。つまり、システム言語としてフランス語を設定していないユーザーの場合、英語のリソース パックをダウンロードして英語で表示するようにフォールバックすることになります。Here, we can see that English is the default language, meaning that for users that does not have a system language of French set, they will fallback to downloading the English resource pack and display in English.

オプション パッケージには、それぞれ個々のパッケージ ファミリ名があり、PackageFamily 要素を使って定義する必要があります。ただし、Optional 属性を true に指定する必要があります。Optional packages each have their own distinct package family names and must be defined with PackageFamily elements, while specifying the Optional attribute to be true. RelatedSet 属性は、オプション パッケージが関連するセット内にあるかどうか、つまりプライマリ パッケージを使ってオプション パッケージを更新する必要があるかどうかを指定するために使用されます (既定では true)。The RelatedSet attribute is used to specify whether the optional package is within the related set (by default this is true) – whether the optional package should be updated with the primary package.

PrebuiltPackage要素は、パッケージレイアウトで定義されていないパッケージを追加するために使用されます。このパッケージは、ビルドされるアプリケーションバンドルファイルに含まれるか参照されます。The PrebuiltPackage element is used to add packages that are not defined in the packaging layout to be included or referenced in the app bundle file(s) to be built. この場合、プライマリアプリケーションバンドルファイルが参照して関連するセットに含めることができるように、別の DLC オプションパッケージがここに含まれています。In this case, another DLC optional package is being included here so that the primary app bundle file can reference it and have it be part of the related set.

パッケージ レイアウトと MakeAppx.exe を使ったアプリ パッケージのビルドBuild app packages with a packaging layout and MakeAppx.exe

アプリのパッケージ レイアウトを作成したら、MakeAppx.exe を使ってアプリのパッケージのビルドを開始できます。Once you have the packaging layout for your app, you can start using MakeAppx.exe to build the packages of your app. パッケージ レイアウトで定義されているパッケージをすべてビルドするには、次のコマンドを使用します。To build all of the packages defined in the packaging layout, use the command:

MakeAppx.exe build /f PackagingLayout.xml /op OutputPackages\

ただし、アプリを更新するが、変更されたファイルがまったく含まれていないパッケージがある場合、変更されたパッケージのみをビルドすることができます。But, if you are updating your app and some packages don't contain any changed files, you can build only the packages that have changed. このページのシンプルなパッケージ レイアウトの例を使って、x64 アーキテクチャ パッケージをビルドすると、次のようなコマンドになります。Using the simple packaging layout example on this page and building the x64 architecture package, this is what our command would look like:

MakeAppx.exe build /f PackagingLayout.xml /id "x64" /ip PreviousVersion\ /op OutputPackages\ /iv

/id フラグを使うとパッケージ レイアウトからビルドするパッケージを選ぶことができます。これは、レイアウトの ID 属性に対応します。The /id flag can be used to select the packages to be built from the packaging layout, corresponding to the ID attribute in the layout. /ip は、この場合はパッケージの以前のバージョンの場所を示すために使用されます。The /ip is used to indicate where the previous version of the packages are in this case. 以前のバージョンを指定する必要があります。これは、アプリバンドルファイルが以前のバージョンのメディアパッケージを参照する必要があるためです。The previous version must be provided because the app bundle file still needs to reference the previous version of the Media package. /iv フラグは、ビルドするパッケージのバージョンを自動的に増分するために使用されます (AppxManifest でバージョンを変更する代わりに)。The /iv flag is used to automatically increment the version of the packages being built (instead of changing the version in the AppxManifest). または、/pv スイッチと /bv スイッチを使うと、それぞれパッケージのバージョン (作成するすべてのパッケージについて) とバンドルのバージョン (作成するすべてのバンドルについて) を直接指定することができます。Alternatively, the switches /pv and /bv can be used to directly provide a package version (for all packages to be created) and a bundle version (for all bundles to be created), respectively. このページの高度なパッケージ レイアウトの例を使って、Themes オプション バンドルとそれが参照する Themes.main アプリ パッケージのみビルドする場合、次のコマンドを使う必要があります。Using the advanced packaging layout example on this page, if you want to only build the Themes optional bundle and the Themes.main app package that it references, you would use this command:

MakeAppx.exe build /f PackagingLayout.xml /id "Themes" /op OutputPackages\ /bc /nbp

/bc フラグは、Themes バンドルの子もビルドする必要があることを指定するために使用されます (この場合、Themes.main がビルドされます)。The /bc flag is used to denote that the children of the Themes bundle should also be built (in this case Themes.main will be built). /nbp フラグは、Themes バンドルの親をビルドしないことを指定するために使用されます。The /nbp flag is used to denote that the parent of the Themes bundle should not be built. オプション アプリ バンドルである Themes の親は、プライマリ アプリ バンドル MyGame です。The parent of Themes, which is an optional app bundle, is the primary app bundle: MyGame. 通常、関連するセットのオプション パッケージの場合、オプション パッケージをインストール可能にするにはプライマリ アプリ バンドルもビルドする必要があります。オプション パッケージが関連するセットに含まれる場合は、プライマリ アプリ バンドルでオプション パッケージも参照する必要があるためです (プライマリ パッケージとオプション パッケージの間でバージョン管理を保証するため)。Usually for an optional package in a related set, the primary app bundle must also be built for the optional package to be installable, since the optional package is also referenced in the primary app bundle when it is in a related set (to guarantee versioning between the primary and the optional packages). パッケージ間の親子関係を次の図に示します。The parent child relationship between packages is illustrated in the following diagram:

パッケージ レイアウトの図