オプションの指示XMLファイルを作成すると、パッケージのインストールをカスタマイズして実行するための指示をパッケージマネージャに提供できます。

指示XMLファイルは、ルートの<instructions>要素と複数の子要素で構成されています。各子要素はオプションです。
  • <targetAttributes>
  • <customDirectories>
  • <shortcuts>
  • <returnCodeConventions>
  • <customExecutes>
  • <osUninstallEntry>

指示XMLファイルにinstructionsという名前を付け、ファイル拡張子を付けずに、ファイルパッケージのdataディレクトリのルートに配置します。

以下のテキストは、ファイルパッケージの指示ファイルの例です。 

<instructions>
    <targetAttributes readOnly="allReadOnly"/>
    <customDirectories>
        <customDirectory name="customDir1" path="D:\subdir"/>
        <customDirectory name="customDir2" path="\\myserver\subdir"/>
    </customDirectories>
    <shortcuts>
        <shortcut>
            <destination root="ProgramMenu" path="Test\Shortcut.lnk">
                <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>
                <localizedDestination root="ProgramMenu" path="Test\Raccourci.lnk" language="fr"/>
                <localizedDestination root="ProgramMenu" path="Test\ショートカット.lnk" language="ja"/>
                <localizedDestination root="ProgramMenu" path="Test\바로가기.lnk" language="ko"/>
                <localizedDestination root="ProgramMenu" path="Test\快捷方式.lnk" language="zh-CN"/>
            </destination>
            <target root="Program Files" path="Shortcuts\executable.exe"/>
        </shortcut>
    </shortcuts>
    <customExecutes>
        <customExecute root="Documents" exeName="executable.exe"/>
    </customExecutes>
</instructions>

<targetAttributes>要素

<targetAttributes>要素は、パッケージマネージャがターゲットシステム上にファイルをインストールする場所に関するオプションの指示を提供します。

<targetAttributes>は、空の要素であり、属性はありますが、要素やテキスト内容は含まれていません。以下の属性があります。

