<Commands> Element (Bootstrapper)

  • Article

Note

This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

The Commands element implements tests described by the elements underneath the InstallChecks element, and declares which package the ClickOnce bootstrapper should install if the test fails.

Syntax

<Commands  
    Reboot  
>  
    <Command  
        PackageFile  
        Arguments  
        EstimatedInstallSeconds  
        EstimatedDiskBytes  
        EstimatedTempBytes  
        Log  
    >  
        <InstallConditions>  
            <BypassIf   
                Property  
                Compare  
                Value  
                Schedule  
            />  
            <FailIf   
                Property  
                Compare  
                Value  
                String  
                Schedule  
            />  
        </InstallConditions>  
        <ExitCodes>  
            <ExitCode   
                Value  
                Result  
                String  
            />  
        </ExitCodes>  
    </Command>  
</Commands>

Elements and Attributes

The Commands element is required. The element has the following attribute.

Attribute Description
Reboot Optional. Determines whether the system should restart if any of the packages return a restart exit code. The following list shows the valid values:

Defer. The restart is deferred until some future time.

Immediate. Causes an immediate restart if one of the packages returned a restart exit code.

None. Causes any restart requests to be ignored.

The default is Immediate.

Command

The Command element is a child element of the Commands element. A Commands element can have one or more Command elements. The element has the following attributes.

Attribute Description
PackageFile Required. The name of the package to install should one or more of the conditions specified by InstallConditions return false. The package must be defined in the same file by using a PackageFile element.
Arguments Optional. A set of command line arguments to pass into the package file.
EstimatedInstallSeconds Optional. The estimated time, in seconds, it will take to install the package. This value determines the size of the progress bar the bootstrapper displays to the user. The default is 0, in which case no time estimate is specified.
EstimatedDiskBytes Optional. The estimated amount of disk space, in bytes, that the package will occupy after the installation is finished. This value is used in hard disk space requirements that the bootstrapper displays to the user. The default is 0, in which case the bootstrapper does not display any hard disk space requirements.
EstimatedTempBytes Optional. The estimated amount of temporary disk space, in bytes, that the package will require.
Log Optional. The path to the log file that the package generates, relative to the root directory of the package.

InstallConditions

The InstallConditions element is a child of the Command element. Each Command element can have at most one InstallConditions element. If no InstallConditions element exists, the package specified by Condition will always run.

BypassIf

The BypassIf element is a child of the InstallConditions element, and describes a positive condition under which the command should not be executed. Each InstallConditions element can have zero or more BypassIf elements.

BypassIf has the following attributes.

Attribute Description
Property Required. The name of the property to test. The property must previously have been defined by a child of the InstallChecks element. For more information, see <InstallChecks> Element.
Compare Required. The type of comparison to perform. The following list shows the valid values:

ValueEqualTo, ValueNotEqualTo, ValueGreaterThan, ValueGreaterThanOrEqualTo, ValueLessThan, ValueLessThanOrEqualTo, VersionEqualTo, VersionNotEqualTo, VersionGreaterThan, VersionGreaterThanOrEqualTo, VersionLessThan, VersionLessThanOrEqualTo, ValueExists, ValueNotExists
Value Required. The value to compare with the property.
Schedule Optional. The name of a Schedule tag that defines when this rule should be evaluated.

FailIf

The FailIf element is a child of the InstallConditions element, and describes a positive condition under which the installation should stop. Each InstallConditions element can have zero or more FailIf elements.

FailIf has the following attributes.

Attribute Description
Property Required. The name of the property to test. The property must previously have been defined by a child of the InstallChecks element. For more information, see <InstallChecks> Element.
Compare Required. The type of comparison to perform. The following list shows the valid values:

ValueEqualTo, ValueNotEqualTo, ValueGreaterThan, ValueGreaterThanOrEqualTo, ValueLessThan, ValueLessThanOrEqualTo, VersionEqualTo, VersionNotEqualTo, VersionGreaterThan, VersionGreaterThanOrEqualTo, VersionLessThan, VersionLessThanOrEqualTo, ValueExists, ValueNotExists
Value Required. The value to compare with the property.
String Optional. The text to display to the user upon failure.
Schedule Optional. The name of a Schedule tag that defines when this rule should be evaluated.

ExitCodes

The ExitCodes element is a child of the Command element. The ExitCodes element contains one or more ExitCode elements, which determine what the installation should do in response to an exit code from a package. There can be one optional ExitCode element underneath a Command element. ExitCodes has no attributes.

ExitCode

The ExitCode element is a child of the ExitCodes element. The ExitCode element determines what the installation should do in response to an exit code from a package. ExitCode contains no child elements, and has the following attributes.

Attribute Description
Value Required. The exit code value to which this ExitCode element applies.
Result Required. How the installation should react to this exit code. The following list shows the valid values:

