<InstallChecks> element (bootstrapper)

Article
11/04/2016

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. 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 InstallChecks element supports starting a variety of tests against the local computer to make sure that all of the appropriate prerequisites for an application have been installed.

Syntax

<InstallChecks>
    <AssemblyCheck
        Property
        Name
        PublicKeyToken
        Version
        Language
        ProcessorArchitecture
    />
    <RegistryCheck
        Property
        Key
        Value
    />
    <ExternalCheck
        PackageFile
        Property
        Arguments
    />
    <FileCheck
        Property
        FileName
        SearchPath
        SpecialFolder
        SearchDepth
    />
    <MsiProductCheck
        Property
        Product
        Feature
    />
    <RegistryFileCheck
        Property
        Key
        Value
        FileName
        SearchDepth
    />
</InstallChecks>

AssemblyCheck

This element is an optional child element of InstallChecks. For each instance of AssemblyCheck, the bootstrapper will make sure that the assembly identified by the element exists in the global assembly cache (GAC). It contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`Name`	Required. The fully qualified name of the assembly to check.
`PublicKeyToken`	Required. The abbreviated form of the public key associated with this strongly named assembly. All assemblies stored in the GAC must have a name, a version, and a public key.
`Version`	Required. The version of the assembly. The version number has the format <major version>.<minor version>.<build version>.<revision version>.
`Language`	Optional. The language of a localized assembly. Default is `neutral`.
`ProcessorArchitecture`	Optional. The computer processor targeted by this installation. Default is `msil`.

ExternalCheck

This element is an optional child element of InstallChecks. For each instance of ExternalCheck, the bootstrapper will execute the named external program in a separate process, and store its exit code in the property indicated by Property. ExternalCheck is useful for implementing complex dependency checks, or when the only way to check for the existence of a component is to instantiate it.

ExternalCheck contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`PackageFile`	Required. The external program to execute. The program must be part of the setup distribution package.
`Arguments`	Optional. Supplies command-line arguments to the executable named by `PackageFile`.

FileCheck

This element is an optional child element of InstallChecks. For each instance of FileCheck, the bootstrapper will determine whether the named file exists, and return the version number of the file. If the file does not have a version number, the bootstrapper sets the property named by Property to 0. If the file does not exist, Property is not set to any value.

FileCheck contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`FileName`	Required. The name of the file to find.
`SearchPath`	Required. The disk or folder in which to look for the file. This must be a relative path if `SpecialFolder` is assigned; otherwise, it must be an absolute path.
`SpecialFolder`	Optional. A folder that has special significance either to Windows or to ClickOnce. The default is to interpret `SearchPath` as an absolute path. Valid values include the following: `AppDataFolder`. The application data folder for this ClickOnce application; specific to the current user. `CommonAppDataFolder`. The application data folder used by all users. `CommonFilesFolder`. The Common Files folder for the current user. `LocalDataAppFolder`. The data folder for non-roaming applications. `ProgramFilesFolder`. The standard Program Files folder for 32-bit applications. `StartUpFolder`. The folder that contains all applications launched at system startup. `SystemFolder`. The folder that contains 32-bit system DLLs. `WindowsFolder`. The folder that contains the Windows system installation. `WindowsVolume`. The drive or partition that contains the Windows system installation.
`SearchDepth`	Optional. The depth at which to search sub-folders for the named file. The search is depth-first. The default is 0, which restricts the search to the top-level folder specified by `SpecialFolder` and SearchPath.

MsiProductCheck

This element is an optional child element of InstallChecks. For each instance of MsiProductCheck, the bootstrapper checks to see whether the specified Microsoft Windows Installer installation has run until it is completed. The property value is set depending on the state of that installed product. A positive value indicates the product is installed, 0 or -1 indicates it is not installed. (Please see the Windows Installer SDK function MsiQueryFeatureState for more information.) . If Windows Installer is not installed on the computer, Property is not set.