属性名 タイプ 可能な値 詳細 例
readOnly 列挙体
  • allWritable —(デフォルト) 元のソースファイルの読み取り専用属性値に関係なく、インストール用のすべてのパッケージファイルを書き込み可能にします。
  • allReadOnly —元のソースファイルの読み取り専用属性値に関係なく、インストール用のすべてのパッケージファイルを読み取り専用にします。
  • keepSource —インストール時に元のソースファイルの読み取り専用属性値を保持します。
    • すべてのファイルを読み取り専用、ファイル書き込み可能にするかどうか、または元のソースファイルから読み取り専用属性値を保持するかどうかをパッケージマネージャに宣言します。
    • readOnly属性を宣言しない場合か、指示ファイルを含む場合、デフォルトはallWritableです。
    		<targetAttributes readOnly="allReadOnly"/>

    <customDirectories>要素

    <customDirectories>要素には、パッケージマネージャがターゲットシステムにファイルをインストールする絶対パスの場所のリストを定義します。

    <customDirectories>には<customDirectory>子要素を定義できます。

    <customDirectory> 要素

    <customDirectory> 要素には、パッケージマネージャがファイルをインストールするターゲットシステム上のの絶対パスまたはネットワークパスを1つ定義します。

    指示ファイルには、<customDirectory> のインスタンスを複数含めることができます。

    属性名 タイプ 値 例
    name 文字列
    Windows ディレクトリ名に使用できる文字:
    • 小文字 (a～z)、数字 (0～9)、プラス記号 (+) およびマイナス記号 (-)、ピリオド (.) のみを含む
    • 英数字文字で始まる
    • 最小文字長は2
    • 最大文字長は58
    name 属性が以下の場合、エラーが発生します。
    • 既存のターゲットルートである
    • ni_ で始まる
    • 無効な文字が含まれている
    		 <customDirectory name="examplename1" path="D:\bin"/>
    path 文字列 ターゲットシステム上の絶対パスまたはネットワークパス <customDirectory name="examplename2" path="\\servername\sharename\subdir"/>

    <shortcuts>要素

    <shortcuts>要素は、パッケージマネージャがインストール中に作成するショートカットのリストを提供します。

    <shortcuts>には<shortcut>子要素が含まれています。

    <shortcut>要素

    <shortcut>要素は、パッケージマネージャがインストール中に作成する1つのショートカットを定義します。

    <shortcut>要素は指示ファイルではオプションですが、パッケージに必要な数だけ含めることができます。<shortcut>には2つの子要素が含まれています。
    • <destination>
    • <target>

    <destination>要素

    <destination>要素は、パッケージマネージャがショートカットファイルを作成する場所を指定します。

    <destination>は必須であり、1個または複数のオプションの<localizedDestination>子要素を持つことができます。以下の属性があります。

    属性名 タイプ 値 サンプル
    root 文字列 サポートされているターゲットルートです。 windows_allアーキテクチャのパッケージは、ProgramFiles_64またはLV2017DIR64などの64ビット専用のターゲットルートを使用できません。 <destination root="Startup" path="testShortcut.lnk"/>
    path 文字列 ルートターゲットに追加されたパスとファイル名です。構文の要件については、「引用符のXML構文規則」を参照してください。 <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

    <localizedDestination>要素

    <localizedDestination>要素は、特定の言語でファイルパッケージをインストールする際にショートカットファイルを使用するための代替のローカライズされたパスを指定します。

    <localizedDestination>は、空の要素であり、属性を持ちますが、要素やテキストコンテンツは含みません。以下の属性があります。

    属性名 タイプ 値 サンプルプログラム
    root 文字列 サポートされているターゲットルートです。 windows_allアーキテクチャのパッケージは、ProgramFiles_64やLV2017DIR64などの64ビット固有のターゲットルートを使用できません。 <localizedDestination root="ProgramMenu"/>
    path 文字列 ルートターゲットに追加されたパスとファイル名です。 <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" />
    language 文字列

    ローカライズされたパスの言語コードです。可能な値:

    • de
    • fr
    • ja
    • ko
    • zh-CN
    		<localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>

    <target>要素

    <target>要素は、パッケージマネージャがショートカットを作成するファイルの場所を指定します。

    <target>は、空の要素であり、属性はありますが、要素やテキスト内容は含まれていません。以下の属性があります。

    属性名 タイプ 値 サンプル
    root 文字列 サポートされているターゲットルートです。 windows_allアーキテクチャのパッケージは、ProgramFiles_64またはLV2017DIR64などの64ビット専用のターゲットルートを使用できません。 <target root="Startup" path="testShortcut.lnk"/>
    path 文字列 解決後にルートターゲットに追加されたパスとファイル名です。構文の要件については、「引用符のXML構文規則」を参照してください。 <target root="ProgramFiles" path="Shortcuts\test.exe"/>
    arguments 文字列 ターゲットファイルに渡されるオプションの引数です。構文の要件については、「引用符のXML構文規則」を参照してください。 <target root="ProgramFiles" path="Shortcuts\test.exe" arguments="--argument1"/>

    <returnCodeConventions>要素

    <returnCodeConventions>要素は、このパッケージのカスタムアクションを実行するときにパッケージマネージャが使用するカスタムリターンコード規約のリストの提供を行います。

    指示ファイル内の<returnCodeConventions>は任意ですが、1つまたは複数の<returnCodeConvention>子要素を含めることができます。

    <returnCodeConvention>要素

    <returnCodeConvention> 要素は、このパッケージ内の1つまたは複数のカスタム実行のリターンコードの解釈方法を定義します。

    <returnCodeConvention>は、1つまたは複数のオプションの<returnCode>子要素を持つことができます。<returnCode>ルールは、定義された順序で評価されます。

    属性名 タイプ 値 サンプルプログラム
    name 文字列 このリターンコード規則の固有の名前です。このパッケージのカスタム実行は、returnCodeConventionフィールドでこの名前を使用して、このリターンコード規則に関連付けることができます。 <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/>
    defaultResult 列挙体 既存のリターンコードのマッピングルールに一致しないリターンコードの意味的結果を示します。
    • success
    • failure
    • rebootRequired
    		 <returnCodeConvention name="ignore" defaultResult="success"/>

    <returnCode>要素

    <returnCode>要素は、親<returnCodeConvention>のリターンコードのマッピングルールを定義します。

    <returnCode>は、空の要素であり、属性を持ちますが、要素やテキストコンテンツは含みません。以下の属性があります。

    属性名 タイプ 値 サンプルプログラム
    min 整数 このルールが一致するリターンコード範囲の下限を示します。value属性と組み合わせることはできません。 <returnCode min="0" max="1024" result="success"/>
    max 整数 このルールが一致するリターンコード範囲の上限を示します。value属性と組み合わせることはできません。 <returnCode min="-50" max="-1" result="success"/>
    value 整数 このルールが一致する単一のリターンコードを示します。minまたはmax属性と組み合わせることはできません。 <returnCode value="1641" result="rebootRequired"/>
    result 列挙体 このルールに一致するリターンコードの意味的結果を示します。 <returnCode value="3010" result="rebootRequired"/>

    <customExecutes>要素

    <customExecutes>要素は、パッケージマネージャがパッケージで実行するカスタムアクションのリストを提供します。

    <customExecutes>には<customExecute>子要素が含まれています。

    <customExecute>要素

    <customExecute>要素は、パッケージマネージャがパッケージに対して実行する1つのカスタムアクションを定義します。

    指示ファイルでは<customExecute>要素はオプションですが、パッケージに必要な数だけ追加することができます。<customExecute>は空の要素で、属性を持ちますが、要素やテキストコンテンツは含みません。以下の属性があります。

    属性名 タイプ 必須 値 説明 サンプルプログラム
    root 文字列 はい 実行ファイルへのルートパスです。windows_allアーキテクチャのパッケージは、ProgramFiles_64やLV2017DIR64などの64ビット固有のターゲットルートを使用できません。 実行ファイルのルートパスを指定します。

    サポートされているターゲットルートサポートされている ターゲットルートについては、「インストール先のターゲットルート」を参照してください。

    メモ 実行ファイルを実行するには、実行ファイルが含まれているパッケージを最初にインストールする必要があります。ターゲットルートパスをNIPkgMgrTempUniqueに設定し、schedule属性をpostに設定すると、実行ファイルを一時的にインストールするようにパッケージを構成できます。パッケージマネージャは、パッケージをNIPkgMgrTempUniqueディレクトリにインストールし、そこから実行ファイルを実行した後、ファイルをディレクトリから削除します。
    		 <customExecute root="Documents" exeName="executable.exe"/>
    exeName 文字列 はい 実行ファイルのファイル名です。 実行ファイルのファイル名を指定します。

    ルートの相対パスを含めることができます。構文の要件については、「引用符のXML構文規則」を参照してください。

    		 <customExecute root="ProgramData" exeName="actions\executable.exe"/>
    arguments 文字列 いいえ 実行ファイルに渡すコマンドライン引数です。 パッケージマネージャが実行ファイルに渡すコマンドライン引数を指定します。
    値はフォーマットされています。サポートされているターゲットルートおよび以下の属性を含めることができます。
    メモ 引数では大文字と小文字が区別されます。構文の要件については、「引用符のXML構文規則」を参照してください。
  • %REBOOTPENDING%—保留中の再起動情報を渡します。トランザクションの終了時に再起動が必要な場合、パッケージマネージャは%REBOOTPENDING%を1に置き換えます。それ以外の場合、パッケージマネージャは%REBOOTPENDING%を0に置き換えます。この引数は、schedule属性の値がpostallの場合にのみ使用できます。
  • %NIPMLANGUAGECODE%—ISO言語コードを使用してパッケージマネージャを実行する言語を指定します。可能な値: en、de、fr、ko、ja、またはzh-CN。
    		•
    • <customExecute root="ProgramData" exeName="executable1.exe" arguments="-open %desktop%\file.txt"/>
    • <customExecute root="ProgramData" exeName="executable2.exe" arguments="-reboot %rebootpending%" schedule=postall/>
    • <customExecute root="ProgramData" exeName="executable3.exe" arguments="-language %nipmlanguagecode%"/>
    step 列挙体 いいえ
  • install —(デフォルト) パッケージマネージャは、パッケージをインストールするときに実行ファイルを実行します。
  • uninstall —パッケージマネージャは、パッケージを削除するときに実行ファイルを実行します。
  • reinstall —パッケージマネージャは、パッケージを修復するときに実行ファイルを実行します。
    		• パッケージマネージャが実行ファイルを実行する処理手順を指定します。
    • インストール、アンインストール、修復など、同じ実行ファイルを複数ステップで実行するには、ステップごとに<customExecute>要素をリストします。
    • この属性を省略した場合、パッケージマネージャはデフォルト値を使用します。
    メモ パッケージの開発の際、stepの値をuninstallに設定する場合は、パッケージマネージャがターゲットシステムからパッケージを削除できない状況を避けるために、ignoreErrorsの値をyに設定してください。
    		 <customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
    schedule 列挙体 いいえ
    • post (デフォルト)
    • pre
    • postall
    		パッケージマネージャが実行ファイルを実行するときの処理手順内の相対的なポイントを指定します。

    この属性を省略した場合、パッケージマネージャはデフォルト値を使用します。

    		 <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
    wait Boolean いいえ
    • n (デフォルト)
    • y
    		カスタム動作が同期かどうかを指定します。同期では、パッケージマネージャは動作が完了するまで待機してから続行し、非同期では、パッケージマネージャは待機しません。

    この属性を省略した場合、パッケージマネージャはデフォルト値を使用します。

    		 <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
    ignoreErrors Boolean いいえ
    • n (デフォルト)
    • y
    		実行ファイルを実行できない場合、または実行ファイルが0以外の値を返した場合、パッケージマネージャがエラーを報告するかどうかを指定します。
    • パッケージマネージャが戻りコードの受信を待機するように、waitの値をyに設定する必要があります。
    • この属性を省略した場合、パッケージマネージャはデフォルト値を使用します。
    • この属性は、ignoreLaunchErrorsまたはreturnCodeConventionと組み合わせて使用することはできません。
    		 <customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
    hideConsoleWindow Boolean いいえ
    • n (デフォルト)
    • y
    		コンソールアプリケーションのコンソールウィンドウを非表示にするかどうかを指定します。
    • GUIアプリケーションの実行時にコンソールメッセージを表示しません。
    • コンソールアプリケーションは実行されますが、ユーザ入力やメッセージ出力用のコンソールウィンドウは表示されません。
    • この属性を省略した場合、パッケージマネージャはデフォルト値を使用します。
    • アプリケーションが追加のコンソールウィンドウを作成することを回避できません。
    		 <customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>
    ignoreLaunchErrors Boolean いいえ
    • n (デフォルト)
    • y
    		実行ファイルを実行できない場合、または実行ファイルが見つからない場合、パッケージマネージャがエラーを報告するかどうかを指定します。この属性は、ignoreErrorsと組み合わせて使用することはできません。 <customExecute root="ProgramData" exeName="executable.exe" ignoreLaunchErrors="y"/>
    returnCodeConvention 文字列 いいえ 事前定義された規則またはこのパッケージで定義された<returnCodeConvention>要素の名前と一致する必要があります。以下の事前定義された規則を使用できます。
    • console (デフォルト)
    • installer
    • ignore
    		 実行ファイルが返すリターンコードの解釈方法を示します。
    • waitはyに設定されている必要があるため、エージェントはリターンコードを受信待機します。
    • consoleは、0 = success およびその他の値はエラーです。
    • installerは、0 = success、1641 = reboot required、 3010 = rebootは必須、その他の値はエラーです。
    • では、パッケージマネージャはリターンコードを無視します。
    • この属性は、ignoreErrorsと組み合わせて使用することはできません。
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    Postallとしてスケジュールされた実行ファイルの動作

    schedule="postall"である<customExecute>要素が含まれている指示ファイルがある場合、パッケージマネージャはパッケージのインストールに影響を与える可能性のある特定の動作を実行します。

    postall値は、すべてのパッケージのインストール、再インストール、および/または削除手順を完了した後で実行ファイルを実行するようパッケージマネージャに指示します。

    • パッケージマネージャは、パッケージのインストールに指定された順序でpostall実行ファイルを実行します。依存項目が最初にインストールされます。
    • パッケージ内のpostall実行ファイルのみが失敗した場合、パッケージマネージャはそのパッケージがインストールされたとみなします。
    • postall実行ファイルが含まれているパッケージが複数ある場合、パッケージマネージャは、1つのpostall実行ファイルが失敗すると、残りの実行ファイルを実行しません。インストール中にそれ以外のエラーが発生しない限り、パッケージはインストールされたとみなされます。
    • MSIの障害またはpreまたはpostとしてスケジュールされた実行ファイルの失敗によりパッケージのインストールに失敗した場合、パッケージマネージャはパッケージのインストールに失敗したことを示すエラーメッセージを表示します。次に、インストールされたパッケージのすべての実行ファイルを、インストールが失敗した時点まで実行します。パッケージマネージャは、壊れたパッケージをインストールされたとみなさず、そのパッケージのpostall実行ファイルは実行されません。障害の発生前にインストールされたパッケージはすべてインストールされたままとなり、パッケージマネージャは、それらのパッケージのpostall実行ファイルを実行します。

    引用符のXML構文規則

    Microsoftの条件付きステートメント構文に準拠し、スペースが含まれているパスを引用符で囲むには、引用符のXML構文規則を確認してください。

    Microsoftの条件文の構文に準拠するには、リテラルテキストを引用符で囲む必要があります。指示XML構文では、この要件に準拠する方法が2つあります。

    • 一重引用符を使用してXML文字列を区切ります。これにより、文字列内で二重引用符を使用できます。以下に例を示します。
      <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • XML文字列内のリテラルテキストを区切るには、二重引用符のXMLエスケープ文字 &quot; を使用します。XMLエスケープ文字を使用することにより、二重引用符または一重引用符を使用してXML文字列を区切ることができます。以下に例を示します。
      <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    スペースが含まれているパスは引用符で囲む必要があります。パスに一重引用符は使用することはできません。

    • XML文字列のパスを囲む二重引用符には、XMLエスケープ文字 &quot; を使用してください。以下に例を示します。
      <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    カスタム実行の例

    次の例は、PowerShellスクリプトを呼び出して、パッケージがインストールし、インストール後に2つの引数を渡します。

    <customExecute root="BootVolume" exeName="Windows\System32\WindowsPowerShell\v1.0\powershell.exe" arguments="-File &quot;%ProgramData%\My App Name\MyInstallScript.ps1&quot; &quot;argument 1&quot; &quot;argument 2&quot;" step="install" schedule="post" wait="y" ignoreErrors="n" hideConsoleWindow="y" />

    <osUninstallEntry>要素

    <osUninstallEntry>要素は、パッケージをプログラムの追加と削除インタフェースに表示するためのオプションの手順を提供します。

    <osUninstallEntry>は空の要素です。つまり、属性を持ちますが、要素やテキストコンテンツは含みません。<osUninstallEntry>は以下の属性を持ちます。

    属性名 タイプ 可能な値 詳細 サンプルプログラム
    ux 列挙体
  • ni —(デフォルト) 変更またはアンインストール操作中に、通常のパッケージマネージャジャインタフェース要素を表示します。
  • oem —変更またはアンインストール操作中に、NIを参照するすべてのダイアログテキストとリンクを非表示にします。
    		• 他社製パッケージの場合、値oemを使用することで、インストールされているアプリケーションのリストにパッケージを第1クラス項目として表示できます。変更およびアンインストール操作を実行する場合、プログラムの追加と削除インタフェースでは名前付きのパッケージのみが参照されます。 <osUninstallEntry ux="oem"/>