ISWiSuiteRelease Object (Advanced UI and Suite/Advanced UI)

InstallShield 2015 » Automation Interface » Advanced UI and Suite/Advanced UI

Project: This information applies to the following project types:

Advanced UI
Suite/Advanced UI

Edition: The Advanced UI project type is available in the Professional edition of InstallShield. The Suite/Advanced UI project type is available in the Premier edition of InstallShield. For information about the differences between these two project types, see Advanced UI Projects vs. Suite/Advanced UI Projects.

Note that some edition- and project-specific differences are noted where applicable.

The ISWiSuiteRelease object represents a release in the Releases view of InstallShield.

To add or remove releases, call ISWiProject.AddSuiteRelease or ISWiProject.DeleteSuiteRelease.

Members

ISWiSuiteRelease Object Members

Name

Type

Description

Build

Method

Build a release. Note that to get any feedback about the build process, you must subscribe to events on the release. To learn more, see Using Build Status Events.

BuildLocation

Read-Write String Property

Gets or sets the top-level directory where the release will be built.

CachePackagesLocally

Read-Write Boolean Property

Gets or sets the Cache Packages Locally setting on the Setup.exe tab in the Releases view. This setting lets you specify whether you want to cache the Advanced UI or Suite/Advanced UI packages that are run on a target system in the location that is defined for each package in the Packages view. The default value is True.

If you are building an uncompressed release, you may want to specify No for the value of this setting.

CertPassword

Write-only String Property

Sets the password for the .pfx file if the file has a password. InstallShield encrypts the password and stores it in your project file (.ism).

At build time, InstallShield uses the password to sign files with a .pfx file. If your certificate is protected by a password but you do not enter it in this setting, signing with a .pfx file fails.

Note: This property is not applicable if the certificate that you are using for signing is in a certificate store. Note that if the certificate was imported into the store with password protection, you will be prompted to enter the password at build time.

DefaultLanguage

Read-Write String Property

Gets or sets the language identifier for the default language of a given release. This property value overrides the default project language that is configured in the General Information view or the String Editor view.

For more information, see Setting the Default Project Language.

DigitalCertificateInfo

Read-Write String Property

Gets or sets the digital certificate that you want to use to sign your release.

To specify a .pfx certificate on your machine, specify the path and file name.

To reference a certificate store that contains the certificate, use a string in the following format:

*Store*StoreLocation:Cert Subject

Store refers to the name of the certificate store that contains the certificate: Available options are:

My
Root
Trust
CA

StoreLocation refers to the location of the certificate store that contains the certificate. Available options are:

User
Machine

Cert Subject refers to the subject of the certificate.

DigitalURL

Read-Write String Property

Gets or sets the URL that is used in your digital certificate to link to a location that you would like end users to visit to learn more about your product, organization, or company. Use a fully qualified URL—for example, http://www.mydomain.com.

EnableLangSelectionDialog

Read-Write Boolean Property

Gets or sets the Languages Dialog setting on the Build tab in the Releases view. This setting lets you specify whether you want your installation to display the language selection wizard page when the installation is run with a full user interface.

LauncherPrivileges

Read-Write String Property

Gets or sets the Required Execution Level setting on the Setup.exe tab in the Releases view. This setting is where you specify the minimum level that is required by your project’s Setup.exe file for running on Windows Vista and later platforms. The available options are:

erelAsAdmin (2)Setup.exe requires administrative privileges to run. Administrators must authorize it; non-administrators must authenticate as an administrator.
erelAsHighestAvail (1)Setup.exe prefers administrative privileges. Administrators must authorize it; non-administrators run it without administrative privileges.
erelAsInvoker (0)Setup.exe does not require administrative privileges, and all users can run it without administrative privileges. Setup.exe does not display any UAC messages prompting for credentials or for consent. This is the default option for Advanced UI and Suite/Advanced UI projects.

InstallShield embeds an application manifest in the Setup.exe launcher. This manifest specifies the selected execution level. Operating systems earlier than Windows Vista ignore the required execution level.

Name

Read-Write String Property

Gets or sets the internal name for the release.

