|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
Adding Custom Prerequisites
The Bootstrapper is a generic installer that can be configured to bootstrap virtually 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 launches 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 of the prerequisites are detected, the Bootstrapper simply launches the application installer.
Once the user accepts the agreement, the download and installation process begins. When all of 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 need to create a package for your redistributable. Typically, you only need to build packages for shared components or system components, which need to install files to the GAC, perform global registration, or comprise a Windows Service.
You should ask the control provider whether you can ship the redistributable file 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 need 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 need 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 .NET Framework SDK. Seefor 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 using the DependsOnProduct schema element. An example of a dependency would be that the Visual J# runtime requires that the .NET Framework be installed first.
You must then copy the product and package manifest files, along with your redistributable files, into a special folder that Visual Studio has reserved for redistributables packages:
\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bootstrapper
To write an installer that copies a redistributable component and its manifests into this folder, you can programmatically discover the Bootstrapper folder location from the following registry keys (read them in this order):
If neither of these keys exists, read the registry key for the SDK installation location:
Each redistributable component appears in its own subfolder under the packages directory. The product manifest and redistributable files are then placed into this subfolder. Localized versions of the component along with the package manifests are placed in subfolders named according to Culture Name (see the table in).
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 on using Bootstrapper to configure your installation, see the MSDN article "Use the Visual Studio 2005 Bootstrapper to Kick-Start Your Installation" at http://msdn.microsoft.com/msdnmag/issues/04/10/Bootstrapper/.
Keeping Bootstrapper Package Redistributables Separate from Application Installations
As a general 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 it is recommended that you install bootstrapper components to the GAC on your development machines, 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, it is recommended 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 needs to be installed on developer machines.
To do this, create a redistributable list in the RedistList folder in your .NET Framework directory (\WINDOWS\Microsoft.NET\Framework).
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 look like this:
<?xml version="1.0" encoding="UTF-8"?> <FileList Redist="Acme.DataWidgets" > <File AssemblyName="Acme.DataGrid" Version="220.127.116.11" PublicKeyToken="b03f5f7f11d50a3a" Culture="neutral" ProcessorArchitecture="MSIL" InGAC="true" /> </FileList>
Adding Packages to the Prerequisites Dialog Box
Theallows you to select which components your application requires before installation. Visual Studio includes a number of 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 above.
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. It will also recommend the J# runtime for a J# project.
For Windows Installer projects, if the current project is a Setup or Websetup Project, the .NET Framework check box will be selected by default. If at build time neither the .NET Framework nor the Windows Installer package is selected, a build warning will be issued.