> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# カスタム インストール アクション

> カスタム インストール アクション

多くのゲームはアンチチートやその他のミドルウェアを使用します。これらのコンポーネントは通常、ユーザーがゲームをインストールするときに連鎖インストールされます。ユーザーは Microsoft Store 経由で 1 つのゲームをインストールし、別の配布チャネル経由で別のゲームをインストールすることがあります。プラットフォームは、両方のゲームが同じミドルウェア パッケージを連鎖インストールしても競合が発生しないことを保証します。ゲームはパッケージに任意の .exe または .msi ファイルを 1 つ以上含めることができ、これらのファイルをアプリのインストール完了の一環として実行するように要求できます。カスタム インストール アクション機能は、ゲームのアンチチート ソフトウェアやその他の再配布可能ミドルウェアをインストールするためのものです。この方法で、Microsoft Store に提出する MSIX と、その他の配布チャネル経由で提出する .msi または .exe ファイルの両方で、まったく同じ連鎖インストーラー .exe ファイルを使用できます。

従来の Win32 アプリでは、共有ミドルウェアは通常、独立した再配布可能ファイル (通常は自己解凍型 .exe、またはゲーム自体にバンドルできる .msi) を介してインストールされます。Microsoft Store アプリは依存関係をフレームワーク パッケージとしてモデル化します。フレームワーク パッケージはゲームにバンドルされず、Microsoft Store を通じて個別にデプロイされます。このモデルでは、利用側のアプリ マニフェストが 1 つ以上のフレームワーク パッケージへの依存関係を宣言します。Microsoft Store はその後、依存関係の連鎖インストールを処理します。多くの再配布可能パッケージは Microsoft Store でフレームワーク パッケージとして利用可能ですが、フレームワーク パッケージとして利用できない再配布可能パッケージも必然的に存在します。これらのパッケージについての解決策は、ゲームがゲーム パッケージ内に再配布可能パッケージをバンドルできるようにすることです。

.exe または .msi 再配布可能パッケージを含めるには、MicrosoftGame.config ファイルを更新する必要があります。これらの変更には、使用したいカスタム アクションのタイプ、およびインストール パッケージ内でのそのカスタム アクションの場所の宣言が含まれます。
再配布可能パッケージはパッケージに含まれ、MicrosoftGame.config で宣言されている必要があります。宣言には、実行可能ファイルへのパス (宣言された Folder パスに対する相対パスで、これはパッケージ自体のルート パスに対する相対) が含まれます。宣言には、実行時に実行可能ファイルに渡されるコマンドライン引数も含まれます。これは MicrosoftGame.config ファイルに **CustomInstallActions** 要素を含めることによって行われます。

## CustomInstallActions

**CustomInstallActions** 要素には、どのカスタム インストール アクションをいつ実行するかについてのすべての定義が含まれます。この要素は MicrosoftGame.config ファイル内で 1 つのインスタンスしか宣言できません。必須の子要素として **Folder** が 1 つあります。これはすべてのカスタム アクションに必要なすべてのファイルを含むフォルダーを指定する文字列です。このフォルダーにはサブフォルダーを含めることができます。パッケージが任意のカスタム アクション実行可能ファイルの依存関係を含み、それらが各々の適切な読み込みパスにあることを保証する責任はあなたにあります。

<Note>タイトルをパッケージ化するとき、`makepkg` はこの **CustomInstallActions** 要素を、生成される `appxmanifest.xml` 内の MSIX `windows.customInstall` 拡張機能に変換します。そこでは同等の要素が `<CustomInstall>` であり、**Folder** は *属性* として表現されます。その `<CustomInstall>` 形式を自分で作成する必要はありません。MicrosoftGame.config では、後述の **ゲーム構成ファイルの変更** の例に示すとおり、**Folder** は **CustomInstallActions** の子 *要素* です。</Note>

<Note>指定した Folder に、主要なゲーム実行可能ファイルやその他のファイルを配置してはいけません。ここは明示的にカスタム インストール ファイル専用です。</Note>