PackageLocation

Read-Write Boolean Property

Gets or sets the run-time location for the packages that are configured in the Packages view of the project. Available options are:

eplSourceMedia (0)—Copy from source media.
eplSetupExe (1)—Extract from Setup.exe.
eplWeb (2)—Download from the Web.
eplIndividual (3)— Follow individual selections.

To learn more, see Specifying the Run-Time Location for Advanced UI or Suite/Advanced UI Packages at the Release Level.

Password

Read-Write String Property

Gets or sets the password for your installation. Passwords are case-sensitive.

This property is used only if you the value of the PasswordProtect property is True.

To learn more, see Password-Protecting an Advanced UI or Suite/Advanced UI Installation.

PasswordProtect

Read-Write Boolean Property

Gets or sets the Password Protect Launcher setting on the Setup.exe tab in the Releases view. This setting lets you indicate whether you want to password-protect your installation.

To learn more, see Password-Protecting an Advanced UI or Suite/Advanced UI Installation.

PathVariableOverrides

Read-Write String Property

Gets or sets the value of a path variable in your project for the specified release. If this property is used to set the value of a path variable, it overrides any value that is set in the Path Variables view.

Note that you can use this variable to get or override user-defined path variables, environment variables, and registry variables that are configured in the Path Variables view; however, you cannot override predefined path variables such as <WindowsFolder>.

Following is sample Visual Basic code that overrides the value of a path variable called PathVar1:

pISWiSuiteRelease.PathVariableOverrides = "PathVar1=C:\Test1" + vbCrLf + "PathVar2=C:\test2"

PostBuildEvent

Read-Write String Property

Edition: This property is available in the Premier edition of InstallShield.

Gets or sets the command that is run after InstallShield has built and signed the release.

To specify more than one command, enter each command on a separate line in the string. At build time, InstallShield runs each command in the order that they are listed. The build waits until a command finishes before proceeding to the next one.

When you are entering a command, you can use any path variables and environment variables that are defined in your project, instead of using a hard-coded path. You can also use certain variables that are defined specifically for build event commands. To learn more, see Specifying Commands that Run Before, During, and After Builds.

PreBuildEvent

Read-Write String Property

Edition: This property is available in the Premier edition of InstallShield.

Gets or sets the command that is run before InstallShield starts building the release. This event runs after InstallShield creates the release folder and log file, but before InstallShield starts building the release.

To specify more than one command, enter each command on a separate line in the string. At build time, InstallShield runs each command in the order that they are listed. The build waits until a command finishes before proceeding to the next one.

When you are entering a command, you can use any path variables and environment variables that are defined in your project, instead of using a hard-coded path. You can also use certain variables that are defined specifically for build event commands. To learn more, see Specifying Commands that Run Before, During, and After Builds.

PreProcessorDefines

Read-Write String Property

Project: This information applies to Suite/Advanced UI projects.

Gets or sets the preprocessor variable definitions. Preprocessor variable definitions that are specified here apply only to the current release; they are not used when compiling the script for other releases. Use the following format, with no spaces before or after equals signs or commas:

MYVARIABLE1=123,MYVARIABLE2

Such variables can be tested in the script by #if and #ifdef statements that control the flow of the script.

Entering the name of a preprocessor variable for this setting defines the variable. For example if you enter MYVARIABLE for this setting, the script commands in the following #ifdef loop are executed:

#ifdef MYVARIABLE

   // Commands

#endif

After you add or change a preprocessor variable definition for this setting, you must compile your installation for the addition or change to take effect.

ProductNameOverride

Read-Write String Property

Gets or overrides the product name that was specified in the General Information view with a new value for the selected release. For information on how the product name is used, see Specifying a Product Name.

ProductVersionOverride

Read-Write String Property

Gets or overrides the product version that was specified in the General Information view with a new value for the selected release. The version must contain only numbers. The version number is typically in the format aaa.bbb.ccccc or aaa.bbb.ccccc.ddddd, where aaa represents the major version number, bbb represents the minor version number, ccccc represents the build number, and ddddd represents the revision number. The maximum value for the aaa and bbb portions is 255. The maximum value for ccccc and ddddd is 65,535.

