The optional Instructions XML file you create provides Package Manager with instructions for customized execution of MSIs and executables. WinInst packages without an instructions file run all MSIs in ascending ASCII order by file name.

The instructions XML file consists of a root <instructions> element with three child elements. Each child element is optional.
  • <upgrade>
  • <msis>
  • <returnCodeConventions>
  • <customExecutes>
Name the instructions XML file instructions, omit the extension, and place it in the root of the data directory of a WinInst package.

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

<instructions>
    <msis>
        <msi name="Setup.msi">
            <property name="ADDLOCAL" value="ALL"/>
            <langFile language="de">transform1.mst</langFile>
            <langFile language="fr">transform2.mst;transform3.mst</langFile>
            <langFile language="ja">transform4.mst</langFile>
            <langFile language="ko">transform5.mst</langFile>
            <langFile language="zh-CN">transform6.mst</langFile>
        </msi>
        <msi name="Setup64.msi">
            <property name="ADDLOCAL" value="ALL"/>
        </msi>
    </msis>
</instructions>

<upgrade> Element

The <upgrade> element specifies how a package upgrades a previous version of itself.

The following enum values are valid inside the <upgrade> tags:

Value Description Example
clean Package Manager removes the old version of the package before installing the new version of the package. This is the default behavior when the element value is blank. <upgrade>clean</upgrade>
native Package Manager installs the new version of the package before removing the old version of the package. (The MSI performs its native upgrade behavior.) <upgrade>native</upgrade>

<msis> Element

The <msis> element provides a list of MSI files in the package.

<msis> contains the <msi> child element.

Package Manager runs the MSIs in the order in which you include them in the list. If you do not list any MSIs here, Package Manager runs all MSIs in the package data directory in no particular order and without conditions, properties, or transforms.

Note When you list any MSIs within the <msis> element, Package Manager runs only the MSIs you include on the list and ignores any other MSIs in the package data directory.

<msi> Element

The <msi> element represents one MSI in the package, along with conditions for running the MSI, properties to set to the MSI, and transforms to apply to the MSI.

The <msi> element is optional in the Instructions file, but you can include as many as needed for your package. List MSIs using one <msi> element for each MSI. <msi> contains the <property> element.

It has the following attributes:

Attribute Name Type Required Description Examples
name String Yes
  • Specifies the path to the MSI, relative from the root of the data directory, including its file name.
  • The path value is case sensitive.
<msi name="temp\example.msi"/>
condition WinInst Condition No
  • Specifies an MSI condition for Package Manager to evaluate before installing the MSI.
  • The value must be a valid MSI condition string. To include quotes in a condition, use single quotes.
  • If you specify a condition, you must include a Depends relationship in your control file that declares a dependency on the ni-msiproperties package of the minimum version you require.
  • Package Manager will install the MSI only on a system where the statement evaluates to TRUE.
  • Packages install only once. If conditions are TRUE, the MSI must install all its features. If conditions are FALSE, the MSI does not install anything.
  • At least one MSI in the instructions file must have a TRUE condition, or else Package Manager does not record that the package is installed.
Note If you specify any condition, property, or command-line in your instructions file, you must declare a dependency on the ni-msiproperties package of the minimum version that you require.
<msi name="example.msi" condition="(VersionNT64 = 601) AND (NIRUNNINGINSILENTMODE)"/>
skipUninstall Boolean No
  • Specifies whether the MSI should not uninstall when its package is uninstalled. The attribute can be one of the following values:
    • n (default)
    • y
  • Consider using this attribute for a package that installs a third-party MSI to prevent the package from removing the MSI when the MSI can be installed separately without the package.
 <msi name="temp\example.msi" skipUninstall="y"/>

<property> Element

The <property> element specifies a property (name-value pair) that Package Manager passes to the MSI engine for this MSI.

Refer to Properties and Conditions in WinInst Packages for a list of supported properties, as well as rules and guidelines.

Attribute Name Type Required Possible Values Description Examples
name string Yes All uppercase string that follows the MSI naming rules for properties.

Specifies the name of the property that Package Manager passes to the MSI when running it.

Note If you specify any condition, property, or command-line in your instructions file, you must declare a dependency on the ni-msiproperties package of the minimum version that you require.
<property name="INSTALLLEVEL" value="1000"/>
value WinInst condition Yes The value of the property.
  • Specifies the value of the property that Package Manager passes to the MSI when running it.
  • The value can be a property in brackets to indicate that Package Manager should evaluate the property at run-time and replace it with the actual value.
