Home Support NI Product Manuals NI Package Manager 18.0 Manual

Table Of Contents

Instructions XML for File Packages

Download Manual | Offline Viewer Required
Version:
Last Modified: November 20, 2017

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 bitness="64" readOnly="allReadOnly"/>
    <shortcuts>
        <shortcut>
            <destination root="Desktop" path="myShortcut.lnk"/>
            <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
bitness Enum
  • Indicates whether the package is built for 32-bit or 64-bit Windows architectures.
  • Use when installing files to Program Files or System32. This value is ignored for other directories.
<targetAttributes bitness="32"/>
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 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 Any supported installation root target. <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"/>

<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 Any supported installation root target. <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. Specifies the root path to the executable.

Must be a supported root path.

spd-note-note
Note  

Package Manager cannot run an executable directly from the package. Package Manager must install the executable to a directory first and then run it from there. For example, install the payload to temp and set the root value to temp.

<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, so you can include a supported root path. <customExecute root="ProgramData" exeName="executable1.exe" arguments="-open %desktop%\file.txt"/>
step Enum No
  • install (default)
  • uninstall
Specifies the transaction step during which Package Manager runs the executable.
  • If you want Package Manager to run the same executable on both install and uninstall, list two <customExecute> elements.
  • Package Manager also runs install actions when repairing the package.
  • 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 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, but still runs its postall executables. All packages installed before the failure occurred remain installed.

Recently Viewed Topics