MsiProductCheck contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`Product`	Required. The GUID for the installed product.
`Feature`	Optional. The GUID for a specific feature of the installed application.

RegistryCheck

This element is an optional child element of InstallChecks. For each instance of RegistryCheck, the bootstrapper checks to see whether the specified registry key exists, or whether it has the indicated value.

RegistryCheck contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`Key`	Required. The name of the registry key.
`Value`	Optional. The name of the registry value to retrieve. The default is to return the text of the default value. `Value` must be either a String or a DWORD.

RegistryFileCheck

This element is an optional child element of InstallChecks. For each instance of RegistryFileCheck, the bootstrapper retrieves the version of the specified file, first attempting to retrieve the path to the file from the specified registry key. This is particularly useful if you want to look up a file in a directory specified as a value in the registry.

RegistryFileCheck contains no elements, and has the following attributes.

Attribute	Description
`Property`	Required. The name of the property to store the result. This property can be referenced from a test underneath the `InstallConditions` element, which is a child of the `Command` element. For more information, see <Commands> Element.
`Key`	Required. The name of the registry key. Its value is interpreted as the path to a file, unless the `File` attribute is set. If this key does not exist, `Property` is not set.
`Value`	Optional. The name of the registry value to retrieve. The default is to return the text of the default value. `Value` must be a String.
`FileName`	Optional. The name of a file. If specified, the value obtained from the registry key is assumed to be a directory path, and this name is appended to it. If not specified, the value returned from the registry is assumed to be the full path to a file.
`SearchDepth`	Optional. The depth at which to search sub-folders for the named file. The search is depth-first. The default is 0, which restricts the search to the top-level folder specified by the registry key's value.

Remarks

While the elements underneath InstallChecks define the tests to run, they do not execute them. To execute the tests, you must create Command elements underneath the Commands element.

Example

The following code example demonstrates the InstallChecks element as it is used in the product file for the .NET Framework.

<InstallChecks>
    <ExternalCheck Property="DotNetInstalled" PackageFile="dotnetchk.exe" />
    <RegistryCheck Property="IEVersion" Key="HKLM\Software\Microsoft\Internet Explorer" Value="Version" />
</InstallChecks>

InstallConditions

When InstallChecks are evaluated, they produce properties. The properties are then used by InstallConditions to determine whether a package should install, bypass, or fail. The following table lists the InstallConditions:

Condition	Description
`FailIf`	If any `FailIf` condition evaluates to true, the package will fail. The rest of the conditions will not be evaluated.
`BypassIf`	If any `BypassIf` condition evaluates to true, the package will be bypassed. The rest of the conditions will not be evaluated.

Predefined properties

The following table lists the BypassIf and FailIf elements:

Property	Notes	Possible Values
`Version9X`	Version number of a Windows 9X operating system.	4.10 = Windows 98
`VersionNT`	Version number of a Windows NT-based operating system.	Major.Minor.ServicePack 5.0 = Windows 2000 5.1.0 = Windows XP 5.1.2 = Windows XP Professional SP2 5.2.0 = Windows Server 2003
`VersionNT64`	Version number of a 64-bit Windows NT-based operating system.	Same as mentioned earlier.
`VersionMsi`	Version number of the Windows Installer service.	2.0 = Windows Installer 2.0
`AdminUser`	Specifies whether a user has administrator privileges on a Windows NT-based operating system.	0 = no administrator privileges 1 = administrator privileges

For example, to block installation on a computer running Windows 95, use code such as the following:

    <!-- Block install on Windows 95 -->
    <FailIf Property="Version9X" Compare="VersionLessThan" Value="4.10" String="InvalidPlatform"/>

To skip running install checks if a FailIf or BypassIf condition is met, use the BeforeInstallChecks attribute. For example:

    <!-- Block install and do not evaluate install checks if user does not have admin privileges -->
    <FailIf Property="AdminUser" Compare="ValueEqualTo" Value="false" String="AdminRequired" BeforeInstallChecks="true"/>