To ease readability, this article uses the terms Suite project to refer to both Suite/Advanced UI project and Advanced UI project.
Suite installer projects enable you to create a feature selection tree that allows end users to select and deselect which packages should be installed at runtime. This support is available through the Features and Packages views in the InstallShield IDE. Furthermore, you can also configure the Suite features to allow selection or deselection of a feature contained in an MSI or InstallScript package.
As an example, consider a Suite installer project that contains the following top-level features in the Features view and the packages that are associated with them in the Packages view: MSI_Package, which runs the installation for an MSI package; and InstallScript_Package, which runs the installation for an InstallScript package.
At runtime, an end user running this Suite installer can select or deselect either feature. However, suppose both packages contain features that you also want end users to be able to select or deselect through the Suite installer (instead of always having all features in a package installed or removed):
- MSI_Package contains the following feature tree:
- MSI_Feature_A
- MSI_Feature_B
- MSI_Feature_C
- InstallScript_Package contains the following feature tree:
- ISP_Feature_A
- ISP_Feature_B
- ISP_Feature_C
- ISP_Feature_A
The quickest way to create these feature trees is to create placeholder features in the Features view of the Suite project, as shown:
Once you have created these features, save and close the project. Then open the .issuite project file in a text editor, and locate the <SelectionTree> element. This element defines the Suite’s feature tree through the use of <Selection> elements. Selection elements provide the following attributes:
Attribute Name | Attribute Value |
---|---|
Name | The internal name used to identify the feature in a Suite installer. |
DisplayName | The name displayed at runtime on a feature selection tree control; you can use localized string IDs for the value. |
Install | A list of package GUIDs (delimited by a space) that are each optionally followed by a colon (:) and a comma delimited list of features contained in the associated package. |
Visible | Yes or No to indicate whether the feature should be visible in a feature selection tree control; the default is visible if the attribute is not specified. |
When you create a feature in the Suite project, the Install attribute normally contains only a package GUID to associate the feature with one or more specific packages. However, you can also directly associate a feature or list of features that are contained in the package with a Suite feature.
To provide the simplest (and therefore more robust) feature tree implementation when exposing features from a package as features in your Suite, collect them all as subfeatures under the Suite feature that is associated with that package. Based on the above example, a possible Suite feature tree implementation could look like the following.
<SelectionTree>
<Selection Name="MSI_Package" DisplayName="MSI Package"
Install="{MSIGUID}">
<Selection Name="MSIFeatureA" DisplayName="MSI Feature A"
Install="{MSIGUID}:MSI_Feature_A"/>
<Selection Name="MSIFeatureB" DisplayName="MSI Feature B"
Install="{MSIGUID}:MSI_Feature_B">
<Selection Name="MSI_Feature_C" DisplayName="MSI Feature C"
Install="{MSIGUID}:MSI_Feature_C"/>
</Selection>
</Selection>
<Selection Name="InstallScript_Package" DisplayName="InstallScript Package"
Install="{ISPGUID}">
<Selection Name="ISP_Feature_A" DisplayName="ISP Feature A"
Install="{ISPGUID}:ISP_Feature_A">
<Selection Name="ISPFeatureB" DisplayName="ISP Feature B"
Install="{ISPGUID}:ISP_Feature_AISP_Feature_B"/>
</Selection>
<Selection Name="ISPFeatureC" DisplayName="ISP Feature C"
Install="{ISPGUID}:ISP_Feature_C"/>
</Selection
</SelectionTree>
(In this example, {MSIGUID} and {ISPGUID} represent the package GUIDs for
the MSI and InstallScript packages, respectively.)
<SelectionTree>
<Selection Name=”MSI_Package” DisplayName=”MSI Package” Install=”{MSIGUID}”>
<Selection Name=”MSIFeatureB” DisplayName=”MSI Feature B” Install=”{MSIGUID}:MSI_Feature_B”>
</Selection>
</Selection>
<Selection Name=”InstallScript_Package” DisplayName=”InstallScript Package” Install=”{ISPGUID}”>
<Selection Name=”ISP_Feature_A” DisplayName=”ISP Feature A” Install=”{ISPGUID}:ISP_Feature_A”>
</Selection>
<Selection Name=”ISPFeatureC” DisplayName=”ISP Feature C” Install=”{ISPGUID}:ISP_Feature_C”/>
</Selection>
</SelectionTree>
The reason for collecting a package’s features under the Suite feature that is associated with the package is due to a requirement in the Suite engine. For a package itself to be selected, there must be a direct association between the package and a feature in that package that is going to be installed. If this didn’t exist, the engine would never know that the package (or a feature in the package) should be installed. The above feature tree example is not the only possible way to configure the feature tree. However, it is necessary that a feature in the Suite project be associated to a package that contains these other features.
At runtime, each Suite feature selection is accumulated into a list of features to be installed or removed. For MSI packages, these lists are passed to the MSI to be installed with the ADDLOCAL and REMOVE properties. For InstallScript packages, these lists are passed to the package and made available through the CMDLINE variable. By default, the OnSuiteInstallBefore and OnSuiteMaintBefore events call the FeatureConfigureFeaturesFromSuite function to parse the feature lists from the command line and select or deselect features based on the parsed information. (InstallScript projects afford a higher degree of customization compared to MSI projects in this scenario, as the default behavior could be overridden if desired.) Note that in the InstallScript feature case, the format used to specify a feature in the InstallScript package follows the syntax documented in the InstallShield help article Specifying Features and Subfeatures in Function Calls.
By providing individual package feature selections in your Suite installer, greater control is available for customers using such an installation.
The Suite/Advanced UI project type is available in the Premier edition of InstallShield. The Advanced UI project type is available in the Professional edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.