**CustomInstallActions** 要素内では、アプリは **InstallActionList**、**RepairActionList**、および **UninstallActionList** の子要素を宣言できます。これらはすべて省略可能です。いずれか、あるいはいずれも宣言しなくても構いません。これらの各リスト内では、1 つ以上の **InstallAction**、**RepairAction**、または **UninstallAction** の子項目を指定します。プラットフォームは、指定したアクションを指定した順序で、指定したコマンドライン引数を伴って実行します。

### アクションの種類

カスタム インストール拡張の 3 つの子ノードは、特定のカスタム アクションが実行されるタイミングを指定します。カスタム インストール アクションには 3 つの種類があります。

* **Install action:** プラットフォームがアプリの最初の起動前に実行するアクション
* **Repair action:** ユーザーが Repair または Reset を選択したときに実行されるアクション
* **Uninstall action:** ユーザーがアプリをアンインストールしたときに実行されるアクション

<Info>名前とは裏腹に、**install action はパッケージがインストールされたときには実行されません**。各アクションのタイプはアプリのライフサイクルの特定の時点で実行され、**InstallAction** はタイトルの *最初の起動直前* に 1 回実行されます (これは、プラットフォームが必要な UAC プロンプトを表示できる最初の時点です)。「Install」、「Repair」、「Uninstall」は、そのアクションが属するライフサイクルの *カテゴリ* を示すもので、実行される瞬間を示すものではありません。実際のパッケージ インストール/ダウンロード時に実行される処理が必要な場合、カスタム インストール アクションはその仕組みではありません。完全なシーケンスについては [カスタム アクションの使用方法](#custom-action-usage) を参照してください。</Info>

通常、いくつかの再配布可能パッケージを **InstallAction** として連鎖インストールし、それを **UninstallAction** としてアンインストールするように指定します。ただし、対応するアンインストールなしにインストールを選択する場合もあります。このシナリオでは、アプリは何かをインストールし、アプリがアンインストールされたときにそれを残します。これは、他のアプリと共有される再配布可能パッケージに適している可能性があります。同様に、**RepairAction** は、**InstallAction** で指定した実行可能ファイルの再宣言でしかない場合もあり、これは一般的なことです。install/repair/uninstall で実行したい各アクションが、それぞれ異なる実行可能ファイルを必要とする可能性もあります。スキーマは非常に柔軟であり、プラットフォームはいずれのアクションも必須としません。ゲームごとに適切な動作を自由に構成できます。

<Info>Uninstall アクションは、Install または Repair アクションが実行された場合にのみ実行されます。システムは Name プロパティを使用してこの状態を追跡します。このため、Install/Repair/Uninstall アクションが同じ Name を持つことが重要です。</Info>

### アクションの構成要素

#### File

各アクションについて、実行するファイルを指定する必要があり、このファイルはパッケージ内に存在している必要があります。パスを指定する場合、それは暗黙的に **CustomInstallActions** の **Folder** パスに対する相対パスになります。絶対パスを指定することはできません。パスはバックスラッシュ (\\) で始まってはいけません。

#### Name

アクションに *Name* を指定する必要があります。この *Name* は親の *Actions* ノード内で一意である必要がありますが、異なる Actions ノード間では共有できます。たとえば、File="MySetup.exe" と *Name*="abc123" を、**InstallAction** と **RepairAction** の両方として指定できます。一方、2 つの **InstallAction** 要素がある場合、それぞれ異なる *Name* を持つ必要があります。実行可能ファイルが変更されない限り、同じ実行可能ファイルに対してはパッケージ バージョン間で同じ *Name* を使用する必要があります。*Name* はアクションの識別子として使用され、プラットフォームがどのアクションが正常に実行されたか、および更新されたパッケージに対して実行する必要があるかを追跡できるようにします。更新されたパッケージが、すでに正常に実行された *Name* を持つカスタム アクションを指定する場合、プラットフォームは更新時にこのアクションをスキップします。

<Info>引数リストの違いは識別性の違いを構成しません。*更新された* パッケージで、同じ実行可能ファイルを異なる引数で実行したい場合は、異なる *Name* を指定する必要があります。宣言する *Name* を適切に構成し、バージョン間で追跡する責任はあなたにあります。</Info>

#### Arguments

各カスタム インストール アクションには 3 番目の要素である *argument* があり、再配布可能コマンドを実行するために必要な引数を含めることができます。

## カスタム アクションの使用方法

アンチチート ソフトウェアのインストールは通常、ユーザーが管理者権限を持っていることを必要とし、一般的に - カスタム アクションは非常に強力な機能であるため - プラットフォームは、カスタム アクションを持つすべてのパッケージに対して管理者権限を要求します。管理者権限で実行される操作については、Windows はアプリの最初の実行時にユーザー アカウント制御 (UAC) プロンプトを表示することを要求します。ユーザー ワークフローは次のとおりです。

* ゲームの Microsoft Store ページには、インストールに昇格権限が必要かどうか、インストールがカスタム アクションを実行するかどうか、およびこれがユーザーにとってどのような意味を持つかを含む要件の説明が含まれます。この情報は、ユーザーがゲームの購入について十分な情報に基づいた決定を下せるように提供されます。
* ユーザーがこれらの制約と影響に納得している場合、Install を選択します。
* プラットフォームは、パッケージにカスタム アクションが含まれていることを検出し、カスタム アクションを実行する必要があるという事実を記録します。ただし、初期インストール フェーズ中はカスタム アクションを実行しません。代わりに、カスタム アクションはユーザーが最初にゲームを起動したときに実行されます。
* ゲームの最初の起動時、プラットフォームがカスタム アクションを実行しようとする時点で、UAC プロンプトが表示されます。ユーザーは管理者資格情報を提供し、昇格を受け入れる必要があります。パッケージに複数のカスタム アクションが含まれていても、ユーザーに表示される UAC プロンプトは 1 つだけです。カスタム アクションの 1 つ以上が変更されない限り、更新時にさらに UAC プロンプトが表示されることはありません。ゲームがアンインストールされるときには UAC プロンプトが表示されます。

すべてのカスタム アクションは、成功時にはゼロを返す必要があります。いずれかのカスタム アクションが失敗した場合でも、プラットフォームは残りのカスタム アクションを実行し続け、アプリを起動しようとし続けます。以降のアプリ起動のたびに、プラットフォームは失敗した/不完全なインストール カスタム アクションを、そのアクションが成功するまで再試行し続けます。カスタム アクションの失敗に直面してアプリが正しく動作しない場合、ユーザーはいつでもアプリの設定ページに移動して、Repair または Reset を選択できます。Repair/Reset ではゲーム ファイルを再ダウンロードしません。単にパッケージを再登録するだけです。失敗した、または未実行のカスタム アクションは、実行されるように再登録されます。成功時に非ゼロ値を返すカスタム インストーラーがある場合、1 つのオプションは、成功時にゼロを返すあなたが作成する別の実行可能ファイルでこのインストーラーをラップすることです。

Microsoft Store のポリシーには、どの種類のミドルウェア/再配布可能ソフトウェアの連鎖インストールが許可されているかについてのガイドラインが含まれます。大まかには、連鎖インストールはゲームの実行に必要な共有ソフトウェアのためのものです。無関係のアプリやその他のソフトウェアをインストールすることを意図したものではありません。

<Note>カスタム インストール アクションは、メインの MSIXVC パッケージ内でのみサポートされます。フレームワーク パッケージ、オプション パッケージ、変更パッケージ、その他の種類のパッケージではサポートされません。</Note>

<Note>カスタムのインストール、修復、およびアンインストール アクションは、小売の Microsoft Store デプロイ パイプラインによって実行されます。開発用にローカルでパッケージをインストールした場合 (たとえば、`wdApp install` を使用してルースな `.msixvc` をインストールする場合、または `Add-AppxPackage` を使用してパッケージを登録する場合) には実行されません。ローカル開発でのインストールでは、パッケージがアクションを正しく *宣言* していること (それらが `windows.customInstall` 拡張機能として生成される `appxmanifest.xml` に表示されること) を検証することは可能ですが、そのパスではカスタム アクションの実行可能ファイル自体は呼び出されません。エンドツーエンドで実行されるアクションを検証するには、Store またはサンドボックスのフロー経由でタイトルをインストールしてください。</Note>

## MSI をカスタム インストール アクションとして実行する

MSI の場合、MSI の名前を提供し、プラットフォームがそのファイルに対して msiexec.exe を実行します。**/i**、**/f**、または **/x** の引数は提供しないでください。これらは宣言されているアクションのタイプ (install、repair、または uninstall) から推測されるためです。**/f** スイッチには任意のオプションを提供できません。ただし、通常 msiexec.exe に提供されるその他のオプション引数は提供できます。これはコマンドライン引数が制約される唯一のシナリオです。MSI 以外のアクションでは、任意の引数を指定できます。MSI 以外のアクションについて、プラットフォームは引数を解析または検証しません。プラットフォームは単にそれらを実行可能ファイルに渡します。引数が正しいことを保証する責任はあなたにあります。

MST (MSI transforms) の直接サポートはありません。MSI/MST の要件がある場合、考えられる回避策の 1 つは、MSI を実行して MST を適用するために msiexec をラップする独立した .exe をビルドすることです。

## ゲーム構成ファイルの変更

以下の XML の例は、カスタム インストール アクションを許可するために MicrosoftGame.config ファイルへ加える適切な追加を示しています。

```xml theme={null}
  <!-- Include CustomInstallActions element. Declare InstallActions, 
  RepairActions and/or UninstallActions as appropriate for your app. --> 
  <DesktopRegistration>
    <!-- ... --> 
    <!-- Other entries omitted for brevity. --> 
    <!-- ... --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /example" />
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName" Arguments="/silent /remove" />
        </UninstallActionList>
    </CustomInstallActions>
  </DesktopRegistration>
```

前述の例では、すべての実行可能ファイルと依存関係は、パッケージのルートに指定した MyInstallers フォルダーに配置する必要があります。そのフォルダー内で、アプリに適した任意のサブフォルダー構造を作成できます。この例では、MySetup.exe へのパスは \<package root>\MyInstallers\Banana\MySetup.exe になります。その実行可能ファイルに依存関係がある場合は、それらも適切なフォルダーまたはサブフォルダーに配置する必要があります。

以下のシーケンスは、複数のバージョンにわたってマニフェストをどのように作成するかを示しています。

```xml theme={null}
<!-- v1 of the game. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
      <InstallActionList>
        <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform records the successful install of TaskName_1. --> 
      </InstallActionList>
      <RepairActionList>
        <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
      </RepairActionList>
      <UninstallActionList>
        <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        <!-- The platform records the successful uninstall of TaskName_1. --> 
      </UninstallActionList>
    </CustomInstallActions>
      
<!-- v2 of the game, where the redist is NOT updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /example" />
          <!-- The platform detects that we've already installed TaskName_1, so we don't  
          run it again. Therefore, there's no UAC prompt. --> 
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
 
<!-- v2 of the game, where a redist IS updated. --> 
    <CustomInstallActions>
      <Folder>MyInstallers</Folder>
        <InstallActionList>
          <InstallAction File="CustomInstaller.exe" Name="TaskName_2" Arguments="/silent /example" />
          <!-- The platform detects that we haven't previously run TaskName_2, so we need 
          to run it this time and show a UAC prompt. -->  
        </InstallActionList>
        <RepairActionList>
          <RepairAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /repair" />
        </RepairActionList>
        <UninstallActionList>
          <UninstallAction File="CustomInstaller.exe" Name="TaskName_1" Arguments="/silent /remove" />
        </UninstallActionList>
      </CustomInstallActions>
```


## Related topics

- [フレームワーク パッケージの依存関係](/ja-jp/build/core-features/common/packaging/packaging-framework-packages.md)
- [MSIXVC ツールを使用した PC タイトル パッケージングの概要](/ja-jp/build/core-features/common/packaging/overviews/packaging-getting-started-for-PC.md)
- [パッケージングの概要](/ja-jp/build/core-features/common/packaging/overviews/packaging.md)
- [Intelligent Delivery: カスタムタグ指定子](/ja-jp/build/core-features/common/packaging/intelligentdelivery-custom.md)
- [VM 作成時にカスタム スクリプトを実行する (プレビュー)](/ja-jp/services/playfab/multiplayer/servers/vmstartupscript.md)