Note that although you can include the fourth field (ddddd), the installation does not use this part of the product version to distinguish between different product versions. To learn more, see Specifying the Product Version.

The product version that you specify is displayed on the Properties dialog box for Setup.exe. For more information, see Customizing File Properties for the Setup Launcher.

ReleaseFlags

Read-Write String Property

Gets or sets a string that contains the release flags that you want to use to filter your features. Separate multiple flags with a comma.

Release flags enable you to customize your installation by including or excluding certain items in each release.

Once you have assigned release flags to features and packages in the Advanced UI or Suite/Advanced UI project, you can create a release that includes features and packages based on those flags. By default, all features and packages are included in a release. Once you specify a flag for the ReleaseFlags property (or for the Release Flags setting on the Build tab in the Releases view), only unflagged items and items that contain the specified release flag are included in your installation.

Note: If a release does not have release flags, it will include all applicable items that have release flags. To include only unflagged items, specify a flag that does not exist. For example, you might use NoFlags. This way, only unflagged items are built into a release.

SetupExeCompany

Read-Write String Property

Gets or sets the value to override the default company name for Setup.exe. Note that you must also select a value of True for the UseMyVersionInfo property.

The company name is displayed on the Properties dialog box for the setup launcher; this Properties dialog box opens when end users right-click the Setup.exe file and then click Properties.

To learn more, see Customizing File Properties for the Setup Launcher.

SetupExeCopyright

Read-Write String Property

Gets or sets a custom copyright notice for Setup.exe. Note that you must also select a value of True for the UseMyVersionInfo property.

The copyright is displayed on the Properties dialog box for the setup launcher; this Properties dialog box opens when end users right-click the Setup.exe file and then click Properties.

To learn more, see Customizing File Properties for the Setup Launcher.

SetupExeDescription

Read-Write String Property

Gets or sets a custom file description for Setup.exe. Note that you must also select a value of True for the UseMyVersionInfo property.

The description is displayed on the Properties dialog box for the setup launcher; this Properties dialog box opens when end users right-click the Setup.exe file and then click Properties.

To learn more, see Customizing File Properties for the Setup Launcher.

SetupExeVersion

Read-Write String Property

Gets or sets the value to override the default product version and file version for Setup.exe with your own version number. Note that you must also select a value of True for the UseMyVersionInfo property.

The product version and file version are displayed on the Properties dialog box for the setup launcher; this Properties dialog box opens when end users right-click the Setup.exe file and then click Properties.

Note that the file version always contains four fields. If you specify fewer than four fields for your product version, the remaining fields are filled with zeros. For example, if you specify a product version of 1.1, the file version that is used in the version resources of Setup.exe is 1.1.0.0.

To learn more, see Customizing File Properties for the Setup Launcher.

SetupFileName

Read-Write String Property

Gets or sets the file name—without the .exe file extension—that InstallShield should use for the setup launcher file that it generates at build time. If this setting is blank, InstallShield uses the default value of Setup, and the setup launcher file is called Setup.exe.

SetupIcon

Read-Write String Property

Gets or sets the release’s Setup.exe Icon File setting, which specifies the fully qualified name of the file from which the executable file’s icon is taken at build time. If the property’s value is null, a default icon is used.

By default, the icon with index 0 is used; to specify a different icon, add a comma (,) as well as the icon's index or resource ID (preceded by a minus sign) after the file name. For example, C:\Temp\MyLibrary.dll,2 indicates the icon with an index of 2, and C:\Temp\MyLibrary.dll,-100 indicates the icon with a resource ID of 100.

Instead of hard-coding a path, you can use a path variable that is defined in the Path Variables view or part of the ISWiPathVariables collection. At build time, InstallShield replaces the path variable with the appropriate value.

SignatureDescription

Read-Write String Property

Gets or sets the signature description for the Setup.exe file. The description that you specify is displayed on the User Account Control (UAC) box to the right of the “Program Name:” label. The UAC dialog box opens when an end user launches the signed file and elevated privileges are required.