Success. Flags the package as successfully installed.

SuccessReboot. Flags the package as successfully installed, and instructs the system to restart.

Fail. Flags the package as failed.

FailReboot. Flags the package as failed, and instructs the system to restart.
String Optional. The value to display to the user in response to this exit code.
FormatMessageFromSystem Optional. Determines whether to use the system-provided error message corresponding to the exit code, or use the value provided in String. Valid values are true, which means to use the system-provided error, and false, which means to use the string provided by String. The default is false. If this property is false, but String is not set, the system-provided error will be used.

Example

The following code example defines commands for installing the .NET Framework 2.0.

<Commands Reboot="Immediate">  
    <Command PackageFile="instmsia.exe"  
             Arguments= ' /q /c:"msiinst /delayrebootq"'  
             EstimatedInstallSeconds="20" >  
        <InstallConditions>  
           <BypassIf Property="VersionNT" Compare="ValueExists"/>  
             BypassIf Property="VersionMsi" Compare="VersionGreaterThanOrEqualTo" Value="2.0"/>  
        </InstallConditions>  
        <ExitCodes>  
            <ExitCode Value="0" Result="SuccessReboot"/>  
            <ExitCode Value="1641" Result="SuccessReboot"/>  
            <ExitCode Value="3010" Result="SuccessReboot"/>  
            <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />  
        </ExitCodes>  
    </Command>  
    <Command PackageFile="WindowsInstaller-KB884016-v2-x86.exe"  
             Arguments= '/quiet /norestart'   
             EstimatedInstallSeconds="20" >  
      <InstallConditions>  
          <BypassIf Property="Version9x" Compare="ValueExists"/>  
          <BypassIf Property="VersionNT" Compare="VersionLessThan" Value="5.0.3"/>  
          <BypassIf Property="VersionMsi" Compare="VersionGreaterThanOrEqualTo" Value="3.0"/>  
          <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired"/>  
      </InstallConditions>  
      <ExitCodes>  
          <ExitCode Value="0" Result="Success"/>  
          <ExitCode Value="1641" Result="SuccessReboot"/>  
          <ExitCode Value="3010" Result="SuccessReboot"/>  
          <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />  
      </ExitCodes>  
    </Command>  
    <Command PackageFile="dotnetfx.exe"   
         Arguments=' /q:a /c:"install /q /l"'   
         EstimatedInstalledBytes="21000000"   
         EstimatedInstallSeconds="300">  
  
        <!-- These checks determine whether the package is to be installed -->  
        <InstallConditions>  
            <!-- Either of these properties indicates the .NET Framework is already installed -->  
            <BypassIf Property="DotNetInstalled" Compare="ValueNotEqualTo" Value="0"/>  
  
            <!-- Block install if user does not have adminpermissions -->  
            <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired"/>  
  
            <!-- Block install on Windows 95 -->  
            <FailIf Property="Version9X" Compare="VersionLessThan" Value="4.10" String="InvalidPlatformWin9x"/>  
  
            <!-- Block install on Windows 2000 SP 2 or less -->  
            <FailIf Property="VersionNT" Compare="VersionLessThan" Value="5.0.3" String="InvalidPlatformWinNT"/>  
  
            <!-- Block install if Internet Explorer 5.01 or later is not present -->  
            <FailIf Property="IEVersion" Compare="ValueNotExists" String="InvalidPlatformIE" />  
            <FailIf Property="IEVersion" Compare="VersionLessThan" Value="5.01" String="InvalidPlatformIE" />  
  
            <!-- Block install if the operating system does not support x86 -->  
            <FailIf Property="ProcessorArchitecture" Compare="ValueNotEqualTo" Value="Intel" String="InvalidPlatformArchitecture" />  
       </InstallConditions>  
  
        <ExitCodes>  
            <ExitCode Value="0" Result="Success"/>  
            <ExitCode Value="3010" Result="SuccessReboot"/>  
            <ExitCode Value="4097" Result="Fail" String="AdminRequired"/>  
            <ExitCode Value="4098" Result="Fail" String="WindowsInstallerComponentFailure"/>  
            <ExitCode Value="4099" Result="Fail" String="WindowsInstallerImproperInstall"/>  
            <ExitCode Value="4101" Result="Fail" String="AnotherInstanceRunning"/>  
            <ExitCode Value="4102" Result="Fail" String="OpenDatabaseFailure"/>  
            <ExitCode Value="4113" Result="Fail" String="BetaNDPFailure"/>  
            <DefaultExitCode Result="Fail" FormatMessageFromSystem="true" String="GeneralFailure" />  
        </ExitCodes>  
  
    </Command>  
</Commands>

See Also

Product and Package Schema Reference
<InstallChecks> Element