Microsoft Build Engine (MSBuild)

InstallShield 2018

InstallShield supports the Microsoft Build engine (MSBuild) included with the .NET Framework. MSBuild support enables you to build Visual Studio solutions with InstallShield projects in build lab environments where Visual Studio is not installed.

Overview

MSBuild is an extensible build framework designed to remove the build dependence on Visual Studio. The .NET Framework functions in a role similar to the InstallShield Standalone Build, providing the capability to build projects or solutions from the command line or any other host of MSBuild. For more information on MSBuild, see the MSDN Library.

MSBuild Tasks

The flexibility and extensibility of MSBuild is controlled through atomic groupings of internal build steps referred to as tasks. One example of a task that ships with MSBuild is Csc, which can compile code from a Visual C# project. InstallShield installs an MSBuild task called InstallShield, which builds an InstallShield project, and a targets file that provides default build steps for the project. This customized task, along with the targets file, enables MSBuild to perform all required actions to build the InstallShield project as part of a Visual Studio solution.

This table describes the parameters of the InstallShield task. The Project Type column lists the applicable project types

MSBuild InstallShield Task

Parameter

Type

Project Type

Description

InstallShieldPath

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the path to folder containing the InstallShield application.

Project

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the location of the project file (.ism).

ProductConfiguration

String

Basic MSI, InstallScript MSI, Merge Module

This parameter specifies the product configuration for the release.

ReleaseConfiguration

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the release name.

Note • You must specify the ReleaseConfiguration or the PatchConfiguration. If you do not specify one of these, or if you specify both of these, a build error occurs.

PatchConfiguration

String

Basic MSI, InstallScript MSI

This parameter specifies the name of the patch configuration in the Patch Design view that is being built.

Note • You must specify the ReleaseConfiguration or the PatchConfiguration. If you do not specify one of these, or if you specify both of these, a build error occurs.

OutDir

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the fully qualified path to the folder where you want the output folders and files to be placed.

MergeModulePath

String[ ]

Basic MSI, InstallScript, InstallScript MSI

This parameter specifies one or more folders that contain the merge modules (.msm files) that are referenced by your project.

InstallShield provides additional ways for specifying the folders that contain merge modules. For more information, see Specifying the Directories that Contain Merge Modules.

PrerequisitePath

String[ ]

Basic MSI, InstallScript, InstallScript MSI

This parameter specifies one or more semicolon-delimited folders that contain the InstallShield prerequisite files (.prq files) that are referenced by your project.

InstallShield provides additional ways for specifying the folders that contain InstallShield prerequisite files. For more information, see Specifying the Directories that Contain InstallShield Prerequisites.

ReleaseFlags

String[ ]

Basic MSI, InstallScript MSI

This parameter enables you to specify any release flags that you want to include in your release. Separate multiple flags with commas.

PathVariables

ITaskItem[ ]

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter enables you to override the path variables for the project. Using this parameter, you can specify the path to the path variable and also define a value for the name of the path variable using the PathVariable subelement.

To reference a file in a sibling project that is within the same Visual Studio solution folder, use the predefined path variable called VSSolutionFolder. For more information, see Using the VSSolutionFolder Path Variable with Visual Studio Solutions.

For more information on MSBuild ITaskItem[ ] properties, see the MSDN Library.

PreprocessorDefines

ITaskItem[ ]

Basic MSI, InstallScript, InstallScript MSI

This parameter enables you to add or override the preprocessor defines for the project. Using this parameter, you can specify the definition of the preprocessor define and also define a value for the name of the preprocessor define using the Token subelement.

For more information on MSBuild ITaskItem[ ] properties, see the MSDN Library.

OutputGroups

ITaskItem[ ]

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the project output groups from the Visual Studio solution. Using this parameter, you can specify the path to the source location of the project output group and also define these additional values using these subelements as listed:

•

Name—Name of the project

•

OutputGroup—Name of the project output group

•

TargetPath—Target path of the project output group (different from its source location)

For more information on MSBuild ITaskItem[ ] properties, see the MSDN Library.

Build

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies what type of build to perform. You can choose from these types of builds:

•

Complete—This option builds the entire release.

•

Compile—This option compiles the Setup.rul script file. In Basic MSI and Merge Module projects, this option also streams ISSetup.dll into the Binary table of the .msi package.

•

Tables—This option builds only the Windows Installer tables for the database. If you have not built this installation already, a new .msi file is created, but no files are added to your installation. If you have built your installation already, the .msi file is updated when all the tables are built, but, again no files are transferred. Ideally, this option is to be used to test the user interface of your installation. This option is applicable to Basic MSI, InstallScript MSI, Merge Module projects.

•

TablesAndFiles—For Basic MSI, InstallScript MSI, and Merge Module projects, this option builds the Windows Installer tables and refreshes the files. This type of build can be run only after a complete build has been performed, and it works only when the media is an uncompressed network image.

For InstallScript projects, this option rebuilds only those portions of the release that have changed since the last build. If this parameter is not used, the entire file media library is rebuilt.

•