If you leave this setting blank, InstallShield uses the name of the file without its extension as the description to the right of the “Program Name:” label on the UAC dialog box.

SignEnabled

Read-Write Boolean Property

Gets or sets the Sign Setup.exe setting on the Signing tab in the Releases view. This setting lets you indicate whether you want to sign the Advanced UI or Suite/Advanced UI installation.

SuiteGuidOverride

Read-Write String Property

Gets or overrides the GUID that uniquely identifies the Advanced UI or Suite/Advanced UI installation.

UILanguages

Read-Write String Property

Gets or sets a comma-delimited string of decimal language identifiers of the user interface languages that are includes in a release.

Note that if a language is not selected in the Setup Languages setting in the General Information view of the project, it is not a valid language for the UILanguages property.

UpdateUrl

Read-Write String Property

If you may want to make updates for your Advanced UI or Suite/Advanced UI setup launcher available for download when they are available, use this property to specify the absolute path, including the file name, for an updated Advanced UI or Suite/Advanced UI setup launcher. This support makes it possible for end users to easily obtain a newer version of your product before installing an earlier version.

For more information about updates for your Advanced UI or Suite/Advanced UI installation, including requirements for the update, see Supporting Downloadable Updates for an Advanced UI or Suite/Advanced UI Installation.

UseMyVersionInfo

Read-Write Boolean Property

Gets or sets the Use Custom Version Properties setting on the Setup.exe tab in the Releases view. This setting lets you specify whether you want to override the default copyright notice and file description for Setup.exe with your own copyright notice and file description. If you specify a value of True, enter your own custom values for the SetupExeCopyright and SetupExeDescription properties.

The copyright and description are displayed on the Properties dialog box for the setup launcher; this Properties dialog box opens when end users right-click the Setup.exe file and then click Properties.

To learn more, see Customizing File Properties for the Setup Launcher.

UsePathVariableTestValues

Read-Write Boolean Property

If you used test values for any of your path variables, set this property to True to set those variables to their actual values at this time.

VMConfig

Read-Write String Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

Gets or sets the name of the group of VM configuration settings that you want to use when distributing the selected release to a VM.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

VMMachinePassword

Read-Write String Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

If a password is specified for the VM configuration that is selected through the VMConfig property, that password is considered to be the default value for the VMMachinePassword property. To override the password for the selected release, set the VMMachinePassword property.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

VMMachineUserName

Read-Write String Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

If a user name is specified for the VM configuration that is selected through the VMConfig property, that user name is considered to be the default value for the VMMachineUserName property. To override the user name for the selected release, set the VMMachineUserName property.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

VMSnapShot

Read-Write String Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

Optionally gets or sets the name of the snapshot that you want to use for distributing the release.

If a snapshot is specified for the VM configuration that is selected through the VMConfig property, the name of that snapshot is considered to be the default value for the VMSnapShot property.

If no snapshot is specified for the VM configuration, InstallShield does not revert to a specific snapshot. InstallShield powers on the VM without reverting it to a specific snapshot, and copies your installation to the VM.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

VMStageMachineCopyPath

Read-Write String Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

The copy path identifies the location on the VM where the release is to be distributed. The last subfolder in the path can be a path that InstallShield creates on the VM; the other folders in the path must already exist.

If a destination path is specified for the VM configuration that is selected through the VMConfig property, that destination path is considered to be the default value for the VMStageMachineCopyPath property. To override the destination path for the selected release, set the VMStageMachineCopyPath property.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

VMStagePostBuild

Read-Write Boolean Property

Project: This is available in Suite/Advanced UI projects.

Edition: The Suite/Advanced UI project type is available in the Premier edition of InstallShield.

Specify whether you want InstallShield to automatically distribute the selected release each time that it is successfully built. Distributing the release to the VM involves the following tasks:

1. Revert the VM to the designated snapshot (if one is specified).
2. Power on the VM.
3. Copy the built release to the VM to make it available for testing.

To learn more about VM distribution, see Distributing Releases to a Virtual Machine that InstallShield Provisions at Build Time or on Demand.

Applies To

ISWiProject