Table Of Contents

Instructions XML for WinInst Packages

Last Modified: August 13, 2018

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>
  • <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>
    <upgrade>clean</upgrade>
    <msis>
        <msi name="Setup.msi">
            <property name="ADDLOCAL" value="ALL"/>
        </msi>
        <msi name="Setup64.msi">
            <property name="ADDLOCAL" value="ALL"/>
        </msi>
    </msis>
    <customExecutes>
        <customExecute/>
    </customExecutes>
</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.

spd-note-note
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.
spd-note-note
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)"/>

<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.

spd-note-note
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="MYLANGID" value="[NIMETALANGID]"/>
step Enum No
  • install (default)
  • repair
  • uninstall
  • 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"/>

<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. It has the following attributes that tell Package Manager conditions for running the executable. They are categorized into four groups:

  • When—The timing of the executable relative to the transaction step. Each When attribute is optional.
  • Why—The conditions that determine if Package Manager runs the executable. Each Why attribute is 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 specify the location of the executable using one of them.
  • How—The manner in which Package Manager handles errors and progress. Each How attribute is optional.
Table 1. When Attributes
Attribute Name Type Possible Values Description Details Example
step Enum
  • install—(default) Package Manager runs the executable only when installing the package.
  • uninstall—Package Manager runs the executable only when removing the package.
Specifies the transaction step during which Package Manager runs the executable.
  • If Package Manager should 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  

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, during upgrade, Package Manager runs a <customExecute> with attribute values step="install" and schedule="pre" after removing the old package, but before installing the new package.
  • If you omit this attribute, Package Manager uses its default value.
spd-note-note
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 2. Why Attributes
Attribute Name Type Possible Value Description Details 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.
spd-note-note
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 3. What Attributes
Attribute Name Type Possible Values Description Details Example
arguments String Command line arguments to pass to the executable. Specifies command line arguments for Package Manager to pass to the executable.
  • This value is formatted, so you can include a ni-msiproperties directory property in brackets. Refer to Properties and Conditions in WinInst Packages for a list of supported properties.
  • You can include the full path to the executable. If you do this, omit the exeName attribute.
spd-note-note
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.
spd-note-note
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 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 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.
    • 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 4. How Attributes
Attribute Name Type Possible Values Description Details Example
wait Boolean
  • n (default)
  • y
Specifies whether the executable is synchronous, where Package Manager should wait for it to finish before continuing, or asynchronous, where 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 Enum
  • console (default)
  • installer
  • ignore
Indicates the set of return codes the executable returns.
  • For console, 0 = success and any value other than 0 is an error.
  • For installer, 0 = success, 3010 or 1641 = reboot required, and anything else is an error.
  • For ignore, Package Manager ignores the return code.
  • If installer, you must set 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 step="uninstall" root="ProgramFilesFolder" exeName="executable.exe" wait="y" 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 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.

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.

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

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.

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
  • REINSTALLMODE = vemus
  • PROMPTROLLBACKCOST = D
  • 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.

Recently Viewed Topics