<InstallChecks> Element (ClickOnce Bootstrapper)

Article
12/08/2006

The InstallChecks element supports launching a variety of tests against the local computer to ensure that all of the appropriate prerequisites for a ClickOnce application have been installed.

<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
        File
        SearchDepth
    />
</InstallChecks>

AssemblyCheck

This element is an optional child element of InstallChecks. For each instance of AssemblyCheck, the bootstrapper will ensure 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 (ClickOnce Bootstrapper).
`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.
`Language`	Optional. The language of a localized assembly. Default is neutral.
`ProcessorArchitecture`	Optional. The machine 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 (ClickOnce Bootstrapper).
`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 (ClickOnce Bootstrapper).
`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 with special significance either to Windows or to ClickOnce. The default is to interpret `SearchPath` as an absolute path. Valid values include: AppDataFolder. The application data folder for this ClickOnce application; specific to the current user. CommonAppDataFolder. The application data folder used by all users. CommonFiles64Folder. The 64-bit Common Files folder. CommonFilesFolder. The Common Files folder for the current user. LocalDataAppFolder. The data folder for non-roaming applications. ProgramFiles64Folder. The Program Files folder for 64-bit applications. ProgramFilesFolder. The standard Program Files folder for 32-bit applications. StartUpFolder. The folder that contains all applications launched at system startup. System16Folder. The folder containing 16-bit system DLLs. System64Folder. The folder containing 64-bit system DLLs. SystemFolder. The folder containing 32-bit system DLLs. WindowsFolder. The folder containing the Windows system installation. WindowsVolume. The drive or partition containing 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 if the specified Microsoft Windows Installer installation has run to completion. 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 refer to the Windows Installer SDK function MsiQueryFeatureState for more information.) . If Windows Installer is not installed on the machine, 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 (ClickOnce Bootstrapper).
`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 if 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 (ClickOnce Bootstrapper).
`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 wish 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 (ClickOnce Bootstrapper).
`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.
`File`	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>