<property name="MYLANGCODE" value="[NIPMLANGUAGECODE]"/>
step Enum No
  • install —(default) Package Manager applies the property when installing the package.
  • reinstall —Package Manager applies the property when repairing the package.
  • uninstall —Package Manager applies the property when removing the package.
    • Specifies the type of transaction during which Package Manager applies the property.
    • If Package Manager should apply the property during multiple steps, list multiple <property> elements.
    • If you omit this attribute, Package Manager uses its default value.
    		<property name="INSTALLLEVEL" value="1000" step="install"/>

    <langFile> Element

    The <langFile> element specifies the transforms to pass to the MSI. You can include multiple transform files for each language by delimiting the transform files with semicolons. The transform files must be in the same directory as the MSI files, and the transform file path is a relative path of the package data directory. For example, if the MSI file path is foo\bar.msi, the transform file path must be foo\transform filename.mst.

    Attribute Name Type Required Possible Values Description Examples
    language Enum Yes
    • de
    • fr
    • ja
    • ko
    • zh-CN

    Specifies the ISO language code of the language in which Package Manager runs.
    • <langFile language="de">transform1.mst</langFile>
    • <langFile language="zh-CN">transform2.mst;transform3.mst</langFile>

    <returnCodeConventions> Element

    The <returnCodeConventions> element provides a list of custom return code conventions for Package Manager to use when performing custom actions for this package.

    <returnCodeConventions> is optional in the instructions file, but can contain one or more <returnCodeConvention> child elements.

    <returnCodeConvention> Element

    The <returnCodeConvention> element defines how to interpret a return code for one or more custom executes in this package.

    <returnCodeConvention> can have one or more optional <returnCode> child elements. <returnCode> rules are evaluated in the order they are defined.

    Attribute Name Type Value Examples
    name String A unique name for this return code convention. A custom execute in this package can use this name in its returnCodeConvention field to associate itself with this return code convention. <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/>
    defaultResult Enum Indicates the semantic result of a return code that does not match any existing return code mapping rules.
    • success
    • failure
    • rebootRequired
    		 <returnCodeConvention name="ignore" defaultResult="success"/>

    <returnCode> Element

    The <returnCode> element defines a return code mapping rule for its parent <returnCodeConvention>.

    <returnCode> 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
    min Integer Indicates the lower bound of a range of return codes this rule matches. May not be combined with the value attribute. <returnCode min="0" max="1024" result="success"/>
    max Integer Indicates the upper bound of a range of return codes this rule matches. May not be combined with the value attribute. <returnCode min="-50" max="-1" result="success"/>
    value Integer Indicates a single return code this rule matches. May not be combined with the min or max attributes. <returnCode value="1641" result="rebootRequired"/>
    result Enum Indicates the semantic result of a return code matching this rule. <returnCode value="3010" result="rebootRequired"/>

    <customExecutes> Element

    The <customExecutes> element provides a list of executables associated with the package.

    <customExecutes> contains the <customExecute> child element.

    <customExecute> Element

    The <customExecute> element provides Package Manager with conditions for running the executable, when to run the executable, arguments to pass to the executable, and how to handle the executable's errors and user interface.

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

  • When—The timing of the executable relative to the transaction step. When attributes are optional.
  • Why—The conditions that determine if Package Manager runs the executable. Why attributes are optional.
  • What—The location of the executable and, if necessary, any arguments Package Manager passes to it. Individually, each What attribute is optional. However, you must use one What attribute to specify the location of the executable.
  • How—The manner in which Package Manager handles errors and progress. How attributes are optional.
    • Table 2. When Attributes
    Attribute Name Type Possible Values Description Example
    step Enum
  • 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 repair, list a <customExecute> element for each step.
    • If you omit this attribute, Package Manager uses its default value.
    Note If you set the value of inPackage to y, you must set the value of step to install or omit the attribute. (See the inPackage attribute below.)
    		 <customExecute step="uninstall" exeName="[NIDIR]\actions\executable.exe"/>
    schedule Enum
  • post —(default) Package Manager runs the executable immediately after completing the transaction step for the current package.
  • pre —Package Manager runs the executable immediately before completing the transaction step for the current package.
  • postall —Package Manager runs the executable after completing the transaction steps for all packages.
  • preall—Package Manager runs the executable before completing the transaction steps for all packages. Valid only when you set the value of step to uninstall.
    		• Specifies the relative point within the transaction steps when Package Manager runs the executable.
    • If the value of <upgrade> is clean, Package Manager runs a <customExecute> with attribute values step="install" and schedule="pre" after removing the old package and before installing the new package.
    • If you omit this attribute, Package Manager uses its default value.
    Note If you set the value of the inPackage attribute to y, you must set the value of schedule to pre or post, or omit the attribute. (See the inPackage attribute below.)
    		 <customExecute step="install" schedule="post" exeName="[NIDIR]\executable.exe"/>
    Table 3. Why Attributes
    Attribute Name Type Possible Value Description Example
    condition WinInst condition The condition for the MSI. Specifies an MSI condition for Package Manager to evaluate before running the executable.
    • Package Manager runs this executable only on a system where the statement evaluates to TRUE. Refer to Properties and Conditions in WinInst Packages for a list of syntax requirements and supported NIPaths.
    • If you omit this attribute, the executable always runs.
    Note If you specify any condition, property, or command-line in your instructions file, you must declare a dependency on the ni-msiproperties package of the minimum version that you require.
    		 <customExecute exeName="[NIDIR]\executable.exe" condition="VersionNT &gt;=600"/>
    Table 4. What Attributes
    Attribute Name Type Possible Values Description Example
    arguments String Command line arguments to pass to the executable. Specifies command line arguments for Package Manager to pass to the executable.
    • This is a formatted value, so you can include a ni-msiproperties directory property in brackets. Refer to Properties and Conditions in WinInst Packages for a list of syntax requirements and supported properties.
    • If you include the full path to the executable, omit the exeName attribute.
    Note If you specify any condition, property, or command-line in your instructions file, you must declare a dependency on the ni-msiproperties package of the minimum version that you require.
    		 <customExecute exeName="[ProgramFilesFolder]\executable.exe" arguments="-listall"/>
    formatArguments Boolean
    • n (default)
    • y
    		 Specifies whether the arguments attribute contains strings that the MSI engine needs to resolve.
    If you set the value of this attribute to y, you must include a Depends relationship in your control file that declares a dependency on the ni-msiproperties package of the minimum version you require.
    Note If you specify any condition, property, or command-line in your instructions file, you must declare a dependency on the ni-msiproperties package of the minimum version that you require.
    		 <customExecute exeName="[ProgramFilesFolder]\executable.exe" arguments="[NIDIR]" formatArguments="y"/>
    exeName String The path and file name of the executable. Specifies the path and the file name of the executable. This value is case-sensitive.
    • If the value of inPackage is n or undefined, exeName must contain an ni-msiproperties property and not a hard-coded path.
    • If you specify an ni-msiproperties property, you must include a depends relationship in your control file that declares a dependency on the ni-msiproperties package of the minimum version that you require. Refer to Properties and Conditions in WinInst Packages for a list of syntax requirements and supported properties.
    • If you omit this attribute, you must specify the full path to the executable in arguments.
    		 <customExecute exeName="[ProgramFilesFolder]\executable.exe"/>
    inPackage Boolean
    • n (default)
    • y
    		 Specifies whether the executable resides in the package data folder.
    • If you set the value of this attribute to y, observe the following rules:
      • The value of exeName must be a relative path to the executable within the package data folder.
      • You must set the value of wait to y. Otherwise, Package Manager may delete the executable before it runs.
      • You must set the value of step to install or reinstall.
      • You must set the value of schedule to pre or post.
      • You must use a File Package to install the executable to the target system.
      • Package Manager does not evaluate exeName for NIPaths properties.
    • If you omit this attribute, Package Manager uses its default value.

    The following example specifies a relative path to the executable, where executable.exe resides in a subfolder named actions within the package data directory.

    <customExecute exeName="actions\executable.exe" inPackage="y"/>
    Table 5. How Attributes
    Attribute Name Type Possible Values Description Example
    wait Boolean
    • n (default)
    • y
    		 Specifies whether the executable is synchronous, meaning Package Manager should wait for it to finish before continuing, or asynchronous, meaning Package Manager should not wait.
    • If the value is n, Package Manager ignores the executable's return code, as if returnCodeConvention="ignore".
    • If the value is n, you must not include the executable within the package because Package Manager may delete the entire package from temp before running the executable.
    • If you omit this attribute, Package Manager uses its default value.
    		 <customExecute exeName="executable.exe" wait="n"/>
    ignoreLaunchErrors Boolean
    • n (default)
    • y
    		 Specifies whether Package Manager reports an error if it cannot run or cannot find the executable.

    If you omit this attribute, Package Manager uses its default value.

    		 <customExecute exeName="executable.exe" ignoreLaunchErrors="y"/>
    hideConsoleWindow Boolean
    • n (default)
    • y
    		 Specifies whether to hide the console window for console applications.
    • Does not display console messages when you run GUI applications.
    • Does not cause any errors for a window application if present.
    • Console applications still run, but without a console window for user input or message output.
    		 <customExecute exeName="executable.exe" hideConsoleWindow="y"/>
    returnCodeConvention String Must match the name of a predefined convention or a <returnCodeConvention> defined in this package. The following predefined conventions are available:
    • console (default)
    • installer
    • ignore
    		 Indicates how to interpret the return codes the executable returns.
    • wait must be set to y, so the agent waits to receive the return code.
    • For console, 0 = success and any value is an error.
    • For installer, 0 = success, 3010 = reboot required or 1641 = reboot required, and anything else is an error.
    • For ignore, Package Manager ignores the return code.
    • If you omit this attribute, Package Manager uses its default value.
    		 <customExecute step="uninstall" exeName="[ProgramFilesFolder]executable1.exe" returnCodeConvention="installer"/>

    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.

    Properties and Conditions in WinInst Packages

    You can use WinInst conditions in <msi> and <customExecute> elements to conditionally execute WinInst MSIs and executable files.

    If you specify any condition, property, or command in your instructions file, you must declare a dependency in your package's control file on the ni-msiproperties package. The ni-msiproperties package has dependencies on additional packages:

    • ni-euladepot
    • ni-mdfsupport
    • ni-metauninstaller
    • ni-security-update-kb67l8lcqw-killbits

    You must include the ni-msiproperties package and its dependencies in the same feed as the package you build. If you have NI software installed on your system, these packages should exist in their default location on your system: %ProgramData%\National Instruments\NI Package Manager\packages. Copy the ni-msiproperties package and its dependencies from this location to the same directory as your package when you build the feed.

    Note You must use version 2.0 or greater of the ni-security-update-kb67l8lcqw-killbits package. For the ni-msiproperties package and its other dependencies, you must use version 17.0 or greater.

    Syntax Requirements for WinInst Conditions

    WinInst conditions included in <msi> and <customExecute> elements must follow Microsoft's MSI conditional statement syntax.

    You must enclose literal text within quotation marks to adhere to Microsoft's conditional statement syntax. The Instructions XML syntax provides two ways of adhering to this requirement:

    • Use single quotation marks to delimit the XML string. This allows the use of double quotation marks inside the string. For example: <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • Use the XML escape character for double quotation marks, &quot;, to delimit the literal text in the XML string. With the XML escape character, you can use double quotation marks or single quotation marks to delimit the XML string. For example: <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    You must enclose paths with spaces within quotation marks. Single quotation marks are not allowed in the path:

    • Use the XML escape character for double quotation marks, &quot;, to enclose path in the XML string. For example: <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    Properties You Can Use in Conditions

    When including conditions in a WinInst package, you can use any Windows property or property defined in the ni-msiproperties package.

    If you use a property in the arguments attribute of a <customExecute>, you must include a formatArgument attribute and set the value to y. For a comprehensive list of Windows Installer properties, such as ProgramFiles64Folder and DesktopFolder, search for Property Reference at https://msdn.microsoft.com.

    You can use the following list of additional Package Manager-specific properties:

    • NIINTERNETCONNECTEDTOMICROSOFT = YES (Package Manager uses this value if a connection to http://go.microsoft.com is successful. Otherwise, the value is NO.)
    • NIRUNNINGINSILENTMODE = 1 (Package Manager uses this value only when running in silent mode. Otherwise, it leaves the value undefined.)
    • NIPKGPROCESSID (The process ID of the current Package Manager process.)
    • NIPMLANGUAGECODE (The ISO language code of the language in which Package Manager runs. Possible values: en, de, fr, ko, ja, or zh-CN.)

    You can use the <property> element to pass additional Windows properties to each MSI, for example:

    • ADDLOCAL = ALL
    • INSTALLLEVEL = 100 (You can also enter a value of 1000, which turns on more or all of your features.)

    Properties You Cannot Use in Conditions

    Do not use properties that exist only inside of your specific MSI.

    • Do not use any property that is defined in your MSI's Property table, by AppSearch, or by the Upgrade table.
    • Do not use any Feature state, Component state, or File key.

    Properties Passed to Every MSI

    Package Manager defines and automatically passes some properties to MSIs run from WinInst packages.

    Package Manager always passes the following properties to every MSI at install, uninstall, and repair. You do not need to specify these in the instructions file.

    • REBOOT = ReallySuppress
    • PROMPTROLLBACKCOST = D
    • NIRUNNINGINSILENTMODE = 1 (Package Manager uses this value only when running in silent mode. Otherwise, it leaves the value undefined.)
    • NIPKGPROCESSID = The process ID of the current Package Manager process.