UpgradeOnly—This option enables you to upgrade—but not build—a Basic MSI project that was created in an earlier version of InstallShield.

BuildCompressed

Boolean

Basic MSI, InstallScript MSI, Merge Module

This parameter specifies whether your release is compressed into one file or remains uncompressed in multiple files.

BuildSetupExe

Boolean

Basic MSI, InstallScript MSI, Merge Module

For Basic MSI and InstallScript MSI projects, this parameter specifies whether you want to create a Setup.exe file along with your installation.

For merge module projects, this option specifies whether you want to build the merge module and also copy it to the merge modules folder, or just build the .merge module without copying it.

ProductVersion

String

Basic MSI, InstallScript MSI, Merge Module

This parameter specifies the product version. This is especially helpful if you want to increment the build version (the third field) of the product version.

For information on valid product version numbers, see Specifying the Product Version.

PropertyOverrides

ITaskItem[ ]

Basic MSI, InstallScript MSI, Merge Module

This parameter enables you to override the value of a Windows Installer property or create the property if it does not exist. To use this parameter, include a property list of items whose value is the new property value, and whose metadata Property is the name of the property.

This parameter is exposed as the InstallShieldPropertyOverrides ItemGroup passthrough to the PropertyOverrides property on the InstallShield task.

RunMsiValidator

ITaskItem[ ]

Basic MSI, InstallScript MSI, Merge Module

This parameter enables you to specify one or more .cub files to use for validating the installation package or merge module after it is built.

To learn more about validation, see Validating Projects.

RunUpgradeValidation

Boolean

Basic MSI, InstallScript MSI

This parameter specifies whether or not to run upgrade validation.

StopOnFirstError

Boolean

Basic MSI, InstallScript MSI, Merge Module

This parameter specifies whether or not to stop the build after an initial error.

MsiVersion

String

Basic MSI, InstallScript MSI, Merge Module

This parameter specifies the minimum version of Windows Installer that the installation can accept on the target machine.

DotNetFrameworkVersion

String

Basic MSI, InstallScript MSI

This parameter specifies the minimum version of the .NET Framework that the installation can accept on the target machine.

DotNetUtilPath

String

Basic MSI, InstallScript MSI

Regasm.exe and InstallUtilLib.dll are utilities that are included with each version of the .NET Framework. This parameter specifies the path for the directory that contains the 32-bit version of these files that you want to use at build time for releases that include .NET installer classes and COM interop. This is not the path to .NET Framework redistributable files.

Note • If you are using InstallShield on a 64-bit system, ISCmdBld.exe determines the location of the corresponding 64-bit version of the .NET Framework based on the path that you specify for this parameter, and ISCmdBld.exe uses the 64-bit location of Regasm.exe and InstallUtilLib.dll when appropriate.

Disk1Folder

Output String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

This parameter specifies the location of the output folder.

SummaryInfoComments

String

Basic MSI, InstallScript, InstallScript MSI, Merge Module

Use this parameter to set Summary Information Stream comments at build time, such as including the build number.

The comments that are added using this property can be viewed on the Properties dialog box of the built installer.

MSIPackageFileName

String

Basic MSI, InstallScript MSI

Use this parameter to specify the MSI package file name at build time. Specify the file name—without the period or the file extension—that InstallShield should use for the .msi file.

MSBuild Scripts

MSBuild natively understands one file format: its XML build script, which is used as the project file format for Visual C# and Visual Basic .NET projects (.csproj and .vbproj). MSBuild also has internal hooks to handle solution files and the Visual C++ project file format (.sln and .vcproj).

The InstallShield integration with Visual Studio uses an MSBuild-compatible XML format project file (.isproj), which enables MSBuild to seamlessly build Visual Studio solutions that include InstallShield projects. To build solutions in a standalone environment, install the InstallShield Standalone Build on the build machine.

Customizing the .isproj File

To incorporate changes for your InstallShield project into your .isproj file, add a PropertyGroup element or an ItemGroup element near the top of your .isproj file, or update an existing PropertyGroup or ItemGroup element. Then add InstallShield-related parameters as needed.

The following sample code from an .isproj file demonstrates how to do the following:

•

Set the product version.

•

Set the product name.

•

Set a custom public property called MY_PROPERTY to the value My Value.

•

Override a path variable called MyPathVariableName with a new value of C:\MyPath.

•

Specify the following search paths for InstallShield prerequisites: <ISProductFolder>\SetupPrerequisites and <ISProjectFolder>\MyCustomPrerequisites.

</PropertyGroup>

<Property>ProductName</Property>

</InstallShieldPropertyOverrides>

<Property>MY_PROPERTY</Property>

</InstallShieldPropertyOverrides>

<PathVariable>MyPathVariableName</PathVariable>

</InstallShieldPathVariableOverrides>

<InstallShieldPrerequisitePath Include="<ISProductFolder>\SetupPrerequisites"/>

<InstallShieldPrerequisitePath Include="<ISProjectFolder>\MyCustomPrerequisites"/>

</ItemGroup>

Microsoft Build Engine (MSBuild)

InstallShield 2018 Help Library

January 2018