Instructions XML文件为Package Manager提供程序包安装的定制化运行选项。

Instructions XML文件由根<instructions>元素与几个子元素组成。子元素都是可选的。
  • <targetAttributes>
  • <customDirectories>
  • <shortcuts>
  • <returnCodeConventions>
  • <customExecutes>
  • <osUninstallEntry>

将Instructions XML文件命名为instructions，忽略文件扩展名，将其放在文件程序包的data根目录下。

以下是文件程序包的Instructions文件示例。 

<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>提供了Package Manager在目标位置安装文件的位置选项。

<targetAttributes>是一个空元素，表示其有属性，但是不包含元素或文本内容。该元素具有以下属性：

属性名称 类型 可能值 详细信息 范例
readOnly 枚举
  • allWritable —（默认）无论源文件的读写属性如何，将安装程序包都设置为可写文件。
  • allReadOnly —无论源文件的读写属性如何，将安装程序包都设置为只读文件。
  • keepSource —在安装时保留原始源文件的读写属性。
    • 向Package Manager声明是否将所有文件设置为只读、可写，或保留源文件的只读属性。
    • 如果不声明readOnly，或提供Instruction文件，默认选项为allWritable。
    		<targetAttributes readOnly="allReadOnly"/>

    <customDirectories>元素

    <customDirectories>元素提供Package Manager在目标系统上安装文件的绝对路径位置列表。

    <customDirectories>包含<customDirectory>子元素。

    <customDirectory>元素

    <customDirectory>元素定义Package Manager在目标系统上安装文件的绝对路径或网络路径。

    Instructions文件中可以包含<customDirectory>的多个实例。

    属性名称 类型 值 范例
    name 字符串
    有效的Windows目录名称字符：
    • 只能包含小写字母(a-z)、数字(0-9)、加号(+)、减号(-)和句号(.)
    • 必须以字母、数字开头
    • 必须至少包含两个字符
    • 最长不得超过58个字符
    如果name属性是以下情况，会产生错误：
    • 是现有的目标根
    • 以ni_开头
    • 包含无效字符
    		 <customDirectory name="examplename1" path="D:\bin"/>
    path 字符串 目标系统上的绝对路径或网络路径 <customDirectory name="examplename2" path="\\servername\sharename\subdir"/>

    <shortcuts>元素

    <shortcuts>元素定义了Package Manager在安装的同时创建快捷方式的列表。

    <shortcuts>包含<shortcut>子元素。

    <shortcut>元素

    <shortcut>元素定义了Package Manager在安装的同时创建一个快捷方式。

    <shortcut>元素是Instructions文件的可选内容，可在文件里包含程序包所需的任意数量该元素。<shortcut>包含两个子元素：
    • <destination>
    • <target>

    <destination>元素

    <destination>元素指定Package Manager创建的快捷方式所在的位置。

    <destination>是必需的属性，可以有一个或多个<localizedDestination>子属性。该元素具有以下属性：

    属性名称 类型 值 范例
    root 字符串 支持的目标根目录。具有windows_all架构的程序包无法使用64位特定目标根目录，例如ProgramFiles_64或LV2017DIR64。 <destination root="Startup" path="testShortcut.lnk"/>
    path 字符串 安装根目录后面的路径和文件名称。关于语法要求，请参考 引号的XML语法规则。 <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

    <localizedDestination>元素

    <localizedDestination>元素指定使用指定语言安装文件程序包时，快捷方式文件使用的其他本地化路径。

    <localizedDestination>是一个空元素，表示其有属性，但是不包含元素或文本内容。该元素具有以下属性：

    属性名称 类型 值 范例
    root 字符串 支持的目标根目录。具有windows_all架构的程序包无法使用64位特定目标根目录，例如ProgramFiles_64或LV2017DIR64。 <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>元素指定Package Manager创建的快捷方式指向文件的位置。

    <target>是一个空元素，表示其有属性，但是不包含元素或文本内容。该元素具有以下属性：

    属性名称 类型 值 范例
    root 字符串 支持的目标根目录。具有windows_all架构的程序包无法使用64位特定目标根目录，例如ProgramFiles_64或LV2017DIR64。 <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>元素提供Package Manager执行该程序包自定义操作时使用的自定义返回代码规范列表。

    <returnCodeConventions>在Instructions文件中是可选的，但可以包含一个或多个<returnCodeConvention>子元素。

    <returnCodeConvention>元素

    <returnCodeConvention>元素定义如何解译此程序包中一个或多个自定义执行的返回代码。

    <returnCodeConvention>可包含一个或多个可选的<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>元素提供了Package Manager在软件包上执行的自定义操作。

    <customExecutes>包含<customExecute>子元素。

    <customExecute>元素

    <customExecute>元素定义Package Manager对程序包执行的一个自定义操作。

    <customExecute>是Instructions文件中的可选元素，可在程序包中包含任意所需数量的该元素。<customExecute>是空元素，表示该元素有属性，但是不包含元素或文本内容。该元素具有以下属性：

    属性名称 类型 必需 值 说明 范例
    root 字符串 是 可执行文件的根路径。具有windows_all架构的程序包无法使用64位特定目标根目录，例如ProgramFiles_64或LV2017DIR64。 指定可执行文件的根路径。

    支持的目标根目录。请参考安装目标根目录了解支持的目标根目录。

    备注 如要运行可执行文件，必须先安装包含可执行文件的程序包。通过将目标根路径设置为NIPkgMgrTempUnique并将schedule属性设置为post，可配置程序包临时安装可执行文件。然后，Package Manager将程序包安装到NIPkgMgrTempUnique目录，并运行可执行文件，最后删除目录中的文件。
    		 <customExecute root="Documents" exeName="executable.exe"/>
    exeName 字符串 是 可执行文件的文件名。 指定可执行文件的文件名。

    可以包含一个相对于根目录的路径。关于语法要求，请参考 引号的XML语法规则。

    		 <customExecute root="ProgramData" exeName="actions\executable.exe"/>
    arguments 字符串 否 传递给可执行文件的命令行参数。 指定Package Manager传递给可执行文件的命令行参数。
    值格式化。可包括一个支持的目标根目录，和/或下列参数：
    备注 参数区分大小写。关于语法要求，请参考 引号的XML语法规则。
  • %REBOOTPENDING%—传递即将进行的重启信息。如果在操作结束时需要重新启动，Package Manager会将%REBOOTPENDING%替换为1。否则，Package Manager会将%REBOOTPENDING%替换为0。仅当schedule属性的值为postall时，才可使用该参数。
  • %NIPMLANGUAGECODE%—指定NI Package Manager使用的语言代码。可能值：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 —（默认）NI Package Manager仅在安装程序包时运行可执行文件。
  • uninstall —NI Package Manager在移除程序包时运行可执行文件。
  • reinstall —NI Package Manager在修复程序包时运行可执行文件。
    		• 指定执行何种操作时Package Manager运行可执行文件。
    • 要在多个步骤（例如，安装、卸载和修复）中运行同一个可执行文件，请为每个步骤列出一个<customExecute>元素。
    • 如忽略该属性，Package Manager使用默认值。
    备注 在开发程序包时，如果将step的值设置为uninstall，将ignoreErrors的值设置为y，可避免Package Manager无法从目标系统中移除程序包的情况发生。
    		 <customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
    schedule 枚举 否
    • post（默认）
    • pre
    • postall
    		指定Package Manager在某个操作步骤上运行可执行文件。

    如忽略该属性，Package Manager使用默认值。

    		 <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
    wait 布尔 否
    • n（默认）
    • y
    		指定自定义操作是否同步或异步。同步时，Package Manager应该等待自定义操作结束后才继续。异步时，Package Manager不做任何等待。

    如忽略该属性，Package Manager使用默认值。

    		 <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
    ignoreErrors 布尔 否
    • n（默认）
    • y
    		如无法运行可执行文件或可执行文件返回非0值，Package Manager是否报告错误。
    • 要求用户将wait的值设置为y，以便Package Manager等待接收返回代码。
    • 如忽略该属性，Package Manager使用默认值。
    • 该属性不能与ignoreLaunchErrors或returnCodeConvention组合使用。
    		 <customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
    hideConsoleWindow 布尔 否
    • n（默认）
    • y
    		指定是否为控制台应用程序银行控制台窗口。
    • 运行GUI应用程序时，不显示控制台消息。
    • 控制台应用程序仍运行，但没有控制台窗口用于用户输入或消息输出。
    • 如忽略该属性，Package Manager使用默认值。
    • 不会阻止应用程序创建其他控制台窗口。
    		 <customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>
    ignoreLaunchErrors 布尔 否
    • n（默认）
    • y
    		指定Package Manager无法运行或无法找到可执行文件时是否报错。该属性不能与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，其他任何值都是错误的。
    • 对于ignore，Package Manager将忽略返回代码。
    • 该属性不能与ignoreErrors组合使用。
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    Postall可执行程序

    如Instructions文件中包含<customExecute>元素，元素的属性为schedule="postall"，会影响Package Manager生成的程序包的安装过程。

    postall值表示Package Manager在完成安装、再次安装、卸载步骤后运行可执行文件。

    • Package Manager按照程序包安装的指定顺序运行postall可执行文件。首先安装依赖项。
    • 如果程序包中只有一个postall可执行文件失败，Package Manager认为程序包成功安装。
    • 当有包含postall可执行文件的多个程序包，如果一个postall可执行文件运行失败，Package Manager不运行其余的可执行文件。如果没有其他错误发生，则认为程序包已成功安装。
    • 如安装程序包失败，无论是MSI出错还是pre或post, 可执行文件出错，Package Manager将显示错误消息，表示程序包安装失败。然后，Package Manager运行程序包中的所有可执行文件。NI Package Manager不认为破损的程序包已被安装，也不在破损的程序包上运行postall可执行文件。错误发生前完成安装的程序包为已安装状态。NI Package Manager将为这些程序包运行postall可执行文件。

    引号的XML语法规则

    查看引号的XML语法规则以确保符合Microsoft的条件语句语法，并将路径用引号括起来。

    必须将literal文本包含在引号内，以符合Microsoft条件语句的语法。Instructions XML语法提供了两种途径：

    • 使用单引号分隔XML字符串。允许在字符串内使用双引号。例如：
      <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • 使用双引号的XML转义符&quot;分隔XML字符串中的literal文本。通过XML转义字符，您可以使用双引号或单引号来分隔XML字符串。例如：
      <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    如路径中包含空格，将路径用引号括起来。路径中不允许使用单引号：

    • 使用双引号的XML转义符&quot;，将路径括起来。例如：
      <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    自定义执行范例

    以下代码调用程序包可能已安装的PowerShell脚本，并在安装后传递两个参数。

    <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 —（默认）在修改或卸载操作中显示常规Package Manager界面元素。
  • oem —在修改或卸载操作过程中，隐藏所有对话框文本和指向NI的链接。
    		• 对于第三方程序包，oem值允许程序包在已安装的应用程序列表中显示为一级项。执行修改和卸载操作时，添加/删除程序界面只指向已命名的程序包。 <osUninstallEntry ux="oem"/>