Home Support NI Product Manuals NI Package Manager 19.6 Manual

Table Of Contents

Instructions XML for File Packages

Download Manual | Offline Viewer Required
Version:
Last Modified: August 12, 2019

The optional Instructions XML file you create provides Package Manager with instructions for customized execution of package installation.

The instructions XML file consists of a root <instructions> element with three child elements. Each child element is optional.
  • <targetAttributes>
  • <shortcuts>
  • <customExecutes>

Name the instructions XML file instructions, omit the file extension, and place it in the root of the data directory of a File package.

The following text is an example instructions file for a File package. 

<instructions>
    <targetAttributes readOnly="allReadOnly"/>
    <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> Element

The <targetAttributes> element provides optional instructions regarding locations where Package Manager installs files on the target system.

<targetAttributes> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

Attribute Name Type Possible Values Details Examples
readOnly Enum
  • allWritable—(default) Makes all package files for installation writable regardless of the original source file's read-only attribute value.
  • allReadOnly—Makes all package files for installation read-only regardless of the original source file's read-only attribute value.
  • keepSource—Keeps the original source file's read-only attribute value when installing.
  • Declares to Package Manager whether to make all files read-only, file-writable, or to keep the read-only attribute value from the original source file.
  • The default is allWritable when you do not declare a readOnly attribute or include an instructions file.
<targetAttributes readOnly="allReadOnly"/>

<shortcuts> Element

The <shortcuts> element provides a list of shortcuts that Package Manager creates during installation.

<shortcuts> contains the <shortcut> child element.

<shortcut> Element

The <shortcut> element defines one shortcut that Package Manager creates during installation.

The <shortcut> element is optional in the Instructions file, but you can include as many as needed for your package. <shortcut> contains two child elements:
  • <destination>
  • <target>

<destination> Element

The <destination> element specifies the location where Package Manger creates a shortcut file.

<destination> is required and can have one or more optional <localizedDestination> child elements. It has the following attributes:

Attribute Name Type Value Examples
root String A supported target root. Packages with a windows_all or windows_x86 architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <destination root="Startup" path="testShortcut.lnk"/>
path String The path and file name appended to the root target. <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

<localizedDestination> Element

The <localizedDestination> element specifies an alternate localized path to use for the shortcut file when installing the file package in a given language.

<localizedDestination> is an empty element, meaning that is has attributes, but does not contain elements or text content. It has the following attributes:

Attribute Name Type Value Examples
root String A supported target root. Packages with a windows_all or windows_x86 architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <localizedDestination root="ProgramMenu"/>
path String The path and file name appended to the root target. <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" />
language String

Language code of the localized path. Possible values:

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

<target> Element

The <target> element specifies the location of the file for which Package Manager creates a shortcut.

<target> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

Attribute Name Type Value Examples
root String A supported target root. Packages with a windows_all or windows_x86 architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <target root="Startup" path="testShortcut.lnk"/>
path String The path and file name appended to the root target after it is resolved. <target root="ProgramFiles" path="Shortcuts\test.exe"/>

<customExecutes> Element

The <customExecutes> element provides a list of custom actions for Package Manager to perform on the package.

<customExecutes> contains the <customExecute> child element.

<customExecute> Element

The <customExecute> element defines one custom action Package Manager performs on the package.

The <customExecute> element is optional in the Instructions file, but you can include as many as needed for your package.<customExecute> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

Attribute Name Type Required Value Description Details Examples
root String Yes The root path to the executable. Packages with a windows_all or windows_x86 architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. Specifies the root path to the executable.

A supported target root.

spd-note-note
Note  

To run an executable, you must first install the package that includes the executable. You can configure a package to temporarily install the executable by setting the target root path to NIPkgMgrTempUnique and setting the schedule attribute to post. Package Manager then installs the package to the NIPkgMgrTempUnique directory and runs the executable from there before deleting files in the directory.

<customExecute root="Documents" exeName="executable.exe"/>
exeName String Yes The file name of the executable. Specifies the file name of the executable. Can include a path relative to the root. <customExecute root="ProgramData" exeName="actions\executable.exe"/>
arguments String No Command line arguments to pass to the executable. Specifies command line arguments for Package Manager to pass to the executable. The value is formatted. You can include a supported target root and/or the following arguments:
spd-note-note
Note  

The arguments are case insensitive.

  • %REBOOTPENDING%—Passes pending reboot information. If a reboot is required at the end of the transaction, Package Manager replaces %REBOOTPENDING% with 1. Otherwise, Package Manager replaces %REBOOTPENDING% with 0. You can use this argument only if the value of the schedule attribute is postall.
  • %NIPMLANGUAGECODE%—Specifies the language in which Package Manager runs using the ISO language code. Possible values: en, de, fr, ko, ja, or 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 Enum No
  • install—(default) Package Manager runs the executable when installing the package.
  • uninstall—Package Manager runs the executable when removing the package.
  • reinstall—Package Manager runs the executable when repairing the package.
Specifies the transaction step during which Package Manager runs the executable.
  • To run the same executable in multiple steps, such as install, uninstall, and reinstall, list a <customExecute> element for each step.
  • If you omit this attribute, Package Manager uses its default value.
spd-note-note
Note  

During the development of a package, if you set the value of step to uninstall, set the value of ignoreErrors to y in order to avoid a situation where Package Manager cannot remove a package from the target system.

<customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
schedule Enum No
  • post (default)
  • pre
  • postall
Specifies the relative point within the transaction steps when Package Manager runs the executable. If you omit this attribute, Package Manager uses its default value. <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
wait Boolean No
  • n (default)
  • y
Specifies whether the custom action is synchronous, where Package Manager should wait for it to finish before continuing, or asynchronous, where Package Manager should not wait. If you omit this attribute, Package Manager uses its default value. <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
ignoreErrors Boolean No
  • n (default)
  • y
Specifies whether Package Manager reports an error if it cannot run the executable or the executable returns a value other than 0.
  • Requires you to set the value of wait to y so Package Manager will wait to receive the return code.
  • If you omit this attribute, Package Manager uses its default value.
<customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
hideConsoleWindow Boolean No
  • n (default)
  • y
Specifies whether to hide the console window for console applications.
  • Does not display console messages when you run GUI applications.
  • Console applications still run, but without a console window for user input or message output.
  • If you omit this attribute, Package Manager uses its default value.
<customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>

Behavior of Executables Scheduled as Postall

For Instructions files in which you include a <customExecute> element where schedule="postall", Package Manager demonstrates specific behaviors that may affect package installation.

The postall value instructs Package Manager to run the executable after completing the installation, reinstallation, and/or removal steps for all packages.

  • Package Manager runs postall executables in the specified order of package installation. Dependencies install first.
  • If only a postall executable in a package fails, Package Manager considers the package installed.
  • When there are multiple packages with postall executables, Package Manager does not run the remaining executables if one of the postall executables fails. Packages are considered installed assuming no other errors occurred during installation.
  • If installation of a package fails, either through MSI failure or failure of an executable scheduled as pre or post, Package Manager displays an error message stating that the package failed to install. Next, it runs all the executables from packages installed up to the point where installation failed. Package Manager does not consider the broken package installed and does not run the postall executables of the broken package. All packages installed before the failure occurred remain installed and Package Manager runs the postall executables of these packages.

Recently Viewed Topics