Adding Custom Prerequisites

Article
08/23/2010

The Bootstrapper is a generic installer that can be configured to bootstrap almost any redistributable that is packaged as a Windows Installer file or an executable program. It is programmed through a set of simple XML manifests that specify all the metadata required for the Bootstrapper to manage the installation of the component. The Bootstrapper does not dictate which installer technology the application must use (Windows Installer or ClickOnce).

When a user starts Setup.exe, it first detects whether any of the prerequisites are already installed. If any of the prerequisites are missing, the Bootstrapper shows an installation dialog box that lists those components and displays their license agreement. Otherwise, if all the prerequisites are detected, the Bootstrapper just starts the application installer.

Once the user accepts the agreement, the download and installation process starts. When all the prerequisites have been installed, the Bootstrapper kicks off the installation process of the application itself.

Creating Custom Packages

There are some cases in which you do not have to create a package for your redistributable. Typically, you only have to build packages for shared components or system components, which have to install files to the GAC, perform global registration, or make up a Windows Service.

You should ask the control provider whether you can ship the redistributable file together with the application. If a simple copy operation would be sufficient to redistribute the prerequisite component (for example, if it has no dependencies), you do not have to create a package. Just make sure that the file is included in the setup or that it is set to Copy Local. (The file's Copy property in Properties View should be set to True.)

You should also determine whether you have to use an installer. If so, use a Bootstrapper package.

To create a new component package, you have to supply:

The redistributable component in the form of an EXE or MSI file.
The product manifest, product.xml, which contains any language-neutral metadata for the package. This contains metadata common to all the localized versions of the redistributable component.
The package manifest, package.xml, which contains language-specific metadata; it typically contains localized error messages. A component must have at least one package manifest for each localized version of that component.

You must create the manifest files by hand, and the metadata they contain must adhere to a specific schema as described by the Package Schema Elements included in the Windows Software Development Kit (SDK). See Product and Package Schema Reference for the schema reference. The setup builder integrated with Visual Studio will validate the manifest files at build time.

You specify dependencies between packages in these manifests by using the DependsOnProduct schema element.

You must then copy the product and package manifest files, together with your redistributable files, into a special folder that Visual Studio has reserved for redistributables packages:

\Program Files\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages

To write an installer that copies a redistributable component and its manifests into this folder, you can programmatically determine the Bootstrapper folder location from the Path value in the following registry key:

HKLM\Software\Microsoft\GenericBootstrapper\3.5

Each redistributable component appears in its own subfolder under the packages directory. The product manifest and redistributable files are then put into this subfolder. Localized versions of the component, together with the package manifests, are put in subfolders named according to Culture Name (see the table in CultureInfo).

Once these files have been copied into the Bootstrapper folder, they automatically appear in the Visual Studio prerequisites dialog box so that the developer can select them by checking a box.

For more information about using Bootstrapper to configure your installation, see the MSDN article Use the Visual Studio 2005 Bootstrapper to Kick-Start Your Installation.

Keeping Bootstrapper Package Redistributables Separate from Application Installations

As a rule, you should keep any components that are part of a bootstrapper package redistributable separate from applications that use these components. For example, assume that you have a bootstrapper package named Acme.DataWidgets.msi that contains component Acme.DataWidgets.dll. Acme.DataWidgets.dll should not appear in the project's bindir directory at development time, and should not be deployed in the application's installer package.

Therefore, we recommend that you install bootstrapper components to the GAC on your development computers, ideally using the same core bootstrapper package redistributable installer. This will prevent bootstrapper components from being copied to the project's bindir directory at development time. Also, we recommend that you define a RedistList file to describe all the assemblies that are part of the bootstrapper redistributable package. This will prevent bootstrapper components from being included in any application deployment projects. The RedistList file only must be installed on developer computers.

To do this, create a redistributable list in the RedistList folder in your .NET Framework directory (\Program Files\Reference Assemblies\Microsoft\Framework\ \version). The redistributable list must be in a directory that correlates to .NET Framework 2.0, .NET Framework 3.0, or .NET Framework 3.5. The file cannot be in a directory for the .NET Framework 3.5 Client Profile.

The redistributable list is an XML file that you should name using the following format: company_name + component_name + RedistList.xml. So, for example, if the component is called "Datawidgets" made by "Acme," use Acme.DataWidgets.RedistList.xml. An example of the redistributable list's contents might resemble this:

<?xml version="1.0" encoding="UTF-8"?>
<FileList Redist="Acme.DataWidgets" >
<File AssemblyName="Acme.DataGrid" Version="1.0.0.0" PublicKeyToken="b03f5f7f11d50a3a" Culture="neutral" ProcessorArchitecture="MSIL" InGAC="true" />
</FileList>

Adding Packages to the Prerequisites Dialog Box

The Prerequisites Dialog Box enables you to select which components your application requires before installation. Visual Studio includes several standard prerequisites. However, you can add other Microsoft or third-party components as prerequisites. To do so, you must author the product and package manifests as described earlier.

In the Prerequisites dialog box, the Choose which prerequisites to install list shows the prerequisite packages that can be installed. The order of the packages in this list is based on the dependencies specified in the manifests, and specifies the order in which the packages will be installed.

After you have added a generic package to the Bootstrapper, it will appear in the Prerequisites dialog box as MyPackage. Visual Studio will not automatically choose packages to install.

For ClickOnce projects, Visual Studio recommends including the .NET Framework for all project types by selecting the .NET Framework check box by default in Choose which prerequisites to install.

By default, for Windows Installer projects, if the current project is a Setup or Websetup Project, the .NET Framework check box will be selected. If at build time neither the .NET Framework nor the Windows Installer package is selected, a build warning will be issued.

Adding Custom Prerequisites

Creating Custom Packages

Adding Packages to the Prerequisites Dialog Box

See Also

Tasks

Concepts

Reference

Other Resources

Additional resources