InstallAware 7

WEB AWARE | SCRIPTING AWARE | WINDOWS INSTALLER AWARE

Welcome to InstallAware for Windows Installer. InstallAware is a next-generation tool for creating scriptable, web enabled, Windows Installer based setup programs.

Use this Help system to find conceptual, procedural, and reference information about InstallAware.

The following Web pages offer additional assistance, information, and resources:

  • InstallAware Online Ordering
  • InstallAware Support Forums
  • InstallAware Home Page

Note:

Not all features described in this Help system are available in all editions of the product.
If your Internet access is limited by network security, or if your computer is protected by a personal firewall, the Web-based links in this Help system might not function properly.

Copyright© 1996-2013 InstallAware Software. All rights reserved.


The Native Engine

InstallAware includes a native code setup engine beginning with InstallAware version 10. The native engine complements Microsoft's Windows Installer setup engine and provides faster execution speeds and greater flexibility at runtime.

Hybrid Installation Technology

Since Windows Installer is database based, the breadth of actions that are possible for execution are essentially locked-in at build-time. While InstallAware transcends the majority of these limitations through MSIcode scripting, certain language constructs like loops cannot be natively supported within the confines of Windows Installer. InstallAware's native engine transcends these limitations, while not sacrificing the flexibility of using the Windows Installer engine, along with the native engine, within the same setup.

The engine modes are even dynamically switchable at runtime.

The native engine also removes any dependencies on the Windows Installer runtime, and can successfully empower installations even when the Windows Installer stack on target systems has been corrupted.

An additional benefit of the native engine is that while the Windows Installer service is not accessible in Windows's Safe Mode, the native engine remains fully accessible. Windows Installer based applications cannot be removed/repaired while in Safe Mode, but this limitation is transcended by the native engine. Applications installed using InstallAware's native engine can be repaired/removed normally while in Safe Mode.

Enabling the Native Engine

You may begin taking advangate of the new native code setup engine in your existing projects with a single line of code:

Set Variable NATIVE_ENGINE to TRUE

There is also a new, pre-built Native Engine project template available, which illustrates how to perform 32 bit-64 bit hybrid installations using the new native code setup engine, including full support for uninstallation of old product versions and the modification of installed setup features during maintenance.

Native Engine Enhancements

Some commands behave differently with the native engine, featuring enhanced and more flexible runtime behavior compared to the Windows Installer engine. Below is the list of commands that perform differently between the two engines:

  • Apply Changes
  • Control Service
  • Copy/Move Local Files
  • Create ODBC DSN
  • Create Shortcut
  • Delete Files
  • Edit INI File
  • Install Files
  • Install Service
  • Set Environment

Typically, where commands would not accept variables with the Windows Installer engine, they now do accept variables when the Native Engine is used instead - offering you greater runtime flexibility. Please refer to the command topics themselves for detailed descriptions of the new functionality provided by the native engine.

Native Engine Limitations

The native engine is not intended to duplicate the Windows Installer engine. Instead, it is designed to provide a faster, non-transactional alternative to the Windows Installer engine. The native engine may be used stand-alone or as a complement to the existing Windows Installer engine. The following are the limitations of the native code setup engine:

  • You cannot create binary differential patches for setups built with the native engine.
  • Setups built wih the native engine do not perform rollbacks, however they do perform cleanups after failed (or cancelled) installations.

Empowered by InstallAware's hybrid installation technology, you are free to choose the engine(s) best suited to your requirements. Remember, you are not limited to using just one engine, and may swap in and out of either engine mode at runtime, directly within your setup script.

Tweaking Native Engine Behavior

The following pre-defined variables control native engine behavior at runtime:

  • DELAYUNTIL_APPLYCHANGES: Emulates Windows Installer behavior with the native engine by preventing changes to the target system until Apply Install is called in the setup script. Also affects progress calculation within the native engine and determines whether native engine errors are treated as fatal.
  • NATIVE_ENGINE: Toggles the setup between native and Windows Installer modes. Each installation mode is logged separately and there is no restriction on the number of times a setup may change installation modes at runtime.
  • NATIVE_ERROR: Controls how errors in the native code setup engine are handled.
  • NATIVE_LOGGING: Enables or disables logging for the native setup engine. May also be used to bind setup to an existing setup log created by an external InstallAware setup.
  • NATIVE_OLDLOG: Points to the native engine log file created by a previous version of the same installer.
  • NATIVE_OVERWRITE: Controls how files are to be overwritten by the native code setup engine.
  • NATIVE_OVERWRITE_OLDER: Determines whether the native engine is permitted to overwrite newer files with older versions.
  • NATIVE_ROLLBACK: Controls whether a cancelled setup will attempt to roll back the changes that were logged.
  • RECOMMENDEDUPGRADE: Indicates whether an old version of the same product has been installed using the native engine.

The following pre-defined compiler variables control native engine behavior at build time:

  • NO_MSI: Controls whether Windows Installer support will be disabled at runtime - when disabled, this speeds up the setup build process.


InstallAware is Web Aware

Every member of the InstallAware product family is aware of online distribution. Setups can be built for and executed directly from the web. Of course, support for traditional distribution methods such as CD/DVD media is also provided.

InstallAware's web aware installation technology offers the following compelling distribution advantages:

  • Only required/chosen features will be downloaded during setup, conserving bandwidth
  • Broken/interrupted downloads will automatically resume when setup is restarted
  • Proxy servers are fully supported - users will be prompted automatically if necessary

If you would like to read a technical whitepaper on InstallAware's web deployment technologies, please follow this link: http://www.installaware.com/webaware_installation_technology.pdf.


InstallAware is Scripting Aware

InstallAware embraces and extends Windows Installer like no other product available today. Using standards compliant Windows Installer technology comes at a cost: loss of scripting, and conditional setup flow. If you have attempted Windows Installer before, you have most likely found yourself concentrating on not what to install, but how to install.

InstallAware's unique technology remains within the bounds of Windows Installer, and brings genuine scripting to this platform:

  • Your entire setup is a visual script with conditional execution and branching
  • Each installation action in your script is automatically converted into Windows Installer tables
  • When your script is running, only Windows Installer actually modifies the target system
  • No matter how complex your installation script is...it always remains fully ICE compliant, at no extra effort on your part!

If you would like to read a technical whitepaper on InstallAware's scripting technologies, please follow this link: http://www.installaware.com/msicode_scripting_technology.pdf.

Beginning with InstallAware version 10, InstallAware also features a native code setup engine.


InstallAware is Windows Installer Aware

All members of the InstallAware family of products use the latest in installation technology: Windows Installer. Coming direct from Microsoft, Windows Installer has become the standard in software installation and provides a streamlined, robust installation experience. Windows Installer is integrated into each recent version of Windows, and can be added to earlier versions of Windows as well.

InstallAware, at no extra effort on your part, gives you the following:

  • Absolutely no knowledge of Windows Installer or its complex database is required
  • Your entire setup is executed by Windows Installer, providing for bullet-proof installations
  • Using Windows Installer means your application qualifies for testing to receive the Designed for Windows certification
  • Windows Installer databases created by InstallAware are all ICE compliant, meaning they will pass installer testing during the certification process

If you would like to read a technical whitepaper on how InstallAware supports and extends Windows Installer, please follow this link: http://www.installaware.com/msicode_scripting_technology.pdf.

Beginning with InstallAware version 10, InstallAware also features a native code setup engine.


InstallAware Digital Rights Management

InstallAware includes DRM functionality beginning with InstallAware version 12.

To start the InstallAware Digital Rights Management tool, in the Start menu, in the InstallAware group, select InstallAware Digital Rights Management.

  1. Enter the full path to the application to wrap in the Application to Convert (*.EXE) field. The specified file will be overwritten with the wrapped file.
  2. Enter a unique identifier for your application in the Unique Identifier (GUID) field. Once an application associated with a particular GUID has expired on a target system, installing a newer version of the same application that has been protected using the same GUID will not restart the trial period - the application will still remain expired.
  3. Enter the title of your application in the Application Title field.
  4. Enter the version of your application in the Application Version field. Be sure to use numeric values only. Decimal points are the only non-numeric characters permitted in this field.
  5. Enter the name of your company in the Application Manufacturer field.
  6. Enter the cost of your application, in USD, in the Application Cost (USD) field. Be sure to use numeric values only. Decimal points are the only non-numeric characters permitted in this field.
  7. To expire the protected application without regard for actual live use, check the Always expire after radio button, and choose from the following additional options (8-11).
  8. To expire the application after a certain number of launches, check the Number of launches box, and specify the number of launches to allow.
  9. To expire the application after a certain number of days from the day of first run, check the Number of days box, choose the Days after installation radio button, and specify the number of days to allow.
  10. To expire the application at a fixed date (such as a beta release product), check the Number of days box, choose the Absolute expiration date radio button, and specify the exact calendar date to expire on.
  11. You may combine a date based expiration limit together with a launch number limit.
  12. To expire the protected application based on actual live use, check the Expire only after actual use box, and specify the number of hours and minutes to allow for the protected application to run.
  13. If you would like to enable in-application purchasing for protected applications, provide the full path to your Softwrap certificate in the Softwrap Certificate File (*.SW9) field. Please note that all ecommerce services, including royalty payments, are provided by Softwrap, and not InstallAware. Populating this field is optional: if the field is empty, your application cannot be purchased after expiration (Try-And-Die); otherwise your application may be purchased after expiration (Try-And-Buy).
  14. Click the Convert button to protect your application with InstallAware DRM and convert it into trialware.

To wrap your applications using InstallAware Digital Rights Management outside of the InstallAware IDE, use this tool.

This tool offers additional manual control over the InstallAware IDE in wrapping your applications:

  • The InstallAware IDE only permits you to wrap applications as part of a setup or patch build process; this tool permits you to wrap applications at any time (including from the command line).
  • The InstallAware IDE does not directly update the application to wrap itself; but instead creates a temporary file for use as the wrapped application and includes that temporary file in the setup being created. This tool directly updates the application to wrap itself.

Using the InstallAware Digital Rights Management tool from the Command Line

You may also run the InstallAware Digital Rights Management tool from the command line. Every field of the tool has corresponding command line parameters. When calling the tool from the command line, provide values for the fields as required for your wrapping mode (use the interactive version of the tool first, if you have any doubts about the parameters that are required). If any of your command line parameters include spaces, also remember to enclose them in double quote signs on the command line.

Parameter | Meaning
EXE | The full path to the application binary.
GUID | The unique identifier of the application.
TITLE | The product name of the application.
VERSION | The application version.
COMPANY | The manufacturer of the application.
PRICE | The USD cost of the application.
ALWAYSEXPIRE | Corresponds to selecting the Always expire after radio button.
BYLAUNCHES | Corresponds to checking the Number of launches box.
LAUNCHES | Indicates the number of launches to allow as part of the trial duration.
BYDAYS | Corresponds to checking the Number of days box.
BYDAYRELATIVE | Corresponds to selecting the Days after installation radio button.
DAYS | Indicates the number of days to allow as part of the trial duration.
BYDAYABSOLUTE | Corresponds to selecting the Absolute expiration date radio button.
YEAR | Indicates the absolute expiration year.
MONTH | Indicates the absolute expiration month.
DATE | Indicates the absolute expiration date.
REALUSE | Corresponds to selecting the Expire only after actual use radio button.
HOURS | Indicates the actual hours to allow as part of the trial duration.
MINUTES | Indicates the actual minutes to allow as part of the trial duration.
CERTIFICATE | The full path to the Softwrap certificate.
BUILD | Instructs the tool to perform the actual wrapping. Required.

Examples:

pdrm.exe "/EXE=C:\output files\myapp.exe" /GUID={B7830C5A-D5BF-4544-B855-990BF09944D0} "/TITLE=My Application" /VERSION=12.00 "/COMPANY=My Company" /PRICE=29.95 /ALWAYSEXPIRE /BYLAUNCHES /LAUNCHES=10 /BYDAYS /BYDAYRELATIVE /DAYS=10

In the above example, the tool will prepare to wrap the executable at the location C:\output files\myapp.exe in Try-And-Die mode with 10 runs and 10 days after installation allowed. Because the /build switch is not specified, the actual wrapping will not begin until end-user interaction.

pdrm.exe "/EXE=C:\output files\myapp.exe" /GUID={B7830C5A-D5BF-4544-B855-990BF09944D0} "/TITLE=My Application" /VERSION=12.00 "/COMPANY=My Company" /PRICE=29.95 /ALWAYSEXPIRE /BYDAYS /BYDAYABSOLUTE /YEAR=2011 /MONTH=8 /DATE=1 /BUILD

In the above example, the tool will immediately wrap the executable at the location C:\output files\myapp.exe in Try-And-Die mode with a hard coded expiration on August 1st, 2011.

pdrm.exe "/EXE=C:\output files\myapp.exe" /GUID={B7830C5A-D5BF-4544-B855-990BF09944D0} "/TITLE=My Application" /VERSION=12.00 "/COMPANY=My Company" /PRICE=29.95 /REALUSE /HOURS=1 /MINUTES=30 "/CERTIFICATE=C:\softwrap certificates\softwrap.sw9" /BUILD

In the above example, the tool will immediately wrap the executable at the location C:\output files\myapp.exe in Try-And-Buy mode with up to 90 minutes of real trial use time permitted.

By using the InstallAware Digital Rights Management tool from the command line, you will enable it to participate in unattended builds. When run from the command line, the wizard does not display any prompts or require any user interaction.

The tool returns the following codes to indicate success/failure:

  • 0: Process completed successfully
  • 1: Error during process


What's New

What's New in InstallAware 15

InstallAware 15 contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • The IDE may now import self-registration data from 64 bit COM servers using the Registry design view.
  • The IDE now allows choosing between three different web update modes: automatic, manual, or scheduled.
  • Settings for the new Native Engine 2.0 have been added to the Power Tweaks design view.
  • All components, including the automation interface, the IDE, plug-ins, and the command line build tool, now transcend path length limitations when building setups.

Tools and Libraries

  • The new InstallAware Inline Update tool permits you to issue inline updates for large monolithic or web deployed setups over low bandwidth connections.
  • The updated PackageAware tool is now the fastest setup repackager in the industry.
  • The updated PackageAware tool supports multiple custom capture profiles.
  • The updated PackageAware tool directly captures setups using proprietary InstallAware technologies.
  • The updated PackageAware tool saves and compares any two arbitrary system snapshots.

Plug-Ins

  • The runtimes for Microsoft .NET Framework 2.x have been enhanced to enable installation on Windows 8 and Windows Server 2012 even on unstable Internet connections.
  • The runtimes for Microsoft .NET Framework 3.x have been updated to enable installation on Windows 8 and Windows Server 2012.
  • The new automatic web update mode directly checks for, downloads, and runs newer setup versions when an installation is run, which may also be used to build dynamically updated product bundles with your main installation.

Setup Engine

  • The setup engine can now successfully install your product under all combinations of display languages, user account names, and system locales for non-unicode programs.
  • The new $NATIVE_OVERRIDE_PERMISSIONS$ pre-defined variable permits to overwrite file and registry data in protected system areas when using the new Native Engine 2.0 when the original object permissions can be retained.
  • The new $NATIVE_OVERRIDE_NON_RESTORABLE_PERMISSIONS$ pre-defined variable permits to overwrite file and registry data in protected system areas when using the new Native Engine 2.0, even when the original object permissions cannot be retained.

Setup User Interface

  • The AeroBackButton now automatically displays Windows 8 style back buttons when running on Windows 8 or newer.

New Scripting Commands

  • The new Find All Registry command obtains the names of all subkeys or values contained within a registry key.

What's New in InstallAware NX

InstallAware NX contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • The Summary, UAC, and ISO design view now lets you set the ISO/IEC 19770-2:2009 software identification (SWID) tag for your application.
  • The New Project dialog now lets you promote any setup project into a project template.
  • The Replace dialog now replaces all instances of text found in a setup command, instead of replacing only the first instance.
  • The Authenticode Signature design view now has an option to automatically code sign all .EXE, .DLL, .OCX, .SYS, .CPL, .DRV, and .SCR files being installed by setup for Windows 8 logo program compliance.
  • The Build Settings design view now has an option to automatically build all setup layouts as MSI files.
  • The Project Manager now opens all script and dialog browsers inside the active project folder.
  • The Add Dialogs to Project window now permits adding more than one custom dialog simultaneously.
  • You may now create and navigate to bookmarks inside the MSIcode script editor.
  • The code navigation drop-downs now include the full list of available MSIcode script bookmarks.
  • The IDE now prompts to confirm when you attempt to save a read-only file, to ensure your project folders remain synchronized with source control.
  • The IDE most recently used file list now accomodates double the number of projects and displays full project paths on mouse-over.

Tools and Libraries

  • The Dialog Editor now automatically refactors rules when the name of a dialog control is changed.
  • A Visual Studio 2012 Add-In is now available. The add-in automatically generates and builds InstallAware setups for your Visual Studio 2012 solutions. These may then be built as App-V virtualized packages using the Build App-V Package tool.
  • All Visual Studio Add-In generated projects have been updated for the Microsoft .NET Framework 4.5 eco-system, automatically including the new Microsoft .NET Framework 4.5 runtimes as necessary.
  • Group Policy Wizard generated MSI files now do not display dual User Account Control elevation prompts. Elevation prompts are no longer hidden in the background.
  • Group Policy Wizard generated MSI files now display progress feedback with cancel support when extracting large payloads.
  • The App-V Viewer tool has been updated with performance and stability improvements.
  • The command line build tool may now add patch references not included in the original project.
  • A new MiaBuildProjectEy function is available as part of the automation interface which displays the build window with a parent handle.
  • A new .NET assembly is now available as part of the automation interface for use within the .NET eco-system.
  • New MFC, C#, and ASP.NET samples are available for use with the automation interface.
  • The Product Name and Product Version fields in the version information structures of built EXE files are now populated.

Plug-Ins

  • A new .NET Plug-In Bridge is available for calling managed code plug-in assemblies from your setups.
  • A new runtime is available for Microsoft SQL Server 2012.
  • The runtimes for Microsoft .NET Framework 2.0, 2.0 with Service Pack 1, and 2.0 with Service Pack 2 have been updated to enable installation on Windows 8 and Windows Server 2012.
  • New runtimes are available for the Microsoft .NET Framework 4.5 in both 32 bit and 64 bit flavors.
  • New runtimes are available for the Microsoft Visual C++ 11 Runtime in both 32 bit and 64 bit flavors.
  • New runtimes are available for the Microsoft SQL Server 2012 Native Client in both 32 bit and 64 bit flavors.
  • New runtimes are available for the Microsoft IIS Express 8 Web Server in both 32 bit and 64 bit flavors.
  • A new Microsoft Report Viewer 2012 runtime is available, including its pre-requisite runtime Microsoft System CLR Types for SQL Server 2012.

Setup Engine

  • The new $CHARSET_OVERRIDE$ pre-defined variable permits to automatically change dialog font character sets without having to duplicate dialogs in multi-lingual setups.
  • Setup billboards now resume automatically from the last billboard shown instead of resetting to the first billboard between different displays of progress dialogs.
  • The $NATIVE_LOGGING$ pre-defined variable can no longer be overridden unless a full file path (including full folder information) is provided.
  • Double-buffering for setup controls is now selectively enabled based on the active system theme, for improved display of setup controls.
  • The new #SIGN_ALL_INPLACE# pre-defined compiler variable controls whether code signing occurs in-place or out-of-place during a build.

New Scripting Commands

  • The new Evaluate XPath Query command runs an XPath query against a specified XML file.
  • The new For Each and Next commands allow for the construction of for loops.

Updated Scripting Commands

  • The Advertised Shortcut/Create Shortcut commands can now run applications as administrator on operating systems with User Account Control (or run them with alternate credentials on operating systems older than Windows Vista).
  • The Advertised Shortcut/Create Shortcut commands can now prevent the automatic inclusion of shortcuts on the new Windows 8 Start Screen.
  • The Advertised Shortcut/Create Shortcut commands can now prevent the user pinning of applications.
  • The Break and Continue commands allow for immediately terminating or continuing to the next iteration of for loops.
  • The Convert Path command now expands environment variables, supports relative paths, and prepends the setup folder to paths that lack drive letters.
  • The Get System Settings command now supports Microsoft Hyper-V virtual machine detection.

What's New in InstallAware 2012

InstallAware 2012 contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • The Files design view now displays both $TARGETDIR$ and $TARGETDIR_X86$ folders when editing hybrid setups containing both 32 bit and 64 bit components, making it very easy to choose where to place your files on 64 bit target operating systems.
  • The IDE now displays native 64 bit registry keys in the Registry design view when running on 64 bit operating systems. Previously, only 32 bit registry keys were visible. These keys still remain visible under the Wow6432Node key.
  • The Shortcuts visual designer of the InstallAware IDE gives your applications prime exposure by pinning them to the Windows 8 Immersive Application Tiles. Use the New Shortcut window to create new shortcuts with pins, or add pins to your existing shortcuts by double-clicking them in the visual designer and editing shortcut properties.

Tools and Libraries

  • The new Build App-V Package tool builds existing InstallAware projects as App-V virtualized packages, either interactively or from the command line. Hybrid 32 bit-64 bit App-V packages are supported.
  • The new App-V Viewer tool views the contents of any existing App-V virtualized package, including those that were not built from InstallAware projects.
  • All build tools, including the automation interface, the IDE, and the command line build tool, may now source files from 64 bit folders when running on 64 bit operating systems. Previously, file system redirection resulted in 32 bit files being sourced instead.
  • A Visual Studio 2011 Add-In is now available. The add-in automatically generates and builds InstallAware setups for your Visual Studio 2011 solutions. These may then be built as App-V virtualized packages using the Build App-V Package tool.

Updated Scripting Commands

  • The Advertised Shortcut/Create Shortcut commands now offer flags to pin the shortcut target to the Windows 8 Immersive Application Tiles. This invaluable real estate provides your applications with prime exposure.
  • The Get Folder Location command can now obtain the path for the Immersive Application Shortcuts folder.
  • The Get OS or SP Level command now supports Windows 8 and Windows Server 2012.
  • The Get System Settings command now supports Windows 8, Windows Server 2012, Internet Explorer 10, and Internet Information Server 8.

What's New in InstallAware 12

InstallAware 12 contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • The new Trialware and DRM design view lets you protect and sell your applications using InstallAware Digital Rights Management.
  • The new Power Tweaks design view lets you browse and edit advanced setup switches, and optimize your setups for performance or integrity.

Tools and Libraries

  • The new InstallAware Digital Rights Management tool permits you to manually wrap your applications and sell them using InstallAware Digital Rights Management, and may participate in automated build processes such as batch files.

Setup Engine

  • The setup engine now features folder path auto-completion for all edit controls which have been bound to path variables. An edit control is bound to a path variable if its Receives Information field has been set to Installation Folder. An edit control is also bound to a path variable if its Receives Information field has been set to [Written Variable Value], and the variable name specified in its Writes Values to Variable field is the same as the name of a button whose Performs Action field has been set to Select Custom Folder (per the same technique used to specify more than one target installation path on the same dialog).
  • The new $CUSTOM_TASKBAR_PROGRESS_ENABLED$ pre-defined variable permits to manually control the new Windows 7 Taskbar progress display.
  • The new $CUSTOM_TASKBAR_PROGRESS_MAX$ pre-defined variable sets the progress maximum for the new Windows 7 Taskbar progress display.
  • The new $CUSTOM_TASKBAR_PROGRESS_PERCENT$ pre-defined variable sets the current progress for the new Windows 7 Taskbar progress display.
  • You may now use the pre-defined variable $NATIVE_LOGGING$ to bind to new setup logs with the Native Code Setup Engine. This enables, for instance, building Multiple Instance setups with the Native Engine.

Updated Scripting Commands

  • The Advertised Shortcut/Create Shortcut commands can now prevent secondary tool and application shortcuts from being highlighted on the new Windows 7 Start Menu.

What's New in InstallAware 11

InstallAware 11 contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • A new free edition of InstallAware is available. The free edition integrates with Visual Studio and does not provide a stand-alone IDE or build tools. Projects created by the free edition may be edited in any of the four paid editions.
  • The IDE now features a new Office 2010 style user interface.
  • The new XML Files visual designer lets you edit data inside new or existing XML files.
  • The new Users and Groups visual designer lets you create user accounts and user groups on target systems.
  • The new Games and Media Center visual designer lets you create Windows Games Explorer items on Windows Vista and higher, and Windows Media Center items on Windows XP Media Center Edition 2005 and higher.

Tools and Libraries

  • Various template and sample projects have been updated to take advantage of new Aero support.
  • The Java Template project has been updated for Java Runtime Environment 6, Standard Edition Update 25.
  • The Code Signing tool has been updated to work with PFX format digital signature files, in addition to the existing SPC/PVK format file pairs.

Plug-Ins

  • The application runtimes for Microsoft .NET Framework 4 have been updated to display deterministic installation progress. The client profile runtime is now a dependency of the full runtime.
  • The SQL Server Express plug-in now installs Microsoft SQL Express 2005 with Service Pack 4.
  • A new runtime is available for Microsoft Internet Information Services Express 4.5.
  • New runtimes are available for Microsoft SQL Server Compact 4.0 in x86 and x64 editions.
  • New runtimes are available for Windows Internet Explorer 9 in x86 and x64 editions.

Setup Engine

  • The $MYAHLOGO$ pre-defined variable may be used to hide the InstallAware Wizard setup dialog caption text.
  • The InstallAware Wizard initialization dialog now renders entirely on Aero Glass where available.
  • The InstallAware Wizard initialization dialog icon may now be changed using the Creatives design view.
  • Aero/Glass support in the setup engine has now left beta stage and is production quality. Please see Building Aero Glass Dialogs for more information.
  • The new $GLASS$ pre-defined variable indicates whether Aero or Basic Windows 7 / Windows Vista theme is currently active on the system.
  • The new #IGNOREMISSINGFILES# pre-defined compiler variable controls whether builds fail when invalid file references are found during a build.

Setup User Interface

  • The Impact dialog theme, Official dialog theme, and the Web Update dialogs have been updated for Aero.
  • New dialog controls are available for Aero: AeroButton, AeroBackButton, AeroPNGButton, and AeroPNGImage.
  • New Aero themes are available for Aero: Aero, and Glass.

New Scripting Commands

  • The new Create Games Explorer command creates a new Windows Games Explorer item.
  • The new Create Group command creates a new user group.
  • The new Create Media Center command registers an application with Windows Media Center.
  • The new Create User command creates a new Windows user account and adds it to one or more user groups, with support for detecting the correct user group name, even on localized systems. The command may also be used to add existing user accounts to one or more user groups.
  • The new Delete Games Explorer command deletes an existing Windows Games Explorer item.
  • The new Delete Group command deletes an existing user group.
  • The new Delete Media Center command deletes an application from Windows Media Center.
  • The new Delete User command deletes an existing Windows user account.
  • The new Edit XML File command creates new XML files or edits existing XML files on the target system.
  • The new Get XML File Settings command returns information on element text and attribute values contained inside XML files on the target system.
  • The new System Restore command creates and deletes Windows System Restore Points.
  • The new Terminate Process command safely terminates a running process by calling ExitThread from the context of the process to terminate.

Updated Scripting Commands

  • The Get IIS Property command has been updated with an IIS 7 specific schema.
  • The Set IIS Property command has been updated with an IIS 7 specific schema.

What's New in InstallAware 10

InstallAware 10 contains the following new features and enhancements for developing Windows Installer and Native Code setups.

IDE

  • The Find, Find Next, and Find and Replace tools may now perform both case sensitive and case insensitive operations.
  • The new Export to Virtualization tool converts existing InstallAware projects to ready-to-build InstallAware Application Virtualization projects.

Tools and Libraries

  • A new Native Setup template is available for creating hybrid 32 bit-64 bit application installers using the new native code setup engine, including support for uninstallation of old product versions as well as the modification of setup features during maintenance mode.
  • A new Win64 Setup template is available for creating 64 bit application installers. The template contains pre-defined system folders for both 32 bit and 64 bit locations.
  • The .NET Setup template has been updated to install .NET Framework version 4.

Plug-Ins

  • The MS SQL Server plug-in no longer attempts connections to Microsoft SQL Server on port 1433 by default. However, any desired port may be specified.
  • A new pair of application runtimes for the SAP Crystal Reports Runtime Engine for .NET Framework 4 are now available (in 32 and 64 bit flavors).

Setup Engine

  • A new Native Code Setup Engine is now built-in. The native code setup engine is capable of executing each Windows Installer based action without requiring Windows Installer on the target system. Additionally, the native code setup engine enables setup actions to execute immediately, without deferring them until Apply Install is called - unlike the Windows Installer engine.
  • The new #NO_MSI# pre-defined compiler variable controls whether MSI databases are created as part of a build process.
  • The new $NATIVE_ENGINE$ pre-defined variable controls whether the native code setup engine or the Windows Installer engine will be driving the installation.
  • The new $DELAYUNTIL_APPLYCHANGES$ pre-defined variable permits emulating Windows Installer engine behavior by delaying the immediate execution of setup actions, even when the native code setup engine is active.
  • The new $NATIVE_ERROR$, $NATIVE_OVERWRITE$, and $NATIVE_OVERWRITE_OLDER$ pre-defined variables control how the native code setup engine handles errors and overwrites during native code installations.
  • The new $NATIVE_LOGGING$ and $NATIVE_ROLLBACK$ pre-defined variables control whether the native code setup engine permits uninstallations and rollbacks of native install actions.
  • The new $RECOMMENDEDUPGRADE$ and $NATIVE_OLDLOG$ pre-defined variables indicate if and where an old setup using the native engine was found on the target system.
  • The new $SETUPPATH$ pre-defined variable provides a convenient way to detect the outer-most folder containing the installation on the target system.

Setup User Interface

  • Images may now be loaded onto dialog controls at runtime as follows: Define a script variable that has the same name as the target TImage control on your dialog. Before showing the dialog, set this variable to the full file system path of the image that you wish loaded onto the control (such as a file in $SUPPORTDIR$, or a file installed/already present on the target system). If the variable is not defined in the script or does not contain the full path of a file that exists, the existing image will be used and no new image will be loaded.
  • A new GlowLabel dialog control is available which renders text on Aero Glass with improved legibility.
  • The Memo dialog control now automatically displays scrollbars on an as-needed basis.

New Scripting Commands

  • The new Break and Continue commands allow for immediately terminating or continuing to the next iteration of repeat and while loops.
  • The new Reboot and Login command restarts the target system and resumes setup after the Windows shell has been loaded, complementing the Reboot and Resume command which restarts the target system and resumes setup before the Windows shell has been loaded.
  • The new Repeat and Until commands allow for the construction of repeat loops.
  • The new While and Wend commands allow for the construction of while loops.

Updated Scripting Commands

  • The Get System Settings command now supports obtaining the exact resolution of the target system display, as well as obtaining the exact amount of physical RAM installed.
  • The Install Files, Install Assembly, Install Service, Install ODBC Driver commands now support relative path names and environment variables for source file paths. All paths are relative to the root project folder.

What's New in InstallAware 9 R2

InstallAware 9 R2 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The InstallAware IDE now runs without requiring elevated privileges.
  • The InstallAware IDE can now optionally save human readable TXT file accompaniments for each of your script files.
  • The InstallAware IDE now features multi-level undo and redo in the script editor.
  • On Windows 7, the InstallAware IDE now displays build progress and build errors on the Taskbar.
  • The InstallAware IDE can now be configured to allow multiple instances, or to allow only a single instance, using the IDE customization window.
  • On Windows 7, the InstallAware IDE now features common tasks for immediately launching the IDE and building the last active installation project (or the current active project, when multiple instances are disabled and the IDE is already active).
  • The Shortcuts visual designer of the InstallAware IDE gives your applications prime exposure by pinning them to the Windows 7 Taskbar, or the new Start Menu that is available with Windows XP or higher. Use the New Shortcut window to create new shortcuts with pins, or add pins to your existing shortcuts by double-clicking them in the visual designer and editing shortcut properties.
  • The InstallAware IDE and tools may now launch directly with script files and dialog files, in addition to project files which were previously supported. Custom icons for each file type are now registered in Windows.
  • The InstallAware IDE and tools now support the .NET Framework 4 eco-system.
  • The IDE now imports InstallShield setup projects in XML format into ready to build InstallAware setup projects.

Tools and Libraries

  • PackageAware now has an expanded registry and file exclusion list to ensure your captured setups contain as little background noise as possible.
  • PackageAware can now optionally create portable projects to make it easier to rebuild setups on systems other than the capture machine.
  • The command line build tool and automation libraries now correctly fail on builds when a compile error occurs in your scripts.
  • The command line build tool now supports multiple simultaneous builds of the same or different projects in any build mode.
  • The Localization Wizard has been updated to provide automatic localizations in 35 languages for InstallAware generated strings found in setup projects.
  • A Visual Studio 2010 Add-In is now available. The add-in automatically generates and builds InstallAware setups for your Visual Studio 2010 solutions.

Plug-Ins

  • The SQL Server Express plug-in now installs Microsoft SQL Express 2005 with Service Pack 3 and Microsoft SQL Express 2008 with Service Pack 1.
  • The MS SQL Server, Oracle Database, and My SQL plug-ins now return detailed error information, including a textual error description as well as the SQL script fragment which caused the error.
  • Plug-Ins can now abort the build process in the CompileTimeBuild function they export.
  • A full collection of 64 bit application runtimes are now built-in.
  • A full collection of runtimes supporting the .NET Framework 4 eco-system are now built-in, including SQL Server 2008 R2 Express.
  • Secure Runtimes for Microsoft Visual C++ are now provided in addition to the legacy runtimes.
  • MySQL Server runtimes are now available.

Setup Engine

  • The setup engine now records restart requests for the installer in the RunOnce registry key, instead of the Run key.
  • The setup engine can be forced to disallow multiple instances using the new #SINGLEINSTANCE# pre-defined compiler variable.
  • The setup engine no longer waits for tasks to complete when cancelled, returning control to the main setup script from plug-ins, external programs, or other external tasks with only a 5 second time-out. This helps prevent unresponsive child tasks from stalling an orderly setup shutdown.
  • The setup engine no longer attempts to re-connect to network or other removable drives at uninstall time, if such drives were used for local resources at install/maintenance time.
  • The setup engine now times out on network downloads (either for web media blocks or with the Download File plug-in) after 10 seconds.
  • The setup engine also restores the previous time-out value after executing a network download.
  • The new #CODEPAGE# pre-defined compiler variable permits you to change the codepage of your MSI databases to ensure successful internationalization of your setups.
  • The new #IAVER# pre-defined compiler variable reports the version of InstallAware used in building the installer, helping you conditionally leverage new InstallAware features, whilst maintaining backwards InstallAware compatibility with your setup projects.
  • The setup engine now provides two new pre-defined variables, $ABORTONERROR$ and $ABORTEDONERROR$, which can be used to prevent setup from exiting when an error occurs or setup is cancelled.
  • The setup engine now reads binary and multi string registry values through Read Registry and Check Registry.
  • The setup compiler now generates shorter MSI component names, but old style long MSI component name generation is still available through the #LONGCOMPONENTS# pre-defined compiler variable.
  • The setup engine now reports the exact include file and line number for runtime errors.
  • The setup engine can now be forced to always preserve downloaded installation data and settings, for a later re-installation, using the new $SAVEDATA$ pre-defined variable. While the setup engine preserves this data during an interrupted installation, it always discards this data after a complete uninstallation.
  • The setup engine can now be instructed to always cache or never cache setup sources, regardless of project build type.
  • The default value for the #NOHARDLINKS# pre-defined compiler variable is now TRUE (previously the default value was FALSE).
  • The new $MYAH_TIMEOUT$ pre-defined variable permits customizing the web download timeout in seconds, including preventing InstallAware from changing this shared system setting at all.
  • The default value for the pre-defined compiler variable #LOCMODE# is now NEWONLY. The previous default value unconditionally applied all localizations, possibly overriding newer script values with older translations.
  • The default value for the pre-defined compiler variable #CODEPAGE# is now 65001. The previous default value was the English codepage of 1252.

Setup User Interface

  • When interactive Flash billboards with sound are used, the sound playback properly stops when the progress dialog is no longer showing.
  • On Windows 7, the setup engine now displays additional notifications in the form of a Taskbar Overlay Icon on the new Windows 7 Taskbar, any time a System Tray command is called with a system tray notification icon set to be displayed.
  • On Windows 7, the setup engine displays native installation progress on the Taskbar. The Taskbar button for setup will additionally turn yellow when end-user input is required, and red when a setup error has occured.
  • The pre-defined variable $PROGRESSMODE$ now provides two additional progress modes on Windows 7 to display native progress in yellow or red color on the Taskbar.

Updated Scripting Commands

  • The Advertised Shortcut/Create Shortcut commands now offer flags to pin the shortcut target to the Windows 7 Taskbar and to pin the shortcut target to the top of the new Start Menu with Windows XP or higher. This invaluable real estate provides your applications with prime exposure.
  • The Advertised Shortcut/Create Shortcut commands now offer the capability to register your application's AppUserModelID with the shortcut.
  • The Create IIS Virtual Folder command now supports ASP.NET 4 associations.
  • The Register Assembly command now offers a flag to set the codebase in the registry.
  • The Get Folder Location command can now obtain the path for the local (non-roaming and non-shared) application data folder.
  • The Get OS or SP Level command now supports Windows 7 and Windows Server 2008 R2.
  • The Get System Settings command now supports Windows Server 2008 R2, Windows 7, Internet Explorer 8, and Internet Information Server 7.5.
  • The Schedule Task command now lets tasks run without requiring users to be logged on to the target workstation.

What's New in InstallAware 8

InstallAware 8 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The InstallAware IDE is now integrated with Visual Studio.
  • The IDE now allows choosing between two different update modes: manual or scheduled.
  • The following new design views are available: INI Files, Local Files.
  • The IDE now substitutes pre-defined system folders with standard MSIcode variables when importing registry entries from COM objects or .REG files. You will still need to make sure that the MSIcode variables substituted by the IDE have been defined by your setup (in case they have not been previously defined).
  • The IDE now lets you connect directly to the InstallAware Community Center to download new application runtimes or new plug-ins which have been authored by InstallAware or third parties.
  • The Files and Registry design views now support recursive delete operations on the files, folders, and registry keys being installed.
  • The Shortcuts, Assemblies, File Associations, ODBC, Services, Environment Variables, Access Control, Drivers, IIS Sites, Shared Folders, SQL Databases, and Scheduled Tasks design views now allow creating and filtering design view elements by setup features.
  • The Assemblies design view now allows generating native images, registering assemblies for COM Interop, and invoking .NET installer classes on listed assemblies through conveniently located check-boxes.

Tools and Libraries

  • The underlying technology for connecting to SQL servers such as Oracle, MySQL, and Microsoft SQL Server has been updated.
  • The built-in update script has been updated to correctly remove previously downloaded update information upon application uninstallation.
  • The DIFx Driver Install plug-in now performs driver installations using Driver Installation Frameworks 2.1.

Plug-Ins

  • The default SQL Server Express application runtime scripts now install SQL Server without enabling network protocols.
  • A new Microsoft .NET Framework 3.5 with Service Pack 1 runtime installs .NET 3.5 with Service Pack 1, along with its sub-components .NET 2 with Service Pack 2 and .NET 3 with Service Pack 2. The sub-components may be individually selected for installation independently of .NET 3.5 with Service Pack 1 as well.
  • A new Microsoft .NET Framework 3.5 runtime installs .NET 3.5, along with its sub-components .NET 2 with Service Pack 1 and .NET 3 with Service Pack 1. The sub-components may be individually selected for installation independently of .NET 3.5 as well.
  • More new runtimes add support for Visual Studio 2008 and Visual Studio 2008 with Service Pack 1 technologies, such as Visual C++ Runtime 9 with Service Pack 1.
  • A new Microsoft SQL Server Compact Edition 3.5 with Service Pack 1 runtime is available.
  • The SQL Server Express plug-in now installs Microsoft SQL Express 2008.

Setup Engine

  • The setup compiler features four new optimization switches for shortening setup build times and improving Windows Installer runtime performance. These switches are also accessible from the command line build tool.
  • The setup compiler now performs fast uncompressed builds using hard links instead of full file copy during the build stage using the new #NOHARDLINKS# pre-defined compiler variable.
  • The setup engine has now been optimized to scale for very large setups and provides an approximate 80%-90% runtime performance enhancement for projects involving a lot of MSIcode commands and variables.
  • The setup engine now waits until the Windows Installer service is available, instead of aborting installation with an error message, when another Windows Installer based setup is in progress. The wait can be cancelled by the end-user if so desired.
  • The setup engine now compresses its installer cache folder on NTFS volumes, saving disk space, as controlled by the new pre-defined variable $MYAH_COMPRESS_INSTALLER_CACHE$.
  • The setup engine can now disable Windows Installer rollback to improve runtime setup performance, as controlled by the new pre-defined variable $MYAH_DISABLE_ROLLBACK$.
  • The setup engine can now disable Windows Vista's Restart Manager to improve runtime setup performance, as controlled by the new pre-defined variable $MYAH_DISABLE_VISTA_RESTART_MANAGER$.
  • The setup engine no longer aborts on missing variables (such as persistent variables which cannot be reloaded because of a missing installer cache) - instead, such variables are re-initialized on the fly with an empty initial value.
  • The setup engine now connect to remote IIS metabases, as controlled by the new pre-defined variable $IISHOST$.
  • The setup engine can now use a custom installer cache location, as controlled by the new pre-defined variable $OVERRIDECACHE$.
  • The setup engine can now natively work with IIS 7 web servers without requiring the IIS 6 compatibility interface. However, remote IIS functionality is only available in IIS 6 mode.
  • It is now possible to manually force UAC elevation on Vista to one of the following three states: asInvoker, highestAvailable (previously the default), and requireAdministrator.

Setup User Interface

  • When their Writes Values to Variable Object Behavior is empty, Memo and RichEdit controls now indicate if they have been scrolled all the way to the end by setting their MaxLength property to 2147483647 (the default value for this property is 0). This feature may be used when you need to build dialog boxes for your license agreement (and readme) files, and you require the end-user to read all of the information in the dialog (possibly in addition to checking an "I Agree" box) before moving to the next dialog.
  • The Panel dialog control now properly resolves variables used within its Caption property.

Updated Scripting Commands

  • The Generate Native Images command now sets its startup folder to the same folder as the assembly being imaged. It also offers a flag to delete previously generated native images.
  • The If command now performs version number comparisons, supporting up to 4 digits in each version number.
  • The Register Assembly command now sets its startup folder to the same folder as the assemby being registered. It also offers a flag to unregister an assembly.
  • The Register Library command now sets its startup folder to the same folder as the library being registered.
  • The Run Program command now sets its startup folder to the same folder as the application being run. A custom startup folder may be specified using the Run Program As command.
  • The Run Program As command can now de-elevate programs being run to original limited user credentials when UAC is enabled on Vista and setup has been elevated to administrator credentials.
  • The Run .NET Installer Class command now sets its startup folder to the same folder as the installer class being run.

What's New in InstallAware 7

InstallAware 7 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The IDE now offers MSIcode categories to easily distinguish between the various kinds of drag-drop scripting commands that are available.
  • Projects now use relative paths for storing the locations of setup scripts, making it easier to move setup scripts and projects between different computers.
  • A new project-level setting now allows you to calculate file hashes during builds.
  • When application runtimes are added using the Application Runtimes view, their associated include scripts are now automatically copied to the local project folder, making it easier for different projects to install runtimes with different settings.
  • When application runtimes are deselected from the Application Runtimes view, their associated include scripts are now automatically removed.
  • When the update script is added using the Project Properties view, the include script is now automatically copied to the local project folder, making it easier for different projects to use different update scripts (and persist changes made to the update script when uninstalling/reinstalling the IDE).
  • When the update script is removed using the Project Properties view, the include script is now automatically removed.
  • Code signing with passwords is now supported during builds inside the IDE.
  • A new Quick Start Wizard is available, allowing you to create functional setups for your applications in literally minutes.

Tools and Libraries

  • The underlying technology for connecting to SQL Servers has been updated.
  • A new IIS Web Sites and Folders sample project is available. This project provides a built-in dialog that enumerates available IIS websites on the target system, and lets the user choose an existing website, or enter a new website name, as well as a virtual folder name. The selected website and virtual folder is then created on the target system.
  • The command line build tool now ignores the debug build project setting during a command line build.
  • Multiple instance dialog editors are now available as an option.
  • Logo suite program tests have been updated with the latest test files from the Windows 6.0 SDK.
  • Builds for compressed, web based, and patch media types now create hard links instead of copying files (where possible). This improves build performance by eliminating redundant file copy steps. This benefit does not apply to uncompressed media types and is not supported on non-NTFS volumes.
  • The compression engine now utilizes all available processors (and cores) on a system to provide near-linear compression performance enhancements.
  • The compression engine now performs nearly twice faster while compressing on a clock-per-clock basis.
  • The Group Policy Wizard has been updated, and now facilitates better distribution of InstallAware MSI packages using Group Policy / Active Directory. Patches may now also be distributed using this wizard.
  • The Code Signing Tool tool has been updated, and now allows specifying a password during the signing process.

Plug-Ins

  • The SQL Server Express plug-in now installs the Service Pack 2 level of Microsoft SQL Express 2005.
  • XML Paper Specification and Windows Imaging Component have been added to the standard .NET 3 installation. These are optional components and can be commented out.

Setup Engine

  • The size of setup packages has been reduced by eliminating redundant data from MSI files.
  • Setup packages can now be extremely large - while packages were previously limited to 32767 files, this limit no longer applies.
  • Setups that use web media blocks and long source file paths no longer run into the maximum path limit. Path generation for files inside web media blocks has been optimized to eliminate problems with source paths of any length.
  • The setup engine has been optimized to perform smoothly for setups containing thousands of lines of MSIcode script - a near 10x improvement over the previous versions.
  • Compiler Variables are now re-substituted during the execution of localized setups.
  • A new pre-defined compiler variable #LOCMODE# is available, determining the way localizations are applied to setups at runtime.
  • A new pre-defined variable is available for use with scripting: $GPOPATH$.
  • The setup engine can now automatically save downloaded web media block files, as well as the main setup file, as controlled by the new pre-defined variable $COPYWEBLOCK$.
  • The setup engine can now automatically load setup data (such as features, feature selections, persistent variables) from an older product version. This behavior is enabled through the new pre-defined compiler variable #LOADOLDDATA#.

Setup User Interface

  • A new VistaGlass component is now available, letting you design your custom glass surfaces in setup wizards on Windows Vista. Please note that Vista Glass support is currently in the beta stage. Adding Vista Glass support to your setup wizards will not affect the reliability or performance of your setup in any way, but may introduce harmless visual artifacts.

New Scripting Commands

  • The Get Component Space command returns the space required by a component, or the entire setup, at runtime.
  • The Get IIS Site List command returns the list of IIS websites available on the local system.
  • The Get OS or SP Level command returns the exact operating system or service pack version (instead of a minimum version check).
  • The Localization Variable command creates stable string IDs for use with translations.
  • The Remove Assemblies command removes all unpinned assemblies installed by your application from the GAC.
  • The Set Component Choice command enables or disables end-user interaction with a setup feature at runtime.
  • The Set Component Visibility command hides or shows a setup feature at runtime.

Updated Scripting Commands

  • The File Bag command now supports exclusion wildcards.
  • The Get System Settings command now detects the exact underlying processor architecture for 64 bit systems.
  • The If command now offers an additional parameter, to check if a variable has been previously defined.
  • The Read from Text File command now supports reading in an entire file with a single call.

What's New in InstallAware 6

InstallAware 6.0 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The IDE features a new Drivers visual view for installing drivers with your setup.
  • The IDE features a new Web Updates node with the Scheduled Tasks, Update Packs, and Versions visual views.
  • The new Scheduled Tasks visual view lets you schedule tasks to run using the Windows Task Scheduler.
  • The new Update Packs visual view lets you define patches, installers, or other types of executable updates that are available for your applications in the field.
  • The new Versions visual view lets you choose which Update Packs are served for which versions of your applications in the field.
  • The IDE provides intelligent balloon tips as you type code in the editor, or use parts of the visual IDE. The balloon tips help you avoid common mistakes and pitfalls while building your setup. They also explain vital concepts as you work.
  • When include scripts referenced in project files cannot be found, the IDE makes two additional attempts to locate them, looking first in the project folder, and second in the InstallAware runtimes folder. This helps eliminate project load problems when the location of the InstallAware IDE or the setup project has changed.
  • The Minimum Operating System field of the Application Requirements visual view can now test for Windows Vista.
  • The Minimum Internet Explorer Version field of the Application Requirements visual view can now test for Internet Explorer 7.
  • The Minimum IIS Version field of the Application Requirements visual view can now test for Internet Information Server 7.
  • A new Special Requirements field is available in the Application Requirements visual view. This field can test for 64 bit operating systems and the presence of a hardware virtualization layer such as VMware or Virtual PC.
  • All visual views have been updated with context menus and keyboard shortcuts to facilitate rapid entry, edit, and removal of view items.
  • The Files visual view has been updated to allow drag-drop interaction with Windows Explorer.

Tools and Libraries

  • New built-in application runtimes are available for Crystal Reports, Microsoft Report Viewer, and Visual C++ 8.0.
  • New InstallAware Web Update unctionality is available, along with its full source code implemented entirely in InstallAware MSIcode. Because the full sources are provided, the default Web Update behavior can be easily adapted to suit your custom requirements.
  • A new MS SQL Server Connection sample project is available. This project provides built-in dialogs that enumerate and then test a connection to a SQL Server on the local system or network.
  • A new DIFx Driver Installation sample project is available. This project installs drivers for a virtual "toaster" hardware, and simulates "attaching" the toaster to the computer to test successful plug-and-play driver installation.

Plug-Ins

  • A new DIFx Driver Install plug-in performs driver installations using Driver Installation Frameworks 2.0.
  • A new Microsoft .NET Framework 3 runtime installs .NET 3.
  • A new Microsoft Internet Explorer 7 runtime installs Internet Explorer 7.
  • A new MS SQL Instances plug-in detects instances of Microsoft SQL Server running locally or on the network.
  • The .NET Framework and JSharp Runtime plug-ins now display native progress feedback during installation, improving user experience during these potentially lengthy operations.
  • The SQL Server Express plug-in now installs the Service Pack 1 level of Microsoft SQL Express 2005.

Setup Engine

  • The setup engine can now perform 64 bit installations, with the capability to set the processor architecture at runtime.
  • New pre-defined compiler variables are available for use with scripting: IADIR, PROJDIR.
  • The setup engine can now interact with the system tray, supporting display of the setup icon and displaying message balloons.
  • Setups that use web media blocks and long source file paths no longer run into the maximum path limit. Path generation for files inside web media blocks has been improved to prevent problems with longer source paths.
  • The setup engine is Vista ready.
  • The setup engine now works under Windows 95 without requiring the common controls update. Therefore you may build a single setup that is capable of installing on all 32 bit and 64 bit Windows versions, from Windows 95 to Windows Vista.
  • The setup engine can detect hardware virtualization solutions such as VMware and Virtual PC.

Setup User Interface

  • A new PageControl is available for building tabbed dialog boxes and consolidating install steps into a single dialog.
  • The CheckListBox control now writes the list of checked items to variables.
  • New pre-built dialogs are available for various specialized tasks, including the new InstallAware Web Update functionality, and detecting/testing SQL Server connections.

New Scripting Commands

  • The Delete Component command deletes a component previously defined using the Define Component command.
  • The Evaluate Expression command evaluates a complex logical expression.
  • The MessageBalloon command displays a message balloon in the system tray.
  • The Register Assembly command registers .NET assemblies.
  • The Schedule Task command schedules a task using the Windows Task Scheduler.
  • The Set 64 Bit Mode command puts the setup in x86, ia64, or x64 installation mode.
  • The System Tray command minimizes a running setup to the system tray.

Updated Scripting Commands

  • The Compiler Variable If command can now ignore case during comparisons.
  • The Get System Settings command can now detect if setup is running under a VMware or Virtual PC virtual machine. Additionally, Windows Vista, Internet Explorer 7, and Internet Information Server 7 can now be detected.
  • The If command can now ignore case during comparisons.
  • The Run Program As command now optionally forces a directory change.
  • The Set Variable command can now persist variable values running in one instance.
  • The Web Media Block command now supports failsafe URL lists, as well as individual passwords for each media block.

What's New in InstallAware 5.3

InstallAware 5.3 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The IDE can now dynamically scan .EXE file dependencies. Found dependencies may be added to any setup feature.
  • The IDE can now visually add any type of registry key supported by Windows Installer.
  • In the compression phase of building setups, hyperthreading, dual core, or multi processor systems are now automatically detected and compression tasks are spread across multiple (logical) CPUs to reduce build times.
  • The IDE now offers the ability to directly create new folders in the Files visual view. Additionally, pre-defined system folders on the target system may now be displayed as part of the target system folder hierarchy, again while working in the Files visual view.
  • The IDE now offers the ability to directly create new keys in the Registry visual view.

Tools and Libraries

  • PackageAware has been updated to automatically detect more types of registry key changes, supporting all key types Windows Installer can work with. The built-in exclusion list has been expanded to reduce, and in most cases eliminate, post-capture setup tuning.
  • The command line build tool now performs significantly faster builds. The tool no longer displays a GUI window and directly writes all of its output immediately to the console window.
  • A new serial number validation sample project is available. This project can be used to validate serial numbers based on registration data entered by the user, such as user name and company name. Every serial number is unique for each individual - no pre-defined range of serial numbers exist, reducing chances of piracy. The sample also doubles as a key generator when built using conditional compilation in key generation mode.

Setup User Interface

  • A new setup theme, Official, is now available.

Plug-Ins

  • The new File Bag plug-in bundles a collection of files, with support for wildcards and subfolders, at compile time with either the main setup.exe file or a web media block. The plug-in returns the location where the bundled files are available at runtime through a script variable. This new plug-in essentially provides a recursive, flexible, wild-card based support files mechanism.

What's New in InstallAware 5.1

InstallAware 5.1 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The IDE now offers drop-down menus for several toobar buttons, enabling you to build and explore different projects and build types without manually changing build modes.
  • The IDE can now import registry data stored in .REG files or COM servers. Imported registry data may be added to any setup feature.

Tools and Libraries

  • The Setup Decompressor has been updated to permit creation of independent self extracting packages.

Setup Engine

  • The setup engine now allows linking file and folder views with edit controls without depending on the TARGETDIR variable.
  • A new pre-defined variable is available for use with scripting: PROGRESSMODE.

Setup User Interface

  • Hollow and/or non-rectangular dialogs may now be created using the Dialog Editor.
  • Bitmap buttons may now be created using the Dialog Editor, including support for custom borders, hover images, and more.

New Scripting Commands

  • The Convert Case command converts a variable to upper or lower case.
  • The Delete Files Recursive command immediately deletes files matching a wildcard pattern in a given folder and all subfolders.

Updated Scripting Commands

  • The Get System Settings command now detects 64 bit, Server, Tablet PC, and Media Center editions of Windows, as well as Windows Vista.
  • The Write Registry command can now persist the data it writes, surviving uninstalls.

What's New in InstallAware 5.0

InstallAware 5.0 contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The IDE now features multiple tabs to edit multiple setup scripts at once.
  • The IDE features a Welcome Page with links to frequently used resources and projects.
  • The IDE now offers an Application Runtimes visual view that allows application runtimes, along with any further dependencies they may have, to be added to/removed from projects with a single click of the mouse.
  • The IDE has a new Copy as Text option that copies code in the script editor in human readable form.
  • The IDE offers new menu items that fold and unfold all regions in a script with a single click.
  • Compile and build processes have been significantly accelerated for setups containing thousands of files.
  • Built setup files now display their own version, company, and copyright information in Windows Explorer.
  • The script editors feature new Code Navigation drop-downs which make it easy to rapidly navigate your setup scripts based on a variety of criteria.

Tools and Libraries

  • A new MSI/MSM Import Wizard converts Windows Installer databases (MSI setup files and MSM merge module files) into ready to build InstallAware projects.

Plug-Ins

  • The .NET Framework plug-in has been updated to support .NET Framework 2.0. The plug-in also offers more return codes.
  • The JSharp Runtime plug-in has been updated to support JSharp Runtime 2.0.
  • The MDAC Refresh plug-in has been updated to support MDAC 2.8 Service Pack 1.
  • The MSXML plug-in has been updated to support MSXML 6.0.
  • A new SQL Server Express plug-in is available to install instances of Microsoft SQL Server Express 2005.
  • The Windows Installer plug-in has been updated to support Windows Installer 3.0 and Windows Installer 3.1.

Setup Engine

  • The setup engine can now install multiple instances of the same product on the same computer with just two lines of additional scripting code.
  • New pre-defined variables are available for use with scripting: DATE, TIME, NEWINSTANCE, and VERSION.

Setup User Interface

  • Two new setup themes are available.

New Scripting Commands

  • The Check Process command checks for running processes on the system.
  • The Check Registry command checks for the presence of a registry key or value on the system.
  • The Check Service command checks for running services on the local system, or a system on the network.
  • The Include Script command includes commands from a setup script file inside another script.
  • The Transform Instance command allows multiple installations of the same product on the same system.

Updated Scripting Commands

  • The Create Share command can now create shares on remote systems on the network.
  • The Delete Share command can now delete shares on remote systems on the network.
  • The Install Files command can now exclude files matching specified wildcard patterns from builds.
  • The Write Registry command has widened parameters which now support all available registry data types.

What's New in InstallAware 2005 Second Edition

InstallAware 2005 Second Edition contains the following new features and enhancements for developing Windows Installer setups.

IDE

  • The code view now features in-place editing. Simply begin typing at any script line, and a drop-down combo box appears with a list of commands that start with the letters you have used. Use auto-complete or scroll through the list of commands to automatically insert a new command into your setup script.
  • The code view also features code folding. You may define custom code folding regions and collapse them to make your setup code more organized.
  • The visual views have been updated for more intuitive operation. The Features visual view now lets you sort the features that comprise your setup. The Files and Registry visual views have also been updated to allow editing the properties of multiple items simultaneously.
  • You may now disable filtering of files and registry keys by application features.
  • Setups which contain a very large amount of files and registry keys may now be loaded and edited in the IDE very rapidly.
  • Visual browse dialogs are now provided with most scripting commands that reference files.
  • Building setups with best compression now requires less memory. The build progress dialog has been redesigned and offers more information, along with animations that illustrate the current build phase.
  • A new CD Autorun template is available for creating autorun programs for your CD based installations. The new CD Autorun template also illustrates how to build custom scripts for specialized tasks.
  • Template and wizard generated setup scripts now have better handling for error conditions that occur during pre-requisite installations.

Tools and Libraries

  • There are several new project converters that convert setups developed in other installation environments, such as Wise Installation System, to InstallAware.
  • Project samples are available which provide pre-built setup scripts that cater to specific needs, such as on-line user registration as an integral part of your software installation.
  • The command line build tool and automation interface now support specifying package passwords and languages on the command line.
  • A new Localization Wizard is available.
  • A new Group Policy Wizard is available, which enables you to use your InstallAware installations with Group Policy / Active Directory deployment.
  • An updated Setup Decompressor is available, which automates the process of decompressing setups to make them more compressible when included with InstallAware setups.

Setup Engine

  • The setup engine now allows components to be defined dynamically at run-time. This enables the creation of setups which determine their feature sets on-the-fly.
  • You may now create password protected setups encrypted using 256 bit strong AES encryption.
  • Multi-lingual setups are now available, letting you choose and override the setup language at run-time.
  • Web media block names are no longer limited to 8 characters. You may use long descriptive names for your web media blocks, as long as they remain valid file names.
  • You may now build light mode setups that exclude the setup runtime for compacting multiple nested installations.

Setup User Interface

  • You may now reference properties of other controls when defining intra-dialog relations. For instance, you may disable the Next button on a dialog unless the two sets of password fields on the dialog match. Previously only hard-coded field comparisons were available.
  • The new Return from Dialog action lets buttons or similar dialog controls return custom values from a modally shown dialog. Previously only three return values were available (Back, Next, Cancel).
  • Memo and RichEdit controls may now be made editable, and write their values to variables.
  • New Transparency and AlphaBlend properties are available for setup dialogs.

New Scripting Commands

  • The Check Disk Space command checks for available (or total) disk space at a given path or network share.
  • The Code Folding Region command defines a collapsable code folding region.
  • The Extract 7Zip Archive command extracts a stand alone 7Zip archive, an InstallAware setup.exe file, or a web media block file.
  • The Find All Files command searches for files in a given path matching a wildcard pattern.
  • The Replace String command replaces occurences of a substring inside a string.
  • The Run Light Mode Setup command runs an InstallAware setup that has been built without InstallAware runtime files.
  • The Set Component Space command overrides the default space requirements for a component.
  • The Terminate with Exit Code command lets you return a custom exit code when ending an installation.

Updated Scripting Commands

  • The Extract Path command now has a new mode which replaces double back-slashes in path values with single ones. Note that all InstallAware commands automatically do this for you whenever a path you pass to them contains a double back-slash.
  • The Get System Settings command has been updated to report on the screen DPI setting.
  • The Mathematics command has been updated to provide new bitwise, character conversion, and random number operations.
  • The .NET Framework command has been updated to allow slipstreamed installations of the .NET Framework version 1.1 including Service Pack 1.

What's New in InstallAware 2005

InstallAware 2005 contains the following new features for developing Windows Installer setups.

IDE

  • Code generation has been significantly enhanced in the visual view, enabling complete creation and maintenance of setups based on entirely the visual view, without ever requiring to access the script view.
  • Brand new pages now available on the visual view are: Access Control for setting access control lists, Run Programs for executing applications before/after an install, IIS Sites for configuring Internet Information Services, Shared Folders for creating network shares, SQL Databases for running scripts on MS SQL, My SQL, and Oracle platforms, and Patches for creating differential patches.
  • The Dialogs visual view now shows a preview of your actual installation dialogs. It also enables you to modify the sequence in which dialogs are displayed without changing your script manually.
  • The Shortcuts and File Associations views now allow rapid transitioning between advertised and non-advertised shortcut and file type declarations.
  • The Compression page on the Project Options window now features an intuitive slider for setting the level of compression. The Patch page on the same dialog enables you to control patch creation options.
  • A new Patch References node is available under the Project Manager window, where you can add links to older versions of your setups to patch against.
  • The Codex runtime and libraries are no longer used by the IDE during compression. The IDE handles compression natively and no seperate progress window opens.
  • The Refactor Paths tool now adds URL support for refactoring.

Tools and Libraries

  • The PackageAware tool enables you to capture the changes made during an installation and creates a ready to use InstallAware script.
  • The MSI Cab Decompressor tool enables you to process existing MSI and MSM database files to increase their compressability when included as part of an InstallAware setup (Note: this tool has been superceded by the Setup Decompressor tool in InstallAware 2005 Second Edition).
  • The Form Batch Update tool enables you to change character set properties and control types on your forms in a single update operation.
  • The Codex runtime is no longer required for redistribution with either of the redistributable automation or build environments.

Plug-Ins

  • The new MS SQL Server plug-in allows you to execute a SQL script on an instance of Microsoft SQL Server.
  • The new My SQL plug-in allows you to execute a SQL script on a My SQL database server.
  • The new Oracle Database plug-in allows you to execute a SQL script on an Oracle database server.

Setup Engine

  • The setup engine now creates patch compatible MSI databases and can apply patches to MSI installations.
  • The setup engine now fully supports advertised shortcuts, file types, and advertised installs.
  • The setup engine now features install-on-demand and self-healing setups.

Setup User Interface

  • Two new setup themes are available.
  • Edit controls now feature auto-tabbing to the next control after an indicated number of characters have been typed in, ideal for use in serial registration dialogs.
  • CSS support is now available on setup HTML progress billboards, along with more advanced HTML rendering functionality.

New Scripting Commands

  • The Advertised File Type command creates an advertised file type.
  • The Advertised Shortcut command creates an advertised shortcut.
  • The Apply Patch command applies a patch to a previously installed product.
  • The Control IIS Site command lets you start/stop/pause/resume an IIS website.
  • The Create IIS Site command creates an IIS website or updates an existing IIS website.
  • The Create Share command defines a new network share.
  • The Create Virtual Folder command creates a new virtual folder as part of an IIS website.
  • The Delete IIS Site command removes an IIS website.
  • The Delete Share command removes a network share.
  • The Delete Virtual Folder command removes a virtual folder inside an IIS website.
  • The Generate Native Images command compiles native images for .NET assemblies.
  • The Get IIS Property command obtains an arbitrary IIS metabase property.
  • The Get IIS Site Index command obtains the numeric identifier for a named IIS website.
  • The Get System Settings command now reports on several additional capabilities, including the IIS anonymous user name, the logged on user/computer/domain name, and the current account priviledges.
  • The Load Feature Selections command loads previously saved feature selection information.
  • The Run Program As command offers additional program execution options.
  • The Save Feature Selections command saves feature selection information.
  • The Set Access Control command sets access rights on various types of system objects.
  • The Set IIS Property command sets an arbitrary IIS metabase property.

What's New in InstallAware 3.0 InstallAware 3.0 contains the following new features for developing Windows Installer setups.

IDE

  • The IDE is now implemented in Win32 and the .NET Framework is no longer required.
  • The new Visual view allows you to visually modify your setups without having to author code. Changes made in the Visual view automatically update your installation script. Changes made to your installation script are automatically reflected back in the Visual view.
  • IDE Layouts are saved seperately for the Visual and Code views. Changing your view automatically changes your active layout as well.
  • The Refactor Paths option allows you to update hard-coded paths in your setup scripts, a helpful option when your setup files change location.

Tools and Libraries

  • The Code Signing Tool is available for signing executables and libraries outside of the IDE build process.
  • The command line build tool is now implemented in Win32 and no longer requires the .NET Framework.
  • The automation library is now implemented in Win32 and no longer requires the the .NET Framework.

Plug-Ins

  • The new Call DLL Function plug-in allows you to call any function inside an arbitrary DLL, without requiring a pre-defined set of function parameters.
  • Plug-Ins may now display custom text in the code editor.
  • Plug-In templates have been updated to show samples of displaying custom text in the code editor.

Setup Engine

  • Setups containing Web Media Blocks now run up to 50% faster.
  • If Web Media Blocks are found inside the same folder as the main setup executable, the installation engine now attempts to use the found blocks directly from that location, instead of downloading them from the Web. If this attempt fails, the installation engine will fall back to downloading from the web.

Setup User Interface

  • Two new setup themes are available.
  • You may now customize the icon which is used in the main setup executable. The same icon also updates the Add-Remove Programs applet and is visible during installer self extraction.
  • A new Flash control is available for use in installation dialogs. An ideal usage scenario would be to provide interactive Flash billboards during installation progress.
  • A Select Destination Directory window may now be spawned from button controls. This mechanism provides an alternative to displaying a tree view in the destination folder step of install wizards.
  • Multiple state changes for dialogs are now allowed in the installation wizard.

New Scripting Commands

  • The Create File Type command allows you to define a file type and the extensions belonging to that type, to become associated with your application.
  • The Get Environment command retrieves the value of an environment variable.
  • The Get File Version command retrieves the version string of a file suitable for display and debugging.
  • The Get Temporary File command obtains a temporary file name.
  • The Install Assembly command installs a .NET assembly, either into the Global Assembly Cache, or a custom folder.
  • The Parse String command enables you to parse a string based on a pattern.
  • The Set Environment command sets the value of an environment variable.
  • The Register Library command registers or unregisters a library (DLL/OCX/EXE/TLB).


Upgrading from InstallAware NX

Upgrading setups created in InstallAware NX to InstallAware 15 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • The web update script has been updated to enable a third, automatic web update installation mode. New projects created in InstallAware 15 automatically use the new web update script. To update projects created using an older version of InstallAware with the new web update script, please follow the steps below:
    1. Uncheck the Receive Application Updates check-box in the Project Properties design view.
    2. Delete the on-disk old web update script files (updates.mia.*) from your project folder.
    3. Re-check the Receive Application Updates check-box in the Project Properties design view.
  • The runtimes for Microsoft .NET Framework 2.x-3.x have been enhanced to provide an improved user experience while installing on Windows 8 and Windows Server 2012. New projects created in InstallAware 15 automatically use the new runtimes. To update projects created using an older version of InstallAware with the new runtimes, please follow the steps below:
    1. Remove the old runtime installation scripts from your setup projects.
    2. Delete the on-disk old runtime installation scripts from your project folder.
    3. Re-add the latest runtime(s) from the Application Runtimes design view.


Upgrading from InstallAware 2012

Upgrading setups created in InstallAware 2012 to InstallAware NX is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • The Continue command now re-evaluates loop conditionals for While loops. The loop conditional was not re-evaluated in prior versions of InstallAware. You may need to revise any logic relying on this behavior when upgrading to InstallAware NX.
  • The runtimes for Microsoft .NET Framework 2.0, 2.0 with Service Pack 1, and 2.0 with Service Pack 2 have been updated to enable installation on Windows 8 and Windows Server 2012. New projects created in InstallAware NX automatically use the new runtimes. To update projects created using an older version of InstallAware with the new runtimes, please follow the steps below:
    1. Remove the old runtime installation scripts from your setup projects.
    2. Delete the on-disk old runtime installation scripts from your project folder.
    3. Re-add the latest runtime(s) from the Application Runtimes design view.
  • The Get Folder Location command no longer provides the path for the Immersive Application Shortcuts folder, because this path is no longer in use in production releases of Windows NT 6.2 (Windows 8 and Server 2012).
  • Previous versions of InstallAware incorrectly spelled the Portuguese language as Portugese. This spelling is automatically corrected in new projects created using InstallAware NX. If you would like to correct this issue in projects created using an older version of InstallAware, please follow the steps below:
    1. Update all on-disk file spellings found in your project folder from Portugese to Portuguese.
    2. Mirror the change above in the Support Files references found in your InstallAware project file.
    3. Update all on-disk file spellings found in any export/import folders created/used by the Localization Wizard.


Upgrading from InstallAware 12.x

Upgrading setups created in InstallAware 12.x to InstallAware 2012 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • No considerations apply at this time.


Upgrading from InstallAware 11.x

Upgrading setups created in InstallAware 11.x to InstallAware 12 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • No considerations apply at this time.


Upgrading from InstallAware 10.x

Upgrading setups created in InstallAware 10.x to InstallAware 11 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • The runtimes for the .NET Framework 4 have been updated with a new distribution layout that permits nested installation of the client profile as part of the full profile, reduces runtime payload, and also displays accurate installation progress. Remove the old runtime installation scripts and code from your setup projects and re-add the latest version(s) from the Application Runtimes design view. You will not be able to build your projects using the old runtimes, because the old files are no longer available due to the changed distribution layout.


Upgrading from InstallAware 9.x

Upgrading setups created in InstallAware 9.x to InstallAware 10 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • No considerations apply at this time.


Upgrading from InstallAware 8.0

Upgrading from InstallAware 8.x

Upgrading setups created in InstallAware 8.x to InstallAware 9 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan to patch setups created with versions of InstallAware before 9.0 with patches built with InstallAware 9, set the pre-defined compiler variable #LONGCOMPONENTS# to TRUE. This will ensure that InstallAware 9.0 generates MSI components using a long naming scheme that is identical to the one used in prior InstallAware versions.


Upgrading from InstallAware 7.0

Upgrading from InstallAware 7.x

Upgrading setups created in InstallAware 7.x to InstallAware 8 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan to patch setups created with versions of InstallAware before 7.5 with patches built with InstallAware 8, disable all of the new compiler optimizations. This will generate setup packages the same way they were created in InstallAware versions before 7.5 and avoid any issues that may arise with patching. InstallAware versions 7.5 and higher feature the same compiler optimizations and will be safe to patch against, as long as you observe the same compiler optimizations in your original and patch versions.
  • The monolithic Microsoft .NET Framework 3.5 (with .NET 2.0 SP1 and .NET 3.0 SP1) application runtime no longer ships with InstallAware 8, which provides improved, granular application runtimes for Microsoft .NET Framework 3.5 and its sub-components (Microsoft .NET Framework 2.0 with Service Pack 1 and Microsoft .NET Framework 3.0 Service Pack 1) through new, stand-alone, nested runtimes. If your projects require the older monolithic application runtime, install it from http://www.installaware.com/dotnet35update.asp.
  • The Microsoft .NET Framework 1.0 application runtime no longer ships with InstallAware 8. If you have projects requiring this application runtime, please contact InstallAware support for instructions on rebuilding your projects requiring this application runtime with InstallAware 8.
  • The Microsoft .NET Framework 3.0 application runtime has been updated in InstallAware 8 to support runtime re-installations on Windows Vista and Windows Server 2008 when it is missing. It is recommended that you take advantage of the updated runtime by manually copying the runtime include files from the InstallAware runtimes folder to each of your project folders that make use of the runtime, overwriting the old include files.
  • InstallAware 8 ships with version 2.0 of the update script updates supporting dual-mode web updates (featuring the new manual mode, in addition to the scheduled mode that was initially available). To take advantage of new dual-mode web updates, you will need to manually replace your existing update script with the new version 2.0 update script. Copying the updates.* include files from the InstallAware runtimes folder to each of your project folders that make use of the web update script, overwriting the old include files, will upgrade you to version 2.0 of the upgrade script. Unless you perform this step, new settings in the InstallAware IDE pertaining to the dual-mode update functionality will have no effect.


Upgrading from InstallAware 6.x

Upgrading setups created in InstallAware 6.x to InstallAware 7 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan on using InstallAware 7 projects back in older versions, you should not use any new/enhanced plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.
  • Due to optimizations made to build directory layouts, you may not create patches for projects built in InstallAware 6.0 or earlier using InstallAware 7.
  • Do not use the Save Feature Selections and Load Feature Selections commands to save/load features on setups built with InstallAware 6.42 or earlier.
  • Do not use the #LOADOLDDATA# compiler variable to load setup data on setups built with InstallAware 6.42 or earlier.


Upgrading from InstallAware 5.x

Upgrading setups created in InstallAware 5.x to InstallAware 6.0 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan on using InstallAware 6.0 projects back in older versions, you should not use any new/enhanced plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.
  • Due to optimizations made to build directory layouts, you may not create patches for projects built in InstallAware 5.x or earlier using InstallAware 6.
  • Do not use the Save Feature Selections and Load Feature Selections commands to save/load features on setups built with InstallAware 5.x or earlier.


Upgrading from InstallAware 2005 Second Edition

Upgrading setups created in InstallAware 2005 Second Edition to InstallAware 5.0 is mostly automatic. Simply open your project in the new IDE as before and continue working normally. However, if you used the MSXML plug-in command in your setups, you will need to follow these steps before you may open and rebuild your projects using the new InstallAware version:

  1. Open your setup script file using Notepad.
  2. Choose Edit [image] Replace.
  3. In the Find what field, enter MSXML 4.0 SP2.
  4. In the Replace with field, enter MXSML.
  5. Click Replace All.
  6. Choose File [image] Save.
  7. Open your setup project normally using InstallAware.

Also, the considerations below apply while working with older projects:

  • If you plan on using InstallAware 5.0 projects back in older versions, you should not use any new plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.


Upgrading from InstallAware 2005

Upgrading setups created in InstallAware 2005 to InstallAware 2005 Second Edition is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan on using InstallAware 2005 Second Edition projects back in older versions, you should not use any new plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.


Upgrading from InstallAware 3.0

Upgrading setups created in InstallAware 3.0 to InstallAware 2005 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with older projects:

  • If you plan on using InstallAware 2005 projects back in older versions, you should not use any new plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.
  • You may not create patches for InstallAware 2005 projects using patch references from older versions of InstallAware.
  • If your dialogs contain HTML controls, process them using the Form Batch Update Tool and upgrade the old HTML controls found on those dialogs. If you do not upgrade the HTML control, you will not be able to take advantage of new HTML rendering features; additionally your old HTML control will be invisible.


Upgrading from InstallAware 2.x

Upgrading setups created in InstallAware 2.x to InstallAware 3.0 is automatic. Simply open your project in the new IDE as before and continue working normally.

However, the considerations below apply while working with 2.x projects:

  • If you plan on using 3.0 projects back in 2.x, you should not use any new plug-ins and/or installation commands, as these will not be available in the older versions and your scripts will fail to load.
  • Do not attempt to auto-upgrade setups created in version 2.x using a setup created in version 3.0. Simply change the Product Code used in your setups to assure that 3.0 setups will not attempt to auto-upgrade 2.x setups.


Starting a New Project

When you open InstallAware for the first time, the New Project dialog will be automatically displayed. At any other time when you wish to start a new project:

  • On the Project tab, in the New group, click any button.
  • Click the InstallAware button, then choose New Project [image] Other.


New Project Dialog

The New Project dialog helps you choose from various types of setup projects when you are starting a new project.

Wizards

Quick Start

For most setup projects, Quick Start is the ideal starting point. It lets you rapidly build a working installer for your application, containing all the logic and dialogs required for a successful setup. Projects created using the Quick Start Wizard can be readily extended with the addition of application runtimes, more features, and other data pertinent to your setup - either using the IDE's visual designers, or by directly editing the setup source code using the MSIcode script editor.

InstallAware recommends you use the Quick Start Wizard when starting new setups.

Project Wizard

The Project Wizard will guide you step by step through the creation of a new setup project. When you are finished with the wizard, you will have created a fully functional installation script. You may then further customize that script in the script editor and IDE visual views.

The Project Wizard contains more steps than the Quick Start Wizard, and creates a more detailed setup project. However, InstallAware recommends you use the Quick Start Wizard when starting new setups - as the actual IDE itself contains a superset of the functionality available in both of these wizards.

PackageAware

Use PackageAware to monitor the system for changes a setup makes, and then convert that information into a ready-to-use installation project. PackageAware may be run on any computer and has absolutely no runtime requirements. It also nicely fits on a single floppy disk for easy transport. We recommend using virtualization software such as VMware or Virtual PC to optimize the capture process.

MSI/MSM Import Wizard

The MSI/MSM Import Wizard converts an existing Windows Installer database (a setup database or a merge module database) into a ready to build InstallAware setup project.

Templates

Templates are the recommended starting point for most setups. They contain the necessary script code to perform basic installation tasks and can be fully fleshed out using the IDE visual or code views.

Plug-Ins

Plug-ins are extensions to the IDE and the setups you generate. Several plug-in projects are available which can be used in your favorite programming environment as starting points for creating InstallAware plug-ins.

Converters

Converters import setup projects developed in a variety of other setup authoring environments to InstallAware. Most setup logic and features are automatically migrated, and the conversion wizards place comments in the imported projects that provide further instructions on how to make most of your imported setups in InstallAware.

Samples

Sample projects illustrate performing specialized tasks with InstallAware, such as online user registration. You may use sample projects as starting points for your own setups that require similar functionality; or copy-paste code from sample projects directly into your existing installations to add in the desired functionality.

Custom

Use Add Custom Template to convert the active setup to a generic template, which may then be re-used as your own custom baseline project when creating new setups.

The product name of your project as specified in the Project Options dialog is used as the name and unique identifier of your new template.

If you associated an icon with your project, that icon is displayed for your template in this dialog (otherwise, a generic InstallAware icon is used).

All templates are stored inside the InstallAware Templates folder found inside your Documents library, with a new subfolder created for each template. To delete templates, remove them from disk at this location. To copy templates from one computer to another, copy the desired contents of the InstallAware Templates folder.


Opening a Project

There are several ways to open an existing project with InstallAware.

Opening from Windows Explorer

Double-click the project file (with .MPR extension) to open it with InstallAware.

Opening from the IDE

  • Click the Open icon on the quick access toolbar, or click the InstallAware button and choose Open Project, or press CTRL+O and browse to the project that you wish to open.
  • Click the InstallAware button and look under Recent Setup Projects to quickly open a previously saved project.


Importing a Project

You may import projects built in various other setup development environments directly into InstallAware:

  • Click the InstallAware button and choose New Project [image] Import Project.
  • Select the environment you are importing from and choose your import file.

If your setup is built in an environment other than those available in the list, try using one of the PackageAware or Database Import Wizard tools to import your projects.


Saving and Moving a Project

You will want to save the project you are working on, or perhaps to move it to a different location. InstallAware projects are comprised of the project file (.MPR extension), script file (.MIA extension), dialog resources (.DFM extension), patch references, include scripts (.MIA extension), and other support items.

Saving a Project

To save a project that is open in the IDE:

  • Click the InstallAware button, then choose Save All, or press CTRL+SHIFT+S.

Saving a Script

To save the script that is current being edited in the IDE:

  • Click the Save icon on the quick access toolbar.
  • Click the InstallAware button, then choose Save, or press CTRL+S.

Moving a Project

To move a project, do not use the IDE. Copy or move the entire project folder using Windows Explorer (or your favorite file manager) to a new location. This process ensures that all project files as well as support files are properly copied over to the new location.

However, if you have any include scripts outside of your main project folder, or if your main script is located outside of your main project folder, even if you have made a copy of the original project, these elements will still be shared with the old project.


Importing from Express

Note:

This topic applies to versions of InstallAware Express prior to InstallAware Express 2005. InstallAware Express 2005 uses the same project format as other InstallAware editions and no import procedure is required.

Importing from Express

InstallAware Express projects have a .MPRX extension and cannot be directly opened in InstallAware. You may however import an existing project you created in the Express edition of InstallAware. To import an Express project, follow these steps:

  • Open the project in Express.
  • Build the project. Building an Express project generates an InstallAware project automatically.
  • Navigate to the build folder, locate the generated project file (.MPR extension), and open it.


Displaying the Project Manager

The Project Manager window gives you a graphical outlook on the script, dialogs, and files you have included in your project. To display this window:

  • On the Project tab, in the Manage group, click Project Manager.
  • Press CTRL+ALT+P.


Modifying the Main Script File

Each InstallAware project references a main script file, with a .MIA extension. You may change the main script file, or where it is located, without altering the remainder of your project. By default, the main script file carries the same name as the project file, and is located in the same project folder.

Warning:

After you modify the main script file, if you later decide to move the project, the main script file will not be automatically moved to the new project location.

To Change the Script File Location

  1. Display the Project Manager.
  2. Select the Script node in the tree view. Right-click on the script file.
  3. Choose Save Script File As, and browse to the new location where you wish to save the script file.

To Modify the Referenced Script File

  1. Display the Project Manager.
  2. Select the Script node in the tree view. Right-click on the script file.
  3. Choose Change Script File, and browse to the new script file you would like to use.


Modifying Project Dialogs

Each project contains references to the dialogs that are a part of its user interface. You may edit, add, and remove existing dialogs.

To Add New Dialogs

  1. Display the Project Manager.
  2. Select the Dialogs node in the tree view.
  3. Right-click and choose Add Dialogs to Project, or press INSERT.
  4. If you wish to add an entire themed collection of dialogs, check Add a Pre-Built, Themed Collection of Dialogs, and select the theme from the drop down menu. If you wish to choose dialogs manually instead, check Choose Dialog(s) to Add by File Name, and browse to the dialog file(s).
  5. All selected dialogs will be copied to the project folder, and will be added to your project as references.

Warning:

If you add a dialog that already exists in your project folder, the new dialog will overwrite the old one.

To Edit Dialogs

  1. Display the Project Manager.
  2. Select the Dialogs node in the tree view.
  3. Double-click the dialog you wish to edit, or select it and press ENTER. The dialog will open in the Dialog Editor.
  4. Modify your dialog as necessary and remember to save your changes.

To Remove Dialogs

  1. Display the Project Manager.
  2. Select the Dialogs node in the tree view
  3. Highlight each dialog you would like to remove. You may select multiple dialogs.
  4. Right-click your selection and choose Remove Dialogs from Project, or press DELETE.


Modifying Support Files

Each installation project contains support files that are used as resources during your setup. For instance, your license agreement file is a support file. Support files are compressed into the main setup executable during builds and are available while the installation is running at the folder referenced by the SUPPORTDIR variable.

To Add Support Files

Adding files such as setup splash screens, license agreements, readme files, is necessary for most setups:

  1. Display the Project Manager.
  2. Select the Support Files node in the tree view.
  3. Right-click and choose Add Files to Project, or press INSERT. Browse to the files you wish to add. You may select multiple files.

Remember that you may include any file as a support file, and access it while the installation is running using the SUPPORTDIR variable.

To Remove Support Files

You may wish to eliminate support files that you no longer use:

  1. Display the Project Manager.
  2. Select the Support Files node in the tree view.
  3. Highlight each support file you would like to remove. You may select multiple files.
  4. Right-click your selection and choose Remove Files from Project, or press DELETE.


Modifying Merge Modules

Your installation projects may contain one or more Windows Installer Merge Modules. Merge Modules are available as .MSM files and are fully self-contained pieces of setup logic and data, used in extending Windows Installer installations. The most typical usage of a Merge Module is to add support for installing a particular application runtime to your setup solution.

Once you add a Merge Module to your setup, the runtime it contains will be properly installed, with no further steps or configuration required. You may add as many Merge Modules as required to your project simultaneously.

To Add Merge Modules

Follow the steps below to add a new Merge Module to your setup:

  1. Display the Project Manager.
  2. Select the Merge Modules node in the tree view.
  3. Right-click and choose Add Merge Modules to Project, or press INSERT. Browse to the Merge Modules you wish to add. You may select multiple Merge Modules.

To Remove Merge Modules

You may wish to eliminate Merge Modules that you no longer need:

  1. Display the Project Manager.
  2. Select the Merge Modules node in the tree view.
  3. Highlight each Merge Module you would like to remove. You may select multiple files.
  4. Right-click your selection and choose Remove Merge Modules from Project, or press DELETE.


Modifying Patch References

You may include one or more patch references in your project. Patch references are links to older installations of your products that you wish to create binary patches against.

You may only add InstallAware EXE and MSI packages as patch references. Patching against setups built with versions of InstallAware older than InstallAware 2005 is not supported.

To Add Patch References

Follow the steps below to add a new Patch Reference to your setup:

  1. Display the Project Manager.
  2. Select the Patch References node in the tree view.
  3. Right-click and choose Add Patch Reference to Project, or press INSERT. Browse to the setup packages you wish to add.

To Remove Patch References

You may wish to eliminate Merge Modules that you no longer need:

  1. Display the Project Manager.
  2. Select the Patch References node in the tree view.
  3. Highlight each Patch Reference you would like to remove. You may select multiple references.
  4. Right-click your selection and choose Remove Patch References from Project, or press DELETE.


Modifying Include Scripts

Each installation project may contain one or more include scripts. Include scripts let you share pieces of code between your setups using the Include Script command. Before you may include scripts in your code with this command, you need to add the physical script files to your project. An include script, once added to your project, appears in its own tab in the code editor. It may be edited in the code editor by switching to this tab, and used in other scripts with the Include Script command.

To Create a New Include Script

If you would like to create a new include script as part of your project:

  1. Display the Project Manager.
  2. Select the Include Scripts node in the tree view.
  3. Right-click and choose Create New Script. Choose a physical location and file name for your new include script.

To Add Include Scripts

If you have an existing include script which you would like to add to your project:

  1. Display the Project Manager.
  2. Select the Include Scripts node in the tree view.
  3. Right-click and choose Add Existing Scripts, or press INSERT. Browse to the files you wish to add. You may select multiple files.

To Remove Include Scripts

You may wish to remove references in your project to include scripts that are no longer used:

  1. Display the Project Manager.
  2. Select the Include Scripts node in the tree view.
  3. Highlight each include script you would like to remove. You may select multiple scripts.
  4. Right-click your selection and choose Remove Scripts, or press DELETE.


Using the Script Editor

The script editor is where you create the heart of your installation. The setup script drives the entire installation, determines your setup logic, and modifies the target system. You will frequently work in the script editor while authoring your installation. The script editor is entirely visual, and has a pseudo-code appearance.

Writing your Setup Script

When working in the script editor, you will add commands that perform setup actions, edit existing commands and fine tune their behavior, and of course remove commands which you wish to eliminate.

Adding Commands

The list of available commands is displayed to the left of the installation script. To add a command:

  • Type directly using the keyboard while the script has the focus. A drop-down menu opens with command names that match the letters that you have typed so far. Press ENTER to choose the matching command that is displayed, or use the UP - DOWN arrow keys to navigate to the command you wish to add to your script, pressing ENTER when the command you wish to insert is displayed.
  • From the command palette, select the command you wish to add using the keyboard, and press ENTER. The command will be added on top of the script item selected in the installation script.
  • Drag and drop the command from the command palette to the installation script. The command will be added on top of the script item you release the mouse button on.

Editing Commands

  1. Using the mouse or the arrow keys, navigate in your script to the command you wish to edit.
  2. Double-click the command, or press ENTER.
  3. If the command has options you can edit, a dialog box will appear allowing you to make your changes.

Removing Commands

  1. Using the mouse or the keyboard, highlight the lines you wish to remove.
  2. Press DELETE.

Script Editor Features

The script editor has several convenient features you may use while working with your setup code.

Clipboard Functions

  1. Using the mouse or keyboard, highlight the code to cut or copy. Or, select the code you wish to paste above.
  2. Right-click the code, and choose Cut, Copy, or Paste. You may also use the shortcuts CTRL+X, CTRL+C, CTRL+V.
  3. If you want to copy code in human readable form, choose Copy as Text. You may also use the shortcut CTRL+SHIFT+C.

Search and Replace

  • To search for a line of code containing specific text, type CTRL+F.
  • To replace occurences of some text with others, type CTRL+R.

Using Code Navigation Drop-Downs

  1. First select the class of script items to navigate to. For instance, choose Web Media Blocks on the left combo box if you want to jump to places in your code where web media blocks have been declared.
  2. Next, select the particular script item to go to. Opening the combo box on the right reveals the matching elements in your script of the chosen class above. Pick one of the items to navigate to that item.
  3. If the right combo box has no contents, then the current script has no items of the chosen class in the first step above.

Moving Code Up or Down

  1. Using the mouse or keyboard, highlight the code to move.
  2. Right-click the code, and choose Move Up or Move Down.

Commenting Code

  1. Using the mouse or keyboard, highlight the code to comment out (or comment in, if it is already commented out).
  2. Right-click the code, and choose Comment Out/In.

Navigating Tabs

  • To move between tabs, click the tabs directly, or use CTRL+LEFT or CTRL+SHIFT+TAB to move to the next left tab, or use CTRL+RIGHT or CTRL+TAB to move to the next right tab.

Code Folding Regions

  • To fold all regions, right click the script, then choose Fold All Regions.
  • To unfold all regions, right click the script, then choose Unfold All Regions.
  • To toggle the folded state of a region, double-click the region line with the mouse, or press CTRL+ENTER.
  • To edit the name of a folded region, select the region line and press ENTER.

Bookmarks

  • To create a bookmark, position the cursor in the line to bookmark, then hold down CTRL+SHIFT and choose a number between 0 and 9. This number becomes the unique identifier of your bookmark.
  • To navigate to a bookmark, hold down CTRL, and type the number of the bookmark to navigate to (between 0 and 9).
  • To remove an existing bookmark, navigate to the bookmark, and re-create the bookmark.
  • Re-creating an existing bookmark on another line moves the bookmark to that line.

Undo and Redo

  • To undo changes, use the shortcut CTRL+Z, or right click the script and then choose Undo.
  • To redo changes, use the shortcut CTRL+Y, or right click the script and then choose Redo. Making any script changes after an undo operation, other than a further undo or redo operation, will lose all redo history.
  • Switching to the visual portion of the InstallAware IDE will lose all undo and redo history for your main script file, but will not lose any history for any include files.


Customizing Script Appearance

You may change the way your script looks in the script editor. On the MSIcode tab, in the Edit group, click Options to display the IDE Options window, and then:

  • Select the Editor tab to change the script font and size. The Editor tab also lets you turn the Code Folding feature on and off. You may also allow the InstallAware IDE to use multiple instances, or allow only a single instance of itself, through the Allow Multiple Instances of the InstallAware IDE check-box also found on the Editor tab.
  • Select the Color tab to change the way script commands are syntax highlighted.
  • Select the Hints tab to show or hide balloon tips for potential error conditions, as well as general coding tips. The Hints tab also lets you enable or disable saving extra human readable TXT file accompaniments for each of your script files - while InstallAware script files are plain text, they are not human readable outside of the IDE. The TXT file accompaniments however are human readable - corresponding exactly to the script text as seen in the IDE - in plain text form, thus serving as a valuable aid in change tracking mechanisms. Note that these human readable files do not contain any project information and therefore cannot be re-opened inside the IDE.


IDE Layouts

The InstallAware IDE is configurable with docking tool windows. IDE layouts provide a quick way to save your docking configuration. Moreover, they let you quickly change configuration, which makes them very practical to use. For instance, you may use to a particular layout while coding your setup, and switch to another while debugging.

Choosing a Layout

The list of available layouts is shown in the Manage group of the Project tab. Simply click the drop-down menu and select the layout you wish to activate.

Saving a Layout

If you have customized your IDE and wish to save your changes, you may store them in a new (or existing) IDE layout:

  • On the Project tab, in the Manage group, click the Save Layout icon.

Deleting a Layout

To remove layouts you do not use anymore:

  • On the Project tab, in the Manage group, click the Delete Layout icon.


IDE Tools

The InstallAware IDE is complemented by tools and plug-ins which work hand-in-hand with it. Note that the installation of some of these tools is optional, and they will not open unless they have been installed. If you realize you failed to install a necessary tool, simply re-run the InstallAware setup and Modify your existing installation to add the required tools.

Tools

Choose a tool for more information.

  • App-V Builder
  • App-V Viewer
  • Digital Rights Management
  • Export to Virtualization
  • Database Import Wizard
  • PackageAware
  • Refactor Paths
  • Dialog Editor
  • Localization Wizard
  • Translator
  • Database Validator
  • Code Signing
  • Group Policy Wizard
  • Setup Decompressor
  • Dialog Batch Updater

Plug-Ins

Plug-ins enhance both the IDE and the setups you create. To see a list of available plug-ins, on the MSIcode tab, in the Edit group, click Plug-Ins, or press F11. You may add new plug-ins by installing them, or uninstall existing ones to remove them. Each available plug-in will be shown on the Commands list and you may use it like any other command while editing your setup script.


Authoring Process

The process of developing a setup can be summarized in the steps below.

  1. Determine Requirements
  2. Design Setup Logic
  3. Define User Interface
  4. Create Baseline Project
  5. Code Installation Logic
  6. Install Application Data
  7. Build and Test
  8. Deploy


Determine Requirements

Before starting work on your installation, lay some conceptual groundwork. This will save you time later, as missed requirements can result in hard to reproduce bugs. Requirements that must be determined include:

  • Minimum computer hardware requirements (display resolution, color depth, physical memory)
  • Minimum computer software requirements (operating system version, Internet Explorer version, any required third party software)
  • Redistributable DLLs (programming language support libraries)
  • Component updates (programming language runtimes)
  • Database platforms (data access components)

InstallAware provides easy ways to check for hardware/software requirements, and install required component updates where necessary. Leverage the power of InstallAware, checking for and enforcing your system requirements.


Design Setup Logic

Your setup logic is essentially the "what happens when" of your installation program. Careful planning and foresight will ensure your setups install right the first time.

Make a list of possible installation scenarios, including:

  • Fresh installs
  • Upgrades
  • Cross-grades

Define the user experience with your installation - what information will you be asking the user for a successful setup? Some examples:

  • Licensing checks
  • Application features
  • Any custom information

Focus on technical aspects of your setup:

  • Differences between 9X and NT based installs
  • Application feature interdependencies
  • Shared third party components


Define User Interface

Based on the target audience of your product, carefully pick a user interface. InstallAware ships with ten pre-built setup themes that range from conservative to fashionable, providing you with a good starting point in designing your user interface (to sample the themes, in the Start Menu program group for InstallAware, choose Dialog Samplers, and pick the theme to try).

InstallAware's Dialog Editor helps you further customize your setup theme and add/remove elements to/from your dialogs. If you need to obtain information from end-users which are specific to your particular product, simply add additional controls to your existing dialogs, or even create new dialogs, extracting the required information. InstallAware makes it very easy to add custom elements to setup dialogs, and access that information from the setup script.


Create Baseline Project

Once you have laid the conceptual groundwork for your installation, you can actually begin coding your setup. While there are many ways to start coding, including starting from a completely blank project, the quickest route would be to start with the Basic Setup (on the Project tab, in the New group).The basic setup provides an ideal baseline, a fully fleshed out setup to which you can simply add the files, registry keys, and other similar settings you need, and obtain a fully extensible, customizable setup program.


Code Installation Logic

Thanks to the unique scripting technology that InstallAware makes available on the Windows Installer platform, you are free to use as many conditional statements and branched executions in your setup as you want. Utilize the power of genuine scripting for Windows Installer, and enjoy complete freedom in your installation. Check for different circumstances and act upon them as necessary. Below are some ideas to get you started:

  • Import data from previous application versions
  • Define and let the user choose from application features
  • Act differently on varying target system configurations
  • Import/export data from/to the registry and configuration files
  • Check local file versions
  • Read/write from/to text files
  • Install application runtimes
  • Conduct interactive user surveys
  • Ask users "why?" when they are uninstalling
  • Ship a single installer for all your different product editions
  • Dynamically define application features based on authentication


Install Application Data

When you have successfully interviewed the user and got the necessary responses from your setup dialogs, you are ready to begin modifying the target system. InstallAware's unique scripting engine makes it possible to execute each action that changes target system state through Windows Installer. No custom actions or any third party technologies are involved. Each of your installation commands will execute directly through Windows Installer.

A short selection of available installation commands, all executing natively through Windows Installer:

  • Install files
  • Copy/move local files
  • Edit registry
  • Edit INI files
  • Create shortcuts
  • Install and/or remove other Windows Installer setups


Build and Test

After you have completed coding your setup, it is time to build your setup. Building a setup converts your installation script, along with all requisite files, to a fully working installation that you can distribute to your end users. Of course, it is necessary to test your installation under all anticipated execution environments before moving ahead to the deployment phase.


Deploy

After you have coded, built, and tested your setup to your satisfaction - it is time for deployment. In a nutshell, deploying your setup is making it available to your end-users. This can mean a lot of different things - publishing your product on a web page and pressing it on a CD to name the two most common options.


Maintain

Once you have deployed your setups to the real world, as you get more and more feedback from users, you will inevitably find aspects of both your product and the install which can be improved. This introduces the maintenance cycle.

InstallAware assists you with the maintenance of your products using patch technology. Build and distribute differential patches of your products to your existing user base, thus avoiding the cost, space, and time requirements of re-distributing an entire setup all over again from scratch.

InstallAware also provides a built-in Web Update mechanism, so you can push application updates to customers who have older versions of your product.


Compiling

To compile your project:

  • On the MSIcode tab, in the Compile group, click Compile, or press CTRL+F9.

Compiling a project does the following:

  • Check your script for correct syntax and valid variable references.
  • Update your Windows Installer database file.

Compiling a project is automatically performed when you do a build or a batch build.

While to deploy a project you need to do a full build, compiling can help save you time in between multiple debugging runs. You do not need to rebuild your project if you have only changed your setup script (and not any of the installed files) since your last build.


Building

To build your project:

  • On the Project tab, in the Build group, choose a build mode.
  • On the MSIcode tab, in the Compile group, click Build, or press sHIFT+F9.
  • On the quick access toolbar, click the Build icon.
  • Use the command line.

Building a project does the following:

  • Delete all files and folders in the build output folder.
  • Compile your project.
  • Pull all referenced files and folders.
  • Generate your selected deployment layout.

You will need to rebuild your project before deploying it. After a build, your setup is ready for testing and deployment. You also need to rebuild your project while debugging if any of the files referenced in your installation have changed.

Building can take a lot of time, especially if you are using a compressed or web deployment type. Consider setting the uncompressed deployment type to accelerate your builds while developing your setup. In some instances a compile may also be used in place of a build.


Batch Building

To batch build your project:

  • On the MSIcode tab, in the Compile group, click Batch Build.

A batch build is essentially the same as a regular build. However, the revision code does not change in between batch builds (even if it is enabled in your settings), and you may build more than one deployment type at a single pass. Batch builds are especially useful when you have finished development, and wish to update your installation with the latest application files and/or are building for multiple deployment types.


Build Settings

Build settings control how your setups are built. These settings allow for changing the deployment type (uncompressed, compressed, web), among other things. To access your build settings:

  • Press SHIFT+CTRL+F11.
  • On the Project tab, in the Manage group, click Project Settings.
  • On the MSIcode tab, in the Compile group, click Project Settings.

Build Node

This page lets you configure your deployment type. The various kinds of deployment types, along with their uses, are explained below. Pick the one that is most suitable for your target audience.

Uncompressed Directory Layout

Your setup is contained in multiple files spanning several layers of multiple nested folders. Each file is uncompressed and immediately available, minimizing installation time, since files will not be uncompressed from an archive or downloaded before installation.

This type of deployment is ideal for CD/DVD media where disk space is not a concern and multiple files/folders can be stored. It also works well on network drives.

This build type does not cache its setup sources by default.

Compressed Single Self-Installing EXE

Your setup is contained inside a single self extracting file. This file, when run, will first extract its contents to a temporary folder, and then start the main setup program. In essence, when executed, the compressed layout converts into the uncompressed layout.

This type of deployment is suitable for Internet distribution, since the entire setup is contained inside a single file.

This build type does not cache its setup sources by default.

Compressed Web-Based EXE

Your setup is comprised of a self extracting file, which similarly to the compressed layout, extracts its contents and starts the main setup; as well as web media blocks, which are defined in your setup script and are downloaded as required from the web.

This type of deployment is ideal for Internet distribution. Setup will download only the web media blocks which are required on the target system. This saves download times and bandwidth since users will not waste either downloading portions of your application and/or its runtimes which they do not need.

This build type does cache its setup sources by default.

Always Cache Setup Sources (enables easy patching)

This three-state check-box lets you control setup source caching. When the box is filled, the default source caching option (as described above for each build type) is in effect. When cleared, setup sources are never cached. When checked, setup sources are always cached.

Caching setup sources consumes additional disk space on the target system. This loss of space is partially offset by the usage of NTFS compression if the target file system is NTFS. The advantage of caching setup sources is that when a patch is being applied, or when setup is being re-run in maintenance mode without the original installation file or media, setup will never prompt for the original setup sources - patching, or repairing/adding new application features automatically.

When setup sources are not cached, no disk space is wasted on the target system for a copy of the installation files. However, running setup in maintenance mode (other than uninstalling the application) will require access to original setup sources, as will patching setup.

Debug Build (allows setups to be debugged in IDE)

If you will be debugging your setup inside the IDE, also ensure the Debug Build checkbox on this page is checked. Note that you cannot run debug builds outside of the IDE.

Authenticode Node

This page lets you digitally sign your packages with authenticode. Provide the paths to your certificate and key files to enable code signing. The default value for the time stamp URL is http://timestamp.verisign.com/scripts/timstamp.dll.

Compression Node

Compression

This slider lets you configure the strength of the compression employed while creating your setups. Move the slider and choose a setting that is optimal for your system. You may wish to set the slider to choose no compression while testing and debugging your setup, as at maximum compression, builds take a long time to complete.

Use 256 bit AES Encryption

You may encrypt your compressed setups with strong 256 bit AES encryption technology. The entire setup payload, including the setup and data files, will be encrypted (even if the compression slider is set to use no compression).

Compiler Node

This page provides compiler optimization switches which improve the runtime Windows Installer performance of your setups, as well as the time it takes InstallAware to build your setups. The default settings on this page reflect the safest settings to use (all compiler optimizations disabled), providing maximum compatibility for:

  • ICE Validation (required for the Designed for Windows logo program),
  • Patching,
  • Advertising (self-healing and installation-on-demand),
  • Web Media Block sharing (sharing/re-using web media blocks across different setup projects, or even different rebuilds of the same project).

You may selectively enable some compiler optimizations to improve the build speed of your setups, as well as their runtime Windows Installer performance. Please note that these optimizations are best turned off for smaller setup projects - since smaller setup projects will not experience build time or runtime performance issues, its best to enable all available compatibility settings instead of a performance trade-off that really is not necessary.

Reduce MSI file component count

The InstallAware compiler normally generates one MSI component for each file that is included with your setup. This can slow down processing significantly on the Windows Installer side (once Apply Install has been called), since Windows Installer has to keep track of every MSI component defined in your setup. Check this box to group multiple files inside a single MSI component. InstallAware will still follow MSI component authoring guidelines when grouping your files together inside fewer MSI file components.

Please note that MSI components are not the same entity as your setup features or components as seen in the either visual IDE or your setup script. Refer to Windows Installer documentation for more information on MSI components - InstallAware does not expose you to MSI components in either the visual IDE or your setup script, and handles them internally at all times.

With this setting enabled, only files that are part of a single Install Files command are optimized. Files that span across different Install Files commands will still be placed inside different MSI components. Use wildcards with the Install Files command to optimize MSI component creation for files.

Reduce MSI registry component count

The InstallAware compiler normally generates one MSI component for each registry value that is created by your setup. This can slow down processing significantly on the Windows Installer side (once Apply Install has been called), since Windows Installer has to keep track of every MSI component defined in your setup. Check this box to group multiple registry values inside a single MSI component. InstallAware will still follow MSI component authoring guidelines when grouping your registry values together inside fewer MSI components.

Please note that MSI components are not the same entity as your setup features or components as seen in the either visual IDE or your setup script. Refer to Windows Installer documentation for more information on MSI components - InstallAware does not expose you to MSI components in either the visual IDE or your setup script, and handles them internally at all times.

With this setting enabled, registry values that reside inside the same If / Else / End block are optimized. Registry values not inside the same If / Else / End block are not placed inside the same MSI component.

Generate stable identifiers

The InstallAware compiler normally generates stable MSIcode statement identifiers for each line of your setup script. These identifiers do not change between each build of your setup, and make each of your MSIcode statements "unique" - they can be tracked and identified by InstallAware and Windows Installer during the different iterations of your setup source code. However, it is costly to generate stable identifiers in terms of processing power; therefore using stable identifiers will slow down the build speed of your setup project.

Stable identifiers do not negatively impact runtime setup performance, and permit Web Media Block sharing between different builds of your setup, as well as different setup projects sharing the same source media layout and plug-ins.

Use dynamic identifiers

If you need to improve the build speed of your setup projects, use dynamic identifiers instead by selecting this option. The InstallAware compiler will not make an effort to generate unique identifiers for each MSIcode statement. This may create problems with patching, and will almost always break Web Media Block reuse. Even when you are rebuilding the same project, when the ordering and/or number of the MSIcode statements in your setup script change, you will need to regenerate your Web Media Blocks with this option.

Blend

Blend offers a "best of both worlds" approach for generating MSIcode statement identifiers. The InstallAware compiler will use stable identifiers for each MSIcode statement that is associated with a source file, enabling Web Media Block reuse. For every other statement, such as registry entries, unstable identifiers will be used, improving build performance. However, this setting might still create problems with patching.

Output Node

This page allows you to customize additional build settings:

  • If you wish to customize the output folder, check Custom Folder and provide your preferred output folder. By default, builds will exist under your project folder.
  • If you wish to customize the name of your main setup executable, enter it in the Output filename field. Leave this field empty to use the default name, which is the same as your project file name.
  • If you wish to automatically update the revision code every time you build (excluding batch builds), check Change revision code automatically upon rebuild. This setting must be unchecked when debugging your setup. Checking it will enable seamless, automatic upgrades of your product.
  • If you wish to generate file hashes for your non-versioned application files, check Calculate file hashes for Windows Installer. To improve build speeds, uncheck this setting. Checking it will enable Windows Installer to better identify changes made to your already-installed application files, but will slow processing.

Patch Node

This page lets you configure how patches are created for your setups.

Include whole files only

Enable this option to disable binary differential patching. Files that have changed between product versions will be included in their entirety. This option may be useful when patching against a large number of reference packages, or the differential algorithm fails to provide satisfactory results.

Optimize for large files

Enable this option if the files you are patching are more than eight megabytes in length.

Ignore missing files

If your patch references contain missing source files, enable this option to allow patching to continue.

Leave debug files

Enable this option to manually investigate the by products of the patching process and the interim installer databases created by the patch engine.


Running Inside the IDE

While the most straightforward way to test your setups will be to execute them from the build output location, you may find it convenient, and at certain times necessary, to run the setup in the IDE, so as to be able to debug your setups. You may execute any setup inside the IDE, however the following special considerations do apply:

  • In the Project Options dialog, on the Build node, make sure the Debug Build checkbox is checked. You may choose any deployment type as long as this checkbox is checked. Note that you do not need to check the Debug build checkbox when building with the Uncompressed Directory Layout option.
  • Build your project at least once before beginning debugging. Remember to rebuild whenever you change your installation files and/or build mode. Rebuilding is not necessary when you change the installation script.
  • The SUPPORTDIR variable, and other variables which refer to the location of the running setup program, will refer to your project folder.
  • The EXEFILE variable, and other variables which refer to the running setup program, will refer to the InstallAware IDE executable file itself.


Debugging

The InstallAware IDE includes integrated debugging capabilities. As long as you have prepared to run your setup inside the IDE, you may make free use of any of the powerful debugging tools described below.

Running in the Debugger

  • Set breakpoints as necessary. Breakpoints alert you when a certain line in your script has been reached and pause program execution. Highlight each line you wish to set a breakpoint on, and on the MSIcode tab, in the Run group, click Set Breakpoint, or press F5.
  • To execute your setup and stop only at your breakpoints, on the MSIcode tab, in the Run group, click Debug, or press F9.
  • To execute your setup line by line, stopping at each line, on the MSIcode tab, in the Run group, click Step, or press F8.
  • To terminate the execution of your current program, on the MSIcode tab, in the Run group, click Reset, or press CTRL+F2. Be sure to close any currently active dialogs shown by your setup before terminating.

Using Variable Watches

Variable watches help you monitor the state of each of the variables used in your setup. You can therefore find out if your expected setup logic is working correctly. Moreover, you can change the values of variables while setup is running.

Displaying the Watches Window

You must first open the Watches Window which displays the variable names and their values.

  • On the Project tab, in the Manage group, click Variable Watches, or press CTRL+ALT+W.

Adding a Watch

  • On the MSIcode tab, in the Run group, click Add Watch, or press CTRL+f5. Type in the name of the variable you wish to watch.

Changing a Variable Value

  • Single-click on the Value column entry corresponding to the variable name displayed under the Variable column that you wish to override. Type in the new value.

Removing a Watch

  • Highlight the watch to remove. Press DELETE.


Logged Execution

Some bugs you encounter in your testing may be very difficult to reproduce, and occur only on systems which you do not have debugging access to. Under these circumstances, you can always try logged execution, in addition to the age-old method of displaying message boxes on the screen.

Logged Information

With the Windows Installer engine, logged execution will create a log file and record both the internal state of the installation (along with all variable values) and the native Windows Installer log inside a plain text file. Since all changes are pending until Apply Changes is called, the log will be created only after Apply Changes has been called.

With the Native Engine, logged execution will create a log file containing diagnostic information on each executed setup command. If the pre-defined variable $DELAYUNTIL_APPLYCHANGES$ is FALSE, the log will be written to as each setup command is executed individually; otherwise the log will be written to when Apply Changes has been called.

Adding Custom Information to the Log

You may add custom diagnostic information to the setup log anywhere in your MSIcode script by calling Write to Text File on the pre-defined variable $LOGGED$.

Enabling Logging

To execute a logged setup, use the following command line:

<setup.exe> /l=<path to logfile>

Notes

  • If your logfile path contains spaces, enclose the full parameter (including the leading /l= part) inside double-quotes.
  • Specifying a file name only is not allowed. You must specify a full valid path in an existing folder, including drive and directory information.
  • It is also possible to enable logging programmatically within your MSIcode script. Set the value of the pre-defined variable $LOGGED$ to a valid, fully qualified file path to turn on logging. No double quotes should be used with this approach.


Compatibility Testing

Because of the wide variety of Windows platforms available today, it is vital that you perform compatibility testing on your setups.

InstallAware features a wide array of runtime components which you may install on the target system if they are not found. This helps cushion the impact that different Windows versions may have on your application. Never assume other Windows computers have all the patches, runtime components, and updates your development system is running on. And, powered by the web deployment feature, InstallAware helps assure users that already have the updates will not waste a single byte or second downloading them again.

InstallAware strongly recommends you include all target editions of Windows in your testing plans.


Deployment

After a project has been built and tested, it is ready for deployment. The output folder of your build, the location where you can find the files to deploy, varies by the build type.

  • Uncompressed Builds: <BUILD Folder>\release\uncompressed
  • Compressed Builds: <BUILD Folder>\release\single
  • Web Builds: <BUILD Folder>\release\web

The particular steps for deployment varies by build type as well.

Deploying Uncompressed Builds

An uncompressed build requires the entire build folder to be deployed. You may deploy onto any medium that is capable of replicating the exact directory structures generated by the build. This includes network drives, hard disks, and removable media (such as CDs and DVDs, which the uncompressed build mode is most suitable for).

Please note that the uncompressed layout, while storing your application files in a readily accessible state, does not permit you to randomly replace those files. Because of the nature of Windows Installer and the way it handles resiliency, if you wish to update any of the files in the installation package, you will have to rebuild the installation. Simply copying the updated file to the proper location in the build folders may cause your installation to fail.

An uncompressed build may be launched by running either the .EXE file or the .MSI file that carries the project name in the build output folder.

Deploying Compressed Builds

To deploy a compressed build, simply copy the single .EXE file that is located in the build output folder. Compressed builds provide the most flexibility in choosing your target media, since they will work with practically all media types (they neither require a directory structure to be preserved, nor Internet connectivity).

A compressed build may be launched by running the single .EXE file.

Deploying Web Builds

A web build has two steps of deployment. The first step is to place the .EXE file found in the root directory of your build folder on your desired target medium. This can be practically any location. This .EXE file is your main installation file.

The next step is publishing your web media blocks on the web. The media blocks each end with a .7zip file extension. The file names will correspond exactly to the web media blocks they contain. For instance, a web media block named mainapp will be contained inside the file mainapp.7zip. Each of these media blocks must be available for HTTP download on the precise URL as specified in the web media block script item. Continuing the above example, if the mainapp media block has the Download URL field set to http://www.mycompany.com/first_component.dat, then the file mainapp.7zip must be renamed first_component.dat and published to the root of the http://www.mycompany.com web server.

Deploying Web Builds Offline

A new feature in InstallAware 3.0 is the ability to deploy your entire web builds offline. If the main setup executable can locate some or all of the web media blocks it requires directly in the same folder as itself, it will first attempt to use these local copies of the web media blocks, instead of downloading them. If this attempt fails, or for web media blocks which cannot be found locally, setup will download from the web.

This option is primarily intended for use in quick deployment and testing scenarios. If you do not intend to download web media blocks during installation, Compressed or Uncompressed builds will always deliver better performance.


Patching

After you have deployed a project, you may want to issue patch updates to it. Patches have the advantage of including only the changed parts of your setup since the last time you built them, and therefore both the installation process and the size of the installation package are extremely streamlined.

When you build a patch, the output folder of the patch will be as follows:

  • <BUILD Folder>\patch

A patch is always built against a collection of Patch References. Each patch reference is simply an older version of your setup which you will be patching against. You may add multiple patch references to your project as necessary.

The patch will be created according to the settings specified in the Build Settings section of the Project Options dialog.

Patch Requirements

For a patch to work successfully, you must correctly specify product, upgrade, and revision codes that are used in the original project and the patch project.

  • The patch references and the patch project must share the same upgrade code. Having the same upgrade code qualifies your patch to Windows Installer as being an update for the products you will be patching.
  • The patch references and the patch project must share the same product code. Having the same product code qualifies your patch to Windows Installer as being a patch for the products you will be patching.
  • The patch references and the path project must have a different revision code. Having a different revision code helps Windows Installer recognize that you are updating the products you will be patching.

To view and update the product, upgrade, and revision codes, use the Project Settings window.

When you create a new project in the InstallAware IDE, it will have its unique set of product, upgrade and revision codes. As you build versions of this setup, the revision code will be automatically changed, as long as the Change Revision Code Automatically Upon Rebuild option remains enabled in the Build Settings window. If these default settings are preserved, you will not need to manually manage your product, upgrade, and revision codes when creating patches.

Additionally, when working with patches, you may want to set the pre-defined compiler variable #NOHARDLINKS# to TRUE. This ensures that during each build, a full copy of each source file going into your setup is created. While this is not a concern for compressed or web build types, it can potentially create a problem with uncompressed builds as follows:

  1. When #NOHARDLINKS# is FALSE (the default value), the uncompressed build process creates hard links to your application files to improve build speeds on supported NTFS systems, instead of creating full copies of those files.
  2. When you update your application files, these changes are also reflected in the "already built" setup files which are just hard links to your original application files.
  3. When building a patch, the patching mechanism cannot detect any changes between old and new file versions, because they all contain the same data - in fact, they are all hard links pointing to the same file.

This is not a concern for compressed or web builds, because while hard links may still be utilized to improve build times, the compression process does store a full copy of your original application files, in their exact state during build time, inside the compressed setup package. Therefore, upon extraction, a full "old" copy of your original application files are created - allowing the patching mechanism to successfully detect any changes to files - instead of hard links that point back to your original application files, as would be the case with uncompressed builds.

When Not to Use a Patch

The following additional considerations apply for patches to work successfully:

  • The patch references and the patch project must have the same product name.
  • The patch references and the patch project must install into the same target directory.
  • The patch references and the patch project, on overall, must follow the same execution logic.

Do not try to build a patch for an old version that has a different product name, installs completely different sets of files, installs files to a different folder, or has a radically different MSIcode script (such that the order of installation commands and/or their execution logic is different from the latest version). Even if your patch builds successfully, the runtime application may yield unexpected results, such as being unable to resolve the patch source folder, and orphaning files installed by the old version.

Adding and removing files and registry keys in a patch is permissible, as long as these changes do not affect the overall structure of your MSIcode script. Significant changes to the MSIcode script will lower Windows Installer's ability to match your old patch reference data with your latest version, and may yield unexpected results. Please note that only Windows Installer commands and Flow Control commands are subject to these limitations. The remainder of your commands are not subject to these limitations, as they fall outside of the scope of Windows Installer's patching mechanism.

In cases where patching is inapplicable or does not produce the expected results, use a full version installer instead. Your full installer is automatically capable of uninstalling the old version before installing the new version, and is not subject to any of the above patching constraints.

Patch Source Resolution

When a patch runs on the target system, it requires access to the source media that was part of the original setup. Locating source media varies according to the build type of the original setup. In addition, a hard-coded path to the original setup sources may be specified on the command line. These options are described in detail below.

Source Resolution for Uncompressed Builds

When the setup runs, it will prompt for the original source media. At this point, if the uncompressed build was distributed on a CD or DVD (as would be typical for most uncompressed builds), the user will need to insert the physical media into the drive and choose the drive letter in the source media browser. If the uncompressed build resides on a hard disk folder, the user will need to choose that folder in the source media browser.

Source Resolution for Compressed Builds

When the setup runs, it will prompt for the original source media. At this point, the user will need to run the self extracting .EXE file that comprises the compressed build. When this file is running, as part of the setup initialization routine, it will extract its contents to a subfolder of the system temporary folder. The user will have to navigate into the system temporary folder, determine which subfolder contains the setup sources (by trial and error if necessary), and choose that in the source media browser.

Because this is a largely inconvenient way for end-users to apply a patch, Compressed Builds are not recommended as the targets of patches.

Source Resolution for Web Builds

When the setup runs, it will not prompt for original source media. It will automatically locate the source media for the setup on the target system. If required web media blocks are missing, they will be downloaded automatically. No source media browser will be shown at any time, and the patch will be applied immediately.

Because this provides the easiest way for users to apply a patch onto, Web Builds are the recommended targets of patches.

Forced Setup Source Caching

The default setup source caching behavior for each build type as described above may be overriden when setting the build type of your setup project using the Always Cache Setup Sources check-box. Even for uncompressed or compressed builds, you may force setup source caching. Alternately, you may force setup source deletion for web builds. If setup sources are forcibly cached, patch source resolution will be automatic. If setup sources are forcibly deleted, patch source resolution will always need to be manually performed as described above, or from the command line as described below.

Source Resolution from the Command Line

To prevent the original source media browser window from being shown, if a particular folder contains the source files of the original setup, you may use command line parameters to point the setup program to that particular folder so as to automate the source resolution process for patching.

<setup.exe> /p=<path to original setup sources>\data

You may specify any accessible folder, including a network location. This especially makes locating sources for patches on corporate networks very convenient. Please remember to specify the data subfolder inside the original setup source folder. This subfolder exists as part of all InstallAware uncompressed builds.


Web Updates

Once you have distributed your application and have many live copies on the field, inevitably the time will come when you will need to issue updates. These updates may be minor improvements and bug fixes, best served as patches, or full blown major new versions, best served as upgrades.

InstallAware provides a very convenient and customizable mechanism that serves updates directly to end-user desktops, no matter what the size or content of the update. InstallAware implements this Web Update mechanism in its entirety using MSIcode, accessible directly in the script editor. While the pertinent sections of the IDE have been built around the default behavior of the Web Update system, and this document discusses that default functionality, remember that you can always custom tailor aspects of the system, minor or major, to suit your own needs - simply by editing the pre-built dialogs and scripts.

What's in an Update?

InstallAware defines an update as an executable file that is downloaded and run on the end-user system. An update could be a patch, or it could be a full new version. An update could be a setup that doesn't update application binaries at all, but just runs, for instance, a SQL script to refresh a database. An update could even be a document that is opened with the default application it has been associated on the end-user system!

The Update Information File

Updates are defined in Update Packs. An Update Pack consists of the name of the update, its long description, download URL, and other similar attributes. You may serve the same update packs to more than one version of your application. You choose which applications receive which update packs on the Versions page, where you associate particular versions of your application on the field with specific update packs.

Once this information has been provided in the InstallAware IDE, every time you build a setup, an update information file, called updates.ini, will be automatically created in your build folder. This regular INI-format file contains all the information on the various update packs and the application versions that receive them. A copy of this file is also available in the project folder, and may be edited directly. The IDE will display your changes when you manually edit the file.

How Do Updates Work?

The first step in enabling your application to receive updates is to check the Receive Application Updates box in the Project Properties page, and specify your update information URL in the Monitor URL field (this URL should serve the update information file mentioned above). The IDE then does the following:

  • Adds pre-built update dialogs to your setup project,
  • Adds the pre-built update script to your setup project,
  • Calls the pre-built update script from your main setup script.

You may, of course, customize both the pre-built dialogs and the update script using the Dialog Editor and the script editor. Nothing is hard coded, and even though the base dialogs and update script cover most usage scenarios and work out of the box, they are still fully extensible to suit your own requirements and update scenarios.

Web Update Modes

InstallAware provides three built-in web update modes as of version 15:

Automatic Web Updates

Your setup performs these additional tasks while installing your application:

  • Checks if any web updates are available.
  • If any web updates are found, they are all are downloaded with progress display visible to the end-user.
  • The end-user is not presented with a choice regarding which of the updates to install - all of them are installed.
  • The original setup does not install at all if any web updates are found.
  • The original setup does install only when web updates are unavailable.
  • A shortcut is created in the Start Menu program group for the application which enables on-demand update checking once setup has installed your application.
  • Running the web update shortcut presents the end-user with the opportunity to download and install any further updates, with the ability to choose the updates that are downloaded and installed.
  • When setup is running in maintenance mode (repair, change, or uninstall), even if any web updates are available, they will not be downloaded or installed - this helps your end-user uninstall your application without having to update it first.

Because of the above workflow, when you are designing your update packs for your various application versions under the automatic web update mode, it is recommended that you only serve the latest version full installer of your application for each of your old versions, and that you serve that installer in non-silent (interactive) installation mode. This ensures that any time any version of your setup is run, the latest version will dynamically download and execute interactively, as long as an Internet connection is available. The only possible exception to this rule could be if you wish to bundle one or more applications with your main application; in this case you would define additional update packs for the bundled applications and install them (possibly silently).

In the automatic web update mode, unless setup is running in maintenance mode, it will not keep a history of updates that were previously installed. This ensures that only the latest version of your application will be made available at all times.

Once your application has been installed and updates are checked for manually, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they already installed.

Manually Triggering Update Checks

To explicitly run setup in web update mode once your application has been installed, for instance in response to a menu item in your main application user interface, you may use the following command line:

<setup.exe> /update

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update check" mode.

Manual Web Updates

Your setup performs these additional tasks while installing your application:

  • A shortcut is created in the Start Menu program group for your application which enables on-demand update checking once setup has installed your application.
  • Running the web update shortcut presents the end-user with the opportunity to download and install any updates, with the ability to choose the updates that are downloaded and installed.

Since the above workflow allows end-users to choose which updates they download, you may elect to serve full version installers, patches, or any other custom executable/process/document as your updates when using manual web updates.

In the manual web update mode, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they had already installed.

Triggering Update Checks

To explicitly run the web update client, for instance in response to a menu item in your main application user interface, you may use the following command line:

<setup.exe> /update

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update check" mode.

Scheduled Web Updates

Your setup performs these additional tasks while installing your application:

  • During installation, an additional registry key is written to run setup once in "update scheduler" mode.
  • On the next logon of the user, setup runs in "update scheduler" mode. This mode allows the end-user to configure a schedule to check for updates online. The user can also elect to not receive updates at all. If the user does choose a schedule, the Windows Task Scheduler is used to create a new task that runs setup in "update" mode at the desired interval.
  • The Windows Task Scheduler starts setup in "update" mode at the scheduled time. Setup connects to the URL specified in the Monitor URL field of the Project Properties page to download the update information file.
  • If the file is successfully downloaded, setup continues running in "update" mode and first downloads, then installs the available updates. The user may be prompted during the process in accordance with the preferences set in the "update scheduler" mode.
  • Updates that have been previously installed for an application version are not installed again, even if the application version has not changed between updates.

Since the above workflow allows end-users to choose which updates they download, you may elect to serve full version installers, patches, or any other custom executable/process/document as your updates when using manual web updates.

In the scheduled web update mode, setup does keep a history of updates that were previously installed. This ensures that end-users are not offered to install updates again that they had already installed.

Re-Triggering Update Scheduling

Because end-users have only one opportunity to schedule web updates with the above workflow, and will not be presented with another opportunity should they cancel the scheduling at that first time; you may wish to manually launch setup in update scheduler mode once your application has been installed (for instance, from a menu item available in your primary application user interface).

To enter the "update scheduler" mode, you may use the following command line:

<setup.exe> /updatesetup

In the above example, setup.exe denotes the main setup executable. The pre-defined variable UNINSTALLLINK refers to the exact location of the setup executable and is available for use as soon as the application has been installed. It may be used to create custom shortcuts, or manually launch setup in the "update scheduler" mode.

Enabling Scheduled Web Updates with the Native Code Setup Engine

If you are using the Native Engine to install your application, you will need to explicitly enable the Native Engine installation mode in the update script by following the steps below:

  1. Switch to the MSIcode view.
  2. Switch to the Updates tab in the MSIcode editor. This tab displays your fully customizable web update script.
  3. Comment-in (enable) line number 8: Set Variable NATIVE_ENGINE to TRUE.
  4. Please keep in mind that the line number above may vary if you have customized your web update script.

Customizing the Web Update Script

You may fully customize the web update script (and dialogs) to inject your business logic - filtering updates that are served by your product editions, languages, subscription status, and more. Please keep the following in mind when editing the update script.

The following variables control some high level behavior in the update script:

  • UPDATE_DOWNLOAD: Set to TRUE to offer a list of updates that are available for download, set to FALSE to automatically download all available updates.
  • UPDATE_AUTO: Set to TRUE to automatically install updates, set to FALSE to offer a list of downloaded updates ready for installation.
  • UPDATE_LOG: Set to TRUE to filter out previously installed updates from the list of available updates (even if their installation failed or was cancelled), and to record the list of updates that were installed (even if their installation failed or was cancelled). Set to FALSE to always present all available updates, and to never record updates that were previously installed.

The compiler variable UPDATE_SCHEDULING conditionally compiles the update script according to the corresponding web update mode:

  • TRUE: Scheduled web update mode.
  • FALSE (or undefined): Manual web update mode.
  • THIRD: Automatic web update mode.


Change Setup Icon

You may customize the default setup icon that is used in several places throughout your setup:

  • Setup self extraction progress window
  • Setup self extractor program
  • Main setup program
  • Setup dialogs system menu
  • Taskbar program button
  • Add-Remove Programs applet

To customize the setup icon

  1. In the Project Options dialog (SHIFT+CTRL+F11), select the Add-Remove node beneath the Project node.
  2. Click the Load Icon button and choose your custom icon.

To revert to the default icon

  1. Remove the file icon.ico from your list of support files.


Change Your Setup Theme

If after creating your project you decide you wish to use another setup theme, change it using the following procedure:

  1. Display the Project Manager .
  2. Select the Dialogs node in the tree view.
  3. Right-click and choose Add Dialogs to Project.
  4. Check Add a Pre-Built, Themed Collection of Dialogs, and select the new theme from the drop down list.

Warning:

If you had customized any of the existing dialogs in your old theme, you will lose all those changes when the old dialogs are overwritten with the new ones from your changed theme.


Creating New Setup Themes

You may wish to customize existing setup dialogs to include your own corporate elements, and make them available for re-use in all your installation projects. The most efficient way of doing this would be by creating your own setup theme.

To create your own setup theme :

  1. Navigate to the InstallAware installation folder using your favorite file manager. Then navigate inside the Dialogs directory.
  2. Duplicate the folder containing the theme closest to the new theme you wish to create. For instance, if you wish to base your new theme on the Classic theme, make a copy of the Classic folder and give it a unique name, such as MyTheme.
  3. Start the Dialog Editor.
  4. Using the editor, open each dialog stored in the MyTheme folder, and customize all elements as necessary:
    • Be sure to preserve existing intra-dialog relations.
    • Also preserve pre-defined dialog behavior.
  5. After you have customized all dialogs, use your new theme as you would any other pre-defined theme.

Feel free to send us any interesting themes you have created. We will include them for download in our online theme gallery for everyone to download and use.

Warning:

Be sure to store a copy of your theme folder somewhere safe, so you can use it on other computers with InstallAware, or when you need to reinstall InstallAware on your own computer.


Customizing Dialog Bitmaps

If you wish to customize the standard elements of any setup dialog, including the bitmaps shown, simply edit your dialogs in the Dialog Editor and update the desired elements.

  1. Display the Project Manager.
  2. Double-click the dialog to edit, or select it and press enter.

Remember to save your changes before exiting the Dialog Editor. If you attempt to edit a new dialog while the old one is still showing, the editor will discard changes made to the old dialog (unless, of course, you had previously saved it).


Displaying a Splash Screen

To display a splash screen while the installation is initializing, simply create a .BMP file and add it to the setup. All bitmap types at all color resolutions are supported; however you may want to keep to 256 colors on your bitmap in consideration of older systems with graphics cards that cannot display higher resolutions.

  1. Name the bitmap file setup.bmp.
  2. Display the Project Manager.
  3. Add the bitmap to the project as support files.

If you later need to remove or update the splash screen, simply modify its file as a regular support file. The Project Manager will maintain a reference to your bitmap file in your project and the bitmap file will be placed in your project folder.


License and ReadMe Files

To display license and readme files in your setup dialogs, you need to add the files to your setup project. Rich text and plain text files may be used for displaying licensing and readme information.

  1. Name the license agreement file license.rtf or license.txt.
  2. Name the readme file readme.rtf or readme.txt.
  3. Display the Project Manager.
  4. Add the files to the project as support files.

If you later need to remove or update these files, simply modify them as regular support files. The Project Manager will maintain a reference to these files in your project and the files will be accessible in your project folder.


Using Interactive Progress Flash

You may use interactive Flash movies as part of your installation dialogs, and in particular inside a progress dialog, to educate and entertain your users while your product is installing. Flash movies provide an unprecedented rich medium for use as installation billboards, with no limits on your creativity.

Adding a Flash Control to a Dialog

In order to display interactive Flash movies in your dialogs, you first need to add a Flash control to your dialogs.

  1. Open the dialog in the Dialog Editor.
  2. Choose the Browser tab on the component palette.
  3. Select and add the FlashFrame control to your dialog.
  4. Double-click the new control to bring up the Define Interactive Characteristics window.
  5. Choose the Object Behavior tab, and under the Receives Information drop-down, select Installation Billboards.

Adding a Flash Movie to a Setup

After adding the Flash control to your setup dialogs, you will want to add the movie itself.

  1. Set the file name of the Flash movie to add as movie.swf.
  2. Display the Project Manager.
  3. Add the SWF file as a support file.

If you later need to remove or update your movie, simply modify it as a regular support file. The Project Manager will maintain a reference to this file in your project and the file itself will be accessible in your project folder.

Flash Runtime Deployment

To display Flash movies, the player runtime needs to be present on the end-user system. The moment a dialog containing the FlashFrame control is shown, InstallAware will automatically attempt to install the player runtime if it is not already available. If the installation fails, the dialog will not render the movie, but no setup error will occur - your installation will continue normally.

The runtime file that is used in this automated installation process is automatically added to your project as a support file under the name flash.ocx. This addition occurs moment you add a movie to your setup. You may replace the default runtime file with a newer/older version of the runtime. To do so, simply add the desired version of the runtime file as a support file under the name flash.ocx to your project. You may also delete the runtime file from the list of support files, however in this case if the end-user system lacks the runtime, none of your movies will render (although the setup itself will not be affected).


Using Interactive Progress HTML

If you were impressed by the interactive HTML content available on the InstallAware progress dialog, you will be pleased to know that you may include the same feature in your own setups. You just need to create your HTML content and the files to your project.

  1. Name the entry point for your progress HTML index.htm.
  2. Create any additional HTML files. The files may reference one another, and include links to graphics.
  3. Make sure none of the links on any of the pages has path specifiers - everything should work in a flat directory structure.
  4. Display the Project Manager.
  5. Add all the HTML files and required support files (such as .GIF and .JPEG files) to the project as support files.

If you later need to remove or update these files, simply modify them as regular support files. The Project Manager will maintain a reference to these files in your project and the files will be accessible in your project folder.

The native HTML viewer on the progress dialog does not require any runtime controls (such as the Internet Explorer control), offering maximum freedom and compatibility with all existing Windows versions. The viewer is also capable of parsing most HTML tags, supports page backgrounds, animated GIFs, page refreshes, external links to websites, and more.


Using Static Progress Billboards

While interactive HTML content is available on the InstallAware progress dialog, you may choose to take a more traditional route and instead display static billboards.

  1. Author an HTML file for each billboard to display:
    • Name the first file index.htm,
    • Add a META REFRESH tag to each HTML file, pointing it to the next file,
    • Display a billboard graphic (and other relevant information) in each HTML file.
  2. Make sure none of the links on any of the pages has path specifiers - everything should work in a flat directory structure.
  3. Display the Project Manager.
  4. Add all the HTML files and required support files (such as .GIF and .JPEG files) to the project as support files.

If you later need to remove or update these files, simply modify them as regular support files. The Project Manager will maintain a reference to these files in your project and the files will be accessible in your project folder.

The native HTML viewer on the progress dialog does not require any runtime controls (such as the Internet Explorer control), offering maximum freedom and compatibility with all existing Windows versions. The viewer is also capable of parsing most HTML tags, supports page backgrounds, animated GIFs, page refreshes, external links to websites, and more.


Testing Interactive Elements

While developing your setup, you may want to test the appearance of interactive progress elements, such as HTML files and Flash movies, exactly as they would appear on your progress dialogs during setup.

  1. Open your progress dialog in the Dialog Editor.
  2. Place the files belonging to your interactive progress elements inside the interop\templates folder of your InstallAware installation folder.
  3. Test your progress dialog.


Run Installed Application

After creating a new setup project using the Default Project type, wizards, or most of the other templates, if you wish to add support for running your installed application after a successful install, make the following changes in your setup script:

  1. Search for the text:
    TO-DO: Insert command that starts your application here
  2. Select the text and insert a Run Program command above it.
  3. Specify in the Run Program command the name and path to your application. For instance, if your application executable is called myapp.exe, specify the following Run Program command:
    $TARGETDIR$\myapp.exe


Creating a Start Menu Uninstall Entry

When an InstallAware setup finishes installing on the target system, it automatically adds an entry to the Control Panel Add-Remove Programs applet. However you may also wish to create a shortcut for maintenance/uninstallation directly on the start menu group for your application. InstallAware includes a convenience variable that holds the full path and file name of the maintenance setup program which you may use for this purpose. This variable is UNINSTALLLINK. Creating a shortcut that targets $UNINSTALLLINK$ will achieve your desired effect.


The Meaning of Product and Revision Codes

The product/revision codes specified on the project options dialog are used by Windows Installer to uniquely identify your installation. If you author two installations that use the same product and revision codes, Windows Installer will treat both as installations of the same product. Therefore, pay attention to the following:

  • For different products, always use different product and revision codes. Whenever you generate a new project, InstallAware will automatically generate a new product and revision code for you.
  • For different versions of the same product, including product updates, you may use identical product codes, however you must use a different revision code. Having identical product codes but different revision codes between installer packages indicates that one of the packages is an upgrade.


Disk Space Calculations

If your products installation is reporting estimated disk space requirements as 0 or inaccurately, you are not making proper use of the Get Component State command in your script. InstallAware requires this command be used at least once in your installation to be able to accurately predict target disk space requirements. Please see the command reference for more information.


Multiple Installations

If you re-run an installation after it has already installed on the target system, it will display a maintenance user interface, instead of an installation user interface. This is because Windows Installer detects that the product is already installed, and enters maintenance mode.

Unfortunately, there is no way to prevent this type of behavior in Windows Installer setups. You may however change the product and revision codes every time you change your product version to help users reinstall multiple versions of the same product, or upgrade over an older version.


Upgrade Installs

InstallAware has a facility to seamlessly upgrade your older product versions to newer ones. If you used the Default Project type, wizards, or most of the other templates to create your setup project, this behavior is already implemented for you. In general, the method used for old version detection and upgrades is as follows:

  • Both the old product to be upgraded and the new product which is the upgrade should have the same product code. However they should have different revision codes. Read more about these codes.
  • Provided the above condition is met, the NEEDSUPGRADE pre-defined script variable will be automatically set to TRUE if a previous version of the product is found, and FALSE if not.
  • Check this variable and use the (Un)Install MSI Setup command to automatically remove previous versions of your product, before allowing the main setup to begin.

Notes

  • You may use the (Un)Install MSI Setup command with both InstallAware and non-InstallAware setups.
  • If your InstallAware setup has custom uninstallation logic, try uninstalling it using the Run Program command and an uninstallation command line, assuring that your custom logic executes.


Uninstalling from the Command Line

You may silently remove InstallAware setups using setup command line parameters.

Silently Uninstalling

<setup.exe> /s MODIFY=FALSE REMOVE=TRUE UNINSTALL=YES

In the above example, setup.exe denotes the main setup executable.


Setup Commands Preceding Apply Uninstall

InstallAware, unlike most other installation authoring toolkits, offers a unified, single script which gives you complete control over the entire installation process, including the uninstallation. However, because of design limitations in Windows Installer, you need to refrain from using new Windows Installer commands before an Apply Uninstall command. Doing so can break the integrity of your setup database and cause uninstalls to fail.

This topic only applies to the Windows Installer engine and not the Native Engine. The precautions and workarounds described in this topic are not needed with the Native Engine.

The Install - Uninstall Cycle

The points below explain the design limitation in Windows Installer.

  • The first time you are installing, your script queues several Windows Installer commands as required by your application. These changes are then executed when the Apply Install command is called from your script. At that point, InstallAware invokes the Windows Installer service and completes the installation.
  • When the setup is run again (in maintenance mode), and a repair/modify action is chosen, your script again queues the pertaining Windows Installer commands, and then calls Apply Install once again to update the system. If the set of installed features changed between the original and maintenance installs, Windows Installer is intelligent enough to reflect those changes to the system: Windows Installer commands which do not execute as a result of changed feature sets are automatically undone (example: Install Files commands belonging to unselected features are undone, since those commands did not execute in this run).
  • To achieve the above flexibility, Windows Installer keeps its own internal record of which actions executed during the last run.
  • When Apply Uninstall is called, all the Windows Installer commands from the last run will be undone, effectively uninstalling the application.
  • If however, immediately before executing the Apply Uninstall command, new Windows Installer commands are queued, this will destroy Windows Installer's internal records of the last standing actions. The net result will be that all installed files and registry settings belonging to your application will be orphaned on the system, without actually being removed.

Workarounds

If you simply must use Windows Installer commands before uninstalling, you may do so by following the exact procedure below.

  • For your new commands to work as expected, you need to call Apply Install first.
  • Keep in mind this will undo actions which executed during the previous run, and may cause a premature removal of some files/registry entries.
  • After this step is complete, call Apply Uninstall normally to undo the changes you just made and remove all traces of your application from the system.

Keep in mind that you may use non-Windows Installer commands freely at any point in your script, including immediately above the Apply Uninstall command. The Call DLL Function command especially provides a lot of flexibility in being able to invoke virtually all of the Windows API directly from your setup.

New Windows Installer Commands May Not Be Necessary

Windows Installer already has mechanisms to work around this limitation. In particular, if you wish to delete files created by your application after it was installed, it may seem that new Delete Files commands are required right above the Apply Uninstall command. However this is not the case. The Delete Files command has an option which explicitly specifies when files are to be deleted - while installing, while uninstalling, or both.

To delete files created by your application after it was installed:

  • Call the Delete Files command as part of your main installation routine (the install/maintain block), and not the uninstallation routine.
  • In the options for the Delete Files command, indicate that the deletion is to occur during an uninstall.
  • Windows Installer adds this command to its internal record, and will remove the specified files when Apply Uninstall is called at a later time.

Unfortunately, Windows Installer does not provide a mechanism to remove registry keys that are not created explicity during the installation. However, InstallAware accomodates this need by providing a non-Windows Installer command to facilitate this task.

To delete registry keys created by your application after it was installed:

  • Call the Delete Registry command as part of your uninstallation routine.
  • This is not a Windows Installer command command, so it is safe to call right above the Apply Uninstall command.


Compress Better

InstallAware utilizes a very advanced form of LZMA compression, featuring Binary Call Jump converter algorithms that pre-process data to increase compressability before being fed to the actual LZMA algorithm. While LZMA with BCJ2 is optimized especially for program files and crunches data like no other algorithm available today, keep the following points in mind to obtain maximum compression:

  • Files that have been compressed before cannot be recompressed. For example, lets say the size of your uncompressed setup is 36 MB. Assume that when ZIPped, the setup size decreases to 11 MB, and when LZMAd instead, the setup size decreases to 4 MB. Now this might lead us to think that if we use LZMA on the 11 MB ZIP, we would gain an additional 7 MB. This is not the case. No matter how strong a compression algorithm is, it can never recompress files that have been already compressed.
  • Make sure your help files are not pre-compressed. Help compilers may produce compressed output.
  • Make sure your application executables are not pre-compressed. Software protection tools, alongside executable packers, may produce compressed output.
  • Make sure any other data files used by your application are not pre-compressed. For instance, do not compress database files used by your application.
  • If your setup includes MSM (merge module), MSI (installation databases), or EXE (stand-alone setup) files, chances are those files already contain compressed data streams inside them. Use the Setup Decompressor tool to decompress those compressed data streams before including the databases in your setup.
  • If some of your files must be compressed, use maximum compression on them. Remember, pre-compressed files - no matter how weakly they are originally compressed - can never be recompressed.
  • Encrypted files cannot be recompressed.

Notes

  • The compression example given above refers to the actual setup program of CompreXX. Feel free to download CompreXX and validate our findings for yourself.
  • Rest assured results with your own setups will also be equally remarkable.


Increasing Build Speeds

While you are testing and debugging your setups, you may find yourself frequently rebuilding your projects. Follow the guidelines below to shorten your code-build-test cycle:

  • Use the Uncompressed Directory Layout build mode while you are in development. Because no compression is involved in this build mode, it will provide the fastest build times.
  • If you must use one of the other build modes, change your compression settings to shorten the time it takes to compress your data. In the Build Settings dialog, move the compression slider all the way to the left, thus disabling compression and accelerating build times.
  • If you are using the Compressed Web-Based EXE build mode, you may further accelerate your build cycle by eliminating rebuilding web media blocks which have not changed since the last build. Enable the Skip on Build option in your Web Media Block commands which you wish to avoid rebuilding.


Encrypting Your Setups

InstallAware can encrypt setups you build using 256 bit strong AES encryption. The entire setup payload will be encrypted, including your setup and data files. Setup will not initialize unless the correct encryption password is provided. However, encryption only works with compressed build types, because the data has to be compacted into collections of archives that can be compressed.

Encrypt your setups by specifying a password in the build settings dialog.

Notes

  • If you want to encrypt your setups and still use no compression, consider using one of the compressed build types with the compression factor set to None.
  • Encryption provides a first line of defense by protecting your setups with a global password. You may still use InstallAware scripting to further authenticate your users once they have entered the main setup phase. For instance, you may authenticate users through an online web page to verify that they are running a legitimate, non-pirated copy of your product using the Download File command and the registration dialog. If you place your confidential product files inside web media blocks and use web builds, those portions of your setup will never be downloaded onto end-user systems until they have successfully passed the authentication checks performed in the setup script, providing an additional line of defense against software piracy.


Sharing Web Media Blocks

If you have web media blocks with identical file contents across multiple setups, such as web media blocks containing common setup pre-requisites, you may share them across your setups:

  • Make sure each web media block contains an identical collection of files.
  • Use the same Download URL in each Web Media Block command.

This way, you will have a single global copy of the web media block file online, instead of one copy for each setup project that uses it.


Debugging Recommendations

When debugging your setups, InstallAware recommends you work in the Uncompressed Build Mode. Compressed build modes take long amounts of time compressing your setup files every time you build, therefore slowing down the code-build-test cycle considerably. When your setup is stable, switch to the actual build mode that is suitable for your deployment requirements.

Notes

  • You may also debug compressed build modes, since setup operates slightly differently based on the build mode you are testing. However, save this option for use only when you are having trouble with compressed build modes that you cannot reproduce with the uncompressed build mode.
  • Skipping building web media blocks is another way to accelerate your build process when testing compressed, web deployed setups.


Compression Memory Requirements

The highly advanced compression technology used in InstallAware has very large memory requirements. When the compression slider is at the Best setting, you may need as much as 512 MB free physical memory for compression to complete. If you are getting errors during build that compression failed, install more physical memory on your development system, close running applications, or lower the compression ratio.

Notes

  • Compression memory requirements only apply when building your setups. Built setups, no matter how large or tightly compressed, work well with as little as 32 MB physical memory installed on the target system.


Building App-V Packages

InstallAware may build your setups as application virtualization packages targeting App-V, beginning with InstallAware version 2012.

The packages you create may be a hybrid collection of both 32 bit and 64 bit applications; where on 64 bit systems both the 32 bit and 64 bit applications will run, and on 32 bit systems, only the 32 bit applications will run.

Packages built are compatible with App-V client versions 4.6 and higher if any 64 bit and/or hybrid capabilities are used; packages which are 32 bit only are compatible with App-V client versions 4.5 and higher.

To start the Build App-V Package tool, on the Design tab, in the Tools group, click Virtualization, and choose Build App-V Package.

  1. Enter the full path to the InstallAware project to build as an App-V package in the Select the InstallAware project file field.
  2. Click the Convert button to begin the build process.
  3. In the next few moments, the conversion process merges all your setup scripts and parses project content.
  4. In the Select application(s) to publish dialog, check each entry-point application for the virtualized package. Applications not selected in this dialog may not be directly launched. You must select at least one entry-point application.
  5. Click the Next button to continue.
  6. In the Set App-V package parameters dialog, choose the detailed App-V package creation settings you desire (these settings are described in detail in the following sections).
  7. Click the Browse button to select an output folder for the App-V package to build in the Save converted package to field.
  8. Click Convert to begin the build process.
  9. The tool builds an App-V application virtualization package out of your InstallAware setup project.

The following considerations apply for the build process:

  • All files and registry keys you are installing as part of your existing setup will be built.
  • Since they are supported by App-V technology, shortcuts, environment variables, file types, and services will also be built.
  • The tool will intelligently parse file system and registry paths and attempt to replicate the exact structure found within your installation.
  • Where possible, script variables will be replaced with their literal values, and intelligently resolved to meaningful values.
  • Compiler variables will be substituted with their literal values as found in your InstallAware project file.
  • Conditional compilation (excluding parts of your scripts based on compiler variable values) is not supported.
  • All of your include scripts will be processed.
  • Any conditions on script execution will be ignored.

App-V Package Generation Parameters

Make App-V package compressed

Check this box to compress your App-V package using standard App-V compression.

Enhance virtual application's interaction with local applications

Check this box to improve the virtualization success rates of applications that may depend on existing COM objects on the physical system.

To completely isolate your application from the physical system, ensure this box is not checked. Some applications may require complete isolation for successful virtualization.

Create App-V package deployment MSI file in addition to other package files

Check this box to automatically create an MSI file which will create Start Menu shortcuts for the entry point applications contained inside your App-V package.

Relocate $TARGETDIR$ (full path) to App-V package virtual drive

Check this box to move the main application folder to the App-V package virtual drive, instead of a merged physical-virtual file system folder.

Checking this box may improve the virtualization success rates of applications that need to be completely isolated from the underlying physical system.

App-V Package Publishing Parameters

App-V package name

Indicates the name of your App-V package.

Streaming source to use

Provides the streaming source for your App-V package.

Save converted package to

Indicates the folder where the your App-V package will be built.

Building App-V Packages from the Command Line

You may also run the Build App-V Package tool from the command line. Every field of the tool has corresponding command line parameters.

The first command line parameter must always be the full path to the InstallAware project file to build (with .MPR file extension). If any of your command line parameters include spaces, remember to enclose them within double quote signs on the command line.

The remainder command line parameters may be provided in any order and are described below.

Parameter | Meaning
relocate | Relocates $TARGETDIR$ to App-V's virtual Q:\ drive.
compress | Compresses the App-V SFT package file.
createmsi | Builds an MSI deployment file along with other App-V package files.
localinteraction | Relaxes isolation of virtual environment for enhanced COM interop support.
name: | Indicates the name of the App-V package.
streamingsource: | Provides the streaming source of the App-V package.
publishapp: | Comma delimited list of executable file names (without paths) for entry-point applications. Required.
output: | App-V package build folder. The specified folder must already exist. Required.

If any parameters other than the first command line parameter are specified, the build will begin immediately and non-interactively, even in the case of build errors. This enables the tool to participate in unattended builds, possibly as part of a larger automated build process, such as batch files.

Examples:

ConvertToAppV.exe "C:\my installers\my setup.mpr"

In the above example, the tool will prepare to build the setup project at the location C:\my installers\my setup.mpr. Because no additional switches have been specified, the actual build will not begin until end-user interaction.

ConvertToAppV.exe "C:\my installers\my setup.mpr" /publishapp:mainapp.exe "/output:c:\my installers\app-v"

In the above example, the tool will immediately build the setup project at the location C:\my installers\my setup.mpr with a single entry point application mainapp.exe, and with the App-V build output placed in folder c:\my installers\app-v. Note that this folder must already exist for the build to succeed.

ConvertToAppV.exe "C:\my installers\my setup.mpr" /publishapp:mainapp.exe,toolapp.exe "/output:c:\my installers\app-v" /relocate /compress /createmsi "/name:Package Name" "/streamingsource:RTSPS://%SFT_SOFTGRIDSERVER%:322/"

In the above example, the tool will immediately build the setup project at the location C:\my installers\my setup.mpr with two published entry point applications mainapp.exe and toolapp.exe, with package name set to My Package, streaming server set to RTSPS://%SFT_SOFTGRIDSERVER%:322/, $TARGETDIR$ relocation for maximum compatibility, an additional MSI file for deployment, and with the compressed App-V build output placed in folder c:\my installers\app-v. Note that this folder must already exist for the build to succeed.

The tool returns the following codes to indicate success/failure:

  • 0: Process completed successfully
  • 1: Invalid or missing command line parameter(s)
  • 2: Error during process


Viewing App-V Packages

InstallAware versions beginning with version 2012 ship with an App-V Package Viewer that may be used to view App-V packages built with InstallAware's App-V Builder, or App-V packages coming from other sources.

The App-V Viewer, a special edition of Application Virtualization Explorer by Gridmetric, allows its users full visibility into the contents of any App-V package; including virtual application entrypoints, virtualized file resources, virtual registry and virtualized services. These resources may be examined for troubleshooting purposes and to better understand how the resulting virtual application package has been laid out - without ever needing to actually run it using an App-V Client.

Please note that if you need to modify the contents of your App-V packages, you may upgrade to Application Virtualization Explorer, which provides full read and write capabilities when working with all of your App-V packages.

To start the View App-V Package tool, from the InstallAware 2012 Start Menu group, select View App-V Package. Alternatively, you may view any App-V package directly from Windows Explorer by double-clicking the App-V package project file (the file with the.sprj extension).

To view the contents of an App-V package, use one of the following File menu options:

  • Load SFT file: Loads only the binary contents of the package, excluding all application entrypoints. Best used to view the files, registry entries, and virtual services contained inside the package.
  • Load App-V package: Loads the entire package, including all application entrypoints. Best used to view all aspects of the package.

After an App-V package has been loaded successfully, the following tabs are shown.

Package Configuration

This tab contains the following views, accessed by clicking or double-clicking their associated icons located in the lower-part of the tab.

Package settings

Shows the overall package configuration options which relate to naming, publishing, and virtual environment settings.

Customize MSI

Shows options which relate to the App-V package MSI file (if the App-V package does actually have an MSI file associated with it).

Published applications

Double-click the icon to access this view. Displays all published applications (application entry points) contained inside the package. Selecting an application entry point in this view shows settings related to that particular application; including naming, publishing, virtual environment settings, and scripting settings.

File associations

Double-click the icon to access this view. Displays all file-type associations contained inside the package. Selecting a file extension in this view shows settings related to that particular file extension; including naming, publishing, virtual environment settings, and scripting settings.

Files & Folders

This tab displays the internal directory structure of the virtual application package. All of the directories and files that make up the actual application(s) being virtualized are listed here. On the left-hand side of this tab, the directory structure of the package is displayed as a tree-view; allowing quick navigation to any desired virtual directory or file. On the right-hand side of this tab, the file and folder attributes of selected directory entries are displayed; including both standard file-system attributes as well as App-V specific virtualization attributes.

The App-V Client mounts this whole directory structure on the App-V virtual drive at the client machine. Any directories and files needing to be overlaid over actual physical partitions are mapped from underneath the VFS subdirectory (a subfolder located at the root of the package folder hierarchy). Resolved file path(s) for any such overlaid directory entries are shown next to the Virtualized as label on the right-hand side of this tab. By default an encoded (parametrized) file path is shown, but you may check the Resolve VFS targets option from the View menu to allow the decoding of variablized (parametrized) file paths into live physical folder paths (as would be valid on the machine where the package is being examined on).

In determining whether an overlaid virtualized directory (as found under the VFS path only) fully overrides the local one (i.e. no files or folders found on the physical system will be visible to the virtualized application), or is just merged (i.e. virtual files and/or folders not present physically are merged with the actual, physical folder contents as present on the local file system - with virtual elements taking precedence over physical elements in cases of collision), the icon for the virtual directory is indicative as follows: A grey folder with a blue symbol represents a merged directory, whereas a yellow folder with a blue symbol represents a fully overridden directory. Deleted files are also shown with their own symbol.

Virtual Registry

This tab displays the contents of the virtual registry contained inside the package, and functions much like Windows's own Registry Editor. The virtual registry is overlaid on top of the physical registry when a package is being run on an App-V Client, and virtualized application(s) are served a combined view of both of the physical and the virtual registries. To determine if a registry key contained inside the package fully overrides the local one (i.e. nothing from that key or underneath that key would be shown through from the physical registry), or is just merged (i.e. virtual registry values and/or extra keys not present locally would be merged with entries from the physical registry, with virtual values taking precedence in cases of collision), notice that the virtual registry key icons are visually different (and similarly for deleted keys, which are also displayed with their own particular icon).

Virtual Services

This view displays all virtualized services contained inside the package. App-V only supports virtual services in the manner wherein the service (set to automatic start) is started when the main virtualized application is launched through the application entry point, and then automatically stopped when the main virtualized application closes down.

Virtualized System View

This tab simulates how virtual applications inside the package would "see" the file system and the registry if running on the present machine.

Upgrading to Application Virtualization Explorer

While the App-V Viewer tool supports editing packages that you have opened for viewing, you cannot save your changes with this read-only edition. Please upgrade to Application Virtualization Explorer if you would like to be able to save changes you have made to your App-V packages. In addition to allowing saving changes made to your packages, with Application Virtualization Explorer you will also be able to:

  • Access package repository functionality for quick loading from a library of multiple App-V packages.
  • Manage AD group policy templates for centralized configuration of the Application Virtualization Explorer.
  • Inspect the App-V Client's cached virtual environment files for better package troubleshooting on a particular App-V Client instance.
  • Receive full support for Application Virtualization Explorer plug-in extensibility.


Export to Virtualization

To start the Export to Virtualization tool, on the Design tab, in the Tools group, click Virtualization, and choose Export to Virtualization.

This tool automatically converts your existing InstallAware setups into Application Virtualization projects that may be instantly re-built using InstallAware Virtualization, producing virtualized applications instead of setup files.

Virtualized applications are run directly without the need for pre-installation, also eliminating application deployment conflicts.

The following considerations apply for the conversion process:

  • All files and registry keys you are installing as part of your existing setup will be converted.
  • The tool will intelligently parse file system and registry paths and attempt to replicate the exact structure found within your installation.
  • Where possible, script variables will be replaced with their literal values. Variables that cannot be resolved to a meaningful value will be left as-is. You may touch up these values inside the InstallAware Virtualization IDE.
  • Elements that cannot be theoretically supported by application virtualization technology, such as services and application runtimes, will not be converted.
  • Compiler variables will be substituted with their literal values as found in your InstallAware project file.
  • Conditional compilation (excluding parts of your scripts based on compiler variable values) is not supported.
  • All of your include scripts will be processed.
  • Any conditions on script execution will be ignored.


Database Import Wizard

The Database Import Wizard opens a Windows Installer setup (MSI file) or merge module (MSM file) database. It inspects the contents of the database, extracts and/or copies files from inside the database and/or source media, and then emits a ready-to-build InstallAware setup, complete with a customizable script. The Database Import Wizard provides a very easy way to import existing Windows Installer databases into InstallAware.

Preparing to use the Database Import Wizard

Make sure you have the original setup database, along with any source media it requires for a complete installation, available at the time of import. Because the wizard copies files from source media to recreate the entire setup, it will require access to any external setup files as well, in addition to the original setup database.

Some setups are contained entirely within the setup database. In this case, external source media is not required.

Using the Database Import Wizard

To use the Database Import Wizard, follow the steps below:

  1. Open the New Project window in the InstallAware IDE, choose MSI/MSM Import Wizard. A new wizard window appears .
  2. Click Browse and choose the MSI or MSM database to import. Click Next to continue to the next step.
  3. Choose a name for the project. Also choose a project folder. The Database Import Wizard automatically suggests both based on the database file you have chosen. Click Next to continue to the next step.
  4. For some packages, you may need to choose the default destination directory of the package. If you are able to make a choice, do so. If not, accept the default selection. Click Next to continue to the next step.
  5. Review your settings. Click Back to change your selections. Click Next to continue to the next step.
  6. The database import process may take a while, depending on the source database structure, the number of source files, and the speed of your computer. You may minimize the wizard to the system tray while the import is in progress. You will be notified with an icon and popup balloon in the system tray when the import process is complete.
  7. Import is now complete. Check the Open project in the InstallAware IDE box to open and build the newly converted setup in InstallAware. If you choose to do so, your newly converted setup opens in a new InstallAware window.
  8. Click Back to import another database. Click Next to exit the wizard.

Working with Imported Databases

After you have imported a database, tune up the generated project.

  • Review product runtimes. Make sure the correct product runtimes are selected for installation.
  • The wizard creates a seperate InstallAware component for each feature in the database. Review each created component and make necessary adjustments. Some database features are meant for internal use only (and are not for the end user to manually select or remove during an installation).
  • Review the files that are installed by the new setup. If possible, consolidate individually specified files using wildcards. The wizard emits a different Install Files command for each file installed by the imported database. For databases installing thousands of files, this approach is not practical. In this case, it is best to revise the installation commands so the original database is mirrored correctly, but without seperately specifying each file. For instance, if the original database installs 1,000 files in a single folder, it is better to specify that folder using a wildcard in a single Install Files command, rather than using 1,000 seperate Install Files commands.
  • Custom actions are not converted by the wizard. You may want to use the PackageAware tool to capture changes carried out by custom actions, and add that logic to your imported setup.
  • Build your setup.
  • Test your setup to make sure it works correctly, and make changes as necessary.
  • You may modify any part of the setup project that is generated by the wizard to meet your deployment needs. In particular, if there are bits of code which you find useful, you may copy-paste them into your own setups and reuse them.

The Database Import Wizard performs intelligent scans and preserves as much of the original setup logic as possible. However not all information can always be successfully migrated. In this case, a process of trial and error usually yields the desired results.

Notes

  • While you may also use this wizard to import Windows Installer installations, the recommended way of executing Windows Installer installations as part of your setup is by using the (Un)Install MSI Package command. This command fully preserves the intended setup logic of the original setup author, and InstallAware will even display the native installation progress of the setup.
  • If you already have the sources of the setup project you are trying to import, you may directly convert the setup project into an InstallAware installation using the project converters.
  • The PackageAware tool takes a different approach to importing setups. It monitors the changes a setup makes to a system and converts that information into a ready to build project. PackageAware also works with any setup, and not just Windows Installer based installations.


PackageAware

PackageAware is an intelligent wizard that captures the changes a setup makes to a system. You may use PackageAware to monitor the results of any installation, and it will create a ready-to-use installation project that can be immediately built in InstallAware. PackageAware provides a very easy way to migrate legacy installations into Windows Installer, and InstallAware.

Preparing to use PackageAware

InstallAware recommends that you use clean-machines while capturing setups. A clean machine is a plain installation of Microsoft Windows with no other software installed (and ideally, no optional Windows components installed either). Clean machine captures are more efficient in setup repackaging because they more closely reflect the target systems your applications will be installed on. Also, they may already contain some of the files and settings that are being installed by the captured setup. When those files and settings are already present on the system, PackageAware will not see them as new additions, and therefore fail to detect all components that have been installed by the captured setup.

In addition, the usage of virtualization software such as EMC VMware or Microsoft Hyper-V is strongly recommended. Virtualization software enable developers to boot more than one operating system simultaneously from their desktop, easily passing files and data between one another. Using virtualization software during setup captures dramatically increases productivity.

Using PackageAware

To use PackageAware, follow the steps below.

Preparing to use PackageAware

  1. Prepare a clean machine, ideally in a virtualized environment, that you will be using while capturing your setup. You do not need to install InstallAware onto this clean machine.
  2. On the computer where you do have InstallAware installed, in the Start Menu group for InstallAware, click Setup Capture. Copy the file PackageAware.exe to your capture system.
  3. Double-click this file on your capture system. The PackageAware wizard launches.

When you have prepared to use PackageAware, select a capture mode.

Selecting a Capture Mode

Starting with InstallAware 15, PackageAware provides two different setup capture modes:

Direct Capture Mode

To immediately capture a setup on the clean machine, choose Capture an installation and click Next to continue.

This is the fastest setup capture method available and may be selected unless there is a specific reason not to.

Snapshot Mode

To create a snapshot based on the current state of the machine, choose Create a snapshot and click Next to continue.

The snapshot based approach enables you to compare any arbitrary two system states (including system states obtained on completely different operating systems and/or underlying hardware).

It may be desirable to use the snapshot based approach over the direct capture approach for a variety of reasons, including the ability to save captured system snapshots and compare any two arbitrary snapshots at any time.

Capturing an Installation

When you have selected your capture mode, continue with the steps below.

  1. If you would like to customize the file system and registry locations that are monitored by default, click the Edit Profiles button. You may customize all aspects of the capture and store them in custom profiles for future re-use via the Capture Profile drop-down menu.
  2. If you are capturing a 64 bit application, check the Scan in native 64 bit mode check-box. This option is only available when running PackageAware on 64 bit operating systems.
  3. Click Next to scan the host system for all existing files and registry data.
  4. While the scan is in progress, do not use the capture machine.
  5. When the scan is finished, if you are running PackageAware in the snapshot mode, click the Finish button and save your snapshot. This step does not apply when running PackageAware in direct capture mode.
  6. If you are running inside a virtualized environment, take a virtual machine snapshot (consult your virtualization product documentation for more information on how to take new snapshots). This way, you may skip the steps above the next time you are virtualizing an application, by starting from this snapshot which already has PackageAware running with the pre-install scan data already collected.
  7. Run the setup for the application you wish to capture. If you are capturing more than one setup, you may run all of them before returning to PackageAware. If one of the setups you ran requested a reboot, restart the capture machine as requested. Rebooting the capture machine, even if none of the captured setups requested it, is a recommended practice. PackageAware survives reboots and continues to collect data in direct capture mode. In snapshot mode, you may need to manually restart PackageAware.
  8. When you have finished making the changes to the capture machine (all setups and reboots finalized), click Next to scan the host system for all new files and registry data if you are running PackageAware in direct capture mode. If you are running PackageAware in snapshot mode instead, choose Create a snapshot and then click Next twice (ensure you choose the same capture profile you selected in step #1 above, if applicable).
  9. Again, do not use the capture machine while the comparison scan is in progress.
  10. When the scan is finished, if you are running PackageAware in the snapshot mode, click the Finish button and save your snapshot. Then, choose Compare two snapshots and click Next. Click the Browse button found next to the Snapshot 1 field, and select the snapshot you saved above in step #5. Click the Browse button found next to the Snapshot 2 field and select the snapshot you saved in the first part of step #10. Then click Next to compare your two selected snapshots. This step does not apply when running PackageAware in direct capture mode.
  11. To create a portable project, check the Create a portable project check-box. This option will copy all required application files into a subfolder of your project folder, replacing all absolute references to files on the capture machine with relative file references to files underneath your project folder. Therefore, when you move this project onto another system - even one that does not have the application to capture already installed - you will be able to rebuild the project successfully. However, since each application file has to be duplicated as part of project creation, this doubles disk space requirements and incurs a performance penalty during the file copy phase. If you are creating portable projects while running PackageAware in the snapshot mode, ensure that you are comparing the snapshots on the system where you obtained the second snapshot as specified in the Snapshot 2 field in step #10 above.
  12. Click Next to generate a ready-to-build InstallAware project from the captured setup. When you press the button, the wizard suggests a project name based on information it has already captured. Save the new project using the suggested name, or enter a custom name. You may save the project in any folder.
  13. If necessary, copy the captured project folder from your capture system onto your production system with InstallAware installed. Open the project in the InstallAware IDE. You are now ready to build an installer out of your captured setup.
  14. If you are running inside a virtualized environment, you may now want to revert to the virtual machine snapshot taken in step 6 above to capture another application.

When you are using the Create a portable project option, PackageAware may occasionally fail to copy files. This is generally a strong indication that some of the files PackageAware detected as a result of the setup capture process are not really a part of the application you were installing, but a part of Windows or another pre-existing application on the system, which changed the files during the capture process, thus misleading PackageAware into associating this updated file with the application you were installing. It is however also possible, especially if you launched the application after its installation, that the application itself is actually using the file and has locked it for access. In this scenario, PackageAware lists the first file name that is causing the issue, and offers you three options:

  • Yes (try again): Clicking this button will attempt to copy the inaccessible file again. You will be prompted again for each file that cannot be copied until the copy succeeds, including the first file that the issue occurs with. Choose this option if the application you are attempting to capture is running, but be sure to entirely shut down the application before clicking the button.
  • No (skip): Clicking this button will discard this file, and any future files that are unable to be copied. You will not be prompted on futher failures, and all failing files will be immediately skipped. Choose this option if the application you are attempting to capture is not running, and you suspect that a Windows component or another unrelated application coincidentally wrote to the file at the same time you were installing the capture application.
  • Cancel (abort): Clicking this button will abandon the entire setup capture process - you will need to re-start from scratch. Choose this option if you are unsure whether to choose Yes or No, and want to try again from the very beginning.

Working with Captured Setups

After you have captured a setup, tune up the generated project.

  • If you do not have InstallAware installed on the capture machine, remember to copy installation files from the capture machine to your development machine. The Create a portable project option in PackageAware helps you avoid manually having to copy files by pre-copying the files for you inside your project folder at project creation time.
  • If you have switched machines after the capture process, the Refactor Paths tool helps you fix up references to directories. For instance, you may use this tool to update folders referring to locations on the capture system to their new locations on your development system.
  • Review the list of captured files, shortcuts, and registry keys to make sure they are pertinent to the setup you captured.
  • PackageAware may occasionally capture files and registry keys that were not actually installed by the setup you were monitoring. Such files may have been changed by other processes and services that were running on the capture machine at the time of the capture, leading PackageAware to believe they were put in place by the setup you were running. If you find references to such unrelated files and registry keys, delete them from your setup project.
  • Build your setup. If you get build errors regarding inaccessible files, make sure no application is using them (such as the application your captured setup may have installed). If you are still getting build errors, remove those inaccessible files from your setup and try again - they are most likely files that were not part of your captured install.
  • Test your setup to make sure it works correctly, and make changes as necessary.
  • You may modify any part of the setup project that is generated by PackageAware to meet your deployment needs.

PackageAware performs intelligent scans and preserves as much of the original setup logic as possible, such as locations of key installation folders, shortcuts, and so on. Typically you will not need to manually edit the generated setup project.

Notes

  • While you may also use this wizard to capture Windows Installer installations, the recommended way of executing Windows Installer installations as part of your setup is by using the (Un)Install MSI Package command. This command fully preserves the intended setup logic of the original setup author, and InstallAware will even display the native installation progress of the setup.
  • If you already have the sources of the setup project you are trying to import, you may directly convert the setup project into an InstallAware installation using the project converters.
  • If you are importing a Windows Installer setup, the Database Import Wizard tool may be used to directly convert Windows Installer databases into InstallAware setup scripts.


Refactor Paths

The Refactor Paths tool helps you stay on top of the changing folder structures of your application. This tool investigates your setup commands for embedded path values. It parses all the paths used by your setup and displays the common locations in an Analysis view. You may then update your paths with new values in one pass.

  1. On the Project tab, in the Manage group, click File Paths.
  2. Review the Analysis listing, which displays each path that has been found to be in use by your setup.
  3. If you would like to update a path, first click the path to update from the Analysis listing. Then type in the new path into the New Path field, or click Browse to visually locate the new path. Remember to click Replace and finalize your new path selection.
  4. If you would like to prevent updating a path that is displayed, click the path from the Analysis listing, then click Delete. Note that this procedure does not delete paths from your setup script - it simply removes them from the Analysis listing of the Refactor Paths tool.
  5. When you are ready to apply changes to your setup script, click OK. None of your changes are actually applied to the setup script until you click OK. If you would like to exit the tool without making any changes, click Cancel.

Notes

  • This tool can also update URL (Internet) and UNC (network) paths used in your setup script.


Dialog Editor

The InstallAware Dialog Editor is a very powerful tool that you may use to customize every aspect of your installation experience, including transparent windows, alpha blending, HTML and Flash controls, Glass regions, and many more.

For more information:

  • Starting the Dialog Editor
  • Using the Dialog Editor
  • Dialog Controls
  • Intra-Dialog Relations
  • Dialog Behavior
  • Passing Variables
  • Building Aero Glass Dialogs


Localization Wizard

The Localization Wizard helps you localize your setup for multiple languages. You may also use the wizard to create multi-lingual setups capable of supporting multiple languages at runtime. To display the Localization Wizard, on the Design tab, in the Tools group, click Localize. The localization process flows as described below:

  1. Implement your setup using the InstallAware IDE.
  2. When your setup is ready to be localized, extract strings from your setup using the wizard.
  3. The wizard produces an output folder that may be sent to any third party translation office. The output folder contains localization text files for each language, along with an executable tool that translators can use to visually localize your setup. Send this output folder to your translators and have them run the executable tool to translate the setup.
  4. The wizard can also translate InstallAware generated strings into 35 languages, automatically. Once you have created your output folder, you may simply feed the wizard this very folder to perform automatic localizations without any manual translation effort. Even if you have custom strings in your setup projects, the automatic localization step will save you time and money as you will only need to get your own custom strings localized. Just let the wizard automatically translate all project strings before sending your output folder to the translation office.
  5. When you receive the translated files, or after having performed an automatic localization, run the wizard again, and import the localized strings back into your project. You may import any number of localized languages that you wish to make available with your setup at runtime.
  6. Run the localization tool for shared strings that are used by all InstallAware setups. Note that when you use the wizard to automatically translate InstallAware generated strings, all shared strings are also automatically localized. You may still review and customize these translations by running the localization tool for shared strings, of course.
  7. If your setup uses other localizable resources, such as readme and license files, add them to your setup project as support files (also called creatives in the visual view of the InstallAware IDE).
  8. Choose the default language for your setup in the Project Settings window, and optionally enable a language selector that can be shown when setup is initializing.
  9. If you wish to switch between languages using your setup script, override the value of the $LANGUAGE$ variable.

Extracting Strings

To extract strings from your setup project, follow the steps described below:

  1. Load your project in the InstallAware IDE.
  2. To display the Localization Wizard, on the Design tab, in the Tools group, click Localize.
  3. Choose the Export Strings from Project to Translator option, and click Next.
  4. Click Browse and choose the target folder that is to receive the extracted strings, and the accompanying translator tool. It is recommended that you choose an empty folder, so you may send the contents of this entire folder to your localization team. If you wish to create a new folder, simply type in a path that includes the new folder. Click Next when you are ready to extract the strings.
  5. The Localization Wizard scans your project script and dialogs, and extracts localizable strings for you automatically. Wait for the process to complete.
  6. Click the Start Tool button to start the visual localization tool, or click the Translate tool to have the wizard automatically translate extracted strings. You may also send the entire contents of your target folder to your localization team and have them perform the translations - in this case, click Next to dismiss the wizard.
  7. Move to the automatic localization step to automatically localize InstallAware generated strings. Move to the import step to import automatically or manually localized setup strings back into your project.

Automatically Localizing Strings

To automatically translate strings extracted from your setup project, follow the steps described below:

  1. Load your project in the InstallAware IDE.
  2. To display the Localization Wizard, on the Design tab, in the Tools group, click Localize.
  3. Choose the Translate InstallAware Generated Strings option, and click Next.
  4. Click Browse and choose the target folder containing the exported setup strings. Click Next when you are ready to translate the strings. Even if you have manually translated part or all of your exported setup strings, the wizard can still automatically translate any un-localized InstallAware generated strings it still finds in the export location.
  5. Check each language you wish to automatically translate. You must check at least one language. Click Next when you are ready to translate. The Localization Wizard will automatically translate InstallAware generated setup strings found in your export folder into all selected languages. As part of this process, setup strings shared by all InstallAware setup projects will also be automatically translated. Wait for the process to complete.
  6. Click the Import button to immediately import the automatically translated setup strings back into your project. You may also still send the export folder to your translation team for review, or if you have any additional strings that still need to be localized. Click Next to dismiss the wizard.
  7. Move to the import step when you have received the localized strings, or are satisfied with the automatic translations as-is.

Importing Strings

To import automatically and/or manually localized strings back into your setup project, follow the steps described below:

  1. Load your project in the InstallAware IDE.
  2. To display the Localization Wizard, on the Design tab, in the Tools group, click Localize.
  3. Choose the Import Strings from Translator to Project option, and click Next.
  4. Click Browse and choose the folder that contains the localized strings as provided by your translation team, and/or as automatically translated by the wizard.
  5. Check each language you wish to import. You must check at least one language. Checking more than one language makes your setups multi-lingual, capable of switching between languages at runtime. Click Next when you are ready to import.
  6. The wizard imports the chosen languages into your setup project.
  7. Click the Edit Installer Messages button to localize strings that are shared by all InstallAware setup projects, or click Next to dismiss the wizard. If you automatically localized setup strings using the wizard, shared strings are also automatically translated - however, you may still review and edit these translations.

Localizing Shared Messages

Some installer messages are shared across all InstallAware projects. To localize these messages:

  • Click the Edit Installer Messages button on the last page of the import process to start the visual localization tool for the shared messages.
  • Run the mTranslator.exe binary found in the trans subfolder of your InstallAware installation folder on your system.
  • Send the entire contents of the trans subfolder to an external translation office. When you have received the translated contents of this folder, simply overwrite the old files in the folder with their new copies.

Please note that using the wizard to perform automatic translations will also automatically translate all shared setup strings - however, you may still manually review and edit these automatic translations using the same process as described above.

Using Localized Resources

If your setup displays a readme/license agreement file, or interactive HTML/Flash billboards, you may also localize these items. Simply open the files in their native editor and localize the content normally. Then, save the files using the following naming convention:

  • For readme files, use the form readme.<Language>.rtf or readme.<Language>.txt
  • For license files, use the form license.<Language>.rtf or license.<Language>.txt
  • For HTML index files, use the form index.<Language>.htm
  • For Flash files, use the form movie.<Language>.swf

In both examples above, remember to subsitute the actual language you are using for <Language>. For instance, save a German readme file as readme.German.txt (without using the square brackets).

When you have created your localized resources, add them to your project as support files.

If the localized resource file for the active setup language cannot be found at runtime, the installer will display the generic resource file (readme.txt, readme.rtf, license.txt, license.rtf, index.htm, or movie.swf).

Switching Between Languages

The Default Language field in the Project Settings window determines the base language that your setup is created with. Shared installer messages and Windows Installer progress text will be displayed using the default setup language.

If you have localized your setup using the localization procedure, you may also display a language selector by checking the Display Language Selector field in the Project Settings window. When checked, your setup will display a list of all available localizations upon initialization. The language for the target system will be pre-selected if it has been localized for.

You may also use your script to override the language that is being used at runtime, as an alternative or complement to using the setup initialization language selector. To do so, simply use a Set Variable command in your script and enter a new value for the pre-defined variable $LANGUAGE$. For instance, to switch the setup language to German at runtime, use the Set Variable command and set the $LANGUAGE$ variable to German. The Project Settings window lists the English names that must be used to identify languages at runtime under the Default Language field.

Based on the extent of languages supported in your setup, you may also need to change dialog font character sets. To do so, use the Set Variable command and the $CHARSET_OVERRIDE$ variable to set your desired character set, without having to manually modify dialogs.

Redistributing the Visual Localization Tool

The visual localization tool that is available in the trans subfolder of your InstallAware installation folder may be freely redistributed, without royalties, to any third party. The Localization Wizard also uses the same tool when it extracts strings to a folder of your choosing, and again, the tool is freely redistributable. Any third party may translate your setup for you without having access to your setup project or the InstallAware IDE using the visual localization tool.

Additionally, since all setup strings are stored inside plain text files, you may open and edit these files using any plain text editor such as Notepad - you are not limited to using only the visual localization tool. Ensure that you do not save files after editing as Unicode, but always use the ANSI format. To maintain compatibility with all Windows versions, including downlevel support all the way down to Windows 95 Gold, InstallAware uses ANSI strings.

Making Updates to Localizations

If you run the Localization Wizard after having already localized your installation, as in when localizing new elements you have since added to your setup, you can have the wizard offer to preserve your existing translations. Just keep your old localization export folder, and when exporting strings, choose that old folder. The wizard will add only new script commands and dialog elements to the old localization export folder, and preserve your existing translations. Thus, your localization team can focus on translating only the newly added elements, with their old translations kept intact.

Automatic translations may also be performed after any time you have updated your setup project using the Localization Wizard as described above.


Translator

The Translator tool helps you localize global strings that are shared across all setups. The same binary is also used when localizing specific projects using the Localization Wizard and is redistributable.

  1. On the Design tab, in the Tools group, click Shared Strings.
  2. The InstallAware Translator opens. Use the tool to visually translate global setup strings.


Database Validator

To start the Database Validator, on the Design tab, in the Tools group, click ICE Checks. Use the validator to make sure your setup script compiles into a valid MSI database, capable of receiving the Designed for Windows logo certification.

  1. Choose the validations to run under the Validation Suite field.
  2. If you would like to see warnings, check the Display Warnings field. Note that warnings do not impair your ability to receive logo certification.
  3. Click Validate to begin the validation progress.
  4. The results of the validation are shown. If you would like to save the results in a text file, right-click the results area and choose Show Log. If the results area does not contain any errors, your setup has passed validation.


Code Signing

To start Code Signing, on the Design tab, in the Tools group, click Code Sign. Use the code sign tool to manually signcode your executables and libraries using authenticode technology.

  1. Check to make sure you have already built your setup, and have obtained the necessary code signing certificates from code signing authorities. An Internet connection is required if you wish to time-stamp your signature.
  2. Fill in the necessary fields for your product, and choose your setup and certificate files.
  3. Click Sign to code sign your setup.
  4. Click Test to verify your code signed setup has been signed and is working properly. A testing dialog appears with your authenticity certificate.


Group Policy Wizard

To create setups that work with Group Policy / Active Directory deployment, on the Design tab, in the Tools group, click Group Policy. This wizard creates a single MSI file that may be used in corporate deployment scenarios.

  1. Enter the full path to your already built setup project in the InstallAware Setup to Package into Single MSI field. Note that the wizard works only with compressed setups (web deployed or single file compressed setups, as well as patches).
  2. If there are any command line parameters you wish to pass to your setup, enter them in the Command Line Parameters field. Note that the single MSI file will automatically pass in the necessary command line parameters for silent installations and uninstallations where applicable, to facilitate seamless operation with Group Policy deployment. If there are any additional parameters to pass, you may enter them here. The parameters entered in this field are recorded into the CMDLINE public MSI property of the new single MSI file, located inside the Property table. Before Group Policy deployment, editing the Property table using MSI transforms or a direct MSI table editor to change the value of the CMDLINE property is allowed. In this way, a custom command line may be used for different deployment scenarios.
  3. In the Output for Single File MSI field, enter the full path and file name of your new, single MSI file that will be created by the wizard. The folder specified for the MSI file must already exist.
  4. In the Group Policy Display Name field, enter the name of your product as you wish for it to appear in the managed installation interface.
  5. In the Group Policy Display Version field, enter the name of your product as you wish for it to appear in the managed installation interface.
  6. Click OK to create your single MSI installer, and deploy your setup using Active Directory.

Using the Group Policy Wizard from the Command Line

You may also run the Group Policy Wizard from the command line. The wizard requires exactly five command line parameters in the correct order. The first parameter is the setup to package. The second parameter is the command line parameters to pass to the install. The third parameter is the output MSI file. The fourth parameter is the display name, and the last parameter is the display version. If you do not wish to pass a particular command line parameter to your setup, use a space wrapped in double quote signs. If your paths include spaces, also remember to enclose them in double quote signs on the command line.

pgplwiz.exe "C:\My Project\Release\Web\My Project.exe" " " "C:\My Project.msi" "My Project" "1.0"

In the above example, the wizard will wrap the installer at the location C:\My Project\Release\Web\My Project.exe inside the file C:\My Project.msi and run it without command line parameters.

pgplwiz.exe "C:\My Project\Release\Web\My Project.exe" "/s" "C:\Temp\setup.msi" "Setup" "2.0"

In the above example, the wizard will wrap the installer at the location C:\My Project\Release\Web\My Project.exe inside the file C:\Temp\setup.msi and run it silently.

By using the Group Policy Wizard from the command line, you will enable it to participate in unattended builds. When run from the command line, the wizard does not display any prompts or require any user interaction.

The wizard returns the following codes to indicate success/failure:

  • 0: Process completed successfully
  • 1: Error during process

Notes

  • InstallAware recommends you use web builds for all kinds of corporate deployment, including Group Policy / Active Directory deployment. Advertised installations and application self-repair work best with web builds, because web builds cache installation content on the local system, and do not prompt for setup sources. Patching setups later also works best with web builds, where patch source resolution is automatic.
  • Web builds also provide an additional line of defense against software theft and piracy. By placing your application content inside web media blocks, and putting the web media block files on your corporate network, you render your setups void when running outside the corporate network, since they will attempt to download web media blocks from the corporate network, and fail when setup is running outside of it.
  • Read the $GPOPATH$ variable inside your script to determine if Group Policy deployment is being used. When this pre-defined variable is empty, Group Policy deployment is not being used. When this variable is not empty, Group Policy deployment is being used, and the variable contains the full path of the folder containing the single file MSI package. This path information may then be used to read additional configuration settings from that distribution folder.


Setup Decompressor

To start the Setup Decompressor, on the Design tab, in the Tools group, click Decompress. Use the setup decompressor tool to increase the compressability of MSI, MSP, and EXE files included in your InstallAware setups:

  1. Click Browse and locate the original MSI, MSP, or EXE file you wish to make more compressible.
  2. Check Backup Original File to save a backup of the original file. Making a backup is strongly recommended as the process makes irreversible changes to the original file.
  3. Click Decompress and wait for processing to complete.
  4. Test the new resulting setup to make sure it works as intended.
  5. Add the new file to your setup project. InstallAware can now utilize its superior compression levels to reduce your package size even further.

Because pre-compressed data cannot be recompressed, even using superior compression algorithms, the above procedure is necessary to assure that your setups which contain pre-compressed data streams are recompressible.

Creating Independent Packages

If you wish to utilize InstallAware's superior compression levels in an existing setup, without adding it to an InstallAware project (or creating a new InstallAware project for it), check the Recompress with InstallAware Wrapper check-box. In addition to decompressing the original setup, this will recompress it with advanced compression technology, and add a self extracting wrapper to the strongly compressed file. The resulting file can be run independently and launch the original installation.

Supported Package Types

Most Microsoft packages are supported by the Setup Decompressor tool. Virtually all Windows Installer packages are supported. Packages created by third party installation technologies not targeting Windows Installer may not be supported.

If a supported package is contained inside an outer "shell", the outer shell may not be recognized by the tool. In most instances, the outer shell extracts the embedded Windows Installer packages, which are recognized, into temporary locations. Two such typical locations are:

<system temporary folder>

<windows folder>\Downloaded Installations

You may try launching the outer "shell", wait until it completes extraction of the embedded files, then review the above locations to find the extracted packages, which will most likely be recognized and processed by this tool.


Dialog Batch Updater

To start the Form Batch Update Tool, in the Start menu, in the InstallAware group, expand InstallAware Tools and select Dialog Batch Updater. Use the dialog batch updater to make modifications to multiple dialogs in a single pass:

  • Change the character set used by fonts in the dialogs.
  • Replace older HTML controls with the new HTML control (only if you are upgrading a project created using a version of InstallAware older than InstallAware 2005).


Building from the Command Line

InstallAware includes a command line build utility which you may use in batch files, automated build processes, or just plain from the command line. The utility is invoked as follows:

miabuild.exe <projectfile> [/o=<outputfolder>] [/b=<buildtype>] [/r]
             [+qf | -qf] [+qr | -qr] [+qi | -qi] [+qib | -qib]
             [/p=<password>] [/l=<language>] [/pr=<patch reference>]
             [COMPILERVAR1=VALUE1 ... COMPILERVARN=VALUEN]

<projectfile>
        Full/partial path to the .MPR project file
/o
        Optional parameter, full/partial path to custom build output folder
/b
        Optional parameter, override default build type
        0: Uncompressed directory layout
        1: Compressed Single Self Installing EXE
        2: Compressed Web-Based EXE
        3: Patch
/r
        Optional parameter, indicates that a new revision code should be used for this build
qf
        Optional parameter, enables or disables MSI file component optimization (runtime performance)
qr
        Optional parameter, enables or disables MSI registry component optimization (runtime performance)
qi
        Optional parameter, enables or disables unstable MSIcode statement ID generation (build performance)
qib
        Optional parameter, enables or disables partially stable MSIcode statement ID generation (blend)
/p
        Optional parameter, specifies the 256 bit AES encryption password to be used for this build
/l
        Optional parameter, specifies the default installer language to be used for this build
/pr
        Optional parameter, adds a patch reference to this build (may be specified more than once)
[COMPILERVARN=VALUEN]
        Optional parameter, compiler variable-value pairs for conditional compilation

The command line build utility returns the following codes to indicate success/failure:

  • 0: Build completed successfully
  • 1: Error during build, or user cancelled build
  • 2: Invalid command line parameters
  • 3: Unhandled fatal exception during build

Notes

  • The command line build tool is not available with the InstallAware Express edition.
  • The command line build tool is not included in a minimum installation of InstallAware.
  • If you are installing the command line build tool without the main InstallAware IDE, keep in mind that you still have to install all required application runtimes and plug-ins that are required by your build, otherwise your builds will fail.


InstallAware Inline Update

InstallAware Inline Update is a command line utility which may be used to issue inline updates to large monolithic or web deployed setups over low bandwidth connections.

While the InstallAware platform permits creation of both binary differential patches and unlimited web updates, as well as precise targeting of updates for each of your product versions and editions; it may also be necessary for you to issue full version updates (inline updates) for your main application downloads.

The utility is invoked as follows:

miaiu.exe [binaryfile] [!es | !et | !ec | !md | !us]
          [/i=<indexfile>] [/if=<targetinputfolder>]
          [/o=<outputfolder>] [/p=<password>] [/v=<version>]

<binaryfile>
     Full/partial path to built setup executable to update
es
     Extract files from source setup, must pass setup as first parameter
et
     Create delta from target setup, must pass setup as first parameter
ec
     Create delta from comparison of previously indexed setups
md
     Merge delta from input folder into output folder
us
     Update setup by rebuilding files in merged output folder
/v
     New version number to inject when updating setup
/i
     Index file from source setup (required for !et and !ec)
/if
     Input folder from target setup (required for !ec and !md)
/o
     Output folder for operation (always required)
/p
     Password for operation (required for encrypted setups)

The inline update utility returns the following codes to indicate success/failure:

  • 0: Operation completed successfully
  • 2: Invalid command line parameters
  • 3: Unhandled fatal exception during operation

Inline Update Workflow

There are three major steps to issuing an inline update.

Before using this utility, ensure that you have built both your old and new setup versions normally using the InstallAware platform.

Be careful not to mix setups built with different source layouts and/or source caching options when updating inline.

1. Extracting Old (and New) Version Setup Source(s)

First, extract the files found in both your old and new setup versions. The source extraction process calculates MD5 checksums for each file found inside each setup package, which is later used in determining the files that need to be updated inline.

Your old and new setup versions may reside on physically different locations - in fact, if you are finding yourself having to issue remote inline updates, this is most likely the case.

To extract the sources of any setup, use a command line similar to the following:

miaiu.exe c:\setups\old.exe "/o=d:\extracted old setup" "/p=my old password" !es

You may use the !es flag to extract both old and new version setups. You do not need to specify a password unless the setup to extract has been encrypted.

Once extraction is complete, an index file containing MD5 checksums for the entire package will be found at the output folder location, named miaiu.txt. You will need to use this file in the following steps.

Ensure to also preserve the entire contents of the folder where the old setup has been extracted into, as the delta from the new setup will be merged into this folder in the following steps.

2. Calculating the Version Delta

Assuming the old and new setup sources are at physically different locations, first download the index file named miaiu.txt generated in step #1 above to the computer where the new setup is located. The index file is plain text and highly compressible, making its transmission over low bandwidth connections very easy.

Then, if you previously extracted both the old and new version setup sources using the !es flag, use a command line similar to the following to directly calculate the version delta using the !ec flag:

miaiu.exe "/i=d:\extracted old setup\miaiu.txt" "/if=d:\extracted new setup" "/o=d:\calculated delta" !ec

Or, you may combine the source extraction for the target setup step and the delta generation step into one command line using the !et flag:

miaiu.exe c:\setups\new.exe "/o=d:\extracted new setup" "/p=my new password" "/i=d:\extracted old setup\miaiu.txt" !et

Once the delta has been calculated, all updated files will be copied into the output folder as specified on either command line.

If the delta contains any files which have not actually been modified in between the old and new setup versions, ensure that you are not mixing setups built with different source layouts and/or source caching options.

3. Integrating the Version Delta and Repackaging

The last step is to actually merge the delta with the old version of the setup, and repackage the output.

Assuming the old and new setup sources are at physically different locations, first compress the delta folder (located inside the output folder specified in step #2 above), together with the list of files to be merged (miaiu-copy.txt) and the list of files to be deleted (miaiu-delete.txt) from the old setup version sources.

This compressed data is all you need to upload to the computer containing the old setup version. After the upload is complete, extract the compressed data - you are now ready to merge the changes into the old setup sources (previously extracted in step #1 above):

miaiu.exe "/if=d:\calculated delta" "/o=d:\extracted old setup" !md

Ensure that the folder specified as the target setup input folder contains both the file lists (miaiu-copy.txt and miaiu-delete.txt) at the root of the specified folder, and the delta subfolder as the immediate subfolder of the specified folder (as created in step #2 above).

Finally, re-compress the merged setup sources to finish the inline update. You may optionally specify a file version number to inject into the newly built setup, as well as an encryption password:

miaiu.exe "/o=d:\extracted old setup" /v=1.1 "/p=my new password" !us

Congratulations! You have now completed the inline update process. You will find the inline updated setup files inside the root of the specified output folder.

Notes

  • The inline update tool is not available with the InstallAware Express or Developer editions.
  • The inline update tool is not included in a minimum installation of InstallAware.


Quick Start Wizard

The Quick Start Wizard offers the fastest way to start your new installation projects. To display the wizard:

  1. Save any changes you have made to the installation open in the IDE.
  2. On the Project tab, in the New group, click Quick Start.
  3. Double-click the Quick Start icon.

Welcome Page

Click the Next button to continue through the welcome page.

Product and Company Name

Enter the name of your product and its manufacturer. You may later change this information in the Project Options window of the IDE, or the Project Properties design view.

Application Folder

Choose the folder where your application currently exists on your local hard disk. You may type in the folder path using the keyboard, or click the Browse button to visually select the folder. The folder you specify in this step will be scanned for files, including any files found inside subfolders. All found files will be added to your setup project, exactly replicating the folder structures existing on your local hard disk. When setup is run on an end-user system, all these files and folders will be re-created exactly as found on your hard disk.

You may change this structure in the Files design view, or by using the Install Files, Copy/Move Local Files, and Create Folder functions in the MSIcode script editor. Note that folders do not need to be explicitly created in MSIcode, as the Install Files function creates them automatically if needed.

Dynamic Folder

If the folder you choose changes frequently, and you would like InstallAware to automatically pick up these changes for you every time you build your setup project, check this box. Otherwise, clear this box. When cleared, InstallAware will emit a separate Install Files command for each file found. When checked, InstallAware will emit a single Install Files command for the parent folder, using the wildcard pattern *.*, and subfolder inclusion at build time.

Application Shortcuts

Once you have chosen your application folder, InstallAware presents a list of all executable files found in that folder. You may then create shortcuts for each of those executables in a variety of locations on the end-user's system. Simply click each file to create a shortcut for, and then check some or all of the Start Menu, Desktop, and Quick Launch Bar check-boxes to create shortcuts for that file at those respective locations on the target system. You may choose any combination of shortcut locations for any number of files on this page.

You may edit your shortcuts in the Shortcuts design view, or by using the Create Shortcut and Advertised Shortcut functions in the MSIcode script editor.

Application File Associations

If your application has its own file type, which it is designed to open, edit, and save, you may create a file association between that file type and your application in Windows.

You may add more file types or make changes to existing ones in the File Associations design view, or by using the Create File Type and Advertised File Type functions in the MSIcode script editor.

File type extension

Type in the file extension that your application uses for its custom file type. This is typically a three letter extension. You do not need to specify a leading period before your extension.

Open files of this type using program

From the drop-down list, choose the executable file in your package to associate with your file type.

Finish Page

You are now ready to create your setup project, explore and customize it further in the main InstallAware IDE (both in the visual designers and the MSIcode script editor), and build a release. Click the Finish button to close the wizard and continue. Click the Back button to review your settings and make any changes.

Build my setup now

Check this box to immediately build setup using your current settings. Clear this box if you wish to edit or review your setup project before building a release.


Project Settings

Project settings control aspects of your installation which are not available in your installation script. These settings allow for changing the product name and code, among other things. To access your project settings:

  • Press SHIFT+CTRL+F11.
  • On the Project tab, in the Manage group, click Project Settings.
  • On the MSIcode tab, in the Compile group, click Project Settings.

Project Node

This page lets you define the most basic aspects of your installation.

Manufacturer

Enter your company name here.

Product Name

Enter the name of the product the setup will install here. This name will be available in the setup script as the TITLE variable.

Product Version

Enter the version of the product being installed here.

Product Code

Click the Generate button to generate a new product code. The product code uniquely identifies your installation to Windows Installer. It must be unique in each different product, as well as different versions of the same product. This code will be available in the script as the PRODUCTCODE variable.

Upgrades Product with Product Code

If your installation upgrades a previous version, enter the product code of that version here.

Default Language

Choose the default language of your installation from the drop-down list.

Display Language Selector

This option is visible only if you have built a multi-lingual setup using the Localization Wizard. Check it to display a language selection dialog when setup is initializing. The chosen language will become the default language for the setup. If the target system language is available among your setups localized languages, it will be pre-selected in the language selection dialog. You may also change the active language from your setup script, as an alternative or complement to showing the language selection dialog.

Summary Node

This page lets you compose the summary stream information that will be available in the Windows Installer database. Be sure to set a unique Revision Code by pressing the Generate button any time you change your Product Code defined on the Project Node. This page also lets you manually set the Vista UAC elevation level.

UAC Elevation

Select your desired UAC elevation level using this combo-box. The default setting is highestAvailable. This setting is not recorded in the MSI file and has effect only on Vista or newer operating systems when UAC is enabled.

You may also want to see the Run Program As command for the related UAC de-elevation option and the Application Requirements design view for the related UAC elevation detection option.

Add-Remove Node

This page lets you configure the way your application appears on the Control Panel Add-Remove Programs applet. Fill in the fields as necessary. The value entered for the Publisher Name field will be available in the setup script as the COMPANY variable.

You may also customize the icon used by your setup here by clicking the Load Icon button.

Compiler Variables Node

The list of all defined compiler variables for the current project is displayed on this page. Press the Add button to define a new variable. Double-click an existing variable, or choose an existing variable and press the Edit button to modify it. Press the Delete button after selecting one or more compiler variables to remove them.

Each setup project also has some pre-defined compiler variables.


Project Wizard

The Project Wizard offers a completely visual way to generate your installation scripts. To display the wizard:

  1. Save any changes you have made to the installation open in the IDE.
  2. On the Project tab, in the New group, click Quick Start.
  3. Double-click the Project Wizard icon.

After you have displayed the wizard, navigate through the pages using the Back and Next buttons, or by directly clicking the section you wish to navigate to. When you click Next on the last page of the wizard, a fully operational setup script will be generated, which you may further customize and edit in the script editor.


Product

The Product page allows you to enter general information about your product. The information entered here will be used throughout the setup.

Name

The name of your product.

Version

The version number of your product.

Manufacturer

The company that is the manufacturer of the product.

Copyright

Legal copyright information.

Website

The product website.


Conditions

Note:

This help topic applies to the Express edition of InstallAware versions earlier than InstallAware 2005.

The Conditions page allows you to check the target system for a minimum of available hardware and software. It also enables installing runtime components on the target system, if they are not already found. An enhanced selection of runtime components is available with the Enterprise edition of InstallAware.

Minimum Operating System

If you choose an operating system, the installation will not proceed unless the target computer has at least that operating system installed. If you choose an operating system platform, the installation will not work on any platform except the chosen one.

Minimum Internet Explorer Version

If you choose an IE version, the installation will not proceed unless the target computer has a browser that is the chosen version or newer.

Minimum Memory

This feature allows to check for a minimum of physical memory installed on the target system. The installation will not proceed unless the minimum indicated amount of physical memory is installed. This feature does not check for available virtual memory.

Minimum Resolution

This feature allows to check for a minimum display resolution on the target system. The installation will not proceed unless the minimum resolution is available on the target system.

Windows Installer 2.0

Version 2.0 of Windows Installer must be present on the target system for the installation to run. Make sure this component is checked to assure Windows Installer 2.0 will be installed if not already present.

Warning:

If you uncheck this component, your setups may fail .

Microsoft .NET Framework 1.1

If your application runs on the .NET Framework, check this component to install Microsoft .NET Framework 1.1 on the target system, if not already present.

Microsoft JSharp Redistributable

If your application is both a .NET application and also requires the JSharp redistributable, check this component. The JSharp redistributable will be installed if not already present on the target system.

DirectX 9b

If your application is a game, or makes use of the DirectX APIs, check this component. The DirectX 9b redistributable will be installed if not already present on the target system.

MDAC Refresh 2.8

If your application is a database application that makes use of data access components, check this. The MDAC 2.8 refresh will be installed if not already present on the target system.

Visual Basic VM SP6

If your application is a Visual Basic 6 application, check this component. The Visual Basic 6, Service Pack 6 virtual machine will be installed if not already present on the target system.

Visual C++ Runtime SP6

If your application is a Visual C++ application and is dynamically linked to ADO/DAO/MFC/VC language DLLs, check this component. The Visual C++ 6 Runtime, Service Pack 6, will be installed if not already present on the target system.


Features

A feature enhances the functionality of an application, however the application does not require the feature to operate. While not all applications will have features, most sophisticated applications will. Moreover, if you are installing more than one application with your installation, each application may be defined as a feature.

Features are defined on the Features page:

  • To add a new feature, choose the parent feature, and click New . If the feature is a top-level feature (it has no parent), choose All Features and click New.
  • To delete a feature, choose the feature, and click Delete. All sub features of the selected feature will also be deleted.
  • To rename a feature, choose the feature, click Rename, and type in the new name for the feature.
  • If your application has no features, delete all items on this screen except the All Features item, which cannot be deleted.
  • The user will only see the features defined on this tab if (s)he performs a custom setup. Only the first feature defined on this tab (without any subfeatures) will be installed if the user requests a minimum installation.
  • Each defined feature will be placed in its own Web Media Block. The All Features feature will be placed in an Offline Media Block.


Files

Copying files onto the target system is one of the most vital setup functions to be performed. The Files page allows you to choose which files and folders are copied onto the target system.

Adding Files

  1. First, use the combo box to choose which feature the files to copy belong to. Unless that feature is selected during setup, the files will not be copied. Use the Feature Independent selection to indicate files that should be copied regardless of selected features.
  2. Choose the target folder on the destination system that the files should be copied into.
  3. Click the Add Files button and choose one or more files to copy into the chosen folder.
  4. If you select some files in error, highlight them and click the Delete button.
  5. If you need to copy files into subfolders of the designated target folder, add the items as folders instead.

Adding Folders

  • First, use the combo box to choose which feature the folders to copy belong to. Unless that feature is selected during setup, the folders will not be copied. Use the Feature Independent selection to indicate folders that should be copied regardless of selected features.
  • Choose the target folder on the destination system that the folder should be copied into. The folder will become a subfolder inside the destination folder.
  • Click the Add Folder button and choose a folder to copy into the destination folder. The chosen folder will be copied along with all files and further subfolders inside it.
  • If you select a folder in error, highlight them and click the Delete button.
  • If you need to copy individual files instead of folders, add the items as files instead.


Shortcuts

Shortcuts defined on the Shortcuts page allow the end-user to launch the installed application, from the Desktop, Start Menu, or Explorer through file associations.

Before defining shortcuts, make sure you have selected some files to be installed on the target system using the Files page. Then:

  1. Click the New button.
  2. In the file browser, navigate to the feature that contains the file which the shortcut will point to.
  3. Navigate to the file itself and click OK.
  4. If you choose a file in error, click Delete to remove it from the shortcuts list.
  5. To rename the shortcut, click the Rename button.
  6. The following options are available for your shorcuts. You may select more than one option simultaneously:
    • Place shortcut in Start Menu: Creates a shortcut in the Start Menu folder for your application.
    • Place shortcut on the Desktop: Creates a shortcut on the Desktop for your application.
    • Associate a file type with shortcut: Creates a file association with the executable the shortcut points to, and the indicated file extension (do not enter a period character before the file extension).


Registry

The Registry page assists you in defining registry entries for your application. The registry is frequently used to store system-wide application information.

  1. First, use the combo box to choose which feature the registry entires belong to. Unless that feature is selected during setup, the registry entries will not be created. Use the Feature Independent selection to indicate registry entires that should be created regardless of feature selection.
  2. Choose a target key for the registry entry.
  3. Click New and add the subkey(s) your registry entry falls under.
  4. If you add a subkey in mistake, click Delete.
  5. Click New and create your registry entry. Leave the Value Name field empty if you will be creating a default value.
  6. To correct a registry entry, choose it and then click Edit.
  7. To delete a registry entry, choose it and then click Delete.


Dialogs

The Dialogs page helps you choose a dialog theme and a maintenance mode for the user interface of your setup.

Dialog Theme

The dialog theme controls the appearance of your setup user interface. Regardless of the actual dialogs you choose to display, the theme determines how the general appearance of the dialogs will be. You will most likely want to preview the available themes before settling on a theme for your setup project.

To preview available dialog themes, choose a theme, and click View Theme. Different themes will be better suited to different types of applications. Be sure to try each theme.

Maintenance Mode

The maintenance mode setting determines what happens when the user re-runs setup, after having already installed your product on his/her computer. Please note that re-running setup after your product has been installed is identical to choosing your product's Change/Remove button in the Control Panel Add Remove Programs listing.

I wish to allow a maintenance user interface

If this setting is enabled, the user will be presented with a maintenance dialog, offering three options: Modify, Repair, and Remove.

  • If Modify is chosen, a feature selection dialog will be shown, and the product will be reinstalled using the newly selected features.
  • If Repair is chosen, the product will be reinstalled using exisiting feature selections.
  • If Remove is chosen, the product will be uninstalled.

If either Modify or Repair has been chosen, the product will be reinstalled. This may mean that product configuration files modified by the user may be replaced with their originals.

I prefer to provide an uninstall option only

If this setting is enabled, the user will be asked whether (s)he wants to uninstall the product, and if comfirmed, the product will be removed from the user's system.


Media

The Media page offers a selection of build modes, encompassing a wide variety of distribution channels.

Uncompressed Directory Layout

The setup is comprised of a collection of uncompressed files and folders, spanning multiple directories, and several levels deep. This media type is ideally suited for software distribution on CDs/DVDs. Because no compression is applied, setup performance will be at maximum. However for the same reason, disk space requirements will also be highest.

The multiple levels of files and folders generated by this media type make it impractical for distribution over the Internet, or where single files are required to contain the entire installation.

Compressed Single Self-Installing EXE

The entire setup is packaged into a single executable file. When run, this executable file will first extract its contents onto a temporary location, and then start the installation. This is the most economical media layout in terms of disk space. Both because the entire setup is located inside a single file, and the superior compression employed, this media type is also ideal for Internet distribution.

Compressed Web-Based EXE

The setup is split into multiple web blocks, which are dynamically downloaded from the Internet at install time as required. Only the runtime components which the user does not already have, along with the features requested for the install, are downloaded. While the splitting reduces some of the compression gains, this media type offers the optimal performance, because of the selective download feature.

The setup is started by a single executable file which will download other blocks as necessary. The single file can be distributed on any medium, and the web blocks must be placed on a web server.

Build in Custom Folder

If you wish to change the build folder of your setup projects (default is the project folder), check Build in Custom Folder, and click Browse to choose the new build folder.

Build Project Now

Checking this item will immediately build a release of your project as soon as you click the Next button on this wizard page.


Project Properties (Application Information)

The Project Properties page allows you to enter important information about the application you are installing and its setup database. The properties entered in this page are not only used for display, but also have important meanings for Windows Installer. This page also enables your application to receive InstallAware Web Updates.

Product Name

Enter the name of your product here. This product name initializes the TITLE pre-defined script variable internally.

Product Version

Enter the version number of your product in the form major.minor.revision. You may only enter numeric values and periods in this field. Using non-numeric version numbers are illegal for Windows Installer.

Manufacturer

Enter the name of the company here. This company name initializes the COMPANY pre-defined script variable internally.

Default Language

Enter the default language for your setup program here. If you would like to build multi-lingual setups, or localize your setup for a particular language, click the Localize button to display the Localization Wizard.

Display language selection dialog box

This check-box is available only if you have already localized your setup using the Localization Wizard. Checking it will display the default InstallAware language selection dialog box when setup starts. If you do not wish to use the default language selection dialog box, leave this box unchecked, and use the LANGUAGE pre-defined setup variable in your setup script to switch languages at runtime.

Product Code

Enter a unique identifier for your product here. Click the Generate button to create a new unique identifier if you are not sure that the displayed identifier is unique. The Product Code must be unique for each different product, but may be the same for different versions of the same product.

Revision Code

Enter a unique identifier for your setup here. Click the Generate button to create a new unique identifier if you are not sure that the displayed identifier is unique. The Revision Code must be unique for each different setup. Unless each setup you build has a unique code, they will appear to be the same installation package to Windows Installer, even when they are not. Even slightly different versions of your setup must have a unique revision code. You can have InstallAware automatically update this code every time you rebuild your setup project using the Build Settings window.

Target Folder

Enter the default installation folder for your application here. This value initializes the TARGETDIR pre-defined script variable using the Set Variable command.

Shortcut Folder

Enter the default Start Menu shortcut folder for your application here. This value initializes the STARTMENU pre-defined script variable using the Set Variable command.

Receive Application Updates

Check this box to have setup check for application updates on the web using InstallAware Web Update. Checking this box adds the update script (updates.*) and pre-built dialogs (update_*.dfm) to your setup from the runtimes subfolder of your InstallAware installation folder.

You cannot select this check-box if your script lacks the Apply Install command. Template and wizard generated setups provide this command.

The following fields are available only when this check-box has been selected:

Monitor URL

Specify the exact URL where you would like the InstallAware Web Update script to check for application updates. This URL is stored in the compiler variable UPDATE_SERVER, which is read by the update script when checking for application updates.

Application update information is stored in an INI file, named updates.ini by default. However, you may specify any URL, including a different filename, in this field. The updates.ini file is created during your setup build process when the Update Packs and Versions views are populated, and as long as this file is uploaded to the specified URL, the update mechanism will work.

Automatic updates (every time setup is run)

Check this box to choose automatic updates as your update mode. The automatic update mode automatically checks for updates at any time setup is run. If any updates are available, they will be immediately downloaded and installed, in place of the main setup itself. The only exception to the automatic update checks rule is when setup is started in maintenance mode. This enables end-users to remove your application without having to update it to its latest version first.

Setup also creates a Start Menu shortcut when this option is selected. This shortcut is accessible from the Shortcuts design view and may be renamed and/or moved to a different folder on the target system at that design view. This shortcut enables updates to be serviced manually after the initial installation has completed - just as would be the case with the following Manual update checking option.

This preference is stored in the compiler variable UPDATE_SCHEDULING set to THIRD. This compiler variable setting builds the update script at compile time in accordance with the automatic web update mode.

Manual update checking (Start Menu shortcut)

Check this box to choose manual updates as your update mode. The manual update mode does not automatically check for updates, but only performs an update check when the Start Menu shortcut created by setup is invoked on-demand by the end-user. The entire update process runs interactively, awaiting for end-user confirmation on the updates to download and install. The Start Menu shortcut that setup creates when this option is selected is accessible from the Shortcuts design view and may be renamed and/or moved to a different folder on the target system at that design view.

This is the default setting for web updates. This preference is stored in the compiler variable UPDATE_SCHEDULING set to FALSE, or any value other than THIRD or TRUE (including having it undefined). This compiler variable setting builds the update script at compile time in accordance with the manual web update mode.

Schedule updates (similar to Windows Update)

Check this box to choose scheduled updates as your update mode. The scheduled update mode mimicks the behavior of Windows Update. Upon the first logon of the end-user after product installation, a message balloon will request the end-user to schedule regular update checks, and determine how interactive they run. The end-user may choose any desired schedule and may opt to manually our automatically download and/or install updates. The update script will then create a scheduled task reflecting the end-user preferences. Until the scheduling step has been successfully completed, no update checks may occur. If the scheduling step is cancelled, there will not be a further opportunity to schedule unless setup is explicitly started again in update scheduling mode.

This preference is stored in the compiler variable UPDATE_SCHEDULING set to TRUE. This compiler variable setting builds the update script at compile time in accordance with the scheduled web update mode.

Please note that when you are using the Native Code Setup Engine, you must edit one line in the web update script for scheduled updates to work.


Summary, UAC, and ISO (Application Information)

The Summary, UAC, and ISO page lets you customize the properties that are written to your setup database and executable files, and are visible in Windows Explorer tool tips and property pages. This page also lets you manually set the requested UAC elevation level. You may also set the ISO/IEC 19770-2:2009 software identification (SWID) tag for your application here.

Database Summary Information

Type in a field to update the value of that field as you wish for it to appear in Windows Explorer tool tips and property pages.

User Account Control

Select your desired UAC elevation level using this combo-box. The default setting is highestAvailable. This setting is not recorded in the MSI file and has effect only on Vista or newer operating systems when UAC is enabled.

You may also want to see the Run Program As command for the related UAC de-elevation option and the Application Requirements design view for the related UAC elevation detection option.

ISO/IEC 19770-2:2009 SWID

Inverse Domain Name

Type the Internet domain name of your organization in inverse form. For example, the inverse form of installaware.com is com.installaware.

Leave this field empty to not set the ISO/IEC 19770-2:2009 software identification (SWID) tag for your application.

First Full Month of Ownership

Choose the first full month your organization owned your Internet domain name for the first time.

Suffix

Optionally provide the name of your department or organization branch. Ensure you use only characters that would be valid for use as file names.

Entitlement

Check this box to indicate that the rights to use your application must be verified during software compliance.


Add-Remove Programs (Application Information)

The Add-Remove Programs page lets you customize how your setup appears in the Control Panel Add Remove Programs applet. In addition, this page lets you load a custom icon for your setup package and executable file.

Setting Fields

Type in a field to update the value of that field as you wish for it to appear in the Control Panel applet.

Using Custom Icons

Adding a Custom Icon

To add a custom icon, click the Load Icon button, and select the icon file to use. This icon will appear in both the Control Panel applet, and also your setup package and executable file.

You may use icons of any color depth and resolution.

Removing a Custom Icon

To remove a custom icon, switch to the Creatives page, and delete the icon.ico creative.


Application Requirements (Application Information)

The Application Requirements page allows you to specify and enforce minimum hardware, software, and user levels before your application is allowed to install. This page can also be used to protect your setup with global passwords.

Managing Requirements

To specify hardware and software requirements, click the drop-down boxes next to a requirement category, and select the minimum requirement. To cancel a previously specified requirement, open the drop-down boxes again, and choose Don't Check.

Setup Encryption

InstallAware can produce strongly encrypted setups that utilize 256 bit AES encryption. To encrypt your setups, just enter a password into the 256-Bit Encryption Key field. Note that only compressed setup media may be encrypted.

Special Requirements

To require administrator privileges for installation, check the Require Administrator priviledges for installation check-box. Otherwise, leave this box unchecked.

To check whether setup has full administrator rights on a Vista or newer operating system with UAC enabled, check the Vista User Account Control Elevation check-box. Otherwise, leave this box unchecked. Checking this box on older operating systems will cause setup to fail, even if setup does have full administrator rights. Checking this box on Vista or newer operating systems when UAC is disabled will require ordinary administrator rights for the check to succeed.

To create a native 64 bit installation which installs on 64 bit operating systems only, check the 64 bit operating system check-box. To create a 32 bit installation which installs natively on 32 bit operating systems, or in compatibility mode on 64 bit operating systems, leave this box unchecked. To create an installation which switches between 32 bit and 64 bit installation modes at runtime, use the Set 64 Bit Mode command in your setup script.

To disallow installations on virtualized hardware platforms, check the Non-virtual hardware check-box. This assures your setup will not run inside VMware and Virtual PC virtual machines. To let your setup run on virtual hardware, leave this box unchecked.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Get System Settings, MessageBox, Set 64 Bit Mode, Terminate Install. Additional general scripting commands may be emitted.

Commands Required

This page does not require any scripting commands to be present, however some pre-existing commands may provide better operation. Template and wizard generated setups provide all necessary commands.


Application Runtimes (Application Information)

The Application Runtimes page allows you to automatically install runtimes required by your application as setup pre-requisites.

Runtimes selected in this page update additional elements in the Application Requirements page, so as to enforce the minimum system and software requirements of the runtimes in question.

Runtimes selected in this page also have accompanying elements inserted in the Web Media Blocks page. These accompanying elements associate web download segments with runtimes to allow partial web deployment of application runtimes, therefore delivering functional installers that still work without mandating an Internet connection.

Adding New Runtimes

To add new runtimes, just check the displayed runtime name. If additional runtimes are required by the selected runtime, they will be automatically checked as well.

Runtimes are supported by InstallAware plug-ins. If plug-ins required for runtimes on the system are not available, setup compilation errors will occur. In this case, just start the InstallAware setup program, and add the missing plug-ins using the Add or Remove Features setup option.

Configuring Runtime Installation Settings

Some runtimes have configurable installation settings. For these runtimes, the Options button will be enabled when the runtime has been checked and is highlighted. To configure the runtime, just click the Options button.

Of the built-in InstallAware runtimes, only the Microsoft Internet Explorer and Microsoft SQL Server Express runtimes require configuration.

Removing Runtimes

To remove runtimes from your setup, just uncheck the runtime.

Downloading New Runtimes

To connect to the online InstallAware Community Center and download new InstallAware or third party authored application runtimes, click the Download Runtimes button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Include Script, Define Web Media Block. Additional general scripting commands may be emitted.

Commands Required

Only template and wizard generated setups provide all necessary commands for visually managing runtimes. Visual runtime management is a complex task and may not work with most custom built scripts, however as long as your customizations are based off of the template and wizard generated setups, you will be able to visually manage runtimes.

Additionally, older versions of InstallAware setup scripts (prior to version 5.0) use a different runtime management technique. When you open and edit setups built in those versions, the Application Runtimes page may not recognize some or all of your existing runtimes (but will be able to insert and manage new runtime installation commands).


Features (Setup Architecture)

The Features page lets you define the conceptual components of your application in a hierarchical manner. As long as the respective dialog is enabled at runtime, end-users will see the features defined in this view, and be able to select/deselect them to customize their product installation at runtime.

New features created in this page also have accompanying elements inserted in the Web Media Blocks page. These accompanying elements associate web download segments with the newly created features.

Creating New Features

To create a new feature:

  1. Select the parent feature of the new feature to create. If the feature is a top level feature, select All Features instead.
  2. Click the New button.
  3. Type in the name of your new feature.
  4. Describe your feature in the Feature Description region.

Updating Features

  • To update the description of an existing feature, select that feature and type directly in the Feature Description region. Changes to the feature description are applied immediately.
  • To update the name of an existing feature, select the feature and click the Rename button. Type in the new feature name.
  • To update the ordering of an existing feature, click the Up Down arrow buttons until the features are sorted as you like.

Deleting Features

To delete a feature:

  1. Select the feature to delete.
  2. Click the Delete button.

Deleting a feature will also remove all of its subfeatures.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Define Component, Define Web Media Block, Get Component State, Set Component State. Additional general scripting commands may be emitted.

Commands Required

This page does not require any scripting commands to be present, however some pre-existing commands may provide better operation. Template and wizard generated setups provide all necessary commands.


Files (Setup Architecture)

The Files page allows you to define which files are installed as part of your product setup. You may assign groups of files to specific setup features, or alternately have files always install if they are vital for your application and should not be deselectable from the setup user interface.

Adding Files to Install

There are various ways to install files and folders as part of your setup.

Defining New Files and Folders

You may define new files and folders from scratch:

  1. Check the Filter Files by Feature button.
  2. If you wish to add files/folders to a particular feature of your setup, choose that feature. If you prefer the files/folders to always install, select the Feature Independent item instead.
  3. In the Target Folders view, select the parent folder for the files/folders to add. If no folders are visible yet, do nothing - you can always specify the parent folder for your items later.
  4. Right click in the Target Files view and choose Add New Files or Add New Folder based on the type of item you wish to add to your setup.
  5. Browse to the item to add and click OK to apply your changes.

This method lets you create files and folders inside folders already visible on the Target Folders structure. Read below for more information on how to install files and folders inside new folders that may not yet be part of the Target Folders structure.

Adding New Folders

To add a new folder:

  1. In the Desktop view, navigate to the folder to add.
  2. Check the Filter Files by Feature button.
  3. If you wish to add the folder to a particular feature of your setup, choose that feature. If you prefer the folder to always install, select the Feature Independent item instead.
  4. Choose the parent folder for the new folder in the Target Folders view. If no folders are visible yet, do nothing - you can always specify the parent folder for your items later.
  5. Click the Add Folder button.

Adding New Files

To add new files:

  1. In the Desktop view, navigate to the folder containing the files to add.
  2. Check the Filter Files by Feature button.
  3. If you wish to add your files to a particular feature of your setup, choose that feature. If you prefer the files to always install, select the Feature Independent item instead.
  4. Choose the parent folder for the new files in the Target Folders view. If no folders are visible yet, do nothing - you can always specify the parent folder for your items later.
  5. Highlight the files to add to your setup and click the Add Files button.

Scanning for Dependencies

You may run an .EXE program file and dynamically scan it for the libraries which it requires at run-time. This way you will not miss any libraries that the program needs and properly install all files associated with the program, eliminating the guesswork involved in determining dependencies.

To dynamically scan a file for its dependencies:

  1. Check the Filter Files by Feature button.
  2. If you wish to add the dependencies to a particular feature of your setup, choose that feature. If you prefer the dependencies to be always installed, select the Feature Independent item.
  3. Click the Scan button.
  4. Browse to the program to scan.
  5. After you have selected the program, the program is launched automatically. Wait for the program to finish loading.
  6. Once the program has loaded, be sure to use all of its features. This way the program loads and uses all of the libraries it may ever need at runtime.
  7. Do not close the program. Return back to the IDE.
  8. Click OK to add detected dependencies to your setup project.
  9. After the dependencies have been added, you may close the scanned program.

Updating Files, Folders

Updating Folders

To update a folder (along with all files inside it):

  1. Uncheck the Filter Files by Feature button to see all folders being created by your setup.
  2. In the Target Folders field, right click the folder to update and choose Edit.
  3. The Install Files dialog opens. Update the dialog fields as appropriate:
    • Updating the Target Folder field changes the destination of the selected folder (and all items inside it).
    • Other installation properties may be updated for all selected items at once.
  4. Click OK to save your changes.

If the Edit option is disabled when you right click the folder, this indicates that the folder you are trying to update is not being explicitly created by your setup (you may be creating a subfolder of the highlighted folder instead).

When you update a folder using this method, subfolders of that folder are not affected.

Updating Files

You may update individual files, or select multiple files and update them simultaneously (in this case, you may change the target folder and installation properties for all selected files in a single pass). You may also specify wildcards for files being installed to dynamically include all matching files in your setup at build time.

  1. Uncheck the Filter Files by Feature button to see all files and folders being created by your setup.
  2. In the Target Files field, highlight all files to update.
  3. Right click the selection and choose Edit Files.
  4. The Install Files dialog opens. Update the dialog fields as appropriate:
    • If you chose multiple files, you may update their target folders and installation properties in a single pass.
    • If you chose a single file, you may update all of its properties - including the file being installed itself. For instance, you may replace a fixed file name with a wildcard to automatically install all matching files of the given wildcard in your setup at build time.
  5. Click OK to save your changes.

The parent folder of the updated files may disappear if there are no longer any files being copied inside it.

Removing Files, Folders

Removing Folders

To remove a folder (along with all the files inside it):

  1. Uncheck the Filter Files by Feature button to see all files and folders being installed by your setup.
  2. In the Target Folders field, right click the folder to delete and choose Delete.

If the Delete option is disabled when you right click the folder, this indicates that the folder you are trying to delete is not being explicitly installed by your setup (you may be installing a subfolder of the highlighted folder instead).

When you delete a folder using this method, subfolders of that folder are not affected.

Removing Files

You may remove single files, or select multiple files, and wildcard patterns, to remove them all:

  1. Uncheck the Filter Files by Feature button to see all files and folders being installed by your setup.
  2. In the Target Files field, highlight all files (or wildcard patterns) to remove.
  3. Right click the selection and choose Delete Files .

The parent folder of the deleted files may disappear if there are no longer any files/folders being installed underneath it.

Working with Target Folders

You may add pre-defined system folders to the Target Folders structure, or create your own custom folders. While explicitly creating folders is not required, while designing your setup it can be easier to build your folder hierarchy first, and then add all the files to your setup.

Defining System Folders

A collection of pre-defined system folders will always be available on the remote system. The IDE displays the most frequently used folders, but you may want to display additional system folders when they are required:

  1. Right click an element in the Target Folders view.
  2. Choose Add System Folder.
  3. In the Display System Folder dialog box, select the pre-defined system folder you wish to add, then click OK to apply your changes.

The folder is added as a top level element to the Target Folders view using an abbreviated name.

Creating Custom Folders

To explicitly create a folder:

  1. Right click an element in the Target Folders view.
  2. Choose Create Subfolder .
  3. In the Create Subfolder dialog box, type the name of the folder to create, then click OK to apply your changes. You may specify multiple (nested) new folders in this field.

You cannot add a custom folder to the root of the Target Folders view - you must always start with a pre-defined system folder.

The $TARGETDIR$ folder represents the end-user chosen installation directory at run-time, and is automatically created for you the first time you add a file. If you do not see this folder, select the Target Folders node in the Target Folders view, and add a file or folder to your setup by clicking the Add Folder or Add Files button. $TARGETDIR$ is automatically created for you and the item you added is placed inside $TARGETDIR$.

Removing Folders

You may remove a custom folder that you explicity created, or a pre-defined system folder that is displayed in the list of folders under the Target Folders view. To remove a folder:

  1. Select the folder to remove in the Target Folders view.
  2. Right-click and choose Remove Subfolder.

If the folder still appears in the Target Folders view, there might be files being installed inside it. Removing those files will remove the folder as well.

Folders that have not been explicity defined or created cannot be removed using this method. They will disappear automatically when no more files are being installed inside them.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Install Files, Create Folder, Get Folder Location. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Registry (Setup Architecture)

The Registry page allows you to create registry entries as part of your installation. You may also import existing entries directly from the system registry in this page. Registry entires may be added to a particular feature of the setup, or may be made feature-independent (so they will always install, regardless of setup features chosen for installation by the end-user at runtime).

Creating Keys and Values

There are various ways to create registry keys and values as part of your setup.

Defining New Values

You may define new values from scratch:

  1. Check the Filter Keys by Feature button.
  2. If you wish to add the values to a particular feature of your setup, choose that feature. If you prefer the values always be installed, select the Feature Independent item.
  3. In the Target Keys view, select the parent key of the new key/value pair.
  4. Right click in the Target Values view and choose New Value.
  5. The Edit Value Name/Data window appears. Populate the fields in this window to describe your new value.
  6. If you would like to create an Integer value, check the Set as Integer box. Otherwise, leave this field unchecked.
  7. Click OK to apply your changes.

This method lets you create values inside keys that are already mapped on the Target Keys structure. Also, you may only create String or Integer data types using this method. Read below for more information on how to create values inside new keys, update existing values to be placed inside new keys, and to create other data types.

Adding Registry Keys

You may add an entire registry key, along with its subkeys and values, directly into your setup. The keys to add must already be a part of your local system registry.

To add registry keys:

  1. In the Source Keys view, expand the root keys and navigate to the key you wish to add.
  2. Check the Filter Keys by Feature button.
  3. If you wish to add the keys to a particular feature of your setup, choose that feature. If you prefer the keys to be always installed, select the Feature Independent item.
  4. Click the Add Key button.

Adding Registry Values

You may add a group of registry values belonging to a registry key directly into your setup. The values to add must already be a part of your local system registry.

To add registry values:

  1. In the Source Keys view, expand the root keys and navigate to the key containing the values you wish to add.
  2. Check the Filter Keys by Feature button.
  3. If you wish to add the values to a particular feature of your setup, choose that feature. If you prefer the values to be always installed, select the Feature Independent item.
  4. In the Source Values view, highlight all values to add.
  5. Click the Add Values button.

Defining Registry Keys

You may define a new, custom registry key if it is not already a part of your local system registry. Once you have defined a key, you may follow the steps above to populate it with the values you need.

To define a new registry key:

  1. Check the Filter Keys by Feature button.
  2. If you wish to add the key to a particular feature of your setup, choose that feature. If you prefer the key to be always installed, select the Feature Independent item.
  3. In the Source Keys view, expand the root keys and click the parent key you wish to define your new key under.
  4. Right-click and choose New Key.
  5. In the New Key dialog that appers, enter the name of your new key. You may enter multiple subkey names if you wish to create a nested key. Click OK to create your key.

Importing Keys/Values

You may directly import keys and values stored in .REG files and COM servers. .REG files are created by the Registry Editor when exporting keys and values from the system registry to a file. COM servers are capable of self-registration and the data they write to the registry as part of their self registration process may be captured and added to your setup, instead of relying on their built-in self-registration mechanism.

To import keys/values:

  1. Check the Filter Keys by Feature button.
  2. If you wish to add the keys/values to a particular feature of your setup, choose that feature. If you prefer the keys/values to be always installed, select the Feature Independent item.
  3. Click the Import button.
  4. Browse to the file containing the data to import. If the file type you are looking for is not listed, select the correct type in the Files of type field.
  5. Click OK to import the registry data from the selected source.

Be sure to review the imported values and their associated data, updating references to hard-coded paths on your system with variables that will point to the actual location of files on the target system at runtime.

Updating Keys/Values

Updating Keys

To update a registry key (along with all the values inside it):

  1. Uncheck the Filter Keys by Feature button to see all registry keys and values being created by your setup.
  2. In the Target Keys field, right click the key to update and choose Edit.
  3. The Write Multiple Registry Values dialog opens. Update the dialog fields as appropriate.
  4. Click OK to save your changes.

If the Edit option is disabled when you right click the key, this indicates that the key you are updating is not being explicitly created by your setup (you may be creating a subkey of the highlighted key instead).

When you update a registry key using this method, subkeys of that registry key are not affected.

Updating Values

You may update single registry values, or select multiple values and update them simultaneously (in this case, you may change the registry root and parent key of all selected values in a single pass):

  1. Uncheck the Filter Keys by Feature button to see all registry keys and values being created by your setup.
  2. In the Target Values field, highlight all values to update.
  3. Right click the selection and choose Edit Values.
  4. If you chose multiple values, the Write Multiple Registry Values dialog opens. If you chose a single value, the Write Registry dialog opens. Both dialogs are similar, with some fields disabled in the former. Update the existing dialog fields as appropriate. If you chose a single value, you may update its data and data type here.
  5. Click OK to save your changes.

The parent key of the values updated may disappear if there are no longer any values being created underneath it. To preserve at least the key, be sure to create at least the default registry value (the value underneath the key with an empty value name).

Removing Keys/Values

Removing Keys

To remove a registry key (along with all the values inside it):

  1. Uncheck the Filter Keys by Feature button to see all registry keys and values being created by your setup.
  2. In the Target Keys field, right click the key to delete and choose Delete.

If the Delete option is disabled when you right click the key, this indicates that the key you are updating is not being explicitly created by your setup (you may be creating a subkey of the highlighted key instead).

When you delete a registry key using this method, subkeys of that registry key are not affected.

Deleting Values

You may delete single registry values, or select multiple values and delete them simultaneously:

  1. Uncheck the Filter Keys by Feature button to see all registry keys and values being created by your setup.
  2. In the Target Values field, highlight all values to delete.
  3. Right click the selection and choose Delete Values.

The parent key of the values updated may disappear if there are no longer any values being created underneath it. To preserve at least the key, be sure to leave at least the default registry value (the value underneath the key with an empty value name).

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Write Registry. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


XML Files (Setup Architecture)

The XML Files page allows you to edit data contained inside new or existing XML files.

XML Files

Editing an XML File

To edit a new or existing XML file:

  1. Click the New button.
  2. Populate the dialog fields in the Edit Xml File dialog that appears.
  3. Click OK to accept your changes.

Updating an XML File Edit

To update an existing XML file edit:

  1. Select the XML edit to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Edit Xml File dialog that appears.
  4. Click OK to accept your changes.

Removing an XML File Edit

To remove an existing XML file edit:

  1. Select the XML edit to no longer perform.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Edit XML File. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


Assemblies (Setup Architecture)

The Assemblies page lets you install .NET assemblies into the Global Assembly Cache or a custom folder on the target system.

Adding an Assembly

To add an assembly to your setup:

  1. Click the Add button.
  2. Browse and select the assembly to add.
  3. The assembly is added to the Global Assembly Cache for the installation.
  4. To change the assembly installation location, read below.

Updating an Assembly

To update an assembly that has been added to setup:

  1. Select the assembly to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Install Assembly dialog.

Configuring Additional Assembly Options

To configure additional options for one or more assemblies:

  1. Select the assemblies to configure the additional options for.
  2. Check the Generate Native Images (ngen) check-box to generate native images for the selected assemblies. Otherwise, clear this check-box.
  3. Check the Register Assembly (regasm) check-box to register selected assemblies with COM Interop. Otherwise, clear this check-box.
  4. Check the Run Installer Class (installutil) check-box to run the (un)installer classes contained in the selected assemblies. Otherwise, clear this check-box.

If the check-box for a particular selection of assemblies is shaded (neither checked nor un-checked), this indicates that some of the selected assemblies have the option enabled, while others have the option disabled. Checking/un-checking the check-box when it is shaded will apply the changes to all selected assemblies uniformly.

To configure whether assemblies should be forcefully removed from the Global Assembly Cache at uninstall time when there are no more applications referencing those assemblies, check the Force uninstall of unpinned assemblies from the GAC check-box. This setting applies to all assemblies globally.

Removing an Assembly

To remove an assembly from your installation:

  1. Select the assembly to remove. You may select multiple assemblies.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Install Assembly, Generate Native Images, Register Assembly, Run .NET Installer Class, Remove Assemblies. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


File Associations (Setup Architecture)

The File Associations page allows you to associate file types with application files that you are installing. An associated file will open with your application when it is double-clicked in Windows Explorer.

Adding a New File Association

There are two ways you may add a file association.

Importing a File Association

To import (and customize) a file association that already exists on the current system:

  1. Click the New button.
  2. Choose Import.
  3. In the File Type field, choose the existing file association to import.
  4. Click OK to import the selected association.
  5. To customize the imported assocation, select it and click the Edit button.

Defining a File Association

To define a custom file association:

  1. Click the New button.
  2. Choose Define.
  3. The Create File Type window appears. Populate the fields in this dialog.
  4. Click OK to save your changes.

Updating an Existing File Association

To update an existing file association:

  1. Select the file association to update.
  2. Click the Edit button.
  3. The Create File Type window appears. Update the fields in this dialog.
  4. Click OK to save your changes.

Deleting a File Association

To remove a file association from your installation:

  1. Select the file association to remove.
  2. Click the Delete button.

Changing the Type of a File Association

To change the type of a file association:

  1. Select the file association to change the type of.
  2. Click the Set Type button.
  3. Choose the new type (Regular or Advertised).

The regular type is the recommended type for most installations because of increased versatility. The advertised type is recommended only if you are already familiar with Windows Installer and know that you require advertising support, a technology specific to Windows Installer (and burdened with its own restrictions and limitations).

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create File Type. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


INI Files (Setup Architecture)

The INI Files page allows you to edit custom data in Windows INI format plain-text files.

Adding New INI File Edits

There are two ways you may add a new edit action on an INI file.

Importing an Existing INI File

To import an existing INI file and replicate all of its contents as part of your setup:

  1. Click the New button.
  2. Choose Import.
  3. Choose the existing INI file to import.
  4. Click OK to import the selected INI file.
  5. To customize any of the imported INI file entries, select it and click the Edit button.

Defining an INI File Edit

You may also manually author INI file edits (including removing existing INI entries):

  1. Click the New button.
  2. Choose Edit.
  3. The Edit Ini File window appears. Populate the fields in this dialog.
  4. Click OK to save your changes.

Updating an Existing INI File Edit

To update an existing INI file edit action:

  1. Select the entry to update.
  2. Click the Edit button.
  3. The Edit Ini File window appears. Populate the fields in this dialog.
  4. Click OK to save your changes.

Deleting an INI File Edit

To remove an INI file edit action from your installation:

  1. Select the entry to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Edit INI File. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Dialogs (User Interface)

The Dialogs page previews each dialog that is a part of your setup. You may also change your setup theme, hide particular dialogs, or launch the dialog editor from this page.

Previewing Dialogs

To preview dialogs, click the dialog name underneath the Dialog Sequence heading. A preview of the dialog appears under the Dialog Preview region.

Hiding Dialogs

While you cannot change the ordering of the dialog display sequence, or add new dialogs to the display sequence, you may hide dialogs that are part of the sequence. Hidden dialogs will not be shown at runtime and be skipped.

To hide a dialog, simply uncheck its listing under the Dialog Sequence heading. To show that dialog again, re-check its listing.

Making more sophisticated changes (such as adding new dialogs, changing the order of display) requires updating the setup script.

Editing Dialogs

To edit a dialog:

  1. Select it under the Dialog Sequence heading.
  2. Click the Edit button.
  3. The dialog editor opens with the selected dialog and you may make customizations as necessary.

Changing Themes

To change your setup theme:

  1. Click the Change Theme button.
  2. From the Available Setup Themes drop-down, select a new theme.
  3. A graphical and textual preview of the new theme shows. To try each individual dialog in the theme, click the View Theme button.
  4. Choose OK to apply the new theme.

InstallAware features 14 unique setup themes, however not all may have been installed depending on your setup choices. To install more setup themes, simply re-run the InstallAware setup program, and add the new themes using the Add or Remove Features setup option.

Changing a theme will overwrite any customizations you may have made to your existing dialogs.


Creatives (User Interface)

The Creatives page allows you to add and modify the support files of your setup.

Updating creatives

  • To add a creative, click the Add button.
  • To remove creatives, highlight the items to remove and click the Remove button.


EULA and ReadMe (User Interface)

The EULA and ReadMe page allows you to load and edit an end user license agreement and readme file for your setup.

Loading a File

To load a file, follow these steps:

  1. In the Text to Display field, choose the type of file to load (readme, or end user license agreement).
  2. Click the Load button to load the file.

Loaded files are added to your project as support files.

Editing a File

To edit a file, follow these steps:

  1. In the Text to Display field, choose the type of file to edit (readme, or end user license agreement).
  2. The current file displays. Make the necessary changes directly on the display.
  3. Remember to click the Save button to save your changes. Your changes will be lost unless you explicitly save them when you choose a different file type, switch to the code view, or switch to a different visual view.

Removing a File

To remove a file, follow these steps:

  1. In the Text to Display field, choose the type of file to remove (readme, or end user license agreement).
  2. Click the Clear button the remove the file.


Shortcuts (User Interface)

From the Shortcuts page you may create links to your installed files, URLs, and more. Various link placement options are available as well. You may also pin any shortcuts you create directly to the new Start Menu available with Windows XP or higher, or directly to the Windows 7 Taskbar, or to the Windows 8 Start Screen - giving your applications access to some prime real estate on your end-user's desktops.

Adding a New Shortcut

To add a new shortcut:

  1. Click the New button.
  2. In the Shortcut Target field, enter the full path of the file you will be linking to on the target system. If the target of the shortcut is a file that you are installing, click the Browse button to visually locate it. You may also enter URLs and paths to files that are pre-existing on the target system here.
  3. In the Shortcut Placement field, check the locations you would like to place your new shortcut. You must check at least one location.
  4. After selecting a location on the Shortcut Placement field, you may also check one or more pinning locations from the Pin Application field, to pin your application directly to the new Start Screen, Start Menu or the Taskbar. The selected shortcut will then also be pinned to your selected pin locations. Each pin is specific to a shortcut, so you may pin multiple shortcuts as necessary - however, you cannot pin an application directly without previously selecting an associated shortcut for it from the Shortcut Placement field. Each pin location is associated with a specific shortcut location, and you may individually manage pins for each selected shortcut location by first selecting the shortcut location from the Shortcut Placement field, and then choosing the pins for that shortcut from the Pin Application field.
  5. In the Shortcut Properties field, enter the display name, and an optional tooltip description for the shortcut.
  6. Click OK to insert the shortcut commands.

If you chose more than one shortcut location, multiple shortcut commands will be created - one for each location.

Updating an Existing Shortcut

To update an existing shortcut:

  1. Select the shortcut to update.
  2. Click the Edit button.
  3. The Create Shortcut window appears. Update the fields in this dialog.
  4. Click OK to save your changes.

Removing a Shortcut

To remove a shortcut from your installation:

  1. Select the shortcut to remove.
  2. Click the Delete button.

Changing the Type of a Shortcut

To change the type of a shortcut:

  1. Select the shortcut to change the type of.
  2. Click the Set Type button.
  3. Choose the new type (Regular or Advertised).

The regular type is the recommended type for most installations because of increased versatility. The advertised type is recommended only if you are already familiar with Windows Installer and know that you require advertising support, a technology specific to Windows Installer (and burdened with its own restrictions and limitations).

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create Shortcut, Get Folder Location. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Games and Media Center (User Interface)

The Games and Media Center page allows you to create new multimedia items for use with the new Windows Games Explorer (available starting with Windows Vista) and Windows Media Center (available starting with Windows XP Media Center Edition 2005).

Games Explorer

Creating a New Games Explorer Item

To create a new games explorer item:

  1. Click the New button.
  2. Click the Games Explorer option.
  3. Populate the dialog fields in the Create Games Explorer dialog that appears.
  4. Click OK to accept your changes.

Updating a Games Explorer Item

To update an existing games explorer item:

  1. Select the games explorer item to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Create Games Explorer dialog that appears.
  4. Click OK to accept your changes.

Removing a Games Explorer Item

To remove an existing games explorer item:

  1. Select the games explorer item to remove.
  2. Click the Delete button.

Media Center

Creating a Media Center Item

To create a new media center item:

  1. Click the New button.
  2. Click the Media Center option.
  3. Populate the dialog fields in the Create Media Center dialog that appears.
  4. Click OK to accept your changes.

Updating a Media Center Item

To update an existing media center item:

  1. Select the media center item to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Create Media Center dialog that appears.
  4. Click OK to accept your changes.

Removing a Media Center Item

To remove an existing media center item:

  1. Select the media center item to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create Games Explorer, Delete Games Explorer , Create Media Center , Delete Media Center. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


ODBC (Advanced Options)

The ODBC page allows you to install new ODBC data sources and drivers.

Installing ODBC Data Sources

Installing a New ODBC Data Source

To create a new ODBC data source:

  1. Click the New button.
  2. Click the Data Source option.
  3. Populate the dialog fields in the Create ODBC DSN dialog that appears.
  4. Click OK to accept your changes.

Updating an ODBC Data Source Installation

To update an existing ODBC data source installation:

  1. Select the data source to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Create ODBC DSN dialog that appears.
  4. Click OK to accept your changes.

Removing an ODBC Data Source Installation

To remove an existing ODBC data source installation:

  1. Select the data source to no longer install.
  2. Click the Delete button.

Installing ODBC Drivers

Installing a New ODBC Driver

To install a new ODBC driver:

  1. Click the New button.
  2. Click the Driver option.
  3. Populate the dialog fields in the Install ODBC Driver dialog that appears.
  4. Click OK to accept your changes.

Updating an ODBC Driver Installation

To update an existing ODBC driver installation:

  1. Select the driver to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Install ODBC Driver dialog that appears.
  4. Click OK to accept your changes.

Removing an ODBC Driver Installation

To remove an existing ODBC driver installation:

  1. Select the driver to no longer install.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create ODBC DSN, Install ODBC Driver. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Services (Advanced Options)

The Services page allows you to install new services, control the state of installed services, and uninstall services.

Installing Services

Installing a Service

To create a new service:

  1. Click the New button.
  2. Click the Install Service option.
  3. Populate the dialog fields in the Install Service dialog that appears.
  4. Click OK to accept your changes.

Updating a Service Installation

To update an existing service installation:

  1. Select the service to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Install Service dialog that appears.
  4. Click OK to accept your changes.

Removing a Service Installation

To remove an existing service installation:

  1. Select the service to no longer install.
  2. Click the Delete button.

Controlling and Uninstalling Services

Adding a Control/Uninstall Command

To add a control/uninstall command:

  1. Click the New button.
  2. Click the Control Service option.
  3. Populate the dialog fields in the Control Service dialog that appears. To uninstall the service, choose the Stop and delete the service on uninstall option in the Control drop-down.
  4. Click OK to accept your changes.

Updating an Existing Control/Uninstall Command

To update an existing control/uninstall command:

  1. Select the control/uninstall command to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Control Service dialog that appears.
  4. Click OK to accept your changes.

Removing an Existing Control/Uninstall Command

To remove a command that controls or uninstalls a service:

  1. Select the command to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Install Service, Control Service. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Environment Variables (Advanced Options)

The Environment Variables page lets you define system and user variables.

Creating New Variables

To create new environment variables, follow these steps:

  1. Click the New button. The Set Environment dialog box appears.
  2. Fill in the dialog fields.
  3. Click OK to accept your changes.

Updating Variables

To update previously declared environment variables, follow these steps:

  1. Select the variable to update.
  2. Click the Edit button.
  3. Update the dialog fields.

Removing Variables

To remove environment variables, follow these steps:

  1. Select the variable to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Set Environment. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Access Control (Advanced Options)

The Access Control page sets access permissions on a variety of system objects, including files, folders, registry keys, shares, services, and printers.

Setting Access Permissions

To set access permissions on a system object, follow these steps:

  1. Click the New button. The Set Access Control dialog box appears.
  2. Fill in the dialog fields.
  3. Click OK to accept your changes.

Updating Access Permissions

To update access permissions on a system object, follow these steps:

  1. Select the system object to update.
  2. Click the Edit button.
  3. Update the dialog fields.

Removing Access Permissions

To cancel setting permissions on a system object, follow these steps:

  1. Select the system object to no longer set permissions for.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Set Access Control. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Run Programs (Advanced Options)

The Run Programs page allows you to run external programs as a part of your installation process. You may also specify the timing of program execution while inserting the run request.

Running a Program

To run a program, follow these steps:

  1. Click the New button. The Run Program dialog box appears.
  2. Enter the full path to the program to run in the Program File field. You may click the Browse button to specify a program that is part of your setup, or you may refer to pre-existing files on the target system. You may also enter Internet URLs in this field to open them in the default browser.
  3. In the Run Timing field, choose the timing that best describes your usage scenario.
  4. In the Run Options field, you may specify commmand line parameters to the program, and optionally wait for the program to finish running before returning control to setup.
  5. Click OK to accept your changes.

Updating Run Options

To update the run settings for a program, follow these steps:

  1. Select the program to update.
  2. Click the Edit button.
  3. Update the necessary fields in the Run Program dialog box.

It is not possible to change the timing of a run command once it has been created. To change the timing, delete the existing command, and then re-create the command with the correct timing.

Removing a Run Program Command

To cancel running a program:

  1. Select the program to delete.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Run Program. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall. Additional commands may be required for the Run Timing Finish Dialog option. Template and wizard generated setups provide all necessary commands.


Drivers (Advanced Options)

The Drivers page allows you to install drivers on the target system.

Installing a Driver

To install a driver, follow these steps:

  1. Click the New button. The Install Driver dialog box appears.
  2. Enter the full path to the driver to install in the Driver Inf File field. You may click the Browse button to specify an INF file that is part of your setup, or you may refer to pre-existing files on the target system.
  3. In the Platform field, choose the processor architecture for your driver.
  4. In the Driver Installation Options field, choose additional driver installation options.
  5. Click OK to accept your changes.

Two new items are now visible in the Drivers page. One of them is for the driver installation, and the other is for the driver uninstallation, which is handled automatically for you at the same time your setup is being uninstalled. If you would not like for the driver to be automatically uninstalled when setup is being removed, select the item pertaining to the uninstall, and delete it.

Updating Driver Options

To update the installation/automatic uninstallation settings for a driver, follow these steps:

  1. Select the driver to update.
  2. Click the Edit button.
  3. Update the necessary fields in the DIFx Driver Installation dialog box.

Removing a Driver Installation

To cancel installing (and automatically uninstalling) a driver:

  1. Select the driver and the step to delete.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: DIFx Driver Install. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


Local Files (Advanced Options)

The Local Files page allows you to copy, move, or delete files already existing on the target system (local files).

Adding a New Local File Action

There are two groups of local file actions that you may add.

Copying/Moving Local Files

To copy or move a local file as part of your setup, follow the steps below:

  1. Click the New button.
  2. Choose Copy/Move Local File(s).
  3. The Copy/Move Local Files window appears. Populate the fields in this dialog..
  4. Click OK to save your changes.

Deleting Local Files

To delete a local file as part of your setup, follow the steps below:

  1. Click the New button.
  2. Choose Delete Local File(s).
  3. The Delete Files window appears. Populate the fields in this dialog.
  4. Click OK to save your changes.

Updating an Existing Local File Action

To update an existing local file copy, move, or delete action:

  1. Select the entry to update.
  2. Click the Edit button.
  3. Populate the fields in the dialog which appears.
  4. Click OK to save your changes.

Deleting a Local File Action

To remove an existing local file copy, move, or delete action:

  1. Select the action to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Copy/Move Local Files, Delete Files. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


IIS Sites (Server Configuration)

The IIS Sites page allows you to create new IIS websites and virtual folders.

New virtual folders created in this page also have accompanying elements inserted in the Access Control page. These accompanying elements grant anonymous Internet user access rights to the virtual folders that are defined in this page.

IIS Websites

Creating a New IIS Website

To create a new IIS website:

  1. Click the New button.
  2. Click the Web Site option.
  3. In the Create IIS Site dialog that appears, enter the properties for your new website. The properties displayed in this dialog are very similar to the properties seen in the native IIS manager and you may copy-paste properties to use them in your setup.
  4. Click OK to accept your changes.

Updating an Existing IIS Website

To update an existing IIS website:

  1. Select the web site identified by its name in the list of websites.
  2. Click the Edit button.
  3. In the Create IIS Site dialog that appears, update the properties for your website. The properties displayed in this dialog are very similar to the properties seen in the native IIS manager and you may copy-paste properties to use them in your setup.
  4. Click OK to accept your changes.

Deleting an Existing IIS Website

To delete an existing IIS website:

  1. Select the web site identified by its name in the list of websites.
  2. Click the Delete button.

Deleting an IIS website that contains virtual folders underneath does not remove the virtual folders automatically.

Virtual Folders

Creating a New Virtual Folder

To create a new virtual folder:

  1. If you will also be creating the website that the virtual folder is a part of, first create that website and select it. If not, skip this step.
  2. Click the New button.
  3. Click the Virtual Folder option.
  4. Virtual folders are created underneath existing websites. The existing sites can be identified by their name or site index. Choose a method to identify the existing site here.
  5. Enter the name or index of the site and click OK to continue.
  6. In the Create IIS Virtual Folder dialog that appears, enter the properties for your new virtual folder. The properties displayed in this dialog are very similar to the properties seen in the native IIS manager and you may copy-paste properties to use them in your setup.
  7. Click OK to accept your changes.

When you create a virtual folder underneath a site that is not explicitly created by your setup, a non-editable site will appear in the web sites view as container for the virtual folder you just created. If you need to edit the properties of this parent site, just explicitly create it in your setup.

Updating an Existing Virtual Folder

To update an existing virtual folder:

  1. Select the virtual folder to update from the list of virtual folders.
  2. Click the Edit button.
  3. In the Create IIS Virtual Folder dialog that appears, update the properties for your virtual folder. The properties displayed in this dialog are very similar to the properties seen in the native IIS manager and you may copy-paste properties to use them in your setup.
  4. Click OK to accept your changes.

Deleting an Existing Virtual Folder

To delete an existing virtual folder:

  1. Select the virtual folder to delete from the list of virtual folders.
  2. Click the Delete button.

If the virtual folder appeared underneath an existing IIS website that is not explicitly created by your setup, and there are no more virtual folders underneath that same website; the non-editable site will disappear from the view upon deletion as well.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Get IIS Site Index, Create IIS Site, Delete IIS Site, Create IIS Virtual Folder, Delete IIS Virtual Folder, Get System Settings, and Set Access Control. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


Shared Folders (Server Configuration)

The Shared Folders page allows you to create network shares on local or remote systems on the network.

Creating a New Share

To create a new share, follow these steps:

  1. Click the New button.
  2. The Create Share window appears. Populate the fields in this window to describe your share.
  3. Click OK to save your changes.

Editing an Existing Share

To update an existing share, follow these steps:

  1. Highlight the network share to edit.
  2. Click the Edit button.
  3. The Create Share window appears. Update the fields in this window to revise your share.
  4. Click OK to save your changes.

Removing an Existing Share

If you would like to remove a share that is being created by your setup, follow these steps:

  1. Highlight the network share to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create Share, Delete Share. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


SQL Databases (Server Configuration)

The SQL Databases page allows you to connect to local or remote database servers and run SQL scripts on them. Absolutely no client software is required on the host machine for the connections, which are carried directly over TCP/IP. In addition, you may use any number of script variables in your connection settings as well as the SQL scripts themselves.

Creating a New Connection

To create a new connection to a SQL server and execute a SQL script, follow these steps:

  1. Click the New button.
  2. Choose the server type to connect to.
  3. Depending on your choice, a MS SQL Server, My SQL, or Oracle Database window appears. Populate the necessary dialog fields for the connection and load your SQL script into the dialog.
  4. Click OK to save your changes.

Editing an Existing Connection

To update an existing SQL server connection, or modify the SQL script, follow these steps:

  1. Highlight the connection to edit.
  2. Click the Edit button.
  3. Depending on your connection, a MS SQL Server, My SQL, or Oracle Database window appears. Update the necessary dialog fields for the connection and if necessary modify your SQL script in the dialog.
  4. Click OK to save your changes.

Removing an Existing Connection

If you would like to remove a SQL server connection (and its associated SQL script), follow these steps:

  1. Highlight the connection to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: MS SQL Server, My SQL, Oracle Database. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install.


Scheduled Tasks (Server Configuration)

The Scheduled Tasks page lets you configure tasks to run on the target system using the Windows Task Scheduler as part of your setup.

Scheduling a Task

To schedule a task, follow these steps:

  1. Click the New button. The Schedule Task dialog box appears.
  2. Fill in the dialog fields.
  3. Click OK to accept your changes.

Updating a Scheduled Task

To update a scheduled task, follow these steps:

  1. Select the task to update.
  2. Click the Edit button.
  3. Update the dialog fields.

Removing a Scheduled Task

To cancel scheduling a task, follow these steps:

  1. Select the task to cancel.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Delete Scheduled Task, Schedule Task. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


Users and Groups (Server Configuration)

The Users and Groups page allows you to create new user accounts, add user group membership to existing user accounts, and create new user groups.

User Accounts

Creating a New User Account (or Adding User Group Membership to an Existing User Account)

To create a new user account, or to add an existing user account to one or more user groups:

  1. Click the New button.
  2. Click the User option.
  3. Populate the dialog fields in the Create User dialog that appears. If you are not creating a new user account but adding user group membership to an existing user account, only the User Name and Remote Server fields are needed to identify the account to update.
  4. Click OK to accept your changes.

Updating a User Account Operation

To update an existing user account operation:

  1. Select the user account to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Create User dialog that appears.
  4. Click OK to accept your changes.

Removing a User Account Operation

To remove an existing user account operation:

  1. Select the user account to no longer process.
  2. Click the Delete button.

User Groups

Creating a New User Group

To create a new user group:

  1. Click the New button.
  2. Click the Group option.
  3. Populate the dialog fields in the Create Group dialog that appears.
  4. Click OK to accept your changes.

Updating a User Group Operation

To update an existing user group operation:

  1. Select the user group to update.
  2. Click the Edit button.
  3. Update the dialog fields in the Create Group dialog that appears.
  4. Click OK to accept your changes.

Removing a User Group Operation

To remove an existing user group operation:

  1. Select the user group to remove.
  2. Click the Delete button.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Create User, Delete User , Create Group , Delete Group. Additional general scripting commands may be emitted.

Commands Required

This page requires the following scripting commands to be already present in your setup script: Apply Install, Apply Uninstall.


Build Settings (Deployment)

The Build Settings page allows you to set the default media type for your setup project, as well as specify a custom output folder, and a custom output filename.

InstallAware recommends that while testing and debugging your setups, you always use the Uncompressed Directory Layout option on this page. Compressed build types take a lot of time for processing, and cannot be debugged unless the Debug Build check-box is checked. Unless you are experiencing a problem which occurs only when running compressed setups, always build and debug your setups using the Uncompressed Directory Layout option. This will provide optimal build times and significantly accelerate your testing and debugging cycles. Once your setup has been fully tested and is working properly, you can switch to your actual deployment type(s).

You may also build your setup for more than one media at a time using the Batch Build option.


Web Media Blocks (Deployment)

The Web Media Blocks page allows you to configure the names and download locations of your web media blocks. Web media blocks are created when you build your setups using the Compressed Web Based EXE media type.

Web media blocks enable partial web deployment: You may build setups that are fully self contained and install without mandating an Internet connection, as long as all product runtimes are available on the target system. Internet downloads will only occur if required runtimes are unavailable.

Web media blocks can also contain rarely used application features, along with application runtimes. You have the complete freedom in deciding what goes where when building your setups.

Editing a Web Media Block

To edit a web media block:

  1. Click the web media block to edit.
  2. Click the Edit button.
  3. Make the necessary changes in the Define Web Media Block window that appears.
  4. Click OK to save your changes.

If you will be updating download URLs for multiple web media blocks, try the Refactor Paths tool which can do the task in a single pass.

Building - Skipping Web Media Blocks

You may share web media blocks between setup projects, and this makes particular sense for application runtimes, such as the .NET Framework, which do not change at all once a version has been released. Instead of re-building web media blocks (which can be a time consuming operation depending on your compression strength), and re-uploading them (which can be a bandwidth consuming process based on the runtime size), you can build your web media blocks once, upload them once, and then leave them untouched.

In the above scenario, and other similar cases, it is best to skip building web media blocks for subsequent builds. To skip building web media blocks, highlight them and click the Skip Selected button. InstallAware will no longer copy or compress files inside the chosen web media blocks during the build process.

If you later need to rebuild those web media blocks, you can always highlight them and click the Build Selected button.


Authenticode Signature (Deployment)

The Authenticode Signature page allows you to sign your setups digitally using code signing certificates. To use code signing, you must first obtain a certificate from a certificate authority. Once you have your code signing certificate, check the Sign the package with Authenticode field, and populate the authenticode fields.


Merge Modules (Deployment)

The Merge Modules page allows you to add merge modules to your setup project. Merge modules are Windows Installer databases with files and logic necessary to install third party runtimes or dependencies.

This page is very easy to use:

  • Click the Add button to add a merge module to your project.
  • Click the Remove button to remove a merge module that is already a part of your project.

You may also import merge modules and directly include them in your setups as InstallAware script code using the Database Import Wizard.


Patches (Deployment)

The Patches page allows you to build patches against older versions of your product installations. Patches are built using binary differential scans and contain only the delta of the changes between the older setups and the newest setup.

Adding Patch References

Before you may build a patch, you need to let InstallAware know where it can find the older versions of your setup. If you are planning to create patches, it is best to keep all old versions of your product handy, so you can reference them in your patches:

  • Click the Add button to add an InstallAware setup to your project as a patch reference.
  • Click the Remove button to remove previously added patch references.

You may only add InstallAware setups as patch references to your project.

Building Patches

Once you have added your patch references, click the Build Patch button and watch InstallAware build a patch that upgrades your older versions to the latest version with just a single click of the mouse!

When the patch is built, click the Browse button to go directly to the build folder containing your patch files. You may now distribute your patch to end users.


Power Tweaks (Deployment)

The Power Tweaks page allows you to control advanced setup switches. While these advanced setup switches have been available in InstallAware for quite some time, this page exposes them in one convenient location, together with pre-sets for quick tuning.

Some of these switches are stored in pre-defined variables. Others are stored in pre-defined compiler variables.

A few of the switches are stored in global project settings, and not in pre-defined variables or compiler variables: MSICODE_STATEMENT_IDS, REDUCE_MSI_FILE_COMPONENTS, and REDUCE_MSI_REGISTRY_COMPONENTS. While these names have been fashioned to sound like pre-defined variables or compiler variables, they are actually neither.

Mouse-over a feature, or click a setting, to receive an extended description of what the setting does and how it may be used to enhance your setups. If you would like to restore a setting to its default value, click the Restore button.

After you have finished making changes, click the Apply button to apply them to your project and main setup script; or click the Cancel button to discard these changes without applying them. If these buttons are not visible on your terminal due to low monitor resolution, simply switch to another page to be prompted to save or discard your changes. Changes made in this page are not saved until explicitly applied by using either the Apply button or the page switching method intended for lower resolution displays.

Global Settings

These settings apply to both Windows Installer and Native Engine setups built with InstallAware.

Native Engine Settings

These settings apply only to Native Engine setups built with InstallAware.

To create a new setup project that can use the Native Engine or Hybrid Installation Technology (both of the Native Engine and Windows Installer engines within the same setup), use the Native Setup project template.

To use the Native Engine or Hybrid Installation Technology in an existing setup project, open two instances of the InstallAware IDE (enabling it, if necessary, via the IDE Options window). Load your existing setup project in one, and create a new setup project using the Native Setup project template in the other. Copy-paste code from the template project into your existing project as necessary.

Windows Installer Settings

These settings apply only to Windows Installer setups built with InstallAware, with one exception:

The NO_MSI setting applies only to Native Engine setups built with InstallAware which are NOT based on Hybrid Installation Technology (setups which never use the Windows Installer engine, and are entirely powered by the Native Engine). For such setups, you may want to disable MSI file creation. This would both shorten setup build times, and reduce setup payload size.

Automatic Settings

To permit InstallAware to automatically optimize your setup switches for you, check the Use my preference emphasizing box, and move the slider towards either Performance or Integrity. A total of three automatic pre-sets are available, including Balanced which attempts to strike a best-of-both-worlds between the two other poles.

Scripting Details

The two-way integrated IDE emits or updates the underlying setup script every time the visual view is used. If you are using InstallAware scripting in your setups, the following information identifies the changes made by this visual page to your setup script.

Commands Used

This page emits the following types of scripting commands: Set Variable . Additionally, pre-defined compiler variables and global project settings are modified by this page.

Commands Required

This page does not require any scripting commands to be already present in your setup script.


Trialware and DRM (Deployment)

The Trialware and DRM page lets you protect your applications using InstallAware Digital Rights Management. Wrap your existing binaries and protect your intellectual property with absolutely zero changes to your code. Choose from a diverse range of trial parameters, and optionally enable ecommerce to instantly sell wrapped applications to end-users.

To use a stand-alone version of InstallAware DRM, run the InstallAware DRM tool. This tool runs outside of the InstallAware IDE and may also participate in automated build processes (such as batch files).

Convert Application into Trialware

Application to Convert (*.EXE)

Enter the full path to the application to convert into trialware. This application must already be one of the files being installed by your setup. Click Browse to visually select the file. If the file is installed as part of a larger group (using, for example, a wildcard pattern such as *.*), it may not be visible to the visual file browser. In this case, manually enter the path the file will be present on the target system in this field.

Unique Identifier (GUID)

Choose a unique identifier for your application. Click Options to automatically enter your project's existing product code or revision code; or alternately to create a brand new GUID. Once an application associated with a particular GUID has expired on a target system, installing a newer version of the same application that has been protected using the same GUID will not restart the trial period - the application will still remain expired.

Application Cost (USD)

Enter the US dollar cost of your application in this field.

Always expire after:

Select this radio button to unconditionally expire your application (and require a purchase for restoring access to it) when a certain number of launches and/or days have passed since the initial installation - even if the application has not been actually used during that time. Recommended for shareware and commercial demonstration applications.

Number of launches

Check this box and specify the maximum number of times your application may be lauched after its first use before expiring. Recommended for shareware applications.

Number of days

Check this box and choose one of the options below.

Days after installation

Select this radio button and specify the maximum number of days your application may be used for after its first launch before expiring. Recommended for commercial demonstration applications.

Absolute expiration date

Select this radio button and specify a hard-coded expiration date for your application - regardless of whether it has been used at all by then. Recommended for time limited beta software that must expire at a certain fixed date.

Expire only after actual use:

Select this radio button to expire your application only after live, actual use - as specified by the total number of hours and minutes allowed. Recommended to provide the most fair trial experience for your end-users.

Add Instant Purchase Capability

Softwrap Certificate File (*.SW9)

Enter the full path to the Softwrap certificate file (as found on your development machine) in this field. Do not include this certificate file in your setup.

If a certificate is not provided in this field, your application will be converted into a Try-and-Die package. Recommended if you would like to use your own ecommerce technology in empowering the sale of your application to your end-users.

If a certificate is provided in this field, your application will be converted into a Try-and-Buy package. Recommended if you would like to use Softwrap's ecommerce technology in empowering the sale of your application to your end-users, directly within the wrapped application itself.


Update Packs (Web Updates)

The Update Packs page allows you to define the updates that are available for your applications on the field. An update can consist of any downloadable file, and will typically be a setup executable; such as an incremental update built using the Patches page, or a full blown major version installer that completely uninstalls the previous version.

An update pack may be served to more than one version of an application. You associate update packs with your available application versions on the Versions page.

Your edits to this page are written immediately to an updates.ini file, which is saved in your project folder. You may also manually edit this regular INI-format file. This INI file will also be copied to your build output location every time you execute a build.

At runtime, setup attempts to download this file from the location specified in the Monitor URL field of the Project Properties page to determine if updates are available for your application. Of course, the Receive Application Updates check-box must be checked in the Project Properties page for setup to check for application updates.

Creating a New Update Pack

To define a new update pack , follow these steps:

  1. Click the New button. The Update Pack dialog box appears.
  2. Enter the full name of your update in the Update name field. This will be the update title that is visible to end-users at runtime.
  3. Enter the full download location of your update in the Full download URL for update installer field. When the end-user selects this pack at runtime, setup attempts to download it from this exact location.
  4. Enter a detailed description for your update in the Update description field. This description will be available for the end-user to read and decide whether to install the update.
  5. Check the Reboot after running update installer box if you require that the target computer should be restarted after installing your update. To improve the end-user experience, individual reboots are always supressed while multiple update packs are being silently installed. If at least one update pack has specified this option, a single global reboot will be performed once all selected update packs have been installed.
  6. Check the Silently run update installer box to allow your update to be silently installed. To improve the end-user experience, it is recommended that updates be silently installed.
  7. If there are any command line parameters you would like to pass to the update program, enter them in the Additional command line parameters for update installer field.
  8. Click OK to accept your changes.

Editing an Update Pack

To change the properties of a previously defined update pack, follow these steps:

  1. Select the update pack to edit.
  2. Click the Edit button.
  3. Update the necessary fields in the Update Pack dialog box.

Deleting an Update Pack

To delete a previously defined update pack:

  1. Select the update pack to delete.
  2. Click the Delete button.


Versions (Web Updates)

The Versions page allows you to broadcast update packs defined in the Update Packs page to copies of your application already installed on the field.

Your edits to this page are written immediately to an updates.ini file, which is saved in your project folder. You may also manually edit this regular INI-format file. This INI file will also be copied to your build output location every time you execute a build.

At runtime, setup attempts to download this file from the location specified in the Monitor URL field of the Project Properties page to determine if updates are available for your application. Of course, the Receive Application Updates check-box must be checked in the Project Properties page for setup to check for application updates.

Defining an Application Version

To define an application version, follow these steps:

  1. Click the Add button. The New Application Version dialog box appears.
  2. Enter an application version in the Version field. This value must be identical to the version number displayed in the Product Version field of the Project Properties page for the already installed versions of your application on the field that you want to update.
  3. Click OK to accept your changes.

Serving Update Packs for an Application Version

To choose the update packs that are served for an application version:

  1. Select the application version to receive the packs under the Application Versions heading.
  2. Check the packs you wish to broadcast to this application version under the Update Packs Served for Selected Version heading.
  3. If necessary, use the Up and Down buttons to re-order the order in which packs will be installed.

Removing an Application Version

To remove a previously defined application version:

  1. Select the application version to remove under the Application Versions heading.
  2. Click the Remove button.


Starting the Dialog Editor

There are several ways to start the InstallAware User Interface Editor.

  • Start the Dialog Editor from the Start Menu shortcut.
  • Press the F12 key while the InstallAware IDE is running.
  • Double-click or press ENTER while a dialog is selected in the Project Manager window. This will load the selected dialog into the editor.

Once the Dialog Editor is started, if an existing dialog is not already loaded, choose File [image] Open to load a dialog into the editor, or work with the empty dialog design.


Using the Dialog Editor

You may use the Dialog Editor to perform any of the following tasks:

  • Add new controls to existing dialogs
  • Customize or remove existing controls on dialogs
  • Pass the values of dialog controls and script variables between one another
  • Customize themes and graphical elements to meet your needs
  • Design entire themes from scratch

Once you've started the Dialog Editor, the general editing process can be summarized in the following steps:

  1. If the dialog you wish to edit is not already loaded, choose File [image] Open to load it. You may also prefer to start with an empty dialog (to do so, start the editor without any command line parameters, for instance from the Start Menu shortcut).
  2. Explore the various tabs (Standard, Additional, Win32, Browser) and get a feel for the available range of dialog controls.
  3. Click on the control you wish to add to the dialog. Then click on the dialog where you wish to place the control.
  4. Position and size the control precisely using the grab handles. You may also use the keyboard in this process.
  5. Explore and set the various properties of the control as visible in the Object Properties window.
  6. Add any further controls, and modify/remove existing ones as required.
  7. Define the way controls in the dialog respond to one another. For instance, you may want to disable a Next button until the license agreement has been accepted.
  8. Specify how your dialog receives information from the setup script. For instance, you may want to define which controls receive the list of available application features.
  9. InstallAware makes it very easy to pass variables between the dialogs and the script. Associate dialog controls with variables.
  10. Choose File [image] Save to save your dialog, or File [image] Save As to save it under a new file name.
  11. Choose Tools [image] Test Dialog to test your dialog before finalizing your changes. If you need to close the dialog while testing, press ALT+F4.


Dialog Controls

The table below summarizes available dialog controls, the tabs they are available on, and example areas for their use.

Page | Control | Usage
Standard | Label | Display static text, clickable links
Standard | Edit Box | Obtain information from user
Standard | Memo | Display readme, license agreements
Standard | Button | Navigate between dialogs, exit setup
Standard | Rz Check Box | Accept license agreement, display other choices
Standard | Rz Radio Button | Accept license agreement, display mutually exclusive choices
Standard | List Box | Display list of items
Standard | Combo Box | Display drop-down list of items
Standard | Group Box | Define a group, use for isolating radio buttons
Standard | Panel | Add a panel or bevel
Additional | Bitmap Button | A button with a bitmap
Additional | Speed Button | A button with a bitmap and no text
Additional | Masked Edit | Edit box with masked characters, useful for passwords
Additional | Picture | Any bitmap or icon, clickable
Additional | Shape | A geometric shape in any color
Additional | Bevel | Bevel useful for defining dialog regions
Additional | Static Text | Display textual progress, static text
Additional | Gauge | Display installation progress using custom progress control
Additional | Rz Form Shape | Create non-rectangular setup dialogs
Win32 | Rich Text | Display RTF files, license agreements, readme information
Win32 | Track Bar | Allow user to select a numeric range
Win32 | Progress Bar | Display installation progress
Win32 | Up Down Button | Single step increment and decrement
Win32 | Animation | Display built in Windows animation, or custom AVI file
Win32 | Check-List Box | Useful for displaying a selectable, flat list of setup features
Win32 | Tree View | Useful for displaying multiple hierarchies of nested setup features
Browser | HTML View | Display interactive html or billboards during installation progress
Browser | Flash Frame | Display interactive flash billboards during installation progress
Browser | File List Box | For file selection
Browser | Directory List Box | For folder selection
Browser | Drive Combo Box | For drive selection
Browser | Filter Combo Box | To constrain file types shown on the file list box
Browser | Shell Tree View | For Explorer style folder selection
Browser | Shell List View | For Explorer style file selection
Browser | Shell Combo Box | For Explorer style folder selection
Glass | Vista Glass | Define a glass region on the setup dialog (not visible at design-time)
Glass | Glow Label | Display textual progress, static text; together with an Aero glow effect (on supported platforms)
Glass | Aero Button | Navigate between dialogs, exit setup; works on Glass regions
Glass | Aero Back Button | Navigate between dialogs, exit setup; works on Glass regions and displays a circular back icon
Glass | Aero PNG Button | Navigate between dialogs, exit setup; works on Glass regions and displays a custom PNG file
Glass | Aero PNG Image | Any PNG image, clickable; works on Glass regions


Intra-Dialog Relations

While working on dialogs, you will realize you need to constrain the behavior of controls shown on the dialogs. A step-by-step procedure is provided below for defining relations in between your dialog controls.

  1. Make sure the dialog contains the controls that are expected to interact with one another.
  2. Double-click one of the controls. The Define Interactive Characteristics dialog appears. Select the Object Rules tab on this dialog.
  3. If you have any existing relations previously defined, they show under the Existing Rules pane. You may highlight rules and move their processing order up or down, or delete the rules altogether. Keep in mind that rules will be processed at runtime following a top-down order.
  4. In the When Control drop down menu, select the control whose state will effect the other control. Controls are listed on this drop down menu by their Name property accessible from the Object Properties window.
  5. Choose the property you wish to check for in the Has Property drop down menu.
  6. Enter the property value in the Equal To field as a string. You may also check not if you wish to test for the exclusion of this property.
  7. In the Change Control drop down menu, choose the target control.
  8. Pick the Property Value to modify from the drop down menu.
  9. Enter the new value into the To New Value field as a string.
  10. Click the Add button to add your new rule to the list of existing rules. Click Replace instead to replace the currently highlighted rule in the Existing Rules pane with the new rule.
  11. If you later wish to customize an existing rule, simply click that rule in the Existing Rules pane. All fields in the rule editor will be automatically populated. You can update your rule and click Replace to store your changes.
  12. Be sure to click Close on the dialog to finalize your changes, and save your dialog in the main editor.

Notes

  • To see example dialog relations in action, open any license agreement dialog.
  • Test the behavior you defined in the main editor by choosing Tools [image] Test Dialog.


Dialog Behavior

In addition to defining relationships between dialog controls themselves, you will also want to connect dialog controls with the installation itself, so that the dialog will receive and display information about the running setup, such as progress information. The procedure for setting up these connections is described below.

  1. Make sure the dialog contains the controls that you wish to display script information in.
  2. Double-click one of the controls. The Define Interactive Characteristics dialog appears. Select the Object Behavior tab on this dialog.
  3. In the Control drop down menu, select the control that will receive setup information. Controls are listed on this drop down menu by their Name property accessible from the Object Properties window.
  4. Depending on the kind of control selected, the fields Receives Information, Writes Values to Variable, and Performs Action will disable or enable.
  5. Interact with the enabled fields to define the setup information that the control will reflect.
  6. Be sure to click Close on the dialog to finalize your changes, and save your dialog in the main editor.

Notes

  • To see example dialog behaviors in action, open any pre-defined setup dialog. Each dialog will have some behaviors defined.
  • Test the behavior you defined in the main editor by choosing Tools [image] Test Dialog.


Passing Variables

InstallAware makes it very easy to connect variables used in the setup script to dialog elements. This makes extracting information the user entered into the setup dialogs a trivial task.

Passing Values from Dialogs to the Script

  1. Make sure the dialog contains the control that you wish to extract information from.
  2. Double-click the desired control. The Define Interactive Characteristics dialog appears. Select the Object Behavior tab on this dialog.
  3. In the Control drop down menu, confirm the desired control is selected. Controls are listed on this drop down menu by their Name property accessible from the Object Properties window.
  4. If the control contains any meaningful information that can be passed back to the script, the Writes Values to Variable field will enable.
  5. Type in the Write Values to Variable field the name of the script variable that you wish to hold control information. This variable must already be defined in your setup script before the dialog is shown. Do not use dollar signs surrounding the variable while you are entering its name here. For instance, if your variable is called MYVAR, input MYVAR into this field. Do not input $MYVAR$.
  6. Be sure to click Close on the dialog to finalize your changes, and save your dialog in the main editor.

An example dialog box illustrating this concept is the setup type dialog.

Passing Values from the Script to Dialogs

While under most circumstances the above procedure will establish a two-way link between the control and the script variable in question, you may want to explicitly obtain the value of a variable, and assign it to a dialog control as a property. You may then use this property in controlling the state of other dialog controls.

  1. Add a label to the dialog. Give the label a descriptive name.
  2. Set the visible property of the label to FALSE using the Object Properties window. Since this control is only used internally, we do no want the end user to see it.
  3. Set the caption property of the label to the dereferenced variable. For instance, if the script variable you wish to capture is called MYVAR, set the caption to $MYVAR$.
  4. Use the caption property of this label in defining intra-dialog relations.

An example dialog box illustrating this concept is the finish dialog.


Building Aero Glass Dialogs

Most setup dialogs automatically transition between Aero, Basic (both available beginning with Windows Vista), Themed (available beginning with Windows XP) and Classic (available beginning with Windows 95) Windows user interfaces, rendering correctly on all four automatically. If your dialog does not contain a VistaGlass control, your dialog will work perfectly and no additional effort is required on your part.

However, if you are using the VistaGlass control, and you have enabled Glass regions, then additional effort on your part may be necessary to ensure your dialog supports all four Windows themes - taking advantage of advanced features such as Desktop Composition where available (rendering some or all of the dialog on Glass), but still looking good on older Windows versions where composition may be unavailable.

When developing dialogs with Glass regions, always be sure to test on all four Windows themes:

  • Aero: With translucent Glass regions (works on Windows Vista or newer).
  • Basic: With "fake" Glass regions that look different from the rest of the dialog, but are not translucent (works on Windows Vista or newer).
  • Themed: Without Glass regions, but with support for themed rendering of dialog controls (works on Windows XP or newer).
  • Classic: Without Glass regions, and without theming for controls (works on Windows 95 or newer).

Best Practices

You may use the pre-defined variable $GLASS$ to determine if the Aero or Basic theme is active, and adjust the visibility of your dialog controls accordingly.

This way, you may build dialogs that look different (and at their best) based on whether Glass regions (even if only "fake") are visible or not, which is the most major consideration when building dialogs that leverage the Aero user interface.

Emulating the Aero Wizard Design

You may also design your dialogs such that no duplicate controls are needed. InstallAware strives to maintain your freedom in designing dialogs with as little manual overhead as possible, while allowing you full use of your creativity and still being standards-compliant.

This is made easier since InstallAware automatically updates some dialog elements for universal Windows theme compatibility. An important standard introduced with the Aero user interface is the Aero Wizard, for which InstallAware provides extensive support.

InstallAware assumes that you are trying to build an Aero Wizard compliant dialog if:

  1. The VistaGlass control GlassEnabled property is True
  2. The dialog has its BorderStyle property set to bsSingle
  3. The VistaGlass control GlassTop property is larger than 0

If all of the above conditions are valid, then InstallAware will automatically make the following runtime changes for universal theme compatibility and for maintaining full design parity with the Aero Wizard look on all Windows themes, as has been implemented in Microsoft's own Aero Wizards.

When the Basic Theme is Active

  • The BorderStyle property of the dialog will be changed at runtime to bsSizeable. Dialog re-sizing will be prevented programmatically. The dialog will be grown slightly to account for the new larger borders while keeping the client area the same. The new border style matches the style used by Aero Wizard dialogs with the Basic theme.
  • A Shape control will be created at runtime, displaying a single line at the ending of the "fake" Glass top region. This matches the color used by Aero Wizard dialogs with the Basic theme.

When Windows is Older Than Windows Vista, or the Classic Theme is Active

  • If the dialog has its Color property set to clWhite (the color of Aero Wizard dialog backgrounds under the Aero or Basic themes), the Color property will be set to clBtnFace at runtime (the color of Aero Wizard dialog backgrounds under Themed or Classic themes).
  • A Shape control will be created at runtime, displaying a single line at the ending of the Glass top region, but in a different color than for the Basic theme.

The intention behind all these changes is to exactly mirror how Aero Wizard windows are rendered by Windows when Aero itself disabled but one of the Basic, Themed, or Classic themes are active.

Additional Compatibility Heuristics

InstallAware also provides additional theme compatibility heuristics, which are useful not only in Aero Wizard design but helpful with Glass design overall.

When the Aero Theme or Basic Theme is Active

  • If the VistaGlass control GlassEnabled property is True; and the VistaGlass control GlassTop property is larger than 0, or the VistaGlass control SheetOfGlass property is True, then the dialog caption and icon will not be rendered on the form caption.

When the Basic Theme is Active

  • If the VistaGlass control GlassEnabled property is True, all Glass regions on the dialog will be rendered as "fake" Glass regions (regions of alternate color on the form).

When Windows is Older Than Windows Vista, or the Classic Theme is Active

  • If the GlowLabel control Glow property is True, because the glow effect is unavailable under the themes in question, the label will be rendered in Bold typeface instead.

All Themes

  • If the VistaGlass control GlassEnabled property is True, the dialog may be moved directly by dragging on the Glass regions, in addition to the default behavior of moving the dialog by dragging the dialog title bar.

Preferred Dialog Controls

The dialog editor now displays a new Glass tab on the component palette.

  • Where possible, use controls from this tab as these controls have been designed from the ground up to work well on Glass.
  • If your desired control is not available on this tab, then check the other tabs.
  • Do not use a control from one of the other tabs when a substitute is already available on the Glass tab.


Support Files

InstallAware uses support files at several places throughout the installation. Support files are not actually installed onto the target system, but they are part of the installation package. They are available temporarily while the installation is executing and are cleaned up when the installer finishes execution. Some example support files are:

  • License agreement and readme files
  • Progress dialog content
  • Setup splash screen

You may add custom items to support files and access these files at runtime using the SUPPORTDIR pre-defined script variable. An example support file could be a small applet you need to run as part of your installation.


The Localization Process

InstallAware contains all the tools and resources necessary for you to localize your setups.

The Localization Wizard makes it easy for you, or any offsite third party, to localize your setups without having access to your development environment, your setup project, or the InstallAware IDE. This wizard extracts strings from your setup script and dialogs and creates a folder containing a helpful visual localization tool that you may freely send to outside parties (or your internal translation team) for localizing your setups. Once the strings have been translated, you may then import them from the same folder back into your InstallAware project.

For InstallAware generated strings found in your setup project, localizations may be performed automatically using the Localization Wizard. If you have not added any custom strings to your setups, the wizard can translate your projects for you automatically into a total of 35 languages.

In addition, the Translator tool helps you localize the global strings that are shared across all setup projects.

For more information:

  • Localization Wizard
  • Translator


Setup Command Line Parameters

Every InstallAware setup supports command line parameters for silent and logged installs. In addition, you may also set/override the values of variables used in your installation from the command line.

You may freely combine all of the parameters displayed below. See uninstalling from the command line for an example.

Silent Installs

With the silent install command line parameter set, the entire installation will execute silently, without a user interface, or any user intervention. When input is required on dialog boxes, the default values of dialog controls will be used.

<setup.exe> /s

In the above example, setup.exe denotes the main setup executable.

Logged Installs

If the logging command line parameter is set, the installation will keep a verbose log of all the internal installation variables, as well as Windows Installer's own installation log. Be aware that logging significantly decreases the runtime speeds of an installation.

<setup.exe> /l=<logfile.ext>

In the above example, setup.exe denotes the main setup executable, and logfile.ext is the full path to the desired log file.

Specifying a Setup Password

You may specify the password for encrypted setups on the command line. This will prevent displaying the password prompt box and attempt to use the password indicated on the command line. This option is most useful when used in conjunction with silent installations, since silent installations cannot prompt for a setup password.

<setup.exe> /k=<password>

In the above example, setup.exe denotes the main setup executable, and password is the setup password.

Specifying Original Setup Sources for Patching

To make sure the setup program does not prompt for the location of the original setup sources during a patch operation, you may use the patch source command line parameter.

<setup.exe> /p=<original setup sources>\data

In the above example, setup.exe denotes the main setup executable, and original setup sources is the full path to the folder containing the original setup sources. Be sure to specify the data subfolder inside the original setup source folder (the data subfolder exists in all InstallAware setups built in uncompressed mode). For more information, see Patch Source Resolution.

Setting Variable Values

To set the values of setup variables from the command line, possibly overriding their default values in the process, specify the variables and their values as follows:

<setup.exe> <VARIABLE_1>=<VALUE_1> [ ... <VARIABLE_N>=<VALUE_N>]

In the above example, setup.exe denotes the main setup executable, VARIABLE_1 is the name of a variable to set, and VALUE_1 provides the value the variable is set to receive. You may set values for an arbitrary number of variables from the command line.

Similar to the above example, to perform an advertised install of a product, the following command line could be used:

<setup.exe> ADVERTISE=TRUE


Classes of Commands

There are several types of commands which are available to you in your scripting. Below is an explanation of these types of commands.

Commands by Usage

The drag-drop MSIcode component palette sorts commands by their intended area of usage:

Scripting

Perform helpful manipulation of script variables (such as Parse String) and evaluate logical or mathematical expressions (such as Evaluate Expression and Mathematics).

Flow Control

Direct program flow (such as If), apply all pending changes to the system (such as Apply Changes), and quit setup (such as Reboot and Resume).

User Interface

Display wizard dialogs (such as Display Dialog), notify the user (such as MessageBalloon), and define user visible setup features (such as Define Component).

System Information

Do not alter the state of the underlying system, but obtain system information (such as Check Process, Get System Settings, and Read from Text File).

Windows Installer

Generate Windows Installer database table entries and modify the target system (such as Install Files, Create Shortcut, and Write Registry).

With the Windows Installer engine, these commands are not applied to the target system until Apply Changes is called, but "cached" until then.

With the Native Engine, these commands are applied immediately, unless the pre-defined variable $DELAYUNTIL_APPLYCHANGES$ is FALSE.

Direct Execute

For setup functionality that is not covered by the standard Windows Installer feature set, directly modify the target system (such as Create IIS Site, Delete Files Recursive, and Write to Text File). Unlike Windows Installer commands, these commands are never "cached" and execute immediately.

Compiler Directives

Statements that affect how your setup is compiled at build-time (such as Comment, Compiler Variable If, and Web Media Block).

Plug-Ins

Any custom command which is not built-in to the IDE, but installable as a plug-in to perform a specialized task (such as Call DLL Function, DIFx Driver Install, and MS SQL Instances).

Commands by Compiler Types

Each command type is highlighted differently in the script editor. This highlighting illustrates how the commands are viewed by the compiler:

Comment

Comments refer both to Comment commands and also portions of code which have been commented out.

Flow Control

These alter program flow, and include commands like Wizard Loop and If.

Plug-In

Plug-in commands perform highly customized actions, from installing runtimes to downloading files.

Directive

Compiler directives are not constrained by program flow and perform compile time tasks, such as the Web Media Block command.

Windows Installer

Windows Installer commands actually perform installation tasks and modify the target system. Every command in InstallAware which effects the target system is a Windows Installer command.

Modify System

Modify system commands finalize queued changes and execute Windows Installer. The Apply Changes command is in this category.

Label

Label commands are used in conjunction with GoTo Label commands.

Statement

Commands that display dialogs, obtain general system information, and perform other similar tasks fall in this category.


Using Variables

Most commands in InstallAware work with variables. You will be storing the state of your installation, choices the end user made, among other things, in your script variables. Keep the following things in mind when working with variables:

  • When specifying a variable for a command that expects a variable, just type in the variable name. For instance, if the variable is called MYVAR, simply type MYVAR.
  • With commands that do not specifically expect a variable, and work with string literals, you may still use variables, however you must dereference them. The syntax for dereferencing a variable in InstallAware is enclosing the variable name between dollar signs. For instance, if the variable is called MYVAR, dereference the variable using $MYVAR$. You may freely combine multiple dereferenced variables in your string literals.

Unless the command you are working with explicitly indicates otherwise, you can always use either a variable or a dereferenced variable.


Using Compiler Variables

InstallAware offers compiler variables in addition to regular, script variables. Compiler variables may be thought of as IFDEF statements available in traditional programming languages. The Compiler Variable If, Compiler Variable Else, and Compiler Variable End statements allow conditional compilation. In addition, much like constants, compiler variables may be used in the script to represent unchanging values.

The values compiler variables can take are set at compile time, either from the IDE or from the command line.

  • When specifying a compiler variable for a command that expects a compiler variable, just type in the variable name. For instance, if the variable is called MYCOMPVAR, simply type MYCOMPVAR.
  • With commands that do not specifically expect a variable, and work with string literals, you may still use compiler variables, however you must dereference them. The syntax for dereferencing a compiler variable in InstallAware is enclosing the variable name between pound signs. For instance, if the variable is called MYCOMPVAR, dereference the variable using #MYCOMPVAR#. You may freely combine multiple dereferenced compiler variables in your string literals.

You can always use compiler variables where regular string expressions are allowed, even if regular (script) variables have been prohibited.


Pre-Defined Variables

Each InstallAware project contains pre-defined variables. These variables are automatically initialized when setup begins based on the state of the target system, your project settings, and whether the application has been previously installed or not. The full list of pre-defined variables and the values they contain is displayed below:

  • ABORT: TRUE if the Cancel button has been clicked, FALSE if not. Setting this variable has no effect on the state of the Cancel button. Setting this variable back to FALSE when setup has been cancelled will permit the installation to continue executing tasks which normally check for setup cancellation and abort when setup is cancelled.
  • ABORTONERROR: Initially TRUE. Set this variable to FALSE if you still need the MSIcode script to continue executing in order to perform any custom logic when a low-level setup error (such as a web media block download error) or a user abort occurs. You should exercise care in overriding the default value of this variable. For instance, when a web media block download fails, setup normally aborts; if setup is permitted to continue after a web media block download failure, certain plug-in calls in the corresponding web media block region may fail, violating any assumptions you may have made about script execution. This variable is distinct from the variable ABORT in that while ABORT exclusively signals user cancellation, this variable signals any kind of setup cancellation or error, including low-level setup errors that are innate to the setup engine.
  • ABORTEDONERROR: Initially FALSE. The setup engine sets this variable to TRUE if an error occured, such as a failed web media block download; or the user cancelled the installation. Test this variable to see if an error occured when setting ABORTONERROR to TRUE (this variable is not updated by the engine otherwise). While the variable ABORT indicates user cancellations only, this variable indicates low-level setup engine errors or cancellations as well. Somewhat unlike what the name suggests, this variable does not mean setup has been cancelled, but that a setup cancelling-level event has occured.
  • ADVERTISE: TRUE if an advertised install has been requested, FALSE if not. The value of this pre-defined variable is typically set from the command line.
  • ALLUSERS: Initially TRUE if platform is NT, FALSE if not. Set to TRUE to perform an installation for all users and FALSE to perform an installation for the current user only.
  • CHARSET_OVERRIDE: Assists in building multi-lingual setups without having to duplicate dialogs for different character sets. Initially an empty string. Set to one of the following values to automatically adjust the character set of fonts used on all setup dialogs that will be subsequently displayed:
    Value | Meaning
    ANSI_CHARSET | ANSI characters.
    DEFAULT_CHARSET

    Default characters as set by Windows for non-Unicode programs on the target system.
    Also the default character set of all pre-built InstallAware setup themes and template projects.
    SYMBOL_CHARSET | Standard symbol set.
    MAC_CHARSET | Macintosh characters.
    SHIFTJIS_CHARSET | Japanese shift-JIS characters.
    HANGEUL_CHARSET | Korean characters (Wansung).
    JOHAB_CHARSET | Korean characters (Johab).
    GB2312_CHARSET | Simplified Chinese characters (mainland china).
    CHINESEBIG5_CHARSET | Traditional Chinese characters (Taiwanese).
    GREEK_CHARSET | Greek characters.
    TURKISH_CHARSET | Turkish characters.
    VIETNAMESE_CHARSET | Vietnamese characters.
    HEBREW_CHARSET | Hebrew characters.
    ARABIC_CHARSET | Arabic characters.
    BALTIC_CHARSET | Baltic characters.
    RUSSIAN_CHARSET | Cyrillic characters.
    THAI_CHARSET | Thai characters.
    EASTEUROPE_CHARSET | Includes diacritical marks for eastern european countries.
    OEM_CHARSET | Depends on the codepage of the operating system.
    Resetting this value back to an empty string will not revert any dialog fonts to their default character set used at design time.
  • CMDLINE: The command line string passed to the installation program.
  • COMPANY: The company manufacturing the product, as set in the Publisher Name field of the project options dialog.
  • COMPLETE: Initially TRUE. Indicates whether a complete installation will be performed.
  • COPYWEBLOCK: This variable has effect only when a web build is being installed. If empty, downloaded web media blocks are processed normally. If non-empty, the installer will copy each downloaded web media block, including the main setup.exe file in case of the pre-defined OFFLINE web media block, to the path specified by this variable. This allows data that is downloaded by setups from the web to be saved in any arbitrary folder for re-use after the original installation has been removed, or for archival purposes.
  • CUSTOM_TASKBAR_PROGRESS_ENABLED: Initially FALSE. By default, the taskbar progress shown on the new Windows 7 Taskbar is the main installation progress, as reflected by the PROGRESS variable. Set this variable to TRUE to display custom progress instead. If you are using web builds for your deployment mode, this can be useful to provide an overall installation progress to your end-users during the download phase of your individual web media blocks: since InstallAware updates the global installation progress during each individual web media block download and extraction, your end-users may find the new Windows 7 Taskbar progress confusing with web builds.
  • CUSTOM_TASKBAR_PROGRESS_MAX: Initially 100. Has no effect unless CUSTOM_TASKBAR_PROGRESS_ENABLED is TRUE. Set to the maximum progress value that you desire. Note that you may not set the minimum, which is always assumed to be 0.
  • CUSTOM_TASKBAR_PROGRESS_PERCENT: Initially 0. Has no effect unless CUSTOM_TASKBAR_PROGRESS_ENABLED is TRUE. Set to the current progress value that you desire.
  • DATADIR: The root of the directory containing the files to be installed.
  • DATE: The current date, reported in human readable textual form in the current locale.
  • DELAYUNTIL_APPLYCHANGES: This variable has no effect unless the native code setup engine is being used. Initially FALSE. If this variable is set to TRUE, the native code setup engine will attempt to emulate the behavior of the Windows Installer setup engine by deferring the execution of setup actions until Apply Install has been called. While this may reduce some setup agility, it may be useful in circumstances when emulating setup behavior found in older InstallAware versions is necessary. One additional benefit of delaying changes is guaranteed correct progress calculation over the entire set of setup actions which have been queued for installation - since native progress is initially calculated over the entire set of setup actions available in the script, it can be inaccurate based on the extent of setup actions that have actually executed. This variable also affects how errors and cancellations in installation actions are treated: If this variable is set to FALSE, the setup engine will consider errors or cancellations in individual setup actions as fatal, since each action is being applied atomically and immediately. If this variable is set to TRUE, the setup engine will not consider errors and cancellations in individual setup actions as fatal, since they will all be applied all at once. Setting ABORTONERROR to FALSE will enable setup to continue even when setup is not delaying installation actions; however in this case the setup script should periodically poll the value of the ABORTEDONERROR variable to ensure setup is still not continuing despite intentions of the end-user to abort.
  • ENGINECACHE: The folder for the locally cached copy of the setup executable. The setup executable is always locally cached for use during uninstallation of the product. In addition, this folder will also contain cached web media block downloads when a web build is installed. This folder's location will change when the value of the ALLUSERS variable changes. This folder may not yet exist before the product has been installed. This folder may be empty or deleted after the product has been uninstalled. This folder is always removed after uninstallation, although a reboot may be necessary for the removal to finalize.
  • EXEDIR: The folder containing the setup executable itself.
  • EXEFILE: The full path and file name of the setup executable.
  • GLASS: TRUE if the Aero theme or the Basic theme is available and enabled on the target system, FALSE otherwise. Requires at least Windows Vista for a positive evaluation.
  • GPOPATH: If an uncompressed directory layout is used, this variable is empty. If setup has not been deployed through Group Policy, this variable is empty. Otherwise set to the full path of the folder containing the Single File MSI that started the current installation.
  • IISHOST: Initially localhost. Indicates the host name to use for all IIS commands. Override to get/set the IIS metabase properties of a remote host.
  • LANGUAGE: Set to an empty string in non multi-lingual installs. In multi-lingual installs, holds the active language. Assign a new value to this variable to change the active language from within your setup script in multi-lingual installs.
  • LASTERROR: Initially an empty string. After Windows Installer executes, set to the last error that occured during execution, if any.
  • LICENSE: Initially FALSE. Indicates acceptance of the EULA.
  • LOGGED: Initially set to the full path for the log file requested in the command line. If an empty string, indicates no logging has been requested at the command line. Set to a valid path name to enable logging from script.
  • MAINTENANCE: Initially TRUE if the same version of the application has been installed before, FALSE otherwise.
  • MINIMUM: Initially FALSE. Indicates whether a minimum installation will be performed.
  • MODIFY: Initially TRUE. Indicates if the existing installation should be modified.
  • MSIFILE: The full path and file name of the setup installation database.
  • MYAH_COMPRESS_INSTALLER_CACHE: Initially TRUE. Indicates if the installer cache location for the setup engine should be compressed on NTFS volumes. Set to FALSE to disable installer cache compression.
  • MYAH_DISABLE_ROLLBACK: Initially FALSE. Indicates whether Windows Installer's built-in rollback functionality should be disabled during setup. Set to TRUE to disable rollback and improve runtime performance; however if setup is cancelled, this will leave the target system in an inconsistent state.
  • MYAH_DISABLE_VISTA_RESTART_MANAGER: Initially FALSE. Indicates whether the Restart Manager on Windows Vista should be disabled. Set to TRUE to disable the Restart Manager and improve runtime performance; however this may necessitate a reboot at the end of the installation if some files are in use by applications that the Restart Manager could have shut down.
  • MYAH_TIMEOUT: Indicates how many seconds InstallAware should wait for web downloads before concluding that the remote server is not responding and aborting the connection. Initially 10 seconds. If set to a non-numeric value, the initial value of 10 seconds will be assumed. This value is stored in the system registry and may affect other applications using the Internet Explorer download engine. InstallAware updates this shared registry value only during the time of an actual download and restores the former registry value after completing the download. The standard registry value is typically 3600 seconds or 60 minutes, which is a very long timeout delay and may unnecessarily stall your setups. However, you may still prevent InstallAware from changing this value at all by setting the variable to 0 before calling any script commands that may initiate a download.
  • MYAHLOGO: Initially an empty string. Setting this variable to TRUE will hide the InstallAware Wizard text appended to setup dialog captions.
  • NATIVE_ENGINE: Initially FALSE. Setting this variable to TRUE instructs InstallAware to perform setups using its own native code setup engine. This variable may be changed multiple times in your script to enter and exit native code installation mode on an as-needed basis. Native code installations perform much faster than Windows Installer installations. Native code installations can also immediately execute each setup action, without having to wait for a call to Apply Install - dramatically increasing your flexibility in building setups.
  • NATIVE_ERROR: Initially PROMPT. With the initial value, when setup errors occur during a native engine installation, the end-user will be prompted with an error description and the option to retry the operation, skip the operation, or abort the installation. Set to ABORT to automatically abort the installation any time an error occurs. Set to RETRY to automatically retry the failed operation when an error occurs (this setting is not recommended since setup may stall indefinitely retrying the same operation, without any indication of why it has hung there). Set to IGNORE to automatically skip failed operations. Setting this variable to any other value will be treated as the initial PROMPT value. This variable is also automatically updated when the end-user makes the choice to apply an error prompt decision to all further actions, so the setup script remains aware of the current choices made by the end-user (and may override such changes).
  • NATIVE_LOGGING: Initially an empty string. Has no effect unless the native engine is being used. Set to FALSE to prevent the logging of setup actions undertaken by the native engine. This will prevent such actions from being undone during an uninstallation or rollback. Stopping logging does not commit the in-memory log to disk (the log is committed when Apply Install is called). This variable may also be used to bind setup to an external (new or existing) setup log. When bound to an external log, all new setup actions executed by the native engine will be injected to the external log, instead of the default setup log. Any setup actions that have already been executed will be committed to the original log at the time of binding to the external log. Set back to an empty string or to an invalid path to revert to the original log for the installation being run. Set to the full path (without any file extensions) of an existing, valid InstallAware installation log to bind the running setup instance to an existing log. Any uninstall/rollback actions undertaken by a setup bound to an external log will use the external log as their basis, facilitating the removal of applications installed by InstallAware setups other than the current running instance (such as the automated uninstallation of the older version of an application that a newer setup is installing). To create a brand new setup log at a custom location instead, set to the full path (without file extensions) of the new log name to use. Note that brand new setup logs created at custom locations may not be detected by the MAINTENANCE, NATIVE_OLDLOG or the RECOMMENDEDUPGRADE variables; disabling your setup from automatically entering maintenance mode, and automatically detecting (and removing) older versions of your products on target systems. Bind to new setup logs when you wish to manually manage a list of setup log stores, such as to facilitate a multiple-instance installation experience with the native engine.
  • NATIVE_OLDLOG: If an old version of the product has been detected that was installed using the native code setup engine, this variable will hold the full valid path to the old installation log (otherwise, the variable will be an empty string). The NATIVE_LOGGING variable may be set to the value of this variable to bind the installation to the old installation log and uninstall the old version of the product directly from the new version installer.
  • NATIVE_OVERRIDE_PERMISSIONS: Initially FALSE. With any value other than TRUE, the native setup engine will not attempt to acquire ownership and other necessary permissions with file and registry objects; resulting in potentially failed updates (and failed installations - based on the designated severity of the objects that failed to install due to missing permissions). When TRUE, the native setup engine will acquire ownership to update file and registry objects. Original ownership will typically be restored with both file objects and registry objects, however original ownership may not be restorable in certain extreme circumstances. The behavior of the native setup engine in those rare circumstances is controlled by the NATIVE_OVERRIDE_NON_RESTORABLE_PERMISSIONS variable.
  • NATIVE_OVERRIDE_NON_RESTORABLE_PERMISSIONS: Initially FALSE. With any value other than TRUE, the native setup engine will not attempt to acquire the ownership of files and registry keys, if it determines that such acquisition will make it impossible to restore the original ownership. When TRUE, the native setup engine will still acquire ownership even if it determines that the original ownership is not restorable, guaranteeing that your changes are applied to the system, but potentially creating an attack surface on the target system.
  • NATIVE_OVERWRITE: Initially PROMPT. With the initial value, when setup is about to overwrite a file during a native engine installation, the end-user will be prompted with an overwrite dialog displaying the file dates and versions for both the new file and the old file, as well as the options to overwrite or skip the file. Set to ALWAYS to automatically overwrite files. Set to NEVER to automatically skip installing files that already exist on the target. Any other value will be interpreted as PROMPT. If the end-user makes the choice to apply the overwrite decision in the prompt dialog to all files, this variable will also be automatically updated, keeping the setup script aware of end-user choices and providing it with the ability to override them.
  • NATIVE_OVERWRITE_OLDER: Initially FALSE. Determines whether the native setup engine is allowed to replace files that have been determined to be newer with older files that are included in the installation. Set to TRUE to permit the native setup engine to replace files that are newer with older copies (this is not recommended). This variable overrides the value of the NATIVE_OVERWRITE variable when FALSE, and the file being installed by setup is determined to be older than the file already present on the target system. The native engine compares files as follows: If both files are versioned, the decision is based on the comparison of the file versions (the installed file has to be a newer version than the present file). If none of the files are versioned, the decision is based on the comparison of file dates (the installed file has to be modified more recently than the present file). If the file being installed lacks version information but the present file contains version information, the file being installed is assumed to be older. If the file being installed contains version information but the present file lacks version information, file dates are compared.
  • NATIVE_ROLLBACK: Initially TRUE. Has no effect unless the native engine is being used. Set to FALSE to prevent the rollback of changes made by setups that have been cancelled at runtime. Only first-time installations can be rolled back (setups running in maintenance/repair mode cannot be rolled back, but uninstalled).
  • NEEDSUPGRADE: TRUE if a previous version of the product was found installed using the Windows Installer engine, FALSE otherwise. When this variable is TRUE, a new version of the product should not be installed using the Windows Installer engine until the old version has been removed successfully. This variable is never TRUE if the previous version of the product was installed using the native code setup engine, and there is no subsequent removal requirement on the old version; however the variable RECOMMENDEDUPGRADE indicates whether a previous version of the product installed with the native engine has been detected (and its removal is recommended).
  • NEWINSTANCE: TRUE if a new instance of the product may be spawned, FALSE otherwise. New product instances cannot be spawned when maintaining an existing installation from the Control Panel, or when no instances of the product have yet been installed (at least the default instance must be installed before new instances can be created).
  • NEWLINE: This is not a real variable, but indicates a new line character.
  • OVERRIDECACHE: Initially an empty string. Overriding the value of this variable allows changing the installer cache location, which can be of significant size when working with a web build. If the override is unsuccessful, the variable will again hold an empty value, indicating that the desired cache location is not writable. If the override is successful, the installer will use the specified cache location as the new installer cache. However, after an override, the installer does NOT move any already-existing files/folders found in in the old cache (such as previously downloaded web media blocks) into the new cache. Additionally, after an override, the setup engine is re-initialized, which has side effects such as the loss of previously declared setup features. For these reasons, if you are planning to change the location of the installer cache, it is recommended to do so early on in your setup script - before any features have been defined, persistent variable values have been assigned, and so forth. If setup is aborted before installation is complete, the overridden value of the installer cache will be volatile. If setup completes normally, the overridden value of the installer cache is persistent. The setup cache should not be overridden when setup is running in maintenance mode.
  • PERSONALIZED: Initially FALSE. Indicates whether a custom setup should be performed.
  • PRODUCTCODE: Set to the full GUID of the product code, as set in the installation database and configured at the project options dialog.
  • PROGRESS: Initially 0. A numerical representation of the current position in installation progress, where 0 is nothing and 100 is complete. This value is displayed in progress dialogs.
  • PROGRESSMODE: Initially an empty string. If set to MARQUEE, the standard ProgressBar control will move like a marquee, ideal for use with tasks whose completion times are indeterminate. On Windows 7, two more progress modes are available: ERROR and PAUSE. Setting this variable to ERROR will display installation progress on the taskbar in red color, alerting the end-user that a possibly fatal error has occured. Setting this variable to PAUSE will display installation progress on the taskbar in yellow color, alerting the end-user that their attention is required for installation to resume. While you may set and use these progress modes at any time to change the installation taskbar progress color from the default green color to red or yellow, it is recommended to do so only when end-user attention is actually required to continue (or abort) setup. These additional progress modes have no effect earlier than Windows 7.
  • PROGRESSTEXT: Initially an empty string. A string description of the current installation task. This value is displayed in progress dialogs.
  • REBOOTCOMPUTER: Initially FALSE. After Windows Installer executes, indicates whether the computer needs to be rebooted for the changes to take effect.
  • REBOOTNOW: Initially OK. When setup is running in silent mode, automatically reboots the computer as necessary to pass through pre-requisite installations that may require reboots. Change the default value to prevent automatic reboots in silent mode.
  • RECOMMENDEDUPGRADE: TRUE if a previous version of the product was found installed using the native code setup engine, FALSE otherwise. When this variable is TRUE, if a new version of the product is installed using the native engine before the old version has been removed successfully, the only guaranteed way to uninstall the old version will be to run the original setup file for the old version: Future installations may not detect the old version for as long as the same GUID is used for the product code between the old and new setups. The Control Panel Programs and Features applet may no longer point to the old version as long as the same product name is used between the old and new setups.
  • REMOVE: Initially FALSE. Indicates whether the product should be uninstalled.
  • REPAIR: Initially FALSE. Indicates whether the existing product installation should be repaired.
  • REVISIONCODE: Set to the full GUID of the revision code, as set in the installation database and configured at the project options dialog.
  • ROOTDIR: The folder containing the setup executable itself.
  • RUNAPP: Initially TRUE. Indicates whether the application should be executed at the end of the installation.
  • SAVEDATA: Initially FALSE. Indicates whether saved installation data (such as already downloaded web media blocks and component selections) should be preserved when the product is being uninstalled. Normally, when a product is removed using a call to Apply Uninstall, all saved installation data is removed. In special cases, such as removing a partially completed installation for a later re-installation, you may want to set this variable to TRUE such that already downloaded installation files and feature selections survive an uninstall.
  • SELECTED: By convention, this variable is used to retrieve feature selection states in the setup script. It is pre-defined with an empty string value and may be used for any general purpose, including retrieving feature selection states.
  • SETUPPATH: This variable provides a convenient mechanism to detect the outermost folder containing the executable program or setup database that initiated the installation. In other words, this value is set to the value of the variable GPOPATH, or SFXPATH, or EXEDIR in that order of priority - until the first variable containing a non-empty value is found.
  • SFXFILE: If an uncompressed directory layout is used, this variable is empty. Otherwise set to the file name of the self extracting executable which bootstrapped the installer.
  • SFXPATH: If an uncompressed directory layout is used, this variable is empty. Otherwise set to the full path of the folder containing the self extracting executable which bootstrapped the installer.
  • SILENT: Initial value set on the command line. TRUE if a silent install should be performed, and FALSE if not. Set the value of this variable from the script to change silent installation mode.
  • STARTMENU: Initial value set to the name of the product being installed, as set in the project options dialog.
  • SUPPORTDIR: Points to the full path of the temporary folder that support files are extracted to before installation beings.
  • TARGETDIR: Initial value set to <Program Files Directory>\Application Title, using the name of the product being installed as the application title.
  • TEMPDIR: Full path to the temporary folder location on the target system.
  • TIME: The current time, reported in human readable textual form in the current locale.
  • TITLE: Initial value set to the name of the product being installed, as set in the Product Name field of the project options dialog.
  • USERCOMPANY: Initial value set to the name of the company that licensed Windows on the system the product is being installed.
  • USERNAME: Initial value set to the name of the person that licensed Windows on the system the product is being installed.
  • UNINSTALLLINK: Initial value set to the full path of the uninstallation setup program.
  • VERSION: Set to the version number of the running setup.
  • WINDOWHANDLE: Value set to the handle of the active installation window.
  • WIZARD: Initial value set to NEXT.

Please note that variables are de-referenced in the script using the form $VARIABLE$.

Also review the list of pre-defined compiler variables.


Pre-Defined Compiler Variables

In addition to pre-defined variables, each InstallAware project also contains pre-defined compiler variables. These compiler variables are automatically initialized when you compile your setup based on your project settings, even if you have not explicity defined them. Explicitly defining a compiler variable will override the implicitly defined value. The full list of pre-defined compiler variables and the values they contain is displayed below:

  • BUILDMODE: CD if the deployment type is Uncompressed Directory Layout, SFX if the deployment type is Compressed Single Self-Installing EXE, WEB if the deployment type is Compressed Web-Based EXE, PATCH if a patch is being built.
  • CODEPAGE: If unspecified, the recommended UTF-8 unicode value of 65001 is used. Other suggested values are 65000 for UTF-7 unicode and 1252 for the English codepage, or 0 for codepage neutral. Change this value if your setup installs or otherwise makes use of files with accented or non-ASCII locale-specific characters in their names. Ensure this codepage matches the codepage of your current host system to prevent data corruption in your MSI databases and to ensure the correct codepage is used on target systems, thus preventing issues with incorrectly interpreted file names leading to failures when finding files at install-time. Using unicode codepages will render your setups unworkable on Windows 9X operating systems (Windows 95, Windows 98, and Windows ME); however it will ensure the broadest compatibility on Windows NT operating systems (Windows NT 4, Windows 2000, Windows XP, Server 2003, Windows Vista, Server 2008, Windows 7, and Server 2008 R2).
  • IADIR: Contains the full location of the InstallAware IDE, build module, or automation DLL folder (without a trailing slash), depending on the element executing the project build.
  • IAVER: Contains the version of InstallAware, beginning with the value 9.02 representing the first version of the product offering this compiler variable.
  • IGNOREMISSINGFILES: When set to TRUE, forces the InstallAware compiler to ignore missing files referenced by Install Files, Install Assembly, Install Service, and Install ODBC Driver commands during a build. Any other value results in the default behavior of the build failing when any given preceding command fails to include at least one file inside the setup package.
  • LANGUAGE: Represents the default language that the installation is built in. The default language is used to initialize the setup user interface in multi-lingual installations.
  • LOCMODE: Controls how localizations are applied at runtime. This compiler variable has impact on script localizations only, and has no effect on dialogs or shared strings:
    • If VARSONLY, the only localizations that are applied to a running setup are those for Localization Variable commands, even if other commands have been localized. This helps prevent incorrect and/or unintentional translations of other script commands from breaking a localized setup at runtime.
    • If NEWONLY, localizations for all commands are applied to a running setup, except commands which have not been localized yet and remain with older default strings, protecting elements which may have since been updated in the script. This helps prevent default values used in unlocalized commands from overwriting the newer values which may have since been changed in the script.
      • Note: For this option to have effect with old setups, add the file translations.Original from your translation export folder to your setup as a support file. New setups will automatically have this file.
    • If no value is specified, the default value of NEWONLY is assumed.
    • With any other value, all localizations are unconditionally applied.
  • LONGCOMPONENTS: If set to TRUE, the setup compiler will use long component names in MSI tables. This compiler variable is primarily intended for backwards compatibility with setups built with InstallAware versions prior to version 9. Especially when building patches against these older setups, you may want to use long component names to ensure maximum backwards compatibility.
  • MSI_ALL: If set to TRUE, the setup compiler will build all setup layouts as MSI files instead of EXE files, with the exception of the Uncompressed Directory Layout layout, which already builds an MSI file. Even if the NO_MSI switch has been set to TRUE, this switch will apply.
  • NO_MSI: If set to TRUE, the setup compiler will skip MSI database generation as part of a build process, significantly speeding up the build. However, setups built without MSI databases will fail at runtime if the Windows Installer installation mode has been selected through the pre-defined variable $NATIVE_ENGINE$. Additionally, when the Native Engine is being used, the MSI file is still required to be built if the Remove Assemblies command is used in the setup script.
  • PROJDIR: Contains the full location of the project folder for the project being built (without a trailing slash).
  • LOADOLDDATA: If set to TRUE, the setup engine will load feature definitions and other saved data (see the Load Feature Selections command for more details) from an older version of setup. Normally this data is loaded only in between the same versions of setup, when working on the same installed application version for a maintenance or uninstall operation. With any other value for this compiler variable, this normal behavior is preserved.
  • NOHARDLINKS: If set to TRUE, and if the deployment type is Uncompressed Directory Layout, full file copy will not be performed on supported NTFS file systems, speeding up builds through the utilization of hard links to source files instead. Set to FALSE to perform full (but slower) file copy when building. All other build types use hard links at all times (on supported NTFS file systems) since they are compressed immediately after building and then the hard links are removed once the build (compression) is complete.
  • SIGN_ALL: If set to TRUE, code signs all .EXE, .DLL, .OCX, .SYS, .CPL, .DRV, and .SCR files being installed by setup using any of the following commands: Install Files, Install Service, Install Assembly, and Install ODBC Driver. Ignored unless code signing has been enabled in the Project Settings dialog for the setup package. Required by the Windows 8 logo program.
  • SIGN_ALL_INPLACE: If set to TRUE, all files code signed when #SIGN_ALL# has been set to TRUE are signed in their immediate locations on disk. With any other value, files are copied to a temporary folder and signed in that temporary location to preserve the original state of files on disk.
  • SINGLEINSTANCE: Disallows running multiple instances of setups sharing the same Revision Code when set to TRUE.
  • SWID: If specified and not empty, records the exact provided ISO/IEC 19770-2:2009 software identification (SWID) tag for your application. This compiler variable is automatically configured in the IDE Summary, UAC, and ISO design view.
  • SWID_ENTITLEMENT: Ignored unless #SWID# is defined and not empty. Corresponds to the Entitlement check-box in the IDE Summary, UAC, and ISO design view.
  • TARGETDIR: Resolves to the $TARGETDIR$ pre-defined variable at build time.
  • TITLE: Set to the name of the product being installed, as set in the Product Name field of the project options dialog.

Please note that compiler variables are de-referenced in the script using the form #VARIABLE#.

Compiler variables may also be used with Compiler Variable If and related commands to conditionally compile the script at build time.

Also review the list of pre-defined variables.


Apply Changes

With first time or maintenance installations, this command applies all pending changes to the target system. Each queued installation action will execute through the Windows Installer engine in a single pass when this command is called.

When the Native Engine is being used, based on the value of the DELAYUNTIL_APPLYCHANGES pre-defined variable, pending changes may be immediately applied to the system without waiting for this command. However, this command is still necessary to commit the installation log to disk, as well as perform a final set of installation related tasks - even though the majority of the installation (such as file copying) could already be complete.

For uninstallations, this command will undo all install actions that have been logged, and works similary with both setup engines.

Return Success State in Variable

This variable holds the result of the installation action. The following values are returned:

Value | Meaning
CANCEL | Installation was cancelled by the user.
COMPLETE | Installation was completed successfully.
ERROR | An error occured during installation. The error description is available in the LASTERROR variable.
REBOOT | Installation was completed successfully, however a reboot is required.

Action to Perform

  • Check Install Product to install your product for the first time, or in maintenance mode.
  • Check Advertise Product to advertise your product. An advertised product creates only the registry entires, file types and shortcuts associated with the product. An advertised product therefore appears to be fully installed to users, but advertising does not actually copy any files. The first time an advertised shortcut or file type is invoked, the product will be fully installed and necessary files copied automatically. After a product has been advertised further maintenance operations may be run on the product, or it may be uninstalled. Advertising is not available with the native code setup engine.
  • Check Uninstall Product to remove a previously installed product.

Notes

  • If no commands which effect the target system have been authored into your setup, this action will fail unless the native code setup engine is used.
  • In wizard generated installs, the SUCCESS variable is used to hold the outcome of this command.
  • More than one Apply Changes command may be used as part of your installation process if necessary. However, each invocation will perform a complete setup routine and may therefore degrade performance if used excessively unless the native code setup engine is being used.


Apply Patch

This command applies a patch to a product that has been previously installed on the target system. This command is valid only when the Windows Installer engine is active and is not supported by the Native Engine.

This command must be used in conjunction with Patch Builds. A patch build scans the Patch References that have been added to your project, and generates differential patch data based on the delta of that scan. This data is then used by the Apply Patch command. If you attempt to use the Apply Patch command outside of a Patch Build, the command will fail as the required differential patch data will be missing.

Return Success State in Variable

This variable holds the result of the installation action. The following values are returned:

Value | Meaning
CANCEL | Installation was cancelled by the user.
COMPLETE | Installation was completed successfully.
ERROR | An error occured during installation. The error description is available in the LASTERROR variable.
REBOOT | Installation was completed successfully, however a reboot is required.

Notes

  • In wizard generated installs, the SUCCESS variable is used to hold the outcome of this command.


Break

This command is used inside For Each, While, and Repeat loops. It has no configurable parameters. It immediately exits the loop without further evaluation of the loop conditional.


Check Disk Space

This command returns the available or total disk space on the target system.

Variable

This variable receives available disk space, in bytes.

Disk Path

Provide the path for the disk to obtain space information from. You may specify an existing disk folder (such as the root folder), or a new folder that has not been created yet. You may also specify network paths using the UNC convention, of the form \\server\share. In this case, the amount of free space in the server share is reported.

Available Space

Check to obtain free disk space.

Total Space

Check to obtain total disk space.

Notes

  • There is no need to explicity check for disk space in your setup script. The install engine automatically verifies available disk space before beginning installation.


Check File Version

This command compares a file version number to another file or a pre-set version string.

Variable

This variable holds TRUE if the file indicated by the Is File parameter is newer. If the file carries the same version or is older, the variable holds FALSE.

Is File

Indicates the source file for the comparison. Only a single file may be specified. If the specified file does not contain version information, its version will be assumed to be 0.0.0.0.

Newer than File

To compare with another file, check this item and provide the target file for the comparison. Only a single file may be specified. If the specified file does not contain version information, its version will be assumed to be 0.0.0.0.

Newer than Version Number

To compare with a version string, check this item and provide the version string. If the version string is absent, it will be assumed to be 0.0.0.0.


Check Process

This command checks for a running processes on the system.

Process Name

Enter the name of the process to look for here. Process names are their executable file names, including the file extension, but without any path information. For instance, to check if Windows Explorer is running, enter explorer.exe in this field.

Return Result in Variable

Enter an existing or new variable name in this field. The variable will hold TRUE if the named process is running, FALSE otherwise.

Notes

  • To check for running services, use the Check Service command.
  • To terminate a running process, use the Terminate Process command.


Check Registry

This command checks for the existence of a registry key or value. If the key or value exists, the function returns the associated data. If the key or value does not exist, the function returns a specific error code. Check Registry is similar to Read Registry, except it returns error codes instead of empty values when the requested data does not exist.

Variable

Type the name of the variable to receive the read value or error condition. If the value/key exists, this variable will hold the actual data held in the value. If the value/key does not exist, this variable will hold one of the following specific error flags:

Value | Meaning
UNKNOWN$TYPE | The value exists, but is of an unknown type.
NO$VALUE | The specified key exists, but the specified value does not exist.
NO$KEY | The specified key does not exist.
READ$ERROR | An error occured during the read operation (check access privileges).

Root

Select the root of the read operation using the drop down menu.

Key

Type the name of the key to check for or read from.

Value

Type the value to read or check for. Leave empty to test for the existence of the key itself (and read the default value if the key exists).

Notes

  • If you would rather receive an empty string when the requested value cannot be found, use the Read Registry command instead.


Check Service

This command checks for a running service on the local system, or a system on the network.

Service Name

Enter the name of the service to look for here.

Actual service names may be different from their human readable display names. In the Control Panel, under Administrative Tools, the Services applet lists services by their display names. Double-clicking a service listed here opens the Service Properties dialog for that service, which reveals the actual name of the service in the Service name field of the dialog. Use this actual name in this field.

Machine Name

To check for the service on the local system, leave this field empty. To check for the service on a remote system on the network, enter the name of the remove computer here.

Return Result in Variable

Enter an existing or new variable name in this field. The following values are returned:

Value | Meaning
CONTINUE_PENDING | Service is still attempting to resume.
PAUSE_PENDING | Service is still attempting to pause.
PAUSED | Service is paused.
RUNNING | Service is running.
STARTING | Service is attempting to start.
STOPPING | Service is attempting to stop.
STOPPED | Service is installed but not active.
NOTINSTALLED | Service is not installed at all.

Notes

  • To check for running processes, use the Check Process command.


Code Folding Region

This command begins a code folding block in your setup script. Code folding blocks, similar to comments, do not impact script flow. They are used for organizing the setup script into easily readable, foldable regions of code. A folded region hides its contents and makes lengthy setup scripts easier to read and manage in the script editor.

Define Region

Check this item to start a new code folding region. Enter the name of your code folding region in the text field below. Each code folding region must have a unique name.

Close Region

Check this item to close the last defined code folding region. Code folding regions must be closed before they may be folded in the script editor.

Notes

  • You may nest multiple code folding regions inside one another.


Comment

This installation command helps you create a remark in your code. It has no effect on the installation.

Edit Comment

Type your remark here. Leave this field empty to display an empty line in your script.


Compiler Variable Else

This command is used in conjunction with Compiler Variable If commands. It has no configurable parameters. It is used to direct conditional compilation.


Compiler Variable End

This command is used in conjunction with Compiler Variable If commands. It has no configurable parameters. It is used to direct conditional compilation.


Compiler Variable If

This command is used to achieve conditional compilation. It is used in conjunction with the Compiler Variable Else and Compiler Variable End commands.

Variable

Type the name of the variable, according to the value of which the conditional evaluation will be performed.

Comparison

Choose a comparison type from the drop down menu. If both variables contain integer values, a numeric comparison will be performed. If at least one variable contains a non-integer value, a string comparison will be performed.

Reverse Comparison

Check this checkbox if you wish to execute an if not evaluation.

Compare With

Provide the string literal to perform the comparison with.


Continue

This command is used inside For Each, While, and Repeat loops. It has no configurable parameters. It immediately starts a new loop iteration.

The loop conditional is re-evaluated for While loops. It is not re-evaluated for Repeat loops. For Each loops proceed to iterate the next member of the collection being enumerated.


Control IIS Site

This command starts, stops, pauses, or resumes an Internet Information Services website identified by its Site Index. It may be necessary to manually start/stop sites during installation, while changes are being made to site configuration.

Site Index

The numeric identifier of the website.

Control

The action to perform on the IIS website.

Notes

  • The site index of a website may be obtained from its name using the Get IIS Site Index command.


Control Service

This command starts or stops, and optionally deletes a service.

Service Name

Enter the name of the service to control here.

Command Line Arguments

Provide any command line arguments to the service file here.

Control

Using the drop down list, choose the type of control to perform on the indicated service.

With the Windows Installer engine, you may specify whether the control operation is performed at installation time or uninstallation time. With the Native Engine, the control operation is performed at the time the command is invoked, regardless of the selected installation or uninstallation timing.

Wait for service state change completion

Check this item to wait until the control operation completes on the service. Uncheck this item to return as soon as the control operation request has been sent to the service.


Convert Case

This command is used to convert the case of characters stored in a variable.

Variable

Enter the name of the variable to convert here.

To Upper Case

Check this radio button to convert the characters to upper case.

To Lower Case

Check this radio button to convert the characters to lower case.

Notes

  • This command performs Ansi character conversions in the current locale.


Convert Path

This command converts a long file name path to a short file name path, or vice versa. Long file name paths may contain spaces and extended characters; short file name paths may not contain either. This command is especially useful when passing command line parameters to external programs. It is best to use short file names because embedded spaces in paths may be interpreted as new parameters, and the program may not recognize the double quote character that generally surrounds long path names. An example for such a program with which short path names should be used is rundll32.exe.

Variable

This variable holds the path to convert. It will be replaced with the updated path after the conversion.

Operation

  • Check Convert to Short Path to convert a long path name to a short path name.
  • Check Convert to Long Path to convert a short path name to a long path name.

Notes

  • If the original path cannot be found, the command will return an empty string in the variable.
  • If the original path contains environment variables, they will be expanded before processing begins.
  • If the original path contains relative paths, they will be flattened before processing begins.
  • If the original path does not contain a drive letter reference, the setup base folder will be prepended before processing begins.


Copy/Move Local Files

This command copies or moves files that are already present on the target system (or installation media) into a new location on the target system.

It should not be used for installing new files onto the system when the Windows Installer engine is active; however the command is more flexible with the Native Engine and may be used extensively (it will be especially useful in creating "live CD" type distributions).

Source Folder

Specifies the source path for copying files from. Must point to a valid folder.

Source Files

Specifies the source files to copy. You may use wildcards.

With the Windows Installer engine, you may not use any variables in this field, only string literals are allowed. The Native Engine does not have this restriction.

Target Folder

Specifies the target path for copying files to. Must point to a valid folder.

Target Files

Fill in this field only if you wish to rename the target files as part of the operation.

With the Windows Installer engine, you may use wildcards. You may not use any variables in this field, only string literals are allowed. For example, if the Source Files field is *.txt and the Target Files field is *.dat, each file ending with a .txt extension on the Source Folder will be copied to the Target Folder as a file ending with a .dat extension.

The Native Engine ignores any values entered into this field if they contain wildcards, or the Source Files field contains wildcards. Variables are allowed.

Copy Files

Check to indicate the operation is to copy files.

Move Files

Check to indicate the operation is to move files.

Include Subfolders

Check to also process files in subfolders. This option is ignored by the Windows Installer engine.

Notes

  • With the Windows Installer engine, files copied or moved by this command are not removed upon uninstallation. Therefore, if removal of such files is required, accompany each Copy/Move Local Files command with a Delete Files command that is set to undo the copy/move local action.
  • The Native Engine does not have this limitation and files copied/moved by this command will be uninstalled normally without requiring manual deletion.


Create File Type

Advertised File Type / Create File Type

These commands create a new file type, bind one or more file extensions to that file type, and associate that file type with an application. Both commands are very similar, however the Advertised File Type command offers additional features over the Create File Type command:

  • If the application owning the file type is missing, it will automatically be re-installed. This provides a self-healing setup.
  • If the product has been installed in advertised mode, opening an advertised file type will automatically install the application on-demand. This provides a setup with installation-on-demand capabilities.

In return for these benefits, the Advertised File Type command has several restrictions:

  • DDE options are not available.
  • The application owning the file type must be directly installed by the setup.

File Type

The file type to create. This file type will own one or more extensions and be associated with an application.

Opens With

Full path to the application executable which is associated with the file type. Some considerations apply for the Advertised File Type command:

  • The Install Files command that installs this file must be located in your script before the Advertised File Type command. This is necessary to allow the setup compiler to properly resolve the target of your advertised command.
  • You may not use the Advertised File Type command with files that are not directly installed by your script using the Install Files command. In such cases, use the Create File Type command instead.

Description

The end-user visible description for the file type.

Icon File

If a custom icon will be used instead of the default icon of the application that is being associated with the file type, enter the full path to the file containing the custom icon here. You may specify an executable, library, or icon file. For Advertised File Type, do not use variables and provide the full path to a file on your local system. The icon will be extracted at compile time. For Create File Type, you may use variables, and the provided path must point to a file on the target system. No icon extraction will occur.

Icon Number

If an icon other than the first icon should be used, enter the index of the icon to use here.

List of Extensions Belonging to File Type

Enter the file extensions that are owned by the file type. You should provide at least one file extension.

Verb

Enter a canonical or custom verb indicating an operation that is available for this file type in the system shell, such as Open or Print.

Parameters

Enter the command line parameters to be passed to the application associated with this file type for the current verb.

DDE Command, DDE Application, DDE Topic (only with Create File Type)

If the application supports DDE, enter the values into the DDE fields to be passed to the application associated with this file type for the current verb. Otherwise leave these fields empty.

Notes

  • Use the File Associations visual view in the IDE to quickly switch the type of a file type command between advertised and non-advertised.
  • For logo certification, use the Advertised File Type command. If logo certification is not important, use Create File Type instead as it is more versatile.
  • If you use the Create File Type command, the command is internally implemented as a series of Write Registry calls.


Create Folder

This command creates a new folder, or multiple sets of folders, on the target system.

Folder

Indicates the full path to the folder to create.

Notes

  • Installation actions will automatically create their required target folders, if they are not already found. You do not need to use the Create Folder command to explicitly create such folders.


Create Games Explorer

This command creates a new Windows Games Explorer item. On operating systems earlier than Windows Vista, the item will not be actually created until an upgrade of the operating system is performed.

Game Definition File Binary

Enter the full physical path to the file containing the GDF resource.

Game Folder

Enter the full path to the folder where the game has been installed.


Create Group

This command creates a new user group on the target system.

Group Name

Enter the name of the user group to create.

Group Description

Provide a description for the user group.

Remote Server

Leave this field empty to create the user group on the local system.

Enter the name of a remote server to create the user group on a remote system.


Create IIS Site

This command creates a new Internet Information Services website, as identified by its Site Name; or it updates an existing IIS website, as indentified by its Site Index.

Site Name

The name of the website.

Site Index

The numeric identifier of the website. If you leave this entry blank, an identifier will be automatically assigned by the system. If you specify a site index that corresponds to a site that already exists, the properties specified in this command will overwrite the properties for the site that already exists.

IP Address

If you wish to assign a specific IP address to this website, enter it here. Otherwise, the site responds to all IP addresses.

Host Name

If you wish to assign a specific host name to this website, enter it here. Otherwise, the site responds to all host names.

TCP Port

Enter the TCP port for the website here.

SSL Port

Enter the SSL port for the website here.

Connection Timeout

Enter the amount of time that must elapse for a connection timeout to occur.

Enable HTTP Keep Alives

Check this box if you wish to enable HTTP keep alives.

Enable Logging

Check this box if you wish visits to this site to be logged.

Enable ASP

If you intend to serve ASP pages on this website, enable this option.

Enable ISAPI

If you intend to run ISAPI applications on this website, enable this option.

Web Site Connections

Choose whether to limit the number of maximum simultaneous connections allowed for the website.

Tuning

Move the slider to match the number of expected hits on the website per day. This allows IIS to internally optimize site performance.

Notes

  • Use the Create IIS Virtual Folder command to create the root and sub folders that are served by this site. The Create IIS Site command does not create or initialize the root folder of a website.
  • The site index of a web site may be obtained from its name using the Get IIS Site Index command.


Create Media Center

This command creates a new Windows Media Center application. The minimum operating system required for this functionality is Windows XP Media Center Edition 2005. Previous releases of Windows Media Center will not display the created application.

Application Binary

Enter the full physical path to the application to add to Windows Media Center.

Command Line Parameters

If you would like to launch the application with any command line parameters, specify them here.

Application Logo

Provide the full physical path to the application logo. The minimum operating system required to display the logo is Windows Vista. Previous releases of Windows Media Center will not display the logo.

For optimum display, the logo should be in 75x75 pixels size, and be in PNG format for transparency support.

Application GUID

Each application must be registered with Windows Media Center using a unique identifier. You may use the pre-defined variables $PRODUCTCODE$ or $REVISIONCODE$ in this field, or generate a new GUID if you are registering more than one application with Windows Media Center.

Application Title

Enter the display name for the application as will be seen in Windows Media Center. You may use the pre-defined variable $TITLE$ in this field, or any other name you prefer if you are registering more than one application with Windows Media Center.

Warnings

  • When running this command on 64 bit operating systems, you must put the installation in 64 bit mode using the Set 64 Bit Mode command.


Create ODBC DSN

This command creates an ODBC data source.

Data Source Name

Enter the name of the data source here. If you wish to duplicate the settings of a DSN already existing on your system, click the drop-down arrow and choose the DSN to capture.

Driver Name

Enter the name of the data provider here. With the Windows Installer engine, no variables may be used in this field. With the Native Engine, variables are allowed.

Registration

  • Check Per Machine to create a System DSN.
  • Check Per User to create a User DSN.

Attributes

Specify your data source attributes here. You may enter multiple attributes by pressing CTRL+ENTER.

Notes

  • Do not dereference variables using $ signs in the Attributes field.
  • Dereference variables using square brackets instead.
  • For instance, instead of using $TARGETDIR$, use [TARGETDIR].


Create Share

This command shares a file system folder on the network with other users. Shares are typically created on network file servers.

Folder to Share

Enter the full physical path to the file system folder that will be shared.

Remote System

To create the share on a remote system on the network, enter the name of the remove computer here. To create the share on the local system, leave this field empty.

Share Name

Enter the name of the folder as you wish it to be visible on the network. For instance, if the computer name is PC, and the Share Name is Share, the shared folder will be accessible on the network using the UNC path \\PC\Share.

Share Description

Enter the textual description of the folder to be shared.

Notes

  • Use the Set Access Control command to grant access rights to the shared folder, identifying the Share object by its Share Name. A typical priviledge would be granting Everyone read access to the shared folder.


Create Shortcut

Advertised Shortcut / Create Shortcut

These commands create a shortcut to a file on the target system. Both commands are very similar, however the Advertised Shortcut command offers additional features over the Create Shortcut command:

  • If the target of the shortcut is missing, it will automatically be re-installed. This provides a self-healing setup.
  • If the product has been installed in advertised mode, opening an advertised shortcut will automatically install the application on-demand. This provides a setup with installation-on-demand capabilities.

In return for these benefits, the Advertised Shortcut command requires that the target of the shortcut must be directly installed by the setup. With the Create Shortcut command, the shortcut may point to any file on the target system, including pre-existing files.

Shortcut to File

The full path of the file that the shortcut will open. Some considerations apply for the Advertised Shortcut command:

  • The Install Files command that installs this file must be located in your script before the Advertised Shortcut command. This is necessary to allow the setup compiler to properly resolve the target of your advertised command.
  • You may not use the Advertised Shortcut command with files that are not directly installed by your script using the Install Files command. In such cases, use the Create Shortcut command instead.

Link Name

The name of the shortcut as it will appear on screen. With the Windows Installer engine, no variables are allowed in this field. With the Native Engine, variables are allowed in this field.

Link Location

The folder that will contain the shortcut.

Link Description

The tooltip hint for the shortcut.

Command Line Parameters

If the file specified by the Shortcut to File parameter will be launched using command line parameters, enter them here.

Startup In Folder

If you wish to customize the folder in which the file specified by the Shortcut to File parameter will be launched, specify that folder here.

Icon File Path

If you wish to customize the shortcut icon, enter the full path to that file in this field.

With the Windows Installer engine, no variables are allowed, only string literals are accepted. The path must point to a file on your development system. This field cannot be used to point to files on the target system. The icon will be extracted during compile time of your installation. Variables are not allowed in this field.

With the Native Engine, compile time icon extraction is not performed, and the path must point to a file on the target system. Variables are allowed in this field.

Icon Number

If you specified an Icon File Path, also indicate the number of the icon as it is found in the file for the shortcut.

Window Size

Choose a startup window size for the file specified by the Shortcut to File parameter.

Application User Model Identifier (Windows 7 and higher)

Enter your application's AppUserModelID value in this field. This setting applies only to applications authored for the new Windows 7 shell (or higher) and may safely be left empty.

Run as administrator (Windows Vista and higher), or prompt for credentials (older Windows)

On Windows Vista and newer operating systems implementing User Account Control, check this box to always elevate the target of the shortcut - even when the target does not include a manifest requesting elevation.

On older operating systems, checking this box prompts the end-user for alternate credentials when the target of the shortcut is run.

Pin Shortcut To: Start Menu (Windows XP and higher)

Check this box to pin the target of the shortcut to the top of the new Start Menu. The new Start Menu is available starting with Windows XP, and includes not only the traditional Start Menu, but also a "summary" Start Menu containing frequently used programs based on end-user usage patterns, or alternately, programs which have been manually "pinned" to the Start Menu by the end-user. For your end-users running an earlier version than Windows 7, this is the best exposure you can provide your application, since the application is not buried inside the traditional Start Menu, but directly accessible on the new Start Menu without end-users having to navigate to the All Programs sub-menu first, or forming frequent usage habits so your application would eventually appear on the new Start Menu.

On older platforms, this setting has no effect.

On newer platforms starting with Windows 8, this setting has no effect.

Pin Shortcut To: Taskbar (Windows 7 and higher)

Check this box to pin the target of the shortcut to the Taskbar on Windows 7. Pinning your application(s) directly to the Taskbar makes them accessible directly by end-users, without even having to click the Start button.

On older platforms, this setting has no effect.

Pin Shortcut To: Start Screen (Windows 8 and higher)

Check this box to pin the target of the shortcut to the new Windows 8 Start Screen.

By default, this is currently the default setting of the Windows 8 Start Screen even when this option has not been requested; however this option guarantees placement.

On older platforms, this setting has no effect.

Disable Shortcut Features: Highlighting on Start Menu (Windows 7)

By default, Windows 7 highlights each shortcut you create on the Start Menu, one at a time, until each has been clicked at least once. This may be undesirable when secondary applications and tools are being unnecessarily showcased. Check this option to conceal such items and save the highlighting for your main product.

On older platforms, this setting has no effect.

Disable Shortcut Features: Inclusion on Start Screen (Windows 8)

By default, Windows 8 places each shortcut you create on the Start Screen, which may cause unnecessary clutter. This may be undesirable when secondary applications and tools are being unnecessarily showcased. Check this option to prevent the automatic placement of all shortcuts you create on the Start Screen.

On older platforms, this setting has no effect.

Disable Shortcut Features: User Pinning (Windows 7 and higher)

If you wish to make your shortcuts unpinnable by your end-users, check this option.

On older platforms, this setting has no effect.

Notes

  • Since advertising is Windows Installer specific, the Advertised Shortcut command will be treated as a regular Create Shortcut command by the Native Engine.
  • Use the Shortcuts visual view in the IDE to quickly switch the type of a shortcut command between advertised and non-advertised.
  • For logo certification, use the Advertised Shortcut command. If logo certification is not important, use Create Shortcut instead as it is more versatile.
  • When pinning to the new Start Menu on Windows 7, if the application has any associated recent files, frequently used files, tasks, pinned items and other custom jump list entries that may have been defined as part of the application, they too become automatically accessible through the pinned Start Menu entry. The system will automatically display an expanding submenu for instant invocation of such entries directly from the summary Start Menu. Note that any such additional entries cannot be defined as part of your installation routine, but must be coded into your application executable itself per Windows 7 development guidelines.
  • Do not confuse the top of the Start Menu (as returned by the Get Folder Location command invoked with the Start Menu->Start Menu Group parameter) with the pinning locations on the "summary" Start Menu. The top of the Start Menu is available on all 32 and 64 bit Windows platforms and is displayed as part of the All Programs listing on the new Start Menu, unlike the pinning locations, which are visible immediately as soon as the Start button is clicked.
  • There is no folder location that can be used with the Get Folder Location command to directly create shortcuts at possible pin targets - as Microsoft has prevented programmatic access to these locations. However, with InstallAware, you may still pin any shortcut to either the new Start Menu or directly to the Windows 7 Taskbar, using the Advertised Shortcut/Create Shortcut command.
  • On Windows 7, sometimes shortcuts cannot be pinned successfully, due to Microsoft's efforts to prevent programmatic access for pinning applications. In that eventuality, InstallAware will still successfully pin your application itself, directly, to your chosen pin targets; however in this case any shortcut properties (such as application startup folders, custom command line parameters) will be lost - since they are part of the shortcut proper and not the application. If this is not acceptable, experiment with creating shortcuts at different locations (such as the Desktop, the Quick Launch bar, among other traditional Start Menu locations) - as some shortcut locations appear to be rejected for pinning while others might be accepted.
  • On Windows 8, if you wish to display your shortcut in the first column of the All Apps section of the Start Screen, set the Link Location field of your shortcut to the Start Menu -> Start Menu Group folder, as returned by the Get Folder Location command. If this placement is undesired, change your shortcut Link Location to another folder.


Create User

This command creates a new user on the target system.

This command may also be used to add an existing user on the target system to one or more user groups.

User Name

Enter the name of the user account to create. This is not the name of the computer operator that the user account is being created for.

Full Name

Enter the full name associated with the user account.

Description

Provide a description for the user account.

Password

Enter the password for the user account.

Remote Server

Leave this field empty to create the user account on the local system.

Enter the name of a remote server to create the user account on a remote system.

User cannot change password

Check this box to prevent users logged in to the account being created from changing their passwords.

Password never expires

Check this box to prevent the expiration of the password associated with the user account.

Account is disabled

Check this box to disable the user account upon creation. Logins to the account will not be accepted until the account is manually enabled after creation.

Group Memberships

User accounts are initially created without any membership in any user groups.

You may add the user account to one or more user groups. For instance, adding the user account to the Administrators group will assign administrative privileges to the user account.

To add the user account to an existing, well-known user group (such as Administrators, Users, or Guests), choose the name of the user group from the Group combox-box drop-down menu and click Add. At runtime, InstallAware will automatically add the user account being created to the appropriate user group (even if the user group has a different name on the target system, due to a localized version of Windows being used).

To add the user account to a custom user group, such as one that may be created with the Create Group command, type the name manually in the Group combo-box and click Add. Because this is a custom user group, unless a user group on the target system exists matching this exact name, the user account will not be added to the user group.

Warnings

  • Users may only be created on the Windows NT family of operating systems. Windows 9X operating systems are not supported.
  • On systems where password complexity requirements are enforced, user accounts may not be created successfully unless the password complexity requirements are met.
  • Well-known user group names should not be localized, or they may fail to resolve to correct user group names on target systems, specifically on those that assign a different name to the user groups than the translated name.
  • Custom user group names may be localized as needed.


Create IIS Virtual Folder

This command creates a virtual folder underneath an Internet Information Services website identified by its Site Index. Every IIS website must have at least one virtual folder, typically the root folder.

Virtual Path

The path of the virtual folder as it will appear underneath the IIS website. Leave this field empty to create the root folder. Enter a path in this field to create a sub folder.

Site Index

The numeric identifier of the website.

Physical Path

The full path to the physical file system folder that contains the files to be served as part of the virtual folder.

Script Source Access

Check this box to allow source code access to script files, such as ASP scripts.

Read

Check this box to allow read access to the folder. Without read access no files can be served from a virtual folder.

Write

Check this box to allow write access to the folder. Write access may be necessary for some kinds of web applications.

Directory Browsing

Check this box to enable the user to see the files and folders contained within this virtual folder if a default document cannot be found.

Log Visits

Check this box if you wish visits to this folder to be logged. The website identified by Site Index must also enable logging.

Index This Resource

Check this box to allow Microsoft Indexing Service to perform a full-text index on this folder.

Application Protection

Choose the level of application protection for this virtual folder here.

Execute Permissions

Choose whether script files (such as ASP files) and executables are allowed to run in this virtual folder, or only static content is permitted (such as HTM files).

Create or Use Pool

Unless Do Not Create Application is specified in the Application Protection field, sets the virtual folder to become part of the named application pool. If the named application pool does not already exist, it will be created.

Default Content Page

Check the Enable default content page check box to display a web page when this folder is accessed without referring to any particular file in it. Add one or more default content pages to display, in order of priority.

Document Footer

If you wish to append a footer to every document that is served by this virtual folder, enter the name of the document containing the footer here.

Enable Anonymous Access

To permit unauthenticated users access to files on this virtual folder, check this box. Most visitors of typical websites are unauthenticated users.

Integrated Windows Authentication

To use Windows user accounts and NTFS permissions for authentication, check this box.

Basic Authentication

To allow passwords sent as clear text, check this box.

Mime Types

To register MIME types with the server, enter them in the list here. Some later versions of IIS only serve file types for which there are MIME type declarations, therefore if you will be serving files with non-standard (unrecognized) file extensions, declare them as MIME types here.

ASP.NET version

To associate a version of ASP.NET with the virtual folder, choose that version here. To inherit the default association, choose the Default setting.

Notes

  • Use the Set Access Control command to grand folder permissions for the anonymous internet user to the physical folder that the Create IIS Virtual Folder command points to.
  • Use the Get System Settings command and query the IIS Anonymous User Account capability to obtain the name of the anonymous internet user account.
  • The site index of a web site may be obtained from its name using the Get IIS Site Index command.
  • Creation of custom application pools is available with IIS 6 and later. It is not available with earlier IIS versions.


Define Component

This command defines a setup component which will be visible in dialog boxes that display available application features.

Component Name

Enter the name for the component here. Specify subcomponents of parent components using the \ character, much as you would specify subfolders of a parent folder. Note that parent components also need to be explicitly defined if you wish them to respond to user selections.

The name of the component entered here will be visible in dialog boxes that display available application features.

Component is Initially Selected

Check this checkbox if the component should be selected by default.

Component Description

Enter a multi-line description of your component here. Press CTRL+ENTER for a line break. This information will be visible in dialog boxes that display available application feature descriptions.


Delete Component

This command deletes a component that was previously defined using the Define Component command.

Component Name

Enter the name of the component to delete here.


Delete Files

This command deletes files already present on the target system.

Delete from Folder

Specify the full path to the folder containing the files to delete.

Files

Specifies the files to delete. You may use wildcards.

With the Windows Installer engine, you may not use any variables in this field, only string literals are allowed.

With the Native Engine, you may use variables in this field.

Delete when Installing

With the Windows Installer engine, check to have the files deleted when the product is being installed or maintained. This field is ignored by the Native Engine.

Delete when Uninstalling

With the Windows Installer engine, check to have the files deleted when the product is being uninstalled. This field is ignored by the Native Engine.

Notes

  • With the Windows Installer engine, if you use the Copy/Move Local Files command in your script, you may want to pair each such command with a Delete Files command that undoes the operation using the Delete when Uninstalling option, since the local files command does not undo its action upon uninstallation.
  • To delete matching files in subfolders as well, use the Delete Files Recursive command.


Delete Files Recursive

This command immediately deletes files specified by a wildcard pattern. This function always deletes all matching files in subfolders as well. To only delete files in the current folder, use the Delete Files command.

Path

Enter the full path and wildcard pattern for the files to delete here.

Notes

  • Locked files that cannot be deleted are not removed by this command.
  • Empty subfolders are always removed by this command.
  • The starting folder is not removed by this command.


Delete Games Explorer

This command deletes a Windows Games Explorer item previously created using the Create Games Explorer command.

Game Definition File Binary

Enter the full physical path to the file containing the binary GDF resource.


Delete Group

This command deletes an existing user group from the target system.

Group Name

Enter the name of the user group to delete.

Remote Server

Leave this field empty to delete the user group from the local system.

Enter the name of a remote server to delete the user group from a remote system.


Delete IIS Site

This command deletes an Internet Information Services website identified by its Site Index.

IIS Site Index

The numeric identifier of the website.

Notes

  • The site index of a website may be obtained from its name using the Get IIS Site Index command.


Delete Media Center

This command deletes a Windows Media Center application previously created using the Create Media Center command.

Application GUID

Provide the GUID for the application to delete, as specified in the Application GUID field of the Create Media Center command that was used to previously register the application with Windows Media Center.

Warnings

  • When running this command on 64 bit operating systems, you must put the installation in 64 bit mode using the Set 64 Bit Mode command.


Delete Registry

This command deletes a value or an entire key from the system registry.

Root

Select the root of the delete operation using the drop down menu.

Key

Type the name of the key to delete (from).

Value

Type the value to delete. Leave empty to delete the default value. If you are deleting the entire key, this field is ignored.

Delete Entire Key (and subkeys)

Check this item to delete the entire key, along with any subkeys it contains.

Delete Value Only

Check this item to delete the named value only.

Warning

  • Windows Installer does not provide an easily timed mechanism to delete registry keys. This action will not execute through the Windows Installer engine and is provided as a convenience for the setup developer.
  • We recommend you create all registry keys used by your application as part of your setup. Doing so assures Windows Installer will automatically remove all such keys upon uninstallation.


Delete Scheduled Task

This command deletes a task scheduled to run using the Windows Task Scheduler.

Task Name

Enter the name of the scheduled task to delete here.

Target Computer

Enter the name of the computer to delete the scheduled task on. To delete the task on the current computer setup is running on, leave this field empty.


Delete Share

This command deletes a network share previously created using the Create Share command.

Share Name

Enter the name of the share to delete here.

Remote System

To delete a share on a remote system on the network, enter the name of the remove computer here. To delete a share on the local system, leave this field empty


Delete User

This command deletes an existing user from the target system.

User Name

Enter the name of the user account to delete. This is not the name of the computer operator that the user account being deleted is associated with.

Remote Server

Leave this field empty to delete the user account from the local system.

Enter the name of a remote server to delete the user account from a remote system.


Delete IIS Virtual Folder

This command deletes the named virtual folder underneath an Internet Information Services website identified by its Site Index.

Site Index

The numeric identifier of the website.

Folder

The path of the virtual folder as it appears underneath the IIS website. Leave this field empty to delete the root folder. Enter a path in this field to delete a sub folder.

Notes

  • The site index of a web site may be obtained from its name using the Get IIS Site Index command.


Display Dialog

This command displays a dialog that is part of your user interface.

Dialog

Click the drop down arrow to select a dialog that is available for use in your project.

Modal

If the dialog is part of a wizard loop, or queries the user for some information, check this checkbox. If the dialog is a progress dialog, and must remain visible on screen while some installation task is executing, uncheck this checkbox.

If Variable

If you wish to display the dialog only if a particular variable is set to TRUE or FALSE, type the name of that variable here, and select the appropriate condition.

Return Result in Variable

Applicable only the modal dialogs. Setting a variable in this field allows you to determine how the user exited the dialog. Possible values the variable may hold are explained below.

Value | Meaning
NOTMODAL | The dialog was not displayed modally.
NEXT | The user exited the dialog by clicking the Next button.
BACK | The user exited the dialog by clicking the Back button.
CANCEL | The user exited the dialog by clicking the Cancel button.

Notes

  • In wizard generated installs, the WIZARD variable is used to hold the return value of the dialog.


Does File/Folder Exist

This command lets you check for the existence of a file or folder on the target system.

Variable

Type the name of the variable that will hold TRUE if the item exists and FALSE if it does not.

Path

Type the full path of the item to check for.

Check for File

Check this box if the item must be a file.

Check for Folder

Check this box if the item must be a folder.


Edit INI File

This command creates, updates or removes a .INI file entry on the target system.

INI File Path

Type the full path to the INI file to edit. Do not include the name of the INI file in this field.

INI File Name

Type the name of the INI file to edit. With the Windows Installer engine, you may not use any variables in this field, only string literals are allowed. With the Native Engine, variables are allowed.

Section

Type the name of the INI section to edit.

Key

Type the name of the section key to edit.

Value

Type the value the key under the indicated section should take.

Action

Choose the desired editing action from the drop down list.


Edit XML File

This command creates, updates or removes an .XML file element and/or attribute on the target system.

XML File Path

Type the full path to the XML file to edit, including the file name.

Backup Existing File

If an XML file with the given name exists on the specified path, check this box to back it up.

Backups are created based on the original file name, with the string .backup.X appended to the file name, where X is the first unique integer found, counting up from 0. This way, multiple simultaneous backups may coexist.

Backup XML files are not uninstalled during product removal.

File Encoding

Choose the encoding to apply to your XML file. The encoding is not enforced upon pre-existing XML files, which always inherit the existing encoding.

File Formatting

Choose the type of formatting to apply to your XML file. This formatting is also enforced upon existing XML files.

Preserve Whitespace

Check this box to preserve any whitespace that is found in an existing document.

Action

Choose the desired editing action from the drop down list. One or more elements may be edited in a single pass, based on the value of the Modify All Matching Elements field. One or more attributes may be edited in a single pass, based on the number of attributes defined in the Attributes field. The implications of each edit action is described below:

Create or Update will create new element(s) and attribute(s) only if they don't already exist, and update existing element(s) and attribute(s) where they are found. This option is the only way to add new attribute(s) to existing element(s), and modify the element text for existing element(s).

Update Only will perform the edits only on those element(s) and attribute(s) that already exist in the document. Elements and attributes that don't already exist will not be created.

Create Only will always create a new element (and thus, attribute(s)) even if one or more elements with the path specified in the Element Path field already exist in the document. Unless the Modify All Matching Elements field is selected, Create Only will create new elements, even when doing so would create an exact duplicate of an existing element, considering the values specified in the Element Text and Attributes fields.

Remove will remove element(s) matching the path specified in the Element Path field, together with all of their attributes - provided that the values specified in the Element Text and Attributes fields exactly match the corresponding values in the element(s) to remove.

Remove Only Attributes will only remove the attributes listed in the Attributes field, from those element(s) matching the path specified in the Element Path field. This option is the only way to remove attribute(s) from existing element(s) while preserving the element(s) themselves. Only matching attributes will be removed, as listed in the Attributes field. If no attributes have been listed in the Attributes field, all attributes will be unconditionally removed.

Element Path

Type the path to the element, including the root element. Start with the root element, and separate each following child element using the \ character.

Modify All Matching Elements

Check this box to process all elements matching the path specified in the Element Path field, in accordance with the action requested in the Action field.

Uncheck this box to modify only the first element matching the path specified in the Element Path field.

Element Text

Type the text for the element being edited in the document. This field is optional.

Attributes

Define one or more attributes for the element being edited in the document. Defining attributes is optional.


Else

This command is used in conjunction with If commands. It has no configurable parameters. It is used to direct program flow.


End

This command is used in conjunction with If commands. It has no configurable parameters. It is used to direct program flow.


Evaluate Expression

This command evaluates complex logical expressions, and stores the result in a variable.

Expression

Enter the expression to evaluate in this field. The expression must have the following syntax:

eval-token <bool-operator> eval-token [<bool-operator> eval-token, ...]

An eval-token is comprised of a token and operator provided in this form: token <operator> token.

A token is either a string literal or a variable. String literals must be enclosed in double quotes. Variables must be enclosed between "$" signs. An example string literal token would be "this is a string". An example variable token would be $EXAMPLE_VAR$.

An operator may be any one of the following: =, <>, <=, <, >=, >. These operators test for equality, inequality, "less than or equal to", "less than", "greater than equal to", and "greater than" relationships between the given tokens. If the relationship holds between the given tokens, the result of the evaluation is TRUE, and FALSE otherwise.

An expression may be compounded using the bool-operator. A bool-operator is either and or or. and evaluates an expression to TRUE if both eval-tokens evaluate to TRUE. or evaluates an expression to TRUE if at least one eval-token evaluates to TRUE.

While operator precedence is not available, you may use bracket signs ( ) to specify priority when evaluating expressions. Otherwise, evaluation proceeds from left to right without any precedence.

An example expression would be: $A$ = "value1" or ($B$ = "value2" and $C$ = "value3"). In this example, A, B, and C are regular script variables. The expression evaluates to TRUE if variable A holds the value value1, or variable B holds the value value2 together with variable C holding the value value3. All three variables must have been defined before the Evaluate Expression command executes to avoid runtime errors.

Variable

Enter the variable to receive the result of the evaluation in this field. If the expression contains a syntax error, this variable receives ERROR. If the expression evaluates to a true condition, this variable receives TRUE. If the expression evaluates to a false condition, this variable receives FALSE. If the expression references an undefined variable, this variable receives ERROR.

Notes

  • The syntax of this command is identical to the third-party Camelot Eval Plug-In.


Evaluate XPath Query

This command runs a specified XPath query against a given .XML file and returns the results in a $NEWLINE$ pre-defined variable delimited collection that may be parsed using a For Each...Next loop.

XML File

Type the full path to the XML file containing the information to retrieve.

Query

Enter the XPath syntax query in this field.

Variable

Type the name of the variable to hold the obtained value here.

Result Type

Choose the desired type of enumeration to receive in this field.

Notes

  • If the requested information cannot be found, the variable will hold an empty string.


Extract 7Zip Archive

This command extracts the contents of a 7Zip archive. InstallAware uses 7Zip data compression technology which provides superior data compression rates for files of all types. Using the Extract 7Zip Archive command, you may extract stand-alone 7Zip archives directly from within your setup. InstallAware web media blocks are also compressed using 7Zip data compression and may be extracted manually, if required, using this command.

Archive

Provide the full path to the 7Zip archive to extract. InstallAware supports only the LZMA or Stored data compression algorithms for extraction from 7Zip archives. 7Zip archives may contain files compressed using other algorithms, however LZMA compressed archives provide the best compression rates.

Password

If the archive to extract is password protected, enter the password here.

Output Folder

Provide the full path to the output folder for the files contained inside the 7Zip archive.

Preserve Folder Names

7Zip archives may contain files stored with folder names, relative to the root of the archive. If you would like to preserve these folder names when extracting an archive, check this option. If you would like to extract files without folder names (by just using base file names), leave this option unchecked. If an archive contains files with identical names in different subfolders, leaving this option unchecked may not extract all of those files, as identically named files will either be overwritten, or skipped.

Always Overwrite

If files being extracted already exist on the target path, they will either be overwritten, or skipped from extraction. Check or uncheck this option based on the behavior you want for replacing pre-existing files.

Return Success State in Variable

If you enter a variable name into this field, the variable will receive the result of the extraction operation. If the extraction completed successfully, the variable holds SUCCESS. If the extraction failed with an error, the variable holds a textual description of the extraction error that occured.

Notes

  • You may also extract InstallAware self extracting EXE files (built using compressed or web deployment options), or other self extracting 7Zip archives using this command. The command will skip executable data and extract the archive that is contained inside the EXE file.
  • If the folder specified by the Output Folder field does not exist, it will be automatically created for you.


Extract Path

This command manipulates a path string to extract the requested drive, folder, file name, or file extension information, OR it replaces double occurences of a backslash character with a single occurence.

Variable

This variable holds the path to convert. It will be replaced with the updated path after the conversion.

Operation

Choose the type of operation to perform. The table below lists the result of each of the available operations against a sample path value of C:\Program Files\My Company\\application.exe.

Operation | Resulting Value
Extract Full File Name | application.exe
Extract File Name Only | application
Extract File Extension Only | exe
Extract File Folder | C:\Program Files\My Company\
Extract Parent Folder | C:\Program Files\
Extract Parent Drive | C:\
Replace \\ with \ | C:\Program Files\My Company\application.exe


Find All Files

This command searches for files matching a wildcard specification on the target system, and returns results in a string variable. If multiple file names match, the returned file names are delimited by the | character. If some of the returned files contain embedded spaces, those file names will additionally be wrapped inside double quote " characters.

Search Path and Wildcards

Provide the full path and wildcard pattern to search for. The search starts in the specified path and all files matching the given wildcard pattern will be returned. * and ? characters are legal wildcards and work in the same way as when used in searches conducted using the operating system. You may also use a single file name, instead of a wild card, to search for a specific file.

Search Subfolders

If the search path contains subfolders, and you wish to search for files inside those subfolders, check this option.

Include Directory Names

If you are searching for files using the *.* wildcard (all files match), the command may also return the folder paths that were traversed. Enable this option to include the folder paths, disable this option to obtain file names only.

Variable

Enter the variable to hold the results of the search.

Notes

  • If no matching files are found, the variable entered in the Variable field will be an empty string.
  • You may easily navigate the results returned by this command using the For Each...Next loop constructs.


Find All Registry

This command searches for the names of subkeys or values contained within a registry key. The returned names are delimited by the $NEWLINE$ variable.

Variable

Type the name of the variable to receive the read names.

Root

Select the root of the read operation using the drop down menu.

Key

Type the name of the key to read from.

Find all key names

Select this box to obtain the names of subkeys within the designated key.

Find all key values

Select this box to obtain the names of values within the designated key. The default value, which is unnamed, will be reported as the string literal (Default). This string literal should be replaced with an empty string before being passed to other registry functions.

Notes

  • If no matching files are found, the variable entered in the Variable field will be an empty string.
  • You may easily navigate the results returned by this command using the For Each...Next loop constructs.


For Each

This command is used to automatically enumerate each element of a given list through a temporary variable. Loops started using this command must be ended using the Next command.

Collection

The list containing the elements to enumerate.

There is no pre-defined list syntax - any dereferenced variable or literal value is permitted in this field.

Separator

The separator that delineates each individual list element for enumeration. Different separators therefore allow for different enumerations on the same source lists.

Separators found at the beginning or at the end of a list, as well as consecutive separators with no elements in between, are not enumerated. In other words, the loop variable will never receive an empty value.

If the separator is not found in the collection, the entire list literal will be enumerated as a single element.

Element

The temporary variable that receives the current member of the list that is being enumerated.

This variable must not have been defined anywhere else in the script.

This variable will only be defined within the scope of the current loop.

Nested loops must use unique variables, but the same variable names may be re-used in non-nested loops.


Generate Native Images

This command generates or deletes native images for a .NET assembly. Native images remove the need for just in time compilation and therefore improve performance for .NET applications. Native images are typically generated for assemblies installed into the Global Assembly Cache using the Install Assembly command.

Beginning with .NET 2.0, this command can be used with .NET 2.0 executables as well. When used with .NET 2.0 executables, this command generates native images for all assemblies associated with the executable (without manually requiring to specify each assembly).

Assembly Path or Full Name

Enter the physical path to the assembly on the target system here, OR enter the full name of the assembly here.

With .NET 2.0, you may also enter the physical path on the target system to an executable, which will generate native images for all assemblies associated with that executable.

Generate Native Images

Generates native images to improve runtime performance.

Delete Native Images

Deletes previously generated native images to recover disk space.

Notes

  • If you are installing into the GAC, it will be easier to enter the full name of the assembly, instead of the physical path on the target machine which can be difficult to determine. To obtain the full name of the assembly, click the Browse button, then choose the assembly file located on your local system. This will automatically obtain the full name of the assembly for you. If you attempt to enter the full name of the assembly yourself, be sure to enter the precise, correct name, otherwise the Generate Native Images command will fail to locate the assembly.
  • If you are not installing into the GAC, it will be easier to enter the full path to the assembly on the target system instead, such as $TARGETDIR$\assemblies\mylibrary.dll. In this case do not use the Browse button.


Get Component Space

This command gets the space requirements of a component previously defined by the Define Component command.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command. Leave this field empty to obtain the total space that is required by all setup components combined, including the "selection independent" implicit component.

Required Space Variable

Type the name of the variable to receive the exact byte size required by the component in this field.

Notes

  • Space required by the children of a component are not reported by this command.


Get Component State

This command determines if a component defined using the Define Component command is selected for installation.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command.

Selection State Variable

Type the name of the variable that will receive TRUE if the component is selected and FALSE if it is not.

Notes

  • In wizard generated installs, the SELECTED variable is used to test selection of each component.
  • InstallAware calculates disk space requirements for each component in connection with the Get Component State command. Each installation action following a Get Component State command is added to the disk cost of the component that the command checks the selection of. You must use Get Component State commands for each of your components for accurate disk space requirements reporting.


Get Environment

This command obtains the value of an environment variable. This command may also be used to return the full list of environment variables and their values.

Environment Variable

The name of the environment variable that the value will be obtained from.

Leave this field empty to obtain the full list of environment variables and their values, delimited by the pre-defined variable $NEWLINE$. The resulting list will be returned in this format: VAR_1=VALUE_1$NEWLINE$VAR_2=VALUE_2$NEWLINE$...VAR_N=VALUE_N.

Variable

The name of the script variable that will receive the value of the indicated environment variable, or the full list of environment variables and their values.


Get File Version

This command obtains the version number of a file.

File Path

Full path to the file that version information should be extracted from.

Variable

The name of the variable that receives version information. The version is represented in human readable form. If version information is not found in the file, this variable will contain the value 0.0.0.0.

Notes

  • To compare a file version to another file version, use the Check File Version command.


Get Folder Location

This command obtains the location of a pre-defined folder on the target system.

Variable

Type the name of the variable to hold the folder location.

Folder

Choose the pre-defined folder that the location should be obtained for.

Get for All Users

Has effect only on NT operating systems. If checked, the command will attempt to obtain the location of the pre-defined folder that is shared by all users of the target system, if it is available.

Notes

  • If the requested location cannot be found, the variable will hold an empty string.
  • In wizard generated installs, the following variables hold the following folder locations:
Variable | Folder Location
PROGRAMFILES | Typically C:\Program Files
COMMONFILES | Typically C:\Program Files\Common Files
SHORTCUTFILESALL | Typically C:\Documents and Settings\All Users\Start Menu\Programs
SHORTCUTFILES | Typically C:\Documents and Settings\<user>\Start Menu\Programs
DESKTOPDIR | Typically C:\Documents and Settings\<user>\Desktop
WINDIR | Typically C:\Windows
WINSYSDIR | Typically C:\Windows\System32


Get IIS Property

Use this command to obtain an arbitrary textual, numeric, or boolean property belonging to an Internet Information Services website identified by its Site Index, or a virtual folder underneath that site.

IIS Object

Choose whether to obtain the property for a website or virtual folder.

Site Index

The numeric identifier of the website.

Virtual Path

The path of the virtual folder as it appears underneath the IIS website. Leave this field empty to indicate the root folder. Enter a path in this field to indicate a sub folder.

Name

Enter the name of the property to obtain. For instance, enter EnableDocFooter for a virtual folder to determine whether that folder serves document footers.

Variable

Enter the name of the variable that will receive the value of the property being queried.

Use IIS 7 Processing

Use a new way of interpreting the data provided above, designed specifically for IIS 7.

Notes

  • Use the Set IIS Property command to set an IIS website or virtual folder property.
  • The site index of a web site may be obtained from its name using the Get IIS Site Index command.
  • The Get IIS Property command may only obtain simple properties from the IIS metabase, it may not be used to obtain properties stored in complex records or structures.


Get IIS Site Index

This command obtains the site index for an Internet Information Services website identified by its site name. Most IIS commands identify a site by its site index instead of its site name. Use the Get IIS Site Index command to obtain the required index before using such commands.

Site Name

The name of the website.

Variable

The variable that receives the site index for the given site name.

Notes

  • If a site with the given name cannot be found, the variable receives the value 0.


Get IIS Site List

This command returns the full list of websites hosted on the IIS web server instance on the local system.

Variable

Enter the name of the variable to receive the list of websites. The variable receives a $NEWLINE$ delimited list of website names.

Notes

  • You may use the Parse String command to obtain individual names from the list of servers that the variable receives.


Get INI File Settings

This command reads the value of a section key from a .INI file.

Variable

Type the name of the variable to hold the obtained value here.

INI File

Type the full path to the INI file containing the value.

Section

Type the name of the INI section.

Key

Type the name of the section key.

Notes

  • If the requested INI file, section, or key cannot be found, the variable will hold an empty string.


Get OS or SP Level

This command obtains exact operating system or service pack version information from the system. It is similar to the Get System Settings command, but different in that it does not check for "at least or newer", and performs an exact comparison. While in most cases a check for "at least" a particular version is sufficient, sometimes an exact check is required, which is the intended usage of this command.

Variable

Type the name of the variable that will receive the version information.

Get Exact Operating System Version

Check this box to obtain the exact operating system version. The possible return values for the Variable field when this option has been selected are as follows:

Value | Meaning
UNKNOWN | An unrecognized operating system version
SERVER8 | Windows Server 2012
METRO | Windows 8
2008R2 | Windows Server 2008 R2
SEVEN | Windows 7
2008 | Windows Server 2008
VISTA | Windows Vista
2003 | Windows Server 2003
XP | Windows XP
2000 | Windows 2000
ME | Windows Millenium Edition
98SE | Windows 98 Second Edition
98 | Windows 98
NT4 | Windows NT 4.0
95 | Windows 95

Get Exact Service Pack Version

Check this box to obtain the exact service pack version. The Variable field holds the exact number of the service pack level. For example, if Service Pack 6.0a has been installed on Windows NT 4.0, this variable receives the value 6.

Notes

  • To check for a minimum capability, use the Get System Settings command.


Get System Settings

This command obtains information on whether the target system meets minimum capabilities.

Variable

Type the name of the variable that will hold TRUE if the system meets the minimum capability, and FALSE if not.

Capability

Choose the capability to check for using the drop down menu.

Notes

  • This function only checks for a minimum capability. For instance, if you are checking for 32 MB Physical Memory, the function will return TRUE if the target system contains at least 32 MB physical memory, or more.
  • If you need to check for an exact operating system or service pack level (and not "at least or newer"), use the Get OS or SP Level command instead.
  • Some capabilities, such as the IIS Anonymous User Account capability, are not returned as TRUE or FALSE values, but as their actual values on the target system. If the requested capability is not available, the return is an empty string.
  • The Logged on User Priviledge Level capability returns the following values, with the meanings as described in the table below.

    Value
    Meaning
    ADMIN
    The logged on user is a system administrator.
    POWER
    The logged on user is a power user (also called a user)..
    USER
    The logged on user is a user (also called a limited user).
    GUEST
    The logged on user is a guest, with very limited rights.
  • The Processor Architecture capability returns the following values, with the meanings as described in the table below.

    Value
    Meaning
    UNKNOWN
    An unknown processor architecture.
    X86
    Intel 32 bit compatible architecture.
    IA64
    Intel Itanium 64 bit compatible architecture.
    AMD64
    X64 (Intel EM64T or AMD64) 64 bit compatible architecture.


Get Temporary File

This command obtains a temporary file name.

Variable

This variable receives a fully qualified temporary file name, located in the system temporary files folder.

Notes

  • This function does not create a file with the given name, it only obtains a legal temporary file name.


Get XML File Settings

This command retrieves information from an .XML file.

Variable

Type the name of the variable to hold the obtained value here.

XML File

Type the full path to the XML file containing the information to retrieve.

Element Path

Type the path to the element, including the root element. Start with the root element, and separate each following child element using the \ character.

Attribute Name

Type the name of the attribute to retrieve, or leave the field empty to retrieve the element text.

If more than one element matches the value in the Element Path field, the text for all matching results is returned; where each result is delineated with the $NEWLINE$ pre-defined variable.

Notes

  • If the requested information cannot be found, the variable will hold an empty string.


GoTo Label

This command directs program execution to the indicated Label. The label must be previously defined.

GoTo Label

Type the name of the label to direct program execution to, as exactly defined by the Label command.

Notes

  • If the GoTo Label is called while inside a conditional block, the block will be immediately exited.


Hide Dialog

This command is used to remove a non-modal dialog from the screen. The dialog will have been previously shown using the Display Dialog command. It does not have any configurable options and will simply remove the last non-modal dialog displayed on-screen.

Hide Dialog is generally used to remove a progress dialog from the screen before showing a finish dialog after a completed installation.


If

This command is used to direct program flow conditionally after performing an evaluation. It is used in conjunction with the Else If, Else, and End commands.

Variable

Type the name of the variable, according to the value of which the conditional evaluation will be performed.

Comparison

Choose a comparison type from the drop down menu. If both variables contain integer values, a numeric comparison will be performed. If at least one variable contains a non-integer value, a string comparison will be performed.

If you choose the Is Defined comparison, the command does not require the Compare With field, and only tests if the variable name specified above has been previously defined using a Set Variable command. This may be useful in cases where persistent variables are used, as it may be hard to determine which variables used in the setup script have been already initialized and which have not been initialized.

Reverse Comparison

Check this checkbox if you wish to execute an if not evaluation.

Compare With

Type the name of the second variable for comparison. You may also use a string literal in this field instead of a variable.


Include Script

This command inserts code from a setup script file into the current position in the active script. The Include Script command adds a great amount of versatility and power in sharing code across different setup projects, breaking up complex scripts into logical, re-usable units; and building code libraries that perform specialized tasks.

Script

Enter the name of the script file to include here, without file path or extension information. Clicking the down arrow will scroll through the list of script files that are already a part of the setup project and can be included.

Notes

  • The insertion occurs at compile time.
  • Include scripts cannot refer to themselves or one another recursively. Include scripts are not seperate program segments like functions with their own stack, local scope, and variables; they are instead direct includes of commands (much like include files in the C++ programming language).
  • The included script must already be a part of the current setup project for the compilation to succeed. See modifying include scripts for more information.


Install Assembly

This command installs a .NET assembly and registers it on the target system.

Source Assembly

Enter the full or relative path to the assembly to install.

Install into the Global Assembly Cache

Check this box to install the assembly into the GAC.

Install into Custom Path

Check this box to install the assembly into a location outside the GAC. Selecting this option is identical to using the Install Files command for installing the assembly file.


Install Files

This command is used to install files on the target system.

Source Files

Provide the full or relative path to the files to install. Relative paths will be resolved relative to the project folder. These files must exist on your development system and therefore no runtime script variables are allowed in this field. Only a string literal may be used here, but wildcards, compiler variables, and environment variables are supported as part of the string literal. This field will be resolved at compile time to the actual files found on your system by the compiler. Check the Include subfolders if wildcards used checkbox to perform a recursive operation.

Exclude Wildcards

If you would like to exclude some of the files matching your source file pattern above, you may do so by specifying exclude wildcards. Exclude wildcards allow you to filter out some files at build time from inclusion in your setup. Leave this field empty if you do not wish to exclude any files. If you wish to exclude a particular file, folder, or a collection of files and/or folders, enter the name(s) of the items to exclude here. You may use wildcards. Seperate multiple items using semi-colons. Remember to enclose items that contain spaces in their names inside double quotes.

Target Folder

Provide the full path to install the files on the target system. This field should not be left empty.

Set Attributes

Check each of the file attributes you wish to set on the files after they have been installed on the target system.

File Properties

Check the relevant file properties for the files you are installing. The checksum property is ignored by the Native Engine.

Copy Options

Check all the desired file copying and removal safeguides.

Notes

  • For accurate disk space requirements, please see the comments following the Get Component State command.
  • The Windows Installer engine behavior is to overwrite files on the target system only if the ones you are copying are newer. This behavior cannot be changed with the Windows Installer engine.
  • Similarly, the Native Engine by default will not overwrite files on the target system if the ones you are copying are not newer, however overwrites may be forced by setting the pre-defined variable NATIVE_OVERWRITE_OLDER to TRUE. However, this is not recommended as it may compromise target system integrity and may break other applications.
  • If you checked File is Self Registering DLL, remember that all files that the Install Files command pertains to must be self registering. If a self registration error occurs, the Windows Installer engine will roll back the entire installation as part of its resiliency mechanism. The Native Engine will not roll back unless the end-user cancels the installation when the self registration error is reported.
  • The Windows Installer engine does not perform self registration for executable files, or across reboots. The Native Engine handles both cases successfully.
  • With the Windows Installer engine, if files you are installing require to be self registered in a particular order, do not check the File is Self Registering DLL option. The Windows Installer engine does not allow the self registration order of files to be specified. Instead, use the Register Library command to manually self register those files.
  • The above limitation does not apply to the Native Engine. Self registering files will be self registered in the exact order of execution as found in your MSIcode script.
  • If you checked File is Vital for Installation, setup will not succeed unless the files in question are selected for installation and successfully installed.


Install ODBC Driver

This command installs an ODBC data provider.

Driver Name

Enter the name of the data provider here. If you wish to duplicate the settings of a driver already installed on your system, click the drop-down arrow and choose the driver to capture.

Driver DLL

Choose the driver DLL file. If the driver requires other files as well, install them normally using the Install Files command.

Setup DLL

Choose the driver setup DLL file.

Target Path

Enter the folder on the target system where the driver should be installed.

Attributes

Specify your data provider attributes here. You may enter multiple attributes by pressing CTRL+ENTER.

Notes

  • Do not dereference variables using $ signs in the Attributes field.
  • Dereference variables using square brackets instead.
  • For instance, instead of using $TARGETDIR$, use [TARGETDIR].


Install Service

This command installs a service.

With the Native Engine, a service installed using this command will be automatically removed during uninstallation. The uninstallation will not attempt to stop the service before removal; this may delay the actual removal of the service until the next reboot of the system. If you would like to immediately stop the service, call the Control Service command before calling Apply Uninstall in your script.

With the Windows Installer engine, service removal does not occur automatically. If you would like to remove the service during uninstallation, call the Control Service command with the control timing set to uninstallation before calling Apply Install in your script.

Service File

Choose the service entry point file. If the service requires other files as well, install them normally using the Install Files command.

Target Path

Enter the folder on the target system where the service should be installed.

Languages

Enter the numeric language identifiers for the service here. For instance, the identifier for English (US) is 1033. Leave this field empty if the driver is language neutral.

Service Name

Enter the name of the service, as it will be identified to the system. You may also use this name with the Control Service command.

Display Name

Enter the display name for the service, as it will appear in the Services Control Panel Application.

Service Description

Enter the ddescription for the service, as it will appear in the Services Control Panel Application.

Service Type

Choose the type of service being installed in the drop-down menu.

Service Interacts with Desktop

Check this item if the service interacts with the user. Uncheck it if the service does not interact with the user.

Load Order Group

If you wish to define the service as part of a load order group, enter the name of that group here.

Dependencies on Services and Load Order Groups

If the service requires that other services must have already been started before it can execute, specify the names of those services in this field:

  • To specify a service name, enter the name of the service.
  • To specify a load order group, consisting of multiple services, enter the name of the load order group prefixed with the + character.
  • If you need to specify dependencies on multiple services and/or load order groups, seperate each name with the [~] characters.

Service Startup

Choose how the service should start when the system is being started using the drop-down menu.

Startup Error Handling

Choose how errors occuring during an attempted service startup as part of a system start should be handled using the drop-down menu.

Account Name

If the service should run in the context of a particular user account, enter the name of that account here.

Account Password

If the service should run in the context of a particular user account, enter the password for that user account here.

Command Line Arguments

If there are any command line arguments to pass to the service, enter those arguments here.


Is MSI Setup Installed

This command checks whether a Windows Installer setup is presently installed on the system.

Product Code (Guid)

Enter the product code for the Windows Installer setup to check for in this field.

To obtain this code, you may open the MSI file in Orca (or another MSI database table editor), view the Property table, and copy the value of the ProductCode property.

Variable

This variable returns TRUE if the indicated setup is installed. Otherwise, the variable holds FALSE.

Notes

  • The NEEDSUPGRADE pre-defined variable automatically indicates whether a previous version of the running setup has been found on the system.
  • Existing installations may be removed using the (Un)Install MSI Setup command.


Label

This command defines a label that program execution can be directed to using the GoTo Label command.

Edit Label

Type the name of the label as you will exactly use in the GoTo Label command.

Notes

  • You may not place a label inside an if/else if/else/end block.


Load Feature Selections

This command loads feature selections that were previously saved using the Save Feature Selections command. Feature selections indicate the features chosen to be installed by the user during a custom setup.

This command also loads the values of any persistent variables, the pre-defined variables TARGETDIR, STARTMENU and ALLUSERS, and the installation processor architecture.

File Path

The full path to the physical file containing feature selection information.

Warning

  • Do not use this command to load feature selections saved on setups built with versions of InstallAware earlier than InstallAware 6.

Notes

  • It is not necessary to manually save and load feature selections in the same version of a setup (that is, setups which have the same product and revision codes). In the same version of a setup, feature selections are saved and loaded automatically by the setup engine.
  • Save and load feature selections manually only if you wish to migrate feature selection states between different versions of a setup.
  • Selection states will be ignored for all features not explicitly defined in the setup script using the Define Component command by the time the Load Feature Selections command executes in the script. Therefore, make sure the Load Feature Selections command comes after all the Define Component commands in your script.


Localization Variable

The Localization Variable command declares a variable, and initializes it to a particular value. It is similar to the Set Variable command in most respects, but intended for use in aiding localization:

The localization process tracks translations for script statements by their unique identifiers. These identifiers, unique for each script command, are created the first time a statement is entered into the script, and change when the statement line is copied, cut, or pasted (but not edited). While this allows for flexibility in providing separate translations for multiple script lines with identical content, it also carries the drawback that any time a line of code is moved around the script, or re-used elsewhere, it will become dissociated from its original translation.

Unlike the Set Variable command, and all other commands in the setup script, this command generates stable string identifiers for the variable declared, which survive all edits in code. Once a variable has been declared using the Localization Variable command, it can only have a single, stable translation, which survives all script modifications.

Localization Variable

Type the name of the variable to define or re-initialize.

Default Value

Type the default value for the variable. If a localized value for this variable has not been made available through the Localization Wizard, this default value will be used.

Notes

  • The usage of variables declared using this command is identical to the usage of variables created using the Set Variable command. In particular, variables are dereferenced in the same way, using the $VARIABLE$ notation.


Mathematics

This command performs a numerical calculation.

Operand 1

Enter the first operand here. If a variable is used, be sure it represents an integer.

Operand 2

Enter the second operand here. If a variable is used, be sure it represents an integer.

Operation

Choose the type of arithmetic to perform. The following operations are supported with the following operands:

  • Add = Operand 1 + Operand 2.
  • Subtract = Operand 1 - Operand 2.
  • Multiply = Operand 1 * Operand 2.
  • Divide = Operand 1 / Operand 2.
  • Modulus = Operand 1 % Operand 2.
  • Bitwise OR = Operand 1 OR Operand 2.
  • Bitwise AND = Operand 1 AND Operand 2.
  • Bitwise XOR = Operand 1 XOR Operand 2.
  • Bitwise SHL = Shift Left Operand 1.
  • Bitwise SHR = Shift Right Operand 1.
  • Bitwise NOT = NOT Operand 1.
  • ASCII number from string character = Returns the numerical ASCII character code for the first character of Operand 1.
  • String character from ASCII number = Converts a numerical ASCII character code into an string character.
  • Set Random Number Generator Constants = Operand 1 sets Constant 1 and Operand 2 sets Constant 2.
  • Set Random Number Generator Seed = Accepts Operand 1 as the seed. Operand 2 is ignored.
  • Generate Random Number = Use Operand 1 (required) to define a maximum return value and Operand 2 (optional) to define a minimum return value. The default minimum value is 0. The result of this operation is equal to: Seed * Constant 1 + Constant 2.

Return Result in Variable

Type the variable that should hold the outcome of the operation.

Notes

  • If an illegal operation is attempted, such as division by zero or string arithmetic, the result variable will hold an empty string.


MessageBalloon

This command displays a message balloon in the system tray. The message balloon may contain useful updates displayed during a lengthy operation while setup has been minimized to the system tray using the System Tray command.

Title

Indicates the title of the message balloon.

Message

Type the message to display here. You may type a message that spans multiple lines by pressing CTRL+ENTER.

Icon

Choose an icon for your message balloon.

Time-Out

Enter the number of seconds after which the message balloon should automatically hide.

Notes

  • If this command is used while there is no setup icon in the system tray, a call to the System Tray command with the Show icon in system tray only option is implied.
  • On operating systems which do not natively implement system tray message balloons (Windows 95, Windows 98, Windows NT 4.0), InstallAware draws a custom message balloon mimicking the appearance of the native Windows message balloon.


MessageBox

This command displays a message box to the user. The message box may contain useful information and also prompt the user for a decision.

Title

Indicates the title of the message box.

Message

Type the message to display here. You may type a message that spans multiple lines by pressing CTRL+ENTER.

Icon

Choose an icon for your message box.

Buttons

Select which buttons should be available on the message box.

Return Result in Variable

If you wish to know which message box button the user pressed, provide the variable to hold that information here. The variable will hold the exact text of the message box button pressed, all in uppercase, as specified in the Buttons field.


Next

This command is used in conjunction with For Each commands. It has no configurable parameters. It is used to signal the end of a for each loop.


Parse String

This command parses a string by a given pattern or position index and splits the result into two new strings.

String

The string to parse.

Pattern or Position

If you are parsing by a pattern, type the pattern to search for. If you are parsing by position, type the position index.

Variable for First Part

If you are interested in the first part of the parse result, enter the name of the variable to receive that part here.

Variable for Second Part

If you are interested in the second part of the parse result, enter the name of the variable to receive that part here.

Operation

Select the type of parsing to perform from the drop-down menu.

Trim Resulting Variables

Check this box to remove leading and trailing spaces, as well as control characters, from the resulting variables.

Ignore Case

If you are parsing by pattern, and you wish to ignore case in pattern matching, check this box.


Read from Text File

This command helps you read a single line of text from a text file. Unicode files are not supported.

Read from File

Enter the full path of the file on the target system to read from.

Into Variable

Enter the variable that will receive the text read.

Return EOF Check in Variable

Provides a way to determine if the end of file has been reached. The variable specified here will contain TRUE if the file end has been reached, and FALSE if not.

Notes

  • The variable specified in the Into Variable field will only be written to if the text file exists and can be successfully read from. An empty string in this variable, if it was not previously empty, will indicate that the source text file contained an empty line.
  • If the file is being read from for the first time, it will be automatically opened. Any previously opened file will be automatically closed.
  • If the file is being read from is already open, the read will continue from the last file position.
  • If the end of file has been reached, or at the end of the installation, the file will be automatically closed.
  • Prefix the path specified in the Read from File field using the special sequence #READALL\ if you wish to read in the entire file, instead of just the first line of the file. Lines in entire files read this way will be separated using the $NEWLINE$ variable.


Read Registry

This command reads data from a key in the system registry. It is similar to the Check Registry command which also returns specific error codes if the requested data is not found.

Variable

Type the name of the variable to receive the read value.

Root

Select the root of the read operation using the drop down menu.

Key

Type the name of the key to read from.

Value

Type the value to read. Leave empty to read the default value.

Notes

  • If the key/value to read from does not exist, or cannot be opened, the variable will hold an empty string. If you need to distinguish between empty values and non-existent values/keys, use the Check Registry command instead.


Reboot and Login

This command will reboot the target system, after safely exiting the installation. It will then restart the installation from the beginning. It does not have any configurable parameters.

This command is ideal for use during pre-requisite installation.

Since this command writes to the Run registry key, the installation will restart after the Windows shell and other startup programs have been loaded. Security settings on Windows Vista or newer operating systems may prevent setup from automatically restarting without manual user approval. If this is a concern, use Reboot and Resume instead.


Reboot and Resume

This command will reboot the target system, after safely exiting the installation. It will then restart the installation from the beginning. It does not have any configurable parameters.

This command is ideal for use during pre-requisite installation.

Since this command writes to the RunOnce registry key, the installation will restart before the Windows shell and other startup programs have been loaded. If you need to interact with the Windows shell (such as for pinning applications to the Windows 7 Taskbar), use Reboot and Login instead.


Reboot Computer

This command will reboot the target system, after safely exiting the installation. It does not have any configurable parameters.


Register Assembly

This command registers or unregisters a .NET assembly. Registering a .NET assembly makes it available for use by COM Interop.

Assembly Path or Full Name

Enter the physical path to the assembly on the target system here, OR enter the full name of the assembly here.

Set the codebase in the registry

Creates a codebase entry in the registry. The codebase entry specifies the file path for an assembly that is not installed in the global assembly cache. You should not specify this option if you will subsequently install the assembly that you are registering into the global assembly cache. The assembly must be a strong named assembly when using this option.

Register Assembly

Registers the .NET assembly for COM Interop.

Unregister Assembly

Unregisters the .NET assembly from COM Interop.

Notes

  • If you are installing into the GAC, it will be easier to enter the full name of the assembly, instead of the physical path on the target machine which can be difficult to determine. To obtain the full name of the assembly, click the Browse button, then choose the assembly file located on your local system. This will automatically obtain the full name of the assembly for you. If you attempt to enter the full name of the assembly yourself, be sure to enter the precise, correct name, otherwise the Register Assembly command will fail to locate the assembly.
  • If you are not installing into the GAC, it will be easier to enter the full path to the assembly on the target system instead, such as $TARGETDIR$\assemblies\mylibrary.dll. In this case do not use the Browse button.


Register Library

This command registers or unregisters a library (DLL/OCX/EXE/TLB).

Library

Full path to the library to register or unregister.

Operation

Choose whether to register or unregister the library.

Return Result in Variable

If you wish to know the result of the (un)registration operation, enter a variable name here. If the (un)registration succeeds, the variable will be set to TRUE, otherwise FALSE.

Notes

  • Windows Installer does not permit the self registration of executable files or type libraries. You may use this command to self register executables or type libraries.
  • Windows Installer does not permit specifying the order of self registration. If the libraries you are installing are inter-dependent and require to be registered in a particular order, do not register them through Windows Installer (do not check the File is Self Registering DLL option in the Install Files command). Use this command instead.
  • Files you self register with this command during an installation must be explicitly unregistered when they are being removed (such as deselection during an installation maintenance operation or a complete uninstallation).


Remove Assemblies

This command removes all assemblies installed by your application from the GAC. For the removal to succeed, the assemblies should be "unpinned", meaning they do not have any clients remaining on the system. For this reason, this command should be called after Apply Uninstall executes. The command will also be unable to remove any assemblies that are still in use by other installed applications.

When the Native Engine is being used, for this command to execute successfully, the setup should not have been compiled with the #NO_MSI# pre-defined compiler variable set to TRUE.


Repeat

This command is used in conjunction with Until commands. It has no configurable parameters. It is used to unconditionally initiate a repeat loop.


Replace String

This command replaces the occurences of a substring with a replacement value in the given string.

Variable

Enter the name of the variable that holds the string containing the values to replace. The variable must already be initialized with a string value.

Old Pattern

Enter the substring to search for.

New Pattern

Enter the new value to replace Old Pattern in Variable.

Ignore Case

Check this option to search and replace without regard for uppercase or lowercase characters. Uncheck this option to match substrings with correct case.

Replace All

If you would like to replace all occurences of Old Pattern with New Pattern, check this option. If you would like to replace only the first occurence, uncheck this option.


Run .NET Installer Class

This command executes a .NET installer class, either in installation mode, or in uninstallation mode.

Assembly Path or Full Name

Enter the physical path to the assembly on the target system here, OR enter the full name of the assembly here.

Install

Calls the class in installation mode.

Uninstall

Calls the class in uninstallation mode.

Notes

  • If you are installing into the GAC, it will be easier to enter the full name of the assembly, instead of the physical path on the target machine which can be difficult to determine. To obtain the full name of the assembly, click the Browse button, then choose the assembly file located on your local system. This will automatically obtain the full name of the assembly for you. If you attempt to enter the full name of the assembly yourself, be sure to enter the precise, correct name, otherwise the Register Assembly command will fail to locate the assembly.
  • If you are not installing into the GAC, it will be easier to enter the full path to the assembly on the target system instead, such as $TARGETDIR$\assemblies\mylibrary.dll. In this case do not use the Browse button.


Run Light Mode Setup

This command executes an InstallAware installation that has been built without the InstallAware runtime files. Normally when a setup is built, it contains all the necessary files that bootstrap the installation, display the setup user interface, and drive the installation script, before passing control to Windows Installer that performs the actual installation. The setup.exe program that is generated after a build is one of those runtime files, as well as other support libraries. If you are nesting multiple InstallAware setups within one another, since the master setup already contains the InstallAware runtime, you may exclude the runtime from the nested setups and save disk space and download times. Setting the compiler variable NOEXE to TRUE builds light mode setups which exclude the overhead of the runtime. Such setups, despite having an EXE extension, cannot execute directly and must be run using the Run Light Mode Setup command from within a master InstallAware setup.

Light Mode Setup

Provide the full path to the InstallAware setup built in light mode.

Parameters

If you would like to specify command line parameters for the installation, enter them here.

Wait for Setup to Finish

If you would like to wait for the spawned light mode setup to finish execution before script execution resumes, check this option.

Return Success State in Variable

If you enter a variable name here, the variable holds the numeric return value from the spawned setup. The return code is normally 0, which indicates successful execution. Notes

  • A successfully executed setup does not necessarily indicate that the installation completed - for instance, the user may have cancelled the setup. If you would like to specify custom return values in your setups, use the Terminate with Exit Code command.
  • The setup file referenced by the Light Mode Setup field must be located inside a writable folder. Light mode setups may not be spawned from non-writable media, such as CD or DVD media.


Run Program

The Run Program command enables you to execute a program on the target system, optionally wait for its completion, and obtain execution result (provided, of course, the program sets a return value). For more execution options, use the Run Program As command.

Run Program

Type the full path to the executable that is to be run.

Hide Program Window

If you wish to hide the window of the executable, check this checkbox.

Command Line

If you will be using any command line parameters, enter them in this field.

Wait For Program to Finish

If you wish to pause the installation script until the indicated program completes executing, check this checkbox.

Return Result in Variable

If the program you are running sets a return value, you may capture it inside a variable by providing the name of the variable in this field. If the program cannot be started, this variable receives the value -1.

Notes

  • Some programs may have difficulty with long path names used in their command lines. It may be best to use the Convert Path command on such paths before executing the program.


Run Program As

The Run Program As command enables you to execute a program on the target system with advanced options. For simpler execution, use the Run Program command.

Run Program

Type the full path to the executable that is to be run.

Working Directory

Type the full path for the startup folder of the executable. Leave empty for the default (current) folder.

Command Line

If you will be using any command line parameters, enter them in this field.

Environment

If you wish to override the existing environment block and pass new environment variables to the program, enter them here. Seperate each variable-value pair using the pre-defined variable $NEWLINE$. An example block could be specified as follows: VAR_1=VALUE_1$NEWLINE$VAR_2=VALUE_2$NEWLINE$...VAR_N=VALUE_N.

Program Window

Choose a display mode for the program window.

User Name

If you wish to run the program under a different user account than the current logged on user, enter that account name here.

Password

If you entered a user account in the User Name field, enter the password for that account here.

Domain

If you wish to run the program under a different domain than the current logged on user's domain, enter that domain name here. You must also populate the User Name field.

Return Result in Variable

If the program you are running sets a return value, you may capture it inside a variable by providing the name of the variable in this field. If the program cannot be started, this field receives a negative integer value.

Run under limited user account when UAC is enabled and setup is elevated (de-elevation)

On Vista or higher, when setup is elevated to full admin rights, all tasks spawned by setup are also elevated to full admin rights. This might be a problem when setup is originally invoked from a limited user account and elevated through a UAC dialog. While setup will complete successfully, any tasks spawned by setup (such as the application being installed) will be run as administrator, instead of the original limited user. This can pose problems for users when they cannot re-run the application being installed as administrator after setup quits; thus potentially leading to misplaced application configuration files and/or user data. To prevent this problem, check this box. This setting has no effect on operating systems older than Vista, or if UAC has been disabled.

Notes

  • Some programs may have difficulty with long path names used in their command lines. It may be best to use the Convert Path command on such paths before executing the program.
  • If a Working Directory is specified, this command will also change the current directory to the specified working directory. This is done in addition to setting the correct startup folder for the new process, which may not always be sufficient. If you do not desire this behavior, use the Run Program command.
  • If you wish to preserve the existing environment and append/prepend to the block, first use the Get Environment command with an empty Environment Variable field to receive all existing variables and values, and then append/prepend your custom variables to this list.


Save Feature Selections

This command saves feature selection information into a physical file. Feature selections indicate the features chosen to be installed by the user during a custom setup. This selection information may later be loaded using the Load Feature Selections command.

This command also saves the values of any persistent variables, the pre-defined variables TARGETDIR, STARTMENU and ALLUSERS, and the installation processor architecture.

File Path

The full path to the physical file that will receive feature selection information. If the file already exists, it will be overwritten.

Warning

  • Do not use this command to save feature selections to be loaded on setups built with versions of InstallAware earlier than InstallAware 6.

Notes

  • It is not necessary to manually save and load feature selections in the same version of a setup (that is, setups which have the same product and revision codes). In the same version of a setup, feature selections are saved and loaded automatically by the setup engine.
  • Save and load feature selections manually only if you wish to migrate feature selection states between different versions of a setup.


Schedule Task

This command schedules a task using the Windows Task Scheduler.

Task Name

Enter the name of your scheduled task here. Your task will be listed in the Windows Task Scheduler management interface under this given name.

Target Computer

Enter the name of the computer to schedule the task on. To schedule the task on the current computer setup is running on, leave this field empty.

When computer boots

Select this radio button to run the scheduled task every time the target computer boots.

When computer boots

Select this radio button to run the scheduled task every time the user logs on to the target computer.

Weekly

Select this radio button to run the scheduled task at the specified schedule.

The schedule is specified using the combo boxes found under the radio button. You may click the drop-down arrow in the combo boxes to choose your desired schedule.

You may also use variables in place of the hard coded values in the combo boxes, as long as the variables contain a value similar to one of the default values in the combo boxes. For instance, to schedule a task to run on Monday, as long as the variable entered into the combo box contains some form of the text monday, the scheduler will schedule the task to run on Monday.

Similarly, when using a variable to indicate your timing, use the same HH:MM AM/PM format that is found in the default combo box values. You are not restricted to using exact hours and may specify any minute.

Run if connected to Internet

Check this box to have the scheduled task run only when an Internet connection is available.

Interactive task

Check this box to indicate that the task runs interactively on the users desktop.

Run only when user is logged on

Check this box to have the task run only when a user is logged on to the scheduled system.

Run Program

Type the full path to the program that this scheduled task should run.

Working Directory

Type the full path for the startup folder of the program. Leave empty for the default (current) folder.

Command Line Parameters

If you will be passing any command line parameters to the program, enter them in this field.

User Name

If you wish to run the program under a different user account than the current logged on user, enter that account name here.

Password

If you entered a user account in the User Name field, enter the password for that account here.

Notes

  • The Windows Task Scheduler is not available on Windows 95 and Windows NT 4.0 with the old shell. This command will fail on such systems.
  • The scheduled task may not run if the task scheduler service is not running at the scheduled time.
  • If the task scheduler service is installed but not running when this command is called, the command starts the service automatically.


Set 64 Bit Mode

This command determines the processor architecture used by the installation. This command may be used to set processor architectures while setup is already running on the target system, making it possible to ship a single installer for both 32 bit and 64 bit Windows, switching by processor architecture at runtime.

The Get System Settings command may be used with the Windows in 64 bit Mode flag to determine the availability of 64 bit capabilities at runtime, and the Processor Architecture flag to determine the exact 64 bit architecture of the underlying processor (Itanium or AMD64/EM64T).

Win32

Setting this option when setup is running on 32 bit Windows performs a native 32 bit installation. On 64 bit Windows, setup performs a compatibility mode 32 bit installation.

Itanium ia64

Setting this option when setup is running on 64 bit Windows with an Intel Itanium processor performs a native 64 bit installation. On any other operating system and processor combination, setup fails when Apply Changes is called.

x64

Setting this option when setup is running on 64 bit Windows running on an AMD64 or EM64T processor performs a native 64 bit installation. On any other operating system and processor combination, setup fails when Apply Changes is called.

Warnings

  • When applications are running on 64 bit Windows in 32 bit compatibility mode, Windows redirects file system and registry access to alternate 32 bit compatibility locations. This may cause undesired behavior with your setup if you call the Set 64 Bit Mode command after other commands that access the file system and registry. The commands that have already accessed the file system and registry will have returned incorrect 32 bit compatibility values that will not accurately reflect the true state of the 64 bit system.
  • Always call the Set 64 Bit Mode command before any commands that may access the file system and registry to assure correct 64 bit returns from those commands. If you have to call the Set 64 Bit Mode command after having accessed the file system and registry, call the file system and registry commands again to obtain correct 64 bit returns.
  • Choosing a 64 bit installation mode while running on 32 bit Windows, or choosing an incorrect 64 bit processor architecture while running on 64 bit Windows, does not cause setup to immediately fail. Setup will continue to run normally until an installation, maintenance, patch, advertisement, or uninstall operation occurs.
  • 64 bit runtime installations are available. Some runtimes are designed to install on both 32 and 64 bit platforms, while others are designed to install on only 32 bit, or only 64 bit platforms. You may use custom scripting to always install the correct set of runtimes based on the target platform.
  • Commands and plug-ins that load executable code into memory will not work with 64 bit executables, even when setup is running under 64 bit installation mode. Such commands and plug-ins include Register Library and Call DLL Function. You may use the various alternatives to such commands when running in 64 bit installation mode.

Notes

  • When restarted, setup remembers the processor architecture previously set by this command (unless setup ends with an uninstallation).
  • The default processor architecture in every InstallAware setup is Win32. To build a setup that always runs in 64 bit mode, simply insert a Set 64 Bit Mode command on the first line of your setup with the Itanium ia64 or x64 option selected.
  • It is legal to call this command multiple times with different processor architecture options. You may do so to obtain both 32 bit and 64 bit returns from commands that access the file system and registry on the target system.
  • It is NOT legal to call Apply Changes in the same setup after changes have already been applied under a different processor architecture. Every time Apply Changes is called, the same processor architecture must be set, even though the processor architecture may have been changed in between the calls.
  • To install files into 32 bit folder locations when running in 64 bit mode, obtain the folder locations in 32 bit mode, then install the actual files in 64 bit mode.
  • To write to 32 bit registry locations when running in 64 bit mode, specify the full 32 bit registry paths when writing to the registry in 64 bit mode (including the Wow6432Node string in the key path).


Set Access Control

This command lets you grant or deny permissions to certain types of system objects for groups of users and named user accounts.

Object Path

Enter the full path to the object for which you are setting permissions here.

  • For a file system object, enter the full physical path to the file or folder.
  • For a share object, enter the network name of the share.
  • For a registry object, enter the full path of the registry key, preceded by one of the following [HKCR\ HKCU\ HKLM\ HKU\ HKCC\] depending on the root of the registry key.
  • For a system service, enter the name of the service.
  • For a printer object, enter the name of the printer.

User Accounts/Groups

Check the user accounts and groups you wish to set permissions for on the target object. To specify a named group or user, check the Named User Account/Group box, and enter the name in the field below. This option has effect only if Operation is set to Set Chosen Users with Access Rights.

Operation

Choose whether to completely deny, completely grant, or selectively grant access to the target object.

Access Rights

Check Read and/or Write to grant those types of access. This option has effect only if Operation is set to Set Chosen Users with Access Rights.

Notes

  • Setting access control only works on Windows NT based operating systems (Windows NT 4, Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Server 2008, Windows 7, Server 2008 R2, Windows 8, Server 2012). It has no effect on Windows 9X based operating systems (Windows 95, Windows 98, Windows ME).
  • This command is non-recursive. For example, when access rights are being granted to a file system folder, this command does not set access rights for any files and subfolders already found within that folder - although new files and folders created within the folder will inherit the new access rights automatically.
    • For new file system folders you are creating, you may use the Create Folder command, immediately followed by the Apply Install command, to create an empty folder. Then use this command to grant your desired access rights before installing any actual content inside the new folder, to ensure any installed content automatically inherits your desired rights.
    • To recursively process the contents of an existing file system folder, use the For Each command on the collection of files and folders returned by the Find All Files command on your desired folder, executing this command on each member of the collection, after having removed the double quote " characters returned as part of long file paths by using the Replace String command.


Set Component Choice

This command determines whether it is possible for the end-user to select or deselect a component previously defined by the Define Component command.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command.

Allow user to select/deselect component

To allow the end-user to select or deselect the component, check this box. Otherwise, clear this box.

Notes

  • When used to disable user interaction, this command does not prevent you from toggling the selection state of components in the setup script using the Set Component State command. It only prevents end-user interaction with the component from changing the selection state of a component.
  • Children of a component that has been disabled from end-user interaction are also automatically excluded from end-user interaction. Parents of a component that has been disabled from end-user interaction are not affected.


Set Component Space

This command sets the space requirements of a component previously defined by the Define Component command.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command.

Component Space Requirement

Type the amount of space required by the component here, in bytes.

Notes

  • The setup compiler automatically determines space requirements, and there is no need to use this command to manually specify the size of each component.
  • The intended use of this command is to override the required space for a particular component, or to specify the space requirements of components created dynamically at run-time.


Set Component State

This command sets the selection state of a component previously defined by the Define Component command.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command.

Component is Selected

Check this checkbox to set component state to selected, uncheck it to set the state to unselected.

Notes

  • Wizard generated installations deselect each defined component, other than the first one, when doing a minimum setup.


Set Component Visibility

This command determines whether a component previously defined by the Define Component command is visible or not in end-user setup wizard dialogs for component selection.

Component Name

Type the name of the component here, including its full path as originally used in the Define Component command.

Component is Visible

To show the component, check this box. Otherwise, clear this box.

Notes

  • When used to hide a component, this command does not prevent you from toggling the selection state of components in the setup script using the Set Component State command. It only affects the visibility of the component in setup wizard dialogs for component selection.
  • Children of a component that has been made invisible are also automatically made invisible. Parents of a component that has been made invisible are not affected.


Set Environment

This command sets the value of an environment variable.

Environment Variable Name

The name of the environment variable to set. With the Windows Installer engine, no variables may be used here. With the Native Engine, variables may be used.

Environment Variable Value

The value to set the indicated environment variable to.

Operation

Choose the type of operation to perform from the drop-down menu.

Placement

Choose how to set the value of the variable from the drop-down menu.

Remove Variable/Value During Uninstall

Enable this option to undo this command during an uninstallation.

Set Variable for All Users

Check this box to define a system environment variable. Uncheck this box to define a user environment variable.


Set IIS Property

Use this command to set an arbitrary textual, numeric, or boolean property belonging to an Internet Information Services website identified by its Site Index, or a virtual folder underneath that site.

IIS Object

Choose whether to set the property for a website or virtual folder.

Site Index

The numeric identifier of the website.

Virtual Path

The path of the virtual folder as it appears underneath the IIS website. Leave this field empty to indicate the root folder. Enter a path in this field to indicate a sub folder.

Name

Enter the name of the property to set. For instance, enter EnableDocFooter for a virtual folder to set whether that folder serves document footers.

Value

Enter the value to set for the property. For instance, enter TRUE to enable a boolean setting.

Use IIS 7 Processing

Use a new way of interpreting the data provided above, designed specifically for IIS 7.

Notes

  • Use the Get IIS Property command to get an IIS website or virtual folder property.
  • The site index of a web site may be obtained from its name using the Get IIS Site Index command.
  • The Set IIS Property command may only set simple properties in the IIS metabase, it may not be used to set properties represented as complex records or structures.


Set Variable

The Set Variable command declares a variable, and initializes it to a particular value. If the variable was previously declared, it takes on the new value specified by the command. Variables must be explicitly declared before they can be used in If commands, dialog boxes, or plug-in actions. Commands that write to variables automatically declare them, as long as the command is not dependent on the input value of the variable.

Set Variable

Type the name of the variable to define or re-initialize.

To Value

Type the value for the variable. Leave the field empty to set the variable equal to an empty string.

Remember value when restarting setup

Except for the pre-defined variables TARGETDIR, STARTMENU and ALLUSERS, setup does not save the value of the variables you use in your setup. If you would like setup to save the values of your variables, so they are initialized to the last value they had when setup was running, check this box. If not, leave this box unchecked.

Notes

  • When the Remember value when restarting setup box is checked, variables will not be saved when setup exits after an uninstallation (when Apply Changes is called with the Uninstall Product option).
  • In all other instances, including starting setup but not fully completing the installation (for instance, due to an interim reboot caused by the Reboot and Resume command), variables will be saved.
  • If setup uninstalls and then reinstalls, variable values will be saved again.
  • After the Set Variable command executes with the Remember value when restarting setup box checked at least once for a given variable, that variable will always be saved (within the guidelines discussed above). It is not necessary to check the same box for future uses of the Set Variable command on that same variable.


System Restore

This command is used to create Windows System Restore Points as part of your installation.

Use this command before your setup has made any changes to the target system with the Begin System Restore Point option. After your setup has completed making all necessary changes to the target system (or has failed/been cancelled), use this command again with the End System Restore Point option.

Multiple calls to this command may be nested within the same setup, or across multiple setups.

Begin System Restore Point

Select this radio button to begin creating a new system restore point. Each invocation of the command with this option must be matched with another invocation using the End System Restore Point option.

The following fields apply only when this radio button has been selected:

Restore Point Name

Type in a descriptive name for the system restore point. This localizable field will be visible to end-users when they are running Windows System Restore.

Action

Select the action that best describes the operation being undertaken by your installation.

Variable for System Restore Point Index

This variable will receive the unique numeric index of the Windows System Restore Point that will be created. The value received in this variable must be preserved and passed to this command when invoked using the End System Restore Point option.

If the command fails, the following values are returned:

Value | Meaning
SAFEMODE | Windows System Restore Points cannot be created in Windows Safe Mode.
DISKFULL | Insufficient disk space for processing.
FILERENAME | A pending file rename operation has aborted processing (applies only to Windows ME).
INTERNAL | An internal error occurred in Windows System Restore.
SEQUENCE | The command has been called with invalid data.
DISABLED | The Windows System Restore service has been disabled.
TIMEOUT | A timeout occurred in Windows System Restore.
UNINSTALLED | Windows System Restore has not been installed (it is not installed by default on the Windows Server family of products).
UNKNOWN | An unknown error occurred. Check to make sure setup is running with fully elevated privileges.

End System Restore Point

Select this radio button to finish creating a previously started system restore point. Each invocation of the command with this option must follow a previously made invocation with the Begin System Restore Point option.

The following fields apply only when this radio button has been selected:

System Restore Point Index

Provide the unique Windows System Restore Point index in this field, obtained using the previous invocation of the command. If a non-numeric value is provided, the call to the command is ignored.

Discard System Restore Point

If setup has failed, been cancelled, or the Windows System Restore Point is to be discarded for any other reason, check this box. Otherwise, leave it unchecked to finalize Windows System Restore Point creation.

Notes

  • Windows System Restore is not consistent across different versions of Windows regarding the file types that are protected. Some versions of Windows even permit end-users to customize the types of files and locations of folders that are monitored (NT 5.x), while others do not allow it (NT 6.x).
  • Windows System Restore may occasionally relocate files to incorrect folders, creating duplicate folders of the form original folder, original folder (2), and so forth - when only one folder was originally present.
  • These limitations also affect your cached setup sources and other saved setup data when Windows System Restore partially restores an InstallAware setup that has since been removed. In this scenario, end-users will receive an error message that mia.lib is missing, because it has not been restored. Some other critical setup data and cached setup sources may also be missing.
  • InstallAware requires end-users to run your original setup file (as originally downloaded or found on optical media), instead of any locally cached copy - including the one accessed using the Control Panel Programs and Features applet - any time an InstallAware setup has been inconsistenly restored to a system.
  • Because of the above considerations, InstallAware recommends you create a Windows System Restore Point only when installing your application (and not when removing it).
  • Uninstalling a partially restored InstallAware setup from its original sources will resolve any inconsistencies produced by Windows System Restore.
  • The same considerations apply to your own applications that may be incompletely restored by Windows System Restore, depending on the type of files produced and consumed by your applications at runtime, the version of Windows you are running, and any end-user customizations.


System Tray

The System Tray command shows or hides the setup icon in the system tray. The visibility of the setup icon in the system tray has the following consequences:

While the setup icon is showing in the system tray, minimizing setup hides the taskbar button for setup, which is ideal for time consuming background operations that do not require user interaction. Setup can be restored by clicking or double-clicking the icon in the taskbar.

While the setup icon is not showing in the system tray, minimizing setup does not hide the taskbar button for setup. Setup can be restored by normally clicking the taskbar button for the setup window.

Show icon in system tray and minimize to system tray

This option displays the setup icon in the system tray, minimizes the setup window, and hides the taskbar button for the setup window.

Show icon in system tray only

This option displays the setup icon in the system tray. It does not minimize the setup window or hide the taskbar button for the setup window. When the user minimizes the setup window, the taskbar button of the setup window will be hidden.

Restore from system tray and keep system tray icon

This option restores setup from the system tray, displays the taskbar button for setup, and retains the setup icon in the system tray. If the user later minimizes the setup window, the taskbar button of the setup window will be hidden.

Restore from system tray and hide system tray icon

This option restores setup from the system tray, displays the taskbar button for setup, and removes the setup icon from the system tray. If the user later minimizes the setup window, the taskbar button of the setup window will remain visible.

Notes

  • To notify users while setup is minimized to the system tray, use the MessageBalloon command.
  • If the MessageBalloon command is used while there is no setup icon in the system tray, a call to the System Tray command with the Show icon in system tray only option is implied.
  • On Windows 7, icons on the system tray are not always visible as the system hides them aggressively. This command will also display a Taskbar Overlay Icon on the Taskbar button for the running setup any time a system tray icon would normally be displayed, in addition to still creating the possibly hidden system tray icon. Similary, when the system tray icon is removed using this command, the Taskbar Overlay Icon is removed. If the setup process is not visible on the Taskbar, however, the additional overlay icon will also not be seen, since its container button is absent. To ensure notification visibility under Windows 7, do not use the Show icon in system tray and minimize to system tray option, but instead use the Show icon in system tray only option, as this latter option does not remove the setup process button from the Taskbar.


Terminate Install

This command performs an orderly shutdown of the installation. The installation will immediately exit and clean up after itself. It has no configurable parameters.

Notes

  • To return an exit code from your setup, use the Terminate with Exit Code command.


Terminate Process

This command attempts a safe shutdown of a running application. It works by calling the ExitProcess API from the context of the running application.

Process Name

Enter the name of the process to terminate. Process names are their executable file names, including the file extension, but without any path information. For instance, to check if Windows Explorer is running, enter explorer.exe in this field.

Return Result in Variable

Enter an existing or new varible name in this field. The variable will hold TRUE if the named process has been terminated successfully or was not running, FALSE otherwise.

Notes

  • To check for running processes, use the Check Process command.
  • For an alternative approach to terminating processes, use the Terminate Program command.


Terminate Program

This command attempts a safe shutdown of a running application. It does not force the application to close, however it attempts to dismiss any open dialogs the application may have running and sends a close request to the main application window.

Program Window Title Contains

Enter text that the program window caption is expected to contain. The text is case sensitive. The text does not have to contain the exact caption of the window, only a portion of it.

Window Class Name

If you wish to narrow the matching list of windows containing the text entered above by specifying a window class, enter it here.

Notes

  • Fill in at least one of the fields as required.
  • While specifying a window class will enhance precision, it is generally not required.
  • For an alternative approach to terminating programs, use the Terminate Process command.


Terminate with Exit Code

This command performs an orderly shutdown of the installation. The installation will immediately exit and clean up after itself. In addition, this command returns the specified numeric exit code. It is similar to the Terminate Install command, which exits and returns the standard error code of 0, indicating successful execution.

Exit Code

Enter the numeric exit code to return. Positive and negative numeric values are allowed. If a non-numeric value is entered here, the function exits with code 0.

Notes

  • The codes returned by this function are accessible to the process that started the installation, and may be used to communicate the resulting state of the install to the parent process.


Transform Instance

This command allows new installations of an already installed product on the same system. Normally Windows Installer allows only a single instance of a product to be installed on a computer. Starting setup again with an existing instance allows to modify, repair, or uninstall that instance only. Beginning with Windows Installer 3.0, it is possible to install multiple copies of a product on the same system using instance transforms. However Windows Installer 3.0 or later is required (and this version of Windows Installer is unavailable on Windows 9X operating systems), along with certain restrictions in package authoring which must be observed.

The Transform Instance command allows multiple instances of a product to be installed on all Windows versions, including Windows 9X operating systems, and without any restrictions in package authoring. This command updates internal installer settings and variables to allow reinstallation of an already installed product, as if it had not been installed before. No manual instance transforms are required.

The following table summarizes the variables that are affected by this command:

Variable | Change
PRODUCTCODE | A new product code identifies the installation as a new product to Windows Installer.
REVISIONCODE | A new revision code identifies the setup database as a new product to Windows Installer.
TARGETDIR | The destination directory is re-initialized with the default value (instead of the first chosen value).
STARTMENU | The start menu folder is re-initialized with the default value (instead of the first chosen value).
ALLUSERS | The install for all users/install for just me option is re-initialized with the default value.
MAINTENANCE | Reset if another instance of the same version of the product was already installed.
NEEDSUPGRADE | Reset if another version of the same product was already installed.
UNINSTALLLINK | Set to the new location of the product uninstallation program.

Transform Instance has no effect when used if the NEWINSTANCE variable is FALSE. The NEWINSTANCE pre-defined variable indicates whether the setup may spawn new instances at runtime. New instances may only be spawned when at least one instance of setup has already been installed, and when setup has not been launched from the Control Panel Add-Remove Programs applet for one of the existing instances (which is the only place to repair, modify, or uninstall existing instances in multi-instance setups).

Warnings

  • After using Transform Instance, the TITLE pre-defined variable must be updated with a unique description of this latest new instance of setup. Because setup instances are identified in the Control Panel Add-Remove Programs applet by their names (as stored in the TITLE variable), each new instance must have a unique name.
  • If the TITLE pre-defined variable is not uniquely updated for each product instance, an existing installation listing in the Control Panel Add-Remove Programs applet may be overwritten when the transformed setup finishes execution. This will orphan the former instance carrying the same name on the system and should be avoided.

Notes

  • Manually updating the variables updated by Transform Instance does not create a new instance - this command updates certain internal installation properties and must be called when a new instance is required.
  • The Multiple Instances sample installation available in the New Project dialog contains example code which illustrates the correct usage of the Transform Instance command. This code may also be reused in your existing setups to add multiple instance behavior.


Until

This command is used to end a loop after performing an evaluation. The loop ended using this command must have been started using the Repeat command. If the evaluation is unsuccessful, one more iteration of the loop will be executed. Upon the ending of each iteration, the loop condition will be re-evaluated, and the loop re-executed until the conditional succeeds.

Variable

Type the name of the variable, according to the value of which the conditional evaluation will be performed.

Comparison

Choose a comparison type from the drop down menu. If both variables contain integer values, a numeric comparison will be performed. If at least one variable contains a non-integer value, a string comparison will be performed.

If you choose the Is Defined comparison, the command does not require the Compare With field, and only tests if the variable name specified above has been previously defined using a Set Variable command. This may be useful in cases where persistent variables are used, as it may be hard to determine which variables used in the setup script have been already initialized and which have not been initialized.

Reverse Comparison

Check this checkbox if you wish to execute an until not evaluation.

Compare With

Type the name of the second variable for comparison. You may also use a string literal in this field instead of a variable.


Web Media Block

This command is directive for the compiler, and is not constrained by conditional execution blocks. It has meaning only when used with Web builds and has no effect on Uncompressed or Compressed build types. However, at least one web media block must be defined before any build type may be compiled.

The Web Media Block command indicates that each installation command which installs files on the target system should place those files in the named source media block. Multiple media blocks may be defined and re-defined in any order. Each media block is effective until a subsequent media block is encountered.

Web Media Block Name

The name of the web media block. The web media block name must be a legal file name (long names may be used). When the installation is built, each file belonging to this media block will be placed inside an archive called <web media block name>.7zip.

Password

Specifying different passwords for each web media block increases the security of your setups, since when a password becomes compromised, other web media blocks are not affected (and, each web media block can use a password different from the global setup password).

This field has effect only when a compressed, encrypted build is being performed. If left empty, the default project password will be used to encrypt this web media block. If non-empty, the given password will be used to encrypt this web media block only, overriding the default project password.

Specifying a password when a non-encrypted build is being performed has no effect. Note that an encrypted build may be performed with an empty global password, in which case web media blocks are encrypted only if this field has been populated.

Download URLs

Specify the full list of HTTP download URLs where the media block can be downloaded from at install time. The file <web media block name>.7zip should be uploaded and available at the exact specified locations for immediate download. You may rename the web media block file. The full file name should be included as part of each URL specified in this field.

Enter one URL per line in this field. To facilitate failsafe download locations, you may enter multiple URLs, and you must provide at least one URL in this field. When a given URL fails, the installer will attempt to download the web media block from the next listed URL, until all available URLs have been exhausted, before raising a failure condition.

Skip on Build

If files in your media block have not changed since the last time you built this setup, check this box to skip rebuilding this media block. Since media blocks are highly compressed, generating them takes time. This will save you time when you are testing and rebuilding your setup, and the media block in question has not been effected.

Notes

  • If you specify an empty string in the Web Media Block Name field, an OFFLINE CONTENT block will be defined instead. This block will not be converted into a downloadable web media block, but instead packaged with the main setup executable itself. Use this option to include files which you will always install in your main setup program.
  • Splice your entire setup into as many media blocks as required. You may use any combination and number of web and offline blocks to achieve your desired effect. We recommend you install your essential application files in an offline block, and place all of your runtime component updates and optional application features each in their own media blocks.
  • Wizard generated projects contain an offline block for Feature Independent files, a seperate web block for each defined application feature, and again a seperate web block for each component update to be installed.
  • The installer automatically saves downloaded web media blocks during installation. Interrupted downloads are automatically resumed, and data which is locally available is not re-downloaded. However, this saved data is deleted when the product is uninstalled, and unavailable for further archival or re-use after uninstallation. See the COPYWEBLOCK pre-defined variable for information on saving downloaded web media blocks for further archival or re-use after uninstallation.


Wend

This command is used in conjunction with While commands. It has no configurable parameters. It is used to signal the end of a while loop.


While

This command is used to start a loop after performing an evaluation. The loop started using this command must be ended using the Wend command. If the evaluation is successful, one iteration of the loop will be executed. Upon the ending of each iteration, the loop condition will be re-evaluated, and the loop re-executed until the conditional fails.

Variable

Type the name of the variable, according to the value of which the conditional evaluation will be performed.

Comparison

Choose a comparison type from the drop down menu. If both variables contain integer values, a numeric comparison will be performed. If at least one variable contains a non-integer value, a string comparison will be performed.

If you choose the Is Defined comparison, the command does not require the Compare With field, and only tests if the variable name specified above has been previously defined using a Set Variable command. This may be useful in cases where persistent variables are used, as it may be hard to determine which variables used in the setup script have been already initialized and which have not been initialized.

Reverse Comparison

Check this checkbox if you wish to execute a while not evaluation.

Compare With

Type the name of the second variable for comparison. You may also use a string literal in this field instead of a variable.


Wizard Loop

The Wizard Loop command provides a convenient way to author a setup wizard. A setup wizard is composed of multiple dialogs shown one after another sequentially, also allowing for backward traversal, and optional skipping of some dialogs based on user selections and installation requirements.

This command starts a wizard loop and has no configurable parameters. The wizard loop may only contain Display Dialog commands inside it and must be closed with an End command.


Write Registry

The Write Registry command records information to the system registry.

Root

Pick the root of the registry where the keys and values should be written to.

Key

Type the full key path.

Value

Type the value name to record. Leave empty to set the default value, which is always a string.

Data

Provide the actual data that will be recorded.

String

Writes the value in the data field to the registry as a string.

Integer

Writes the value in the data field to the registry as an integer.

Binary

Writes the value in the data field to the registry as a binary value.

Expand String

Writes the value in the data field to the registry as an expand string value.

Multi String (append)

Writes the value in the data field to the registry as a multi line string, adding the new value in the last position of the multi line value.

Multi String (prepend)

Writes the value in the data field to the registry as a multi line string, adding the new value in the first position of the multi line value.

Permanent

Check this field to never remove a registry entry once it has been recorded using this command. The registry entry will survive uninstalling the product, or changing the installed feature set.

Notes

  • When recording binary values, enter values into the data field in the form 0F. That is, values should be in hexadecimal notation, be provided as plain strings, and not include any non-hexadecimal characters in the entire data field.
  • When recording multi string values, if you are writing the first value of the multi string value, you may choose either of the append or prepend choices.
  • When running setup in 64 bit installation mode, if you need to make changes to the registry for 32 bit programs, please refer to the instructions in the notes section of the Set 64 Bit Mode command.


Write to Text File

This command enables you to output a single line of text to a text file. Unicode files are not supported.

Write to File

Indicates the full path of the file on the target system to write to.

Value

Indicates the value to write. Check Write to Start of File to insert the value at the beginning of the text file. Check Write to End of File to append the value at the end of the text file.

Notes

  • If the file being to written to does not already exist, it will be created.
  • The file will be opened for writing, written to, and then closed immediately after the write.


(Un)Install MSI Setup

This plug-in provided command installs, re-installs, or uninstalls a Windows Installer setup. A full Windows Installer setup command line may be specified. The progress of the Windows Installer setup will be captured and displayed as part of the installation progress.

Action String

The action string designates whether the Windows Installer setup will be installed, re-installed, or uninstalled. Custom action strings may also be used, for instance to change the installed feature set of an application.

Enter any legal Windows Installer command line parameter here. Click one of the Install, Re-Install or Uninstall buttons to automatically generate a standard command line parameter.

Use Package Guid

Check this field and enter the package guid of the Windows Installer setup to operate on. The package guid option is most useful when you intend to uninstall an already installed Windows Installer setup, and do not wish to include the MSI file for the setup.

Use Package File

Check this field and enter the full path to the Windows Installer setup database file to operate on. The package file option is most useful when you intend to install a Windows Installer setup, and will be distributing the MSI file with your own setup.

Package is InstallAware generated installation

Check this field if the command will be used to operate on an InstallAware setup. This command will fail on InstallAware setups unless this field is checked. Checking this field for non-InstallAware setups is not recommended.

Log File

If you wish to log the result of the (un)installation, enter the full path to the log file to use here.

Return Result in Variable

This variable, if previously defined, will hold one of the following values based on the result of the (un)install operation:

Value | Meaning
SUCCESS | Installation was completed successfully.
ERROR | An error occured during installation.
REBOOT | Installation was completed successfully, however a reboot is required.

Return Last Error in Variable

If an error occured during installation, this variable, were it previously defined, will hold a textual description of that error.

Notes

  • Think of this command as a shell to Windows Installer.
  • If you wish to install a Windows Installer setup as part of your application:
    1. Add the MSI database of the setup to your project as a support file.
    2. Use this command with the Use Package File option, and specify the path to the MSI database using the form $SUPPORTDIR$\<setup database>.msi.
  • If you wish to uninstall a previous version of your own application using this command:
    1. Check if a previous version of your application exists on the system using the NEEDSUPGRADE variable.
    2. Use this command with the Use Package Guid option, and specify $PRODUCTCODE$ as the package guid.


.NET Framework

This plug-in provided command checks for or installs the Microsoft .NET Framework on the target system.

Check for Framework

Check this radio button to check for the presence of the framework, and not install it.

Install Framework

Check this radio button to install the framework if it is not already present.

.NET 1.0

If this radio button is checked, version 1.0 of the framework will be checked for/installed.

.NET 1.1

If this radio button is checked, version 1.1 of the framework will be checked for/installed.

.NET 1.1 with Service Pack 1

If this radio button is checked, version 1.1 of the framework, including service pack 1, will be checked for/installed.

.NET 2.0

If this radio button is checked, version 2.0 of the framework will be checked for/installed.

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Framework check requested. Requested version of framework is available.
  • FALSE: Framework check requested. Requested version of framework is NOT available.
  • SUCCESS: Framework install requested. Framework was installed successfully, or was already available. No reboot is required.
  • REBOOT: Framework install requested. Framework was installed successfully, and a reboot is required.
  • ERROR: Framework install requested. Framework was not installed successfully, or system does not meet minimum requirements.

Notes

  • Installing .NET Framework 1.1 with Service Pack 1 will install both the .NET Framework 1.1 and its Service Pack 1 update if the .NET Framework 1.1 was not previously installed. If the .NET Framework 1.1 was previously installed, it will be updated with Service Pack 1.
  • Installing .NET Framework 1.1 with Service Pack 1 will fail on Windows Server 2003. Windows Server 2003 mandates using Windows Update for updating the .NET Framework - even the official .NET Framework 1.1 Service Pack 1 package fails on Windows Server 2003.
  • Installing .NET Framework 1.1 with Service Pack 1 on a system with .NET Framework 1.1 already installed will fail when using uncompressed builds running from removable media (CD, DVD). This failure condition will not occur when .NET Framework 1.1 is not already installed, when the uncompressed build does not reside on removable media (CD, DVD), or when any build type other than uncompressed builds are used (even if .NET Framework 1.1 is already installed and setup is running from removable media).


Call DLL Function

This plug-in provided command calls a function exported from a DLL. The function must be available under the specified function name and use the __stdcall calling convention.

DLL Path

The full path to the DLL file that exports the function. If a full path is not specified, the DLL will be loaded using the same guidelines that the LoadLibrary API call uses.

Function Name

The name of the function to call that the DLL exports. If the function with the indicated name is not exported from the DLL, the plug-in will make a second attempt to load a function exported with an "A" character appended to the function name.

Parameter Type

Indicates the type of the parameter being passed to the function.

Parameter Value

Indicates the value of the parameter being passed to the function. If a variable is provided in this field, and the parameter is being passed to the function by reference, the passed variable will contain the new value of the parameter. If a variable is not provided, even if the parameter is being passed by reference, the new value of the parameter will not be obtained.

Return Type

Indicates the return type of the function.

Return result in variable

Indicates the variable to hold the result of the function call. If the function call succeeds and the function has a void return parameter, this field is empty. If the function call succeeds and the function has a non-void return parameter, this field is set to the return value of the function. If the function call fails, the variable will hold one of the following values:

Value | Meaning
DLLLOADFAILED | The DLL could not be loaded. It may not exist at the given path or one or more of its dependencies may be missing.
FUNCTIONNOTFOUND | A function with the given name, or the given name appended with an "A", is not exported from the DLL.
EXTERNALEXCEPTION | An exception occured while executing the function code in the DLL.

If specified, this variable must have been previously defined in the setup script using the Set Variable command.

Notes

  • You may use the Call DLL Function command to call virtually any Windows API function.
  • Be sure to use ANSI versions of the Windows API functions you call. Such API calls typically end with an "A". For instance, enter SetCurrentDirectoryA into the Function Name field to change the current directory.
  • When passing variables, be sure to use the convention $VARIABLENAME$.


DIFx Driver Installation

This plug-in provided command installs or uninstalls drivers for a device.

Inf file

Enter the full path to the driver inf file.

Task

To install the driver, select the Install driver option. To uninstall the driver, select the Uninstall driver option.

Architecture

Select the processor architecture that the driver has been written for.

Delete binary driver files when uninstalling

When the Uninstall driver option is selected, checking this option will remove all files that were copied onto the system as part of the driver installation, including files that may be in use by devices attached to the system. When this option is not checked, the driver is deleted from the driver store only.

Install driver only if device is already installed

When the Install driver option is selected, checking this option installs the driver only if the device that requires the driver has been physically connected to the system.

Do not create Add Remove Programs entry for driver

When the Install driver option is selected, checking this option will not create an Add Remove Programs entry for the driver in the Control Panel. If this option is not checked, an Add Remove Programs entry for the driver in the Control Panel enables users to manually uninstall the driver.

Install unsigned drivers and/or drivers with missing files

When the Install driver option is selected, checking this option installs drivers that have not been digitally signed, or have missing files. For maximum resiliency during driver installation, it is recommended that you check this option.

Force installation even if driver is not a better match than existing driver

When the Install driver option is selected, checking this option will always install the supplied driver, even if it is not a better match than a currently installed driver on the system for the device.

Installed

If this field is not empty, the supplied variable receives the number of drivers that were successfully installed. The variable must have been previously defined.

Copied

If this field is not empty, the supplied variable receives the number of drivers that were successfully copied to the driver store, but not activated on a device. The variable must have been previously defined.

Failed

If this field is not empty, the supplied variable receives the number of drivers whose installation failed. The variable must have been previously defined.

Reboot required

If this field is not empty, the supplied variable receives TRUE when a reboot is required, FALSE if not. The variable must have been previously defined.

Notes

  • When installing a driver, this command processes all drivers found in the folder specified in the Inf file field, in addition to the actual driver file that was specified.
  • When uninstalling a driver, this command processes only the driver file specified in the Inf file field.


DirectX Runtime

This plug-in provided command checks for or installs the DirectX Runtime on the target system.

Check for runtime version at least 8.1

Check this checkbox to check for the presence of the most commonly required version of the runtime.

Check for runtime version at least 9b

Check this checkbox to check for the presence of the latest available version of the runtime

Get available version

Check this checkbox to obtain the exact version of the runtime.

Install Runtime version 9b

Check this checkbox to install version 9b of the runtime.

Return result in variable

If you specify a previously defined variable in this field, it will hold runtime information as follows:

  • <version>: Runtime version check requested. Variable receives the full DirectX version string from the system registry. The version string for version 9b of the runtime is 4.09.00.0902. The version string for version 8.1 of the runtime is 4.08.01.0810.
  • TRUE: Runtime check requested. Requested version of runtime is available.
  • FALSE: Runtime check requested. Requested version of runtime is NOT available.
  • SUCCESS: Runtime was installed successfully, or was already available. No reboot is required.
  • REBOOT: Runtime was installed successfully. However, a reboot IS required.
  • ERROR: Runtime was not installed successfully, system does not meet minimum requirements.


Download File

This plug-in provided command downloads any file from the Internet.

URL

Enter the full HTTP URL to the file that should be downloaded.

Local file path and name

Enter the full path for the local copy of the file on the target system. If file already exists, and the Allow resume broken downloads checkbox is checked, it will be assumed to be a previously broken download and the Download File command will attempt to resume the download from where it left off.

Return result in variable

If you wish to receive information on whether the file was successfully downloaded, enter the variable to hold success information here. Possible values are:

  • SUCCESS: File was downloaded successfully.
  • ERROR: File was not downloaded successfully. Check Internet connectivity.

If specified, this variable must have been previously defined in the setup script using the Set Variable command.

Proxy Server

If you wish to redirect the download through a proxy server, provide that information here.

Proxy Port

If the proxy server requires port information, enter that here.

Allow resume broken downloads

Check this checkbox to permit continuation of broken downloads. Uncheck it to always download files from the beginning.

Notes

  • Since downloads can take some amount of time, it is recommended you use the Display Dialog command to show a progress dialog while your download is taking place.


File Bag

This plug-in provided command includes a collection of files (and folders) with setup. The included files are available only while setup is running and are not permanently installed on the target system. This command is typically used when a collection of files are temporarily required at (un)install time, but not by the installed application itself.

Files to include with setup

The full path, including wildcards, to the files to include with setup.

Include subfolders if wildcard specified

When checked, and wildcards specified in the previous field, subfolders will also be included with setup.

Exclude Wildcards

If you would like to exclude some of the files matching your source file pattern above, you may do so by specifying exclude wildcards. Exclude wildcards allow you to filter out some files at build time from inclusion in your setup. Leave this field empty if you do not wish to exclude any files. If you wish to exclude a particular file, folder, or a collection of files and/or folders, enter the name(s) of the items to exclude here. You may use wildcards. Seperate multiple items using semi-colons. Remember to enclose items that contain spaces in their names inside double quotes.

Variable to receive runtime location of files

Enter the name of the variable to receive the fully qualified path where the included files will be available at runtime. Not providing a variable in this field renders this command practically useless, as the actual runtime location of files included with setup will vary each time setup is run.

If specified, this variable must have been previously defined in the setup script using the Set Variable command.

Due to the way the IDE loads plug-ins while running setups internally, the return value of this variable will be incorrect during all in-IDE runs.


Internet Explorer 6 (SP1)

This plug-in provided command installs or re-installs Internet Explorer 6 Service Pack 1.

Install Internet Explorer 6 (SP1)

Choose whether to perform a complete, standard, or minimal installation of Internet Explorer using the drop-down menu.

Shell Integration

Choose whether you wish to:

  • Make Internet Explorer the default browser, and create all shell shortcuts
  • Create the shell shortcuts only
  • Just install the Internet Explorer browser control, and do not create any shortcuts (useful if your application requires the browser control)

Return result in variable

If you indicate a previously defined variable in this field, it will hold one of the following values, based on the outcome of the attempted installation:

  • REBOOT: Installation completed successfuly, system must be restarted for changes to apply
  • ERROR: Installation failed

Notes

  • This command does not check whether a current or newer version of Internet Explorer already exists on the system. It will re-install Internet Explorer even if it has already been installed.
  • Use the Get System Settings command to check for an existing version of Internet Explorer.


JSharp Runtime

This plug-in provided command checks for or installs the Microsoft JSharp Runtime on the target system.

Check for Runtime

Choose this option to check for the presence of the runtime, and not install it.

Install Runtime

Choose this option to install the runtime if it is not already present.

1.1

Choose this option to install version 1.1 of the runtime.

2.0

Choose this option to install version 2.0 of the runtime.

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Runtime check requested. Requested version of runtime is available.
  • FALSE: Runtime check requested. Requested version of runtime is NOT available.
  • SUCCESS: Runtime install requested. Runtime was installed successfully, or was already available. No reboot is required.
  • ERROR: Runtime install requested. Runtime was not installed successfully, a reboot is pending or system does not meet minimum requirements.


MDAC Refresh

This plug-in provided command checks for or installs the MDAC Refresh on the target system. This runtime installation contains the following components: ADO, ODBC, OLE DB, and JET.

Check for specified version

Select this option to check for the presence of the indicated version of the refresh.

Get available version

Select this option to obtain the exact version of the runtime.

Install specified version

Select this option to install the indicated version of the refresh.

2.8

Select this option to install version 2.8 of the refresh.

2.81 (2.8 with Service Pack 1)

Select this option to install version 2.8 of the refresh with service pack 1. Note that you may not install version 2.8 with service pack 1 on Windows XP or Windows Server 2003 - the only way of installing MDAC 2.8 with Service Pack 1 on those systems is through installing operating system service packs.

Return result in variable

If you specify a previously defined variable in this field, it will hold runtime information as follows:

  • <version>: Refresh version check requested. Variable receives the full MDAC version string as reported by the system. The version string for version 2.8 of the refresh is 2.8.
  • TRUE: Refresh check requested. Requested version of refresh is available.
  • FALSE: Refresh check requested. Requested version of refresh is NOT available.
  • SUCCESS: Refresh was installed successfully, or was already available. No reboot is required.
  • REBOOT: Refresh was installed successfully. However, a reboot IS required.
  • ERROR: Refresh was not installed successfully, system does not meet minimum requirements.
  • CANCEL: Refresh was not installed successfully, operation aborted by user.
  • DISKFULL: Refresh was not installed successfully, destination drive lacks sufficient free space.


MSI Transaction

This plug-in provided command starts or ends a Windows Installer 4.5 transaction. This command requires Windows Installer 4.5 to be installed on the target system.

Begin New Transaction

Select this option to begin a new MSI transaction. Any Windows Installer based installations that occur after the new transaction has begun can be committed or rolled back in a single step based on installation success/failure states or end-user choice or any other arbitrary factor using this same command.

End Transaction

Select this option to end an MSI transaction that was previously started. Choose the Commit all changes option to have all the installations which were a part of the transaction commit. Choose the Rollback all changes option to discard all the installations which were a part of the transaction, returning the system into the prior state before the transaction was begun.

Return result in variable

Indicates the variable to hold the result of the transaction attempt. The variable will hold one of the following values:

Value | Meaning
MSI45REQUIRED | Windows Installer 4.5 is not installed. No action was taken.
SUCCESS | Transaction was started or finished successfully.
SERVICEUNAVAILABLE | Windows Installer service not available, failed to start transaction.
ALREADYRUNNING | An (un)installation is already in progress, failed to start transaction.
INTERNALERROR | An internal error occured, failed to start transaction.
ROLLBACKDISABLED | Windows Installer rollback disabled, failed to start transaction.
ACCESSDENIED | Access denied, failed to end transaction.
INSTALLERROR | An (un)installation error occured, failed to end transaction.
INSTALLSTILLACTIVE | An (un)installation is still in progress, faield to end transaction.

If specified, this variable must have been previously defined in the setup script using the Set Variable command.


Detect MS SQL Server Instances

This plug-in provided command enumerates available instances of Microsoft SQL Server on the local system and network.

Return result in variable

Enter the name of the variable to receive the list of SQL Server instances found on the local system and network. The variable receives a $NEWLINE$ delimited list of instance names. The variable must have been previously defined.

Notes

  • You may use the Parse String command to obtain individual names from the list of servers that the variable receives.


MS SQL Server

This plug-in provided command executes a SQL script on an instance of Microsoft SQL Server. Supported server platforms include SQL Server 7, SQL Server 2000, SQL Server 2005, SQL Server 2008, and MSDE.

Server

Enter the network name or IP address of the physical machine that the server instance resides on. Use localhost for the local machine.

You may also enter in a specific port to connect. Type the port number immediately after the network name, separating the two fields with a comma, and without spaces. An example value could be servername,1433.

Other ports that may be used include 445.

Instance

Enter the name of the SQL Server instance that the script will execute on.

Database

Enter the name of the database to connect to, or the database to create if you wish to create a new database on the server instance.

Create Database If Absent

If you wish to create a new database, check this box.

User

Enter the name of a user authenticated to make changes on the SQL Server instance.

Password

Enter the password for the user named in the User field.

Return result in variable

Indicates the variable to hold the result of the script execution. If specified, this variable must have been previously defined in the setup script using the Set Variable command.

The variable will hold one of the following values, or a custom error message as described below:

Value | Meaning
SUCCESS | Connection to the database succeeded. The script executed successfully, or there were some script execution errors and Abort Execution on Script Error was not checked.
CONNECT_ERROR | Connection to the server failed.
CONNECT_DATABASE_ERROR | Connection to the database failed.
ERROR | An unknown error occured.

In addition to the values in the table above, when Abort Execution on Script Error is checked, and an error occurs during script execution (where database and server connections succeeded), this variable holds detailed error information as follows: The variable is split into two parts, delineated by the string literal DELINEATOR. The first part of the variable holds the exact textual error message. The second part of the variable holds the exact SQL script fragment where execution errors occured. You may parse the variable using the Parse String function to extract both fields and utilize them separately.

Abort Exection on Script Error

Check this box to halt processing of the SQL script if any SQL statement fails. Uncheck this box to allow the SQL script to continue execution even if some SQL statements fail.

SQL Script

Type the SQL script to execute here, or click the Load Script button to load the script from a text file.

Notes

  • You may use variables in your SQL scripts and connection fields.
  • It is strongly recommended that MDAC 2.8 be installed on the target system before this command executes. No other client software is required on the target system. MDAC 2.8 may be installed using the MDAC Refresh command.
  • If you wish to load your SQL Script from a file at runtime, use the special #FILESCRIPT# value to indicate this. This option is especially useful for very long scripts that contain tens of thousands of lines. If your script has the value #FILESCRIPT# at the first position in the first line of the SQL Script field, the script will be read from the file following the value. For instance, if you enter the value #FILESCRIPT#$SUPPORTDIR$\sqlscript.sql into the SQL Script field, the plug-in will load the file sqlscript.sql from the installer's support files (creatives) folder at run-time, and execute the script contained within that file.
  • If a user name is specified in the User field, SQL authentication will be used. If the User field is empty, Windows authentication will be used.


MSXML

This plug-in provided command checks for or installs Microsoft XML onto the system.

Check for MSXML

Select this option to check for the presence of the module, and not install it.

Install MSXML

Select this option to install the module if it is not already present.

4.0 SP2

Select this option to check/install version 4.0 SP2 of MSXML.

6.0

Select this option to check/install version 6.0 of MSXML. MSXML 6.0 may only be installed on computers with Windows Installer 3.1 or above.

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Module check requested. Requested version of module is available.
  • FALSE: Module check requested. Requested version of module is NOT available.
  • SUCCESS: Module install requested. Module was installed successfully, or was already available. No reboot is required.
  • ERROR: Module install requested. Module was not installed successfully, an error occured or system does not meet minimum requirements.
  • REBOOT: Module install requested. Module was installed successfully, and a reboot is pending.


My SQL

This plug-in provided command executes a SQL script on a My SQL database server. Supported server platforms include versions up to 5.

Server

Enter the network name or IP address of the physical machine that the server instance resides on. Use localhost for the local machine.

Port

Enter the name of the port that the server is listening for connections on.

User

Enter the name of a user authenticated to make changes on the server.

Password

Enter the password for the user named in the User field.

Return result in variable

Indicates the variable to hold the result of the script execution. If specified, this variable must have been previously defined in the setup script using the Set Variable command.

The variable will hold one of the following values, or a custom error message as described below:

Value | Meaning
SUCCESS | Connection to the server succeeded. The script executed successfully, or there were some script execution errors and Abort Execution on Script Error was not checked.
CONNECT_ERROR | Connection to the server failed.
ERROR | An unknown error occured.

In addition to the values in the table above, when Abort Execution on Script Error is checked, and an error occurs during script execution (where database and server connections succeeded), this variable holds detailed error information as follows: The variable is split into two parts, delineated by the string literal DELINEATOR. The first part of the variable holds the exact textual error message. The second part of the variable holds the exact SQL script fragment where execution errors occured. You may parse the variable using the Parse String function to extract both fields and utilize them separately.

Abort Exection on Script Error

Check this box to halt processing of the SQL script if any SQL statement fails. Uncheck this box to allow the SQL script to continue execution even if some SQL statements fail.

SQL Script

Type the SQL script to execute here, or click the Load Script button to load the script from a text file.

Notes

  • You may use variables in your SQL scripts and connection fields.
  • No client software or libraries are required on the target system for this action to succeed. A TCP/IP connection to the physical machine that the server resides on is required.
  • If you wish to load your SQL Script from a file at runtime, use the special #FILESCRIPT# value to indicate this. This option is especially useful for very long scripts that contain tens of thousands of lines. If your script has the value #FILESCRIPT# at the first position in the first line of the SQL Script field, the script will be read from the file following the value. For instance, if you enter the value #FILESCRIPT#$SUPPORTDIR$\sqlscript.sql into the SQL Script field, the plug-in will load the file sqlscript.sql from the installer's support files (creatives) folder at run-time, and execute the script contained within that file.


Oracle Database

This plug-in provided command executes a SQL script on an Oracle database server. Supported server platforms include versions up to 11g.

Server

Enter the network name or IP address of the physical machine that the server instance resides on. Use localhost for the local machine.

Port

Enter the name of the port that the server is listening for connections on.

SID

Enter the system identifier of the database to execute the script on.

User

Enter the name of a user authenticated to make changes on the server.

Password

Enter the password for the user named in the User field.

Connect As

Enter the requested connection priviledges for the user named in the User field.

Return result in variable

Indicates the variable to hold the result of the script execution. If specified, this variable must have been previously defined in the setup script using the Set Variable command.

The variable will hold one of the following values, or a custom error message as described below:

Value | Meaning
SUCCESS | Connection to the server succeeded. The script executed successfully, or there were some script execution errors and Abort Execution on Script Error was not checked.
CONNECT_ERROR | Connection to the server failed.
ERROR | An unknown error occured.

In addition to the values in the table above, when Abort Execution on Script Error is checked, and an error occurs during script execution (where database and server connections succeeded), this variable holds detailed error information as follows: The variable is split into two parts, delineated by the string literal DELINEATOR. The first part of the variable holds the exact textual error message. The second part of the variable holds the exact SQL script fragment where execution errors occured. You may parse the variable using the Parse String function to extract both fields and utilize them separately.

Abort Exection on Script Error

Check this box to halt processing of the SQL script if any SQL statement fails. Uncheck this box to allow the SQL script to continue execution even if some SQL statements fail.

Connect Without Client Software (Net)

Check this box to allow a direct connection to the server, without requiring any client software. The target server must have been installed using the Net option.

SQL Script

Type the SQL script to execute here, or click the Load Script button to load the script from a text file.

Notes

  • You may use variables in your SQL scripts and connection fields.
  • If the Connect Without Client Software (Net) option is checked, no client software or libraries are required on the target system for this action to succeed. A TCP/IP connection to the physical machine that the server resides on is required.
  • If the Connect Without Client Software (Net) option is not checked, Oracle client software is required on the target system for this action to succeed.
  • If you wish to load your SQL Script from a file at runtime, use the special #FILESCRIPT# value to indicate this. This option is especially useful for very long scripts that contain tens of thousands of lines. If your script has the value #FILESCRIPT# at the first position in the first line of the SQL Script field, the script will be read from the file following the value. For instance, if you enter the value #FILESCRIPT#$SUPPORTDIR$\sqlscript.sql into the SQL Script field, the plug-in will load the file sqlscript.sql from the installer's support files (creatives) folder at run-time, and execute the script contained within that file.


SQL Server Express

This plug-in provided command installs an instance of Microsoft SQL Server Express 2005 or 2008 on the target system.

Select the version of SQL Express to install using the drop-down combo box on the top right corner of the plug-in dialog. If the combo box is not enabled, you have only installed support for a single (the pre-selected) version of SQL Express. To add support for more SQL Express versions, install them using InstallAware setup.

Automatically Generate Command Line

The fields in this region help you automatically form a setup command line for the SQL Express native installer. Please note that the command line is not generated until you have clicked the Generate Command Line button.

Options

Mixed mode (SQL) authentication

Check this box to allow mixed mode authentication in the new SQL Express instance.

Enable network protocols

Check this box to allow network connections in the new SQL Express instance. Only available with SQL Express 2005.

Sysadmin password

Enter a strong password for the sysadmin user here. A strong password must be specified for setup to succeed.

Instance name

Enter the name for your new instance here. To install the default instance, leave this field blank.

Features

Click to select each SQL Express feature you would like to install. If you would like to install all features, uncheck all features. The feature list varies by the selected version of SQL Express.

Accounts

This page is only available for SQL Express 2008.

SQL Server Service Account Name

Enter the name of the Windows account to associate with the SQL Server Service. Selecting one of the pre-defined system accounts NT AUTHORITY\NETWORK SERVICE or NT AUTHORITY\SYSTEM eliminates the need to enter a service account password in the next input field. SQL Express 2005 uses the pre-defined system accounts, but SQL Express 2008 permits you to use a custom account.

SQL Server Service Account Password

Enter the password for the Windows account to associate with the SQL Server Service. Not necessary and disabled when a pre-defined system account is used.

SQL Server Administrator Account Name

Enter the name of the Windows account to set as the database administrator account using the form domain\user. Click the Add Current User button to insert a script variable denoting the account name of the user installing your product. This script variable is pre-defined only when used in conjunction with the built-in Microsoft SQL Server Express 2008 runtime displayed on the Application Runtimes design view, but you may copy and paste the code from the built-in runtime scripts to re-define this variable elsewhere when necessary.

Setup Command Line

The actual command line that will be passed to the setup program. You may auto-generate this field visually using the Automatically Generate Command Line dialog region, or manually enter/update a command line here. When manually specifying a command line, do not provide install mode or quiet installation flags, as these are automatically added to the specified setup command line at runtime.

Return result in variable

If you specify a previously defined variable in this field, it will hold the numeric return code of the native SQL Express installation. Some return codes are:

  • 0: Successful installation.
  • 3010: Successful installation, but a reboot is required.

Any other return code designates an error. The numeric return codes are standard Windows Installer result codes.

Notes

  • When you request a new instance installation, the plug-in will fail if the named/default instance already exists on the system. Use the Check Service command to determine if your named/default instance already exists. The service name to check for is MSSQL$SQLEXPRESS for default instances, and MSSQL$MYINSTANCE for named instances (where MYINSTANCE represents your instance name).


Visual Basic VM

This plug-in provided command checks for or installs the Visual Basic 6 Virtual Machine (Service Pack 6) on the target system.

Check for Runtime version SP5

Check this checkbox to check for the presence of the most commonly required version of the runtime.

Check for Runtime version SP6

Check this checkbox to check for the presence of the latest available version of the runtime

Install Runtime

Check this checkbox to install the runtime.

Return result in variable

If you specify a previously defined variable in this field, it will hold runtime information as follows:

  • <version>: Runtime version check requested. Variable receives the full virtual machine version string from the virtual machine DLL file. The version string for SP6 of the runtime is 6.0.97.82. The version string for SP5 of the runtime is 6.0.89.64.
  • TRUE: Runtime check requested. Requested version of runtime is available.
  • FALSE: Runtime check requested. Requested version of runtime is NOT available.
  • SUCCESS: Runtime was installed successfully, or was already available. No reboot is required.
  • REBOOT: Runtime was installed successfully. However, a reboot IS required.


Visual C++ Runtime

This plug-in provided command checks for or installs the Visual C++ 6 (Service Pack 6) runtime on the target system. This runtime installation contains the following components: MFC, ATL, and language DLLs.

Check for Runtime

Check this checkbox to check for the presence of the runtime, and not install it.

Install Runtime

Check this checkbox to install the runtime if it is not already present.

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Runtime check requested. Requested version of runtime is available.
  • FALSE: Runtime check requested. Requested version of runtime is NOT available.
  • SUCCESS: Runtime install requested. Runtime was installed successfully, or was already available. No reboot is required.
  • ERROR: Runtime install requested. Runtime was not installed successfully, a reboot is pending or system does not meet minimum requirements.


Windows Installer

This plug-in provided command checks for or installs the Windows Installer runtime on the target system.

Check for Runtime

Select this option to check for the presence of the runtime, and not install it.

Install Runtime

Select this option to install the runtime if it is not already present.

Windows Installer 2.0

Select this option to install Windows Installer version 2.0. Windows Installer 2.0 is the last version of Windows Installer that is installable on all 32 bit Windows operating systems - from Windows 95 to Server 2003.

Windows Installer 3.0 (NT kernels only)

Select this option to install Windows Installer version 3.0. Windows Installer 3.0 may only be installed on Windows 2000, XP, and 2003. Windows versions based on the 9X kernels (Windows 95, 98, ME) do not support Windows Installer 3.0. In addition, Windows NT 4.0 does not support Windows Installer 3.0.

If setup is running on a system with a 9X kernel, then for both runtime checks and runtime installations, the plug-in will assume version 2.0 of Windows Installer instead (even if version 3.0 was specified). The reason for this behavior is that setups which require Windows Installer 3.0 on Windows NT based operating systems work well with Windows Installer 2.0 on Windows 9X based operating systems.

However, if setup is running on a system with Windows NT 4.0 installed, the plug-in does not make this assumption. The reason for this behavior is that setups which require Windows Installer 3.0 will fail on Windows NT 4.0 unless it is available. Since Windows Installer 3.0 can never be installed on Windows NT 4.0, the plug-in will always fail and correctly report this failure state.

The above plug-in logic helps you keep your setup script simple when installing third party runtimes that require Windows Installer 3.0 (such as .NET Framework 2.0). Simply select the Windows Installer 3.0 option in your setup script, and the plug-in will correctly detect/install v3.0 on systems that require it (Windows NT kernels), and it will correctly detect/install v2.0 on systems that do not require v3.0 (Windows 9X kernels).

Windows Installer 3.1 (NT kernels only)

Select this option to install Windows Installer version 3.1. Windows Installer 3.1 may only be installed on Windows 2000, XP, and 2003. Windows versions based on the 9X kernels (Windows 95, 98, ME) do not support Windows Installer 3.1. In addition, Windows NT 4.0 does not support Windows Installer 3.1.

If setup is running on a system with a 9X kernel, then for both runtime checks and runtime installations, the plug-in will assume version 2.0 of Windows Installer instead (even if version 3.1 was specified). The reason for this behavior is that setups which require Windows Installer 3.1 on Windows NT based operating systems work well with Windows Installer 2.0 on Windows 9X based operating systems.

However, if setup is running on a system with Windows NT 4.0 installed, the plug-in does not make this assumption. The reason for this behavior is that setups which require Windows Installer 3.1 will fail on Windows NT 4.0 unless it is available. Since Windows Installer 3.1 can never be installed on Windows NT 4.0, the plug-in will always fail and correctly report this failure state.

The above plug-in logic helps you keep your setup script simple when installing third party runtimes that require Windows Installer 3.1 (such as .NET Framework 2.0). Simply select the Windows Installer 3.1 option in your setup script, and the plug-in will correctly detect/install v3.1 on systems that require it (Windows NT kernels), and it will correctly detect/install v2.0 on systems that do not require v3.1 (Windows 9X kernels).

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Runtime check requested. Requested version of runtime is available.
  • FALSE: Runtime check requested. Requested version of runtime is NOT available.
  • SUCCESS: Runtime install requested. Runtime was installed successfully, or was already available. No reboot is required.
  • REBOOT: Runtime install requested. Runtime was installed successfully, and a reboot is required.
  • ERROR: Runtime install requested. Runtime was not installed successfully, or system does not meet minimum requirements.

Warning

  • Version 2.0 of the Windows Installer runtime must be installed on the target system for your application installation to succeed.

Notes

  • InstallAware setups run on all systems with Windows Installer version 2.0 and above.


Windows Media Format 9

This plug-in provided command installs support for Windows Media Format version 9.

Check for format version at least 9

Check this checkbox to check for the presence of the format, and not install it.

Install format version 9

Check this checkbox to install the format if it is not already present.

Return result in variable

If you specify a previously defined variable in this field, it will hold framework information as follows:

  • TRUE: Format check requested. Requested version of format is available.
  • FALSE: Format check requested. Requested version of format is NOT available.
  • SUCCESS: Format install requested. Format was installed successfully, or was already available. No reboot is required.
  • REBOOT: Format install requested. Format was installed successfully. A reboot is required before format will be available for use.
  • ERROR: Format install requested. Format was not installed successfully, a reboot is pending or system does not meet minimum requirements.


Plug-In Authoring Overview

The InstallAware IDE and setups are plug-in extensible. This document describes how to develop plug-ins for extending InstallAware installations. To jump start your plug-in development:

  1. Click the InstallAware button, then choose New Project [image] Other.
  2. On the Plug-Ins tab, pick a plug-in template.

Plug-In Files

A plug-in consists of two DLLs:

  • Design-Time/Compile-Time DLL. Invoked from the IDE while setup is being designed, and compiled.
  • Run-Time DLL. Invoked from the running setup program while product is actually being installed.

More files may be present in the plug-in folder as required by the plug-in. These files may be support files for the DLLs, or files that the plug-in makes available to the running setup.

Design-Time/Compile-Time DLL

This DLL should:

  • Display user interface, allowing programmer to configure plug-in options
  • Participate in the build process, by copying the runtime dll, and required support files, to the build location

This DLL may include dependencies on other libraries.

Run-Time DLL

This DLL should:

  • Perform the actual plug-in task while install is running
  • Properly return updated state of variables to calling process
  • Update progress for lengthy operations with callbacks

This DLL must not have any runtime dependencies. It should be able to carry out its task in any operating environment, since it will be called from the setup at runtime in a production environment.

Plug-In Registration

A plug-in should create keys in the system registry, letting the InstallAware development environment know of its existence.

HKEY_LOCAL_MACHINE
  SOFTWARE
    MimarSinan
      InstallAware
        2.0
          Plug-Ins
            {Plug-In Name}
              (Default) = {Full Path to Plug-In Design-Time/Compile-Time DLL}
              Action = {Plug-In Name}
              Execute = {File Name (without path) to Plug-In Run-Time DLL}
              Script = {Plug-In Script Display}

Plug-In Name

The name of the plug-in. This will also be used for displaying the plug-in command on the commands list.

Plug-In Script Display

The text that will be displayed in the script editor when a plug-in command has been added into the script.


Design Time Exports

The functions which must be exported by the design time DLL and their expected behavior is described below.

CompileTimeBuild

This function is called when the project is being compiled. The function should copy the necessary files for its operation, modify the Windows Installer database if necessary, and indicate whether it will require access to setup files during installation.

bool WINAPI CompileTimeBuild(
    int MSIHandle,
    const char* State,
    const char* BuildPath,
    bool Build,
    bool* Fetch
);

MSIHandle

Handle to the Windows Installer database being currently generated.

State

The state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The plug-in generates and returns state information in the DesignTimeEdit function also located in this DLL.

BuildPath

The full path to the folder where the plug-in must copy its build files to. At a minimum, the plug-in should copy its Run-Time DLL to this build location. The plug-in may also copy other files as needed (for instance, if the plug-in installs any files, it should also copy those files).

Build

Indicates whether files should actually be copied.

Fetch

If the plug-in requires access to the setup media (that is, the files it copied to BuildPath, excluding the runtime DLL file) for the current value of the State parameter, the plug-in should set this variable to TRUE. Otherwise, the variable should be set to FALSE.

InstallAware uses this information to determine if a web media block should be downloaded at runtime while the plug-in is executing.

Return

The function should return TRUE if the plug-in's own compilation succeeded or FALSE if it failed. Returning FALSE from this plug-in will immediately abort the InstallAware project compilation currently taking place with a generic plug-in compilation error. Since there is no field to pass detailed error information when failing the project compilation from a plug-in, you may display a message box or write to a custom log before failing the compilation.

DesignTimeEdit

This function is called when the plug-in command is being added to the script for the first time, or an already existing command edited. The function should display a plug-in defined window enabling the user to configure plug-in settings (such as, what the plug-in does at install time). These settings will be passed back to the caller enabling their storage in a persistent medium.

int WINAPI DesignTimeEdit(
    int Window,
    const char* State,
    char* NewState
);

Window

Handle to parent window, the InstallAware IDE.

State

The existing state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The plug-in generates and returns state information in this function.

If the command is being added to the script for the first time, this parameter will be NULL. The plug-in should initialize its user interface and reflect default plug-in settings, or display the settings previously configured by the user.

NewState

The new state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The plug-in generates and returns state information in this function.

The plug-in should generate this string based on the settings configured by the user in the plug-in defined window. If NewState is not NULL, the plug-in should pass the state string back to the caller. The caller will then store this state information for later use in setup projects and running setups.

Remarks

The DesignTimeEdit function will always be called twice:

  1. The first call of the function will always have the NewState parameter set to NULL. The function should display its user interface, generate the NewState string, and store it in a buffer. The function should return the length of the buffer as its result. This will enable the caller to allocate sufficient memory to hold the NewState string.
    If the user cancelled the operation in the plug-in user interface, the function should return -1 indicating that command insertion to the script was aborted. In this case, the function will not be called again, since it is not necessary to obtain state information anymore.
  2. The second call of the function will always pass a non-NULL NewState parameter, with just enough space to hold the NewState string. In this second iteration, the function should not display a user interface at all. It should instead copy to the buffer pointed to by the NewState variable the NewState string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

DesignTimeText

This function returns custom plug-in text for display in the script editor. This function is optional.

int WINAPI DesignTimeText(
    const char* State,
    char* Text
);

State

The existing state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The state parameter passed here has been previously generated by the plug-in in the DesignTimeEdit function.

Text

The human readable representation of the plug-in state, as will be displayed in the script editor.

Remarks

The DesignTimeText function will always be called twice:

  1. The first call of the function will always have the Text parameter set to NULL. The function should parse the State parameter, generate the Text string, and store it in a buffer. The function should return the length of the buffer as its result. This will enable the caller to allocate sufficient memory to hold the Text string.
  2. The second call of the function will always pass a non-NULL Text parameter, with just enough space to hold the Text string. In this second iteration, the function should not re-parse the State parameter at all. It should instead copy to the buffer pointed to by the Text variable the Text string it generated and stored in the first iteration. In the second iteration, the function should always return 0.

AboutPlugIn

This function displays the plug-in about box, containing general and copyright information on the plug-in.

void WINAPI AboutPlugIn(
    int Window
);

Window

Handle to parent window, the InstallAware IDE.


Run-Time Exports

The functions which must be exported and called by the run-time DLL, and their assumed behavior, is described below.

PlugInProgressIndicator

This is a setup executable defined callback function. The plug-in will receive the address of the callback function in the RunTimeExecute function, also located in this DLL. It should periodically call this function to keep the setup user interface updated of the overall progress of the task the plug-in is performing.

typedef BOOL (WINAPI* lpPlugProgressIndicator)(
    int,
    const char*
);

Integer Parameter

This parameter should contain the numeric representation of the overall task progress, where 0 is nothing and 100 is complete.

Char* Parameter

This parameter should contain a textual description of the currently executing task.

Boolean Return

The callback function will return TRUE if the plug-in is permitted to continue its task. If the setup has been cancelled by the user, the callback function will return FALSE. In this case, the plug-in should immediately end its task and clean up after itself.

RunTimeExecute

This function will perform the actual plug-in task, and update script variables as necessary. It will be called at runtime by the setup executable.

int WINAPI RunTimeExecute(
    int Window,
    const char* Variables,
    const char* State,
    lpPlugProgressIndicator Progress,
    int* Return,
    char* NewVariables
);

Window

Handle to parent setup window.

Variables

This parameter contains the names and values of all variables used in the setup script as a comma delimited string list of the form <variable name>,<variable value>,...,<variable name>,<variable value>. If a variable name or value contains embedded spaces, the entire value will be enclosed in double quotes.

State

The state of the plug-in represented as a string. This state parameter is opaque to InstallAware. The plug-in generates and returns state information in the DesignTimeEdit function located in the design time DLL.

In essence, this variable tells the plug-in what to do.

Progress

Pointer to the progress callback function which the function must periodically call, both updating the setup user interface, and allowing the user to abort the operation if so required.

Return

Reserved. Set to 0.

NewVariables

The new state of the installation variables. The plug-in should modify the script variables list received in the Variables parameter and return it in this parameter if NewVariables is not NULL. Of course, if the plug-in did not change the state of any script variable, the plug-in should instead return a copy of the original Variables parameter.

If NewVariables is NULL, the plug-in should internally store the script variables. See the remarks for more information.

Remarks

The RunTimeExecute function will always be called twice:

  1. The first call of the function will always have the NewVariables parameter set to NULL. The function should perform its installation action, perpare the NewVariables string, and store it in a buffer. The function should return the length of the buffer as its result. This will enable the caller to allocate sufficient memory to hold the NewVariables string.
  2. The second call of the function will always pass a non-NULL NewVariables parameter, with just enough space to hold the NewVariables string. In this second iteration, the function should not perform an installation action at all. It should instead copy to the buffer pointed to by the NewVariables variable the NewVariables string it generated and stored in the first iteration. In the second iteration, the function should always return 0.


Automation Overview

InstallAware ships with an automation interface that can be used to programmatically emit and build complete setup projects. The automation interface is available as both a standard Win32 DLL, callable from any Windows application, and as a COM object, for use in ASP scripts on a web server. Use the interface that is most convenient for your project requirements.

Starting with InstallAware NX, the automation interface is also available as a .NET assembly, suitable for use within the entire .NET eco-system.

Win32 DLL

The Win32 DLL may be used by any application which is capable of calling standard Windows DLLs. The DLL exports several functions and can perform the following tasks:

  • Emit installation scripts
  • Emit project files
  • Build projects

Example projects using the DLL, including headers for the DLL, are located in the Automation\Examples folder inside your InstallAware installation folder.

Please see the runtime files section for information on where to locate the DLL and its dependencies.

COM Object

The COM object is ideal for scripting access to the automation interface from ASP pages on a web server. This way, you could generate a custom install dynamically from a web page, build it, and deliver it to the site visitor. The COM object implements the IDispatch interface and provides the following functionality:

  • Emit installation scripts
  • Build projects

An example ASP page which uses the interface, as well as the COM object itself, are found in the Automation\Web Support folder inside your InstallAware installation folder.

Please see the runtime files section for information on where to locate the object and its dependencies.

.NET Assembly

A .NET assembly is available starting with InstallAware NX which exposes the automation interface to the entire .NET eco-system. Examples are provided for building C# and ASP.NET applications. An MFC example is also available (note that this example does not require the .NET assembly, and natively invokes the Win32 DLL). The InstallAware .NET assembly lets you perform the following functions:

  • Emit installation scripts
  • Emit project files
  • Build projects

Example projects, as well as documentation for the .NET assembly, are provided at the following locations:

  • The MFC example is located inside the Automation\Examples\MfcAutomation folder inside your InstallAware installation folder.
  • The C# example is located inside the Automation\Examples\NetAutomation folder inside your InstallAware installation folder.
  • The ASP.NET example is located inside the Automation\Web Support\AspNetAutomation folder inside your InstallAware installation folder.

Please see the runtime files section for information on where to locate the assembly and its dependencies.


Runtime Files

Applications built on top of InstallAware automation technology require the following sets of runtime files. Please note that none of these runtime files are redistributable within your organization or outside of your organization; their usage is permitted only together with an InstallAware Studio Admin license, and only on the machine that the license has been activated on.

Libraries

Library files provide core functionality. These files, found in the Automation\Libraries folder of your main InstallAware installation folder, must be located inside the same folder as your application:

  • mia.lib
  • miaforms.dll
  • miainfo.dll
  • mext.dll
  • actex.dll
  • dependent.exe
  • MSIDBWrap.dll
  • mmergemod.dll
  • mergemod.dll
  • mspatchc.dll
  • PatchWiz.dll
  • asInvoker
  • highestAvailable
  • requireAdministrator
  • interop\miastub.exe
  • interop\mia.lib
  • interop\actad.dll
  • interop\actadv.dll
  • trans\*

Items in the list above with parent paths must reside inside subfolders relative to the root of the application as indicated above.

Please ensure that the library mergemod.dll has been self-registered, if you are planning to use Merge Modules as part of your build process.

If you are planning on code signing your setups, you should also duplicate the authenticode subfolder (found beneath your main InstallAware installation folder) inside the directory of your application..

Plug-Ins

If your installation makes use of plug-ins (and virtually all installers do), each plug-in must be installed. If you need to manually re-install plug-ins:

  1. Copy the plug-in files to your desired folder (this folder does not need to be a subfolder of your application folder),
  2. Create the plug-in registry entries, pointing to the plug-in files in the folder chosen in step #1 above.

You may obtain the plug-in files and registry entries by observing your development system. See the plug-in authoring overview for more information.

Note that if your installations make use of application runtimes, they too must also be present when you are invoking InstallAware automation.

Command Line Build Tool

This tool is available in the root your InstallAware installation folder as miabuild.exe.

Manually installing this tool is not recommended, you should use the InstallAware setup itself to install the tool, along with any required plug-ins and application runtimes, as well as the authenticode support files to enable code signing.

Automation Libraries

Win32 DLL

The DLL is available at the following path, relative to the root of your InstallAware installation folder: Automation\Libraries\miaauto.dll.

The DLL requires the Libraries/Plug-Ins described above for proper operation.

COM Object

The COM Object files are mAutoWeb.dll and mAutoWebStub.exe. They are found at the following location, relative to the root of your InstallAware installation folder: Automation\Web Support.

Before the COM object may be used, its server DLL, mAutoWeb.dll, must be self-registered using regsvr32.

.NET Assembly

The .NET assembly is found inside the following locations, both relative to the root of your InstallAware installation folder:

  • Automation\Examples
  • Automation\Web Support\AspNetAutomation

The .NET assembly requires the Libraries/Plug-Ins described above for proper operation, and it also requires the Command Line Build Tool (unlike the Win32 DLL, which does not require the Command Line Build Tool).


Using the Win32 DLL

The steps for programmatically emitting and building an InstallAware setup are summarized as follows:

  1. Use the script management functions to programmatically generate a setup script.
  2. Store the total number of lines used in your script for use in step 3 below.
  3. Use the project management functions to programmatically generate a setup project. Have the project reference an existing setup script.
  4. Use the build function to build a newly generated or existing setup project.

Script Management Functions

miaInitializeScript
miaAddCommand
miaFinalizeScript
miaGetTotalLines

Project Management Functions

miaInitializeProject
miaSetScriptFile
miaClearDialogFiles
miaClearSupportFiles
miaClearMergeFiles
miaClearPatchFiles
miaClearIncludeFiles
miaAddDialogFile
miaAddSupportFile
miaAddMergeFile
 miaAddPatchFile
miaAddIncludeFile
miaFinalizeProject

Build Function

miaBuildProject
 miaBuildProjectEx
 miaBuildProjectEy

Structure

COMMATEXT


miaInitializeScript

This function initializes in-memory structures for programmatically emitting a new InstallAware script.

void WINAPI miaInitializeScript();


miaAddCommand

This function adds an installation command to the in-memory installation script.

void WINAPI miaAddCommand(
    const char* Command,
    const char* Parameters
);

Command

Provides the name of the command to add. The command may be a built-in or plug-in defined command.

Parameters

Provides the parameters for the command. Each command has a unique set of parameters.

All command parameters must be combined into a single string value, formatted as COMMATEXT.

If the command does not expect a parameter, pass NULL in this parameter.


miaFinalizeScript

This function flushes in-memory structures for an InstallAware script to disk and forms a valid MIA script file which may later be referenced from a setup project.

void WINAPI miaFinalizeScript(
    const char* SaveFile
);

SaveFile

Specifies the full path to the script file. It is recommended the project file end with a MIA extension since this is the standard file extension used for InstallAware scripts.


miaGetTotalLines

This function obtains the total number of lines that the in-memory script is comprised of. It must be called before the script is finalized.

int WINAPI miaGetTotalLines();


miaInitializeProject

This function initializes in-memory structures for programmatically emitting a new InstallAware project.

void WINAPI miaInitializeProject(
    bool BuildDebug,
    int BuildLayout,
    const char* CompressProfile,
    bool BuildInFolder,
    const char* BuildCustomFolder,
    const char* OutputFile,
    bool AutoIncrement,
    const char* Conditionals,
    const char* Manufacturer,
    const char* Name,
    const char* Code,
    const char* UpgradeCode,
    const char* Version,
    const char* Language,
    const char* Title,
    const char* Subject,
    const char* Author,
    const char* Comments,
    const char* Revision,
    const char* arPublisher,
    const char* arContact,
    const char* arHelp,
    const char* arUpdates,
    const char* arComments
);

BuildDebug

Indicates whether the project will be built in debug mode.

BuildLayout

Indicates the media type to be used in builds by default. The following values are possible:

  • 0: Uncompressed Directory Layout
  • 1: Compressed Self Extracting EXE
  • 2: Compressed Web Based EXE

CompressProfile

Indicates the strength of compression. Acceptable values are below:

  • 0: No compression, just store
  • 1: Minimum compression
  • 2: Medium compression
  • 3: Good compression
  • 4: Best compression

Note that this value is passed as a string.

BuildInFolder

If this value is false, builds will take place in the folder pointed at by the BuildCustomFolder parameter.

If this value is true, builds will take place in the default location, which is the project folder.

BuildCustomFolder

Specifies the custom build folder to use. Ignored unless the BuildInFolder parameter is false.

OutputFile

Allows to override the default name of the setup.exe install launcher file. By default, the name of the launcher file is identical to the project file name. Specify an alternate file name in this field to use a different file name.

AutoIncrement

Indicates whether the project revision code should be automatically updated each time a new build is made.

Please note that building a project from the command line or the automation interface will not increment the revision code.

Conditionals

Provides a list of compiler variables for conditional compilation in the form "VAR1=VALUE1","VAR2=VALUE2".

Manufacturer, Name, Code, UpgradeCode, Version, Language, Title, Subject, Author, Comments, Revision

Sets the corresponding fields as used in the Project Properties and Summary Information pages on the Project Options dialog in the InstallAware IDE.

arPublisher, arContact, arHelp, arUpdates, arComments

Sets the corresponding fields as used in the Control Panel Add-Remove Programs Listing page on the Project Options dialog in the InstallAware IDE.


miaSetScriptFile

This function sets the script file referenced by an InstallAware project.

void WINAPI miaSetScriptFile(
    const char* ScriptFile
);

ScriptFile

Specifies the script file to use:

  • If a file name without path information is used, the script file will be assumed to exist in the same folder as the project file. This allows for maximum portability when moving projects to different folders/computers.
  • If a file name with path information is used, the script file must exist in the absolute path referenced. This may make it more difficult to move projects, because the script file will still be expected to reside in the same folder.

Note

The script file does not need to exist at the time the function is called. This function only sets the project reference for the script file, it does not attempt to access the script file itself.


miaClearDialogFiles

This function clears the list of dialog files referenced by an InstallAware project.

void WINAPI miaClearDialogFiles();


miaClearSupportFiles

This function clears the list of support files referenced by an InstallAware project.

void WINAPI miaClearSupportFiles();


miaClearMergeFiles

This function clears the list of Merge Modules referenced by an InstallAware project.

void WINAPI miaClearMergeFiles();


miaClearPatchFiles

This function clears the list of patch references in an InstallAware project.

void WINAPI miaClearPatchFiles();


miaClearIncludeFiles

This function clears the list of include scripts referenced by an InstallAware project.

void WINAPI miaClearIncludeFiles();


miaAddDialogFile

This function adds a dialog file to an InstallAware project.

void WINAPI miaAddDialogFile(
    const char* Dialog
);

Dialog

Specifies the full path to the dialog file to use. The dialog file must already exist. The dialog file will be copied to the project folder when the project is finalized using the miaFinalizeProject function.


miaAddSupportFile

This function adds a support file to an InstallAware project.

void WINAPI miaAddSupportFile(
    const char* Support
);

Support

Specifies the full path to the support file to use. The support file must already exist. The support file will be copied to the project folder when the project is finalized using the miaFinalizeProject function.


miaAddMergeFile

This function adds a Merge Module to an InstallAware project.

void WINAPI miaAddMergeFile(
    const char* Merge
);

Merge

Specifies the full path to the Merge Module to use. The Merge Module must already exist. The Merge Module will be copied to the project folder when the project is finalized using the miaFinalizeProject function.


miaAddPatchFile

This function adds a patch reference to an InstallAware project.

void WINAPI miaAddPatchFile(
    const char* Patch
);

Patch

Specifies the full path to the patch reference to use. The patch reference must already exist. The patch reference must be an InstallAware installation, in EXE or MSI form. The patch reference will be linked to the project file.


miaAddIncludeFile

This function adds an include script to an InstallAware project.

void WINAPI miaAddIncludeFile(
    const char* Include
);

Include

Specifies the full path to the include script to use. The include script must already exist. The include script will not be copied to the project folder but referenced directly from its current location.s


miaFinalizeProject

This function flushes in-memory structures for an InstallAware project to disk and forms a valid MPR project file which may later be used by the IDE, the command line build tool, or the automation interface.

void WINAPI miaFinalizeProject(
    const char* SaveFile,
    int ScriptLines
);

SaveFile

Specifies the full path to the project file. It is recommended the project file end with a MPR extension since this is the standard file extension used for InstallAware projects.

ScriptLines

Indicates the number of lines present in the script file referenced by the project. This value may be obtained using the miaGetTotalLines function.


miaBuildProject

This function builds an existing InstallAware project.

bool WINAPI miaBuildProject(
    const char* Project,
    const char* Output,
    const char* Log,
    const char* Conditionals,
    int Mode
);

Project

Specifies the full path to the MPR project file.

Output

Specifies the full path to the build output folder.

If NULL, the default project output folder will be used.

Log

Specifies the full path to the log file. The log file will receive verbose information on the build process, and may be helpful for tracking build errors.

If NULL, no log file will be created.

Conditionals

Provides a list of compiler variables for conditional compilation in the form "VAR1=VALUE1","VAR2=VALUE2".

Mode

Specifies the kind of media to build. Use one of the following values:

  • 0: Uncompressed Directory Layout
  • 1: Compressed Self Extracting EXE
  • 2: Compressed Web Based EXE
  • 3: Patch

Notes

  • This function is provided for backward compatibility purposes only. Newer applications should use the miaBuildProjectEx function.


miaBuildProjectEx

This function builds an existing InstallAware project.

bool WINAPI miaBuildProjectEx(
    const char* Project,
    const char* Output,
    const char* Log,
    const char* Conditionals,
    const char* Language,
    const char* Password,
    int Mode
);

Project

Specifies the full path to the MPR project file.

Output

Specifies the full path to the build output folder.

If NULL, the default project output folder will be used.

Log

Specifies the full path to the log file. The log file will receive verbose information on the build process, and may be helpful for tracking build errors.

If NULL, no log file will be created.

Conditionals

Provides a list of compiler variables for conditional compilation in the form "VAR1=VALUE1","VAR2=VALUE2".

Language

Indicates the default setup language.

If NULL, the setting from the project file will be used.

Password

Indicates the 256 bit AES strong encryption key for the setup package.

If NULL, the setting from the project file will be used.

Mode

Specifies the kind of media to build. Use one of the following values:

  • 0: Uncompressed Directory Layout
  • 1: Compressed Self Extracting EXE
  • 2: Compressed Web Based EXE
  • 3: Patch


miaBuildProjectEy

This function builds an existing InstallAware project.

bool WINAPI miaBuildProjectEy(
        hwnd Handle,
        const char* Project,
        const char* Output,
        const char* Log,
        const char* Conditionals,
        const char* Language,
        const char* Password,
        int Mode
);

Handle

Handle to the parent window for the build progress window shown during build.

Project

Specifies the full path to the MPR project file.

Output

Specifies the full path to the build output folder.

If NULL, the default project output folder will be used.

Log

Specifies the full path to the log file. The log file will receive verbose information on the build process, and may be helpful for tracking build errors.

If NULL, no log file will be created.

Conditionals

Provides a list of compiler variables for conditional compilation in the form "VAR1=VALUE1","VAR2=VALUE2".

Language

Indicates the default setup language.

If NULL, the setting from the project file will be used.

Password

Indicates the 256 bit AES strong encryption key for the setup package.

If NULL, the setting from the project file will be used.

Mode

Specifies the kind of media to build. Use one of the following values:

  • 0: Uncompressed Directory Layout
  • 1: Compressed Self Extracting EXE
  • 2: Compressed Web Based EXE
  • 3: Patch


COMMATEXT

This structure represents a collection of multiple items in a single comma-delimited string. Each item is additionally surrounded by a double quote.

For example, the collection of the following strings:

Stri,ng 1
Stri"ng 2
String 3

String5

will be represented as the following single string:

"Stri,ng 1","Stri""ng 2","String 3","","String5"


Using the COM Object

The COM object implements an IDispatch interface and can be called from environments supporting the interface. For instance, use the COM object to dynamically emit InstallAware setup scripts and build them from webpages via ASP scripting.

mAutoWeb.CoInstallAware Methods

InitializeScript
AddCommand
FinalizeScript

mAutoWeb.CoInstallAware Properties

BuildProject
GetTotalLines

Example ASP Script

Set IA = Server.CreateObject("mAutoWeb.CoInstallAware")
IA.InitializeScript
IA.AddCommand "Set Variable","PREREQ","FALSE"
IA.FinalizeScript Request("ScriptFile")
Dim LineCount
LineCount = IA.GetTotalLines
Dim BuildResult
BuildResult = IA.BuildProject(Request("ProjectFile"), "$NULL$", Request("LogFile"), 0)


Command Parameters

Each installation command, whether built-in or plug-in provided, has a unique set of parameters. The parameters are often very similar to, although not identical, to the values entered in the IDE while the command editing window is open.

To discover the exact parameters of any command

  1. In the IDE, add the command to your script. Use meaningful values while completing the fields. This will help you recognize parameter ordering.
  2. Copy the command to the clipboard. Open Notepad, and paste the command from the clipboard. The command will paste as plain text.
  3. Observe the text. The values following the GUID are the command parameters. Each line after the GUID represents a single command parameter.
  4. You will recognize how parameter fields are ordered via the values you entered in step 1 above.
  5. Add the command to your script programmatically using all parameters discovered in this way.

Notes

  • If there are empty lines among command parameters, it indicates those fields are reserved. Simply duplicate the exact behavior in your automation projects
  • If there are no lines after the GUID, it indicates the command has no parameters
  • See the automation example projects for more information


Visual Studio Integration Overview

InstallAware integrates with Microsoft Visual Studio to provide automated setup creation from within the Visual Studio IDE itself.

Supported Versions

InstallAware supports versions 2003, 2005, 2008, and 2010 of Microsoft Visual Studio.

Available Functionality

InstallAware's Visual Studio Add-In provides the following functionality directly inside the Visual Studio IDE:

  • Automatically detect the files built by each project in a Visual Studio solution
  • Create an InstallAware setup project to install all detected solution files
  • Build and run the created InstallAware setup within Visual Studio
  • Configure code generation and additional project settings for InstallAware setup generation within Visual Studio
  • Launch InstallAware with the generated setup project to further customize and build automatically generated setups

You may access this functionality through one of the following three ways inside Visual Studio:

  • By clicking on the Visual Studio toolbar icons for InstallAware,
  • By clicking on the Visual Studio menu items for InstallAware,
  • By right-clicking the solution in the Visual Studio Solution Explorer, and choosing the InstallAware sub-menu from the solution context menu.


Creating an InstallAware Setup inside Visual Studio

To create an InstallAware setup for your solution inside Visual Studio, choose InstallAware [image] Create Setup Project on the main Visual Studio menu.

If you had previously created a setup, performing this step again will refresh the existing setup with any changes made to your solution since you last created your setup.


Building an InstallAware Setup inside Visual Studio

To build an InstallAware setup for your solution inside Visual Studio, choose InstallAware [image] Build Setup on the main Visual Studio menu.

If a previously created InstallAware setup project does not exist or is out of date, this step will automatically create the setup project before building it.


Running an InstallAware Setup inside Visual Studio

To run an InstallAware setup for your solution inside Visual Studio, choose InstallAware [image] Run Setup on the main Visual Studio menu.

If a previously built InstallAware setup project does not exist or is out of date, this step will automatically build the setup project before attempting to run it.


Launching InstallAware from Visual Studio

To launch the main InstallAware IDE from Visual Studio, choose InstallAware [image] Launch InstallAware on the main Visual Studio menu.

If a previously created setup project exists for your currently loaded Visual Studio solution, the InstallAware IDE will open that setup project. Otherwise, the InstallAware IDE will open your last edited setup project.


Configuring InstallAware Setup Settings inside Visual Studio

To configure InstallAware setup creation settings for your solutions inside Visual Studio, choose InstallAware [image] Setup Properties on the main Visual Studio menu. The Setup Properties window appears, which allows you to control basic setup creation settings. For more extensive setup settings, edit your setup project inside the main InstallAware IDE.

Project Node

This page lets you define the most basic aspects of your installation.

Manufacturer

Enter your company name here.

Product Name

Enter the name of the product the setup will install here. This name will be available in the setup script as the TITLE variable.

Product Version

Enter the version of the product being installed here.

Product Code

Click the Generate button to generate a new product code. The product code uniquely identifies your installation to Windows Installer. It must be unique in each different product, as well as different versions of the same product. This code will be available in the script as the PRODUCTCODE variable.

Upgrades Product with Product Code

If your installation upgrades a previous version, enter the product code of that version here.

Default Language

Choose the default language of your installation from the drop-down list.

Summary Node

This page lets you compose the summary stream information that will be available in the Windows Installer database. Be sure to set a unique Revision Code by pressing the Generate button any time you change your Product Code defined on the Project Node. This page also lets you manually set the Vista UAC elevation level.

Vista UAC Elevation

Select your desired Vista UAC elevation level using this combo-box. The default setting is highestAvailable. This setting is not recorded in the MSI file and has effect only on Vista or newer operating systems when UAC is enabled.

Add-Remove Node

This page lets you configure the way your application appears on the Control Panel Add-Remove Programs applet. Fill in the fields as necessary. The value entered for the Publisher Name field will be available in the setup script as the COMPANY variable.

You may also customize the icon used by your setup here by clicking the Load Icon button.

Compiler Variables Node

The list of all defined compiler variables for the current project is displayed on this page. Press the Add button to define a new variable. Double-click an existing variable, or choose an existing variable and press the Edit button to modify it. Press the Delete button after selecting one or more compiler variables to remove them.

Each setup project also has some pre-defined compiler variables.

Themes Node

The list of all installed InstallAware setup themes is available on this page, along with a brief textual description and screenshot for each theme. Click the View Theme button to interactively test each dialog available in a theme. The theme selected on this page will be used for your setup project.

Code Generation Node

This page lets you define how InstallAware's Visual Studio Add-In is to generate code for your setups created automatically inside Visual Studio.

Emit Include Files to preserve custom setup logic in main script

Each InstallAware project consists of a main script file which serves as the entry point into your installation, and one or more include script files, which are added to the main script file using the Include Script command. Include scripts provide a way to reuse code blocks across setup projects. Include scripts are not parsed by the InstallAware IDE's visual designers. The design views parse only the main setup script.

If this option is disabled, you will be able to visually view and edit your generated setup projects in the InstallAware IDE. However, any time your setup project has to be re-created, any customizations made to your main script file will be lost when the Add-In overwrites your main script to refresh your setup project.

If this option is enabled, you will not be able to visually view and edit your generated setup projects inside the InstallAware IDE. Of course, you will still be able to edit generated setup projects using the IDE's script editor. Additionally, any customizations made to your main script file will not be lost as the Add-In will store all of its auto-generated code inside include files, instead of the main script file. Therefore, any time the Add-In needs to update its auto-generated code, it will not have to overwrite your main script file, thus preserving your customizations to your main setup logic and code flow.

Emit new Features for each project in solution

Each InstallAware setup may have one or more end-user selectable features. This helps you break down your application into logical components and enable end-users to install only those features that they require. Using InstallAware technologies such as partial web deployment, you may also save end-users and yourself valuable time and bandwidth when multiple features are used in a setup.

If this option is enabled, the Add-In will generate one feature for each project that is a member of your Visual Studio solution.

If this option is disabled, the Add-In will not break up your setup into user-selectable features.

Files Node

This page lets you customize the folders files are installed into, determine which files to run after setup completes successfully, and choose whether shortcuts are created for files that are being installed. To choose these options:

  1. Select a file from the list of available files.
  2. To change the target folder of the selected file, click the Properties button. The Install File window appears. Choose your desired target folder in this window and click OK to apply your changes. $TARGETDIR$ refers to the installation folder chosen by the end-user while your setup is running, and therefore is the default destination for files being installed. Other system defined folders are available as alternatives.
  3. To create a shortcut for this file in your application's Start Menu group, check the Create shortcut for program check-box.
  4. To run this file when your application installs successfully and the end-user opts-in to run your program in your setup finished dialog, check the Run Program after Installation check-box.

Assemblies Node

This page lets you customize the way assemblies are installed by your setup. To choose these options:

  1. Select an assembly from the list of available assemblies.
  2. To change the target folder of the selected assembly, click the Properties button. The Install Assembly window appears. Choose your desired target folder in this window and click OK to apply your changes. You may choose to install your assemblies into the Global Assembly Cache by selecting the Install into the Global Assembly Cache option, or choose any pre-defined system folder by selecting the Install into Custom Path option. $TARGETDIR$ refers to the installation folder chosen by the end-user while your setup is running, and is the recommended custom path destination.
  3. To generate native images for that assembly at install-time, check the Generate Native Images (ngen) check-box. This helps your .NET code run faster as JIT compilation is performed at install time.
  4. To register your assemblies for COM Interop, check the Register Assembly (regasm) check-box.
  5. If your assembly contains an (un)installer class that you wish to call while setup is running, check the Run Installer Class (installutil) check-box.

Build Node

This page lets you configure your deployment type. The various kinds of deployment types, along with their uses, are explained below. Pick the one that is most suitable for your target audience. If you will be debugging your setup inside the IDE, also ensure the Debug Build checkbox on this page is checked. Note that you cannot run debug builds outside of the IDE.

Uncompressed Directory Layout

Your setup is contained in multiple files spanning several layers of multiple nested folders. Each file is uncompressed and immediately available, minimizing installation time, since files will not be uncompressed from an archive or downloaded before installation.

This type of deployment is ideal for CD/DVD media where disk space is not a concern and multiple files/folders can be stored. It also works well on network drives.

Compressed Single Self-Installing EXE

Your setup is contained inside a single self extracting file. This file, when run, will first extract its contents to a temporary folder, and then start the main setup program. In essence, when executed, the compressed layout converts into the uncompressed layout.

This type of deployment is suitable for Internet distribution, since the entire setup is contained inside a single file.

Compressed Web-Based EXE

Your setup is comprised of a self extracting file, which similarly to the compressed layout, extracts its contents and starts the main setup; as well as web media blocks, which are defined in your setup script and are downloaded as required from the web.

This type of deployment is ideal for Internet distribution. Setup will download only the web media blocks which are required on the target system. This saves download times and bandwidth since users will not waste either downloading portions of your application and/or its runtimes which they do not need.

Authenticode Node

This page lets you digitally sign your packages with authenticode. Provide the paths to your certificate and key files to enable code signing. The default value for the time stamp URL is http://timestamp.verisign.com/scripts/timstamp.dll.

Compression Node

Compression

This slider lets you configure the strength of the compression employed while creating your setups. Move the slider and choose a setting that is optimal for your system. You may wish to set the slider to choose no compression while testing and debugging your setup, as at maximum compression, builds take a long time to complete.

Use 256 bit AES Encryption

You may encrypt your compressed setups with strong 256 bit AES encryption technology. The entire setup payload, including the setup and data files, will be encrypted (even if the compression slider is set to use no compression).

Output Node

This page allows you to customize additional build settings:

  • If you wish to customize the output folder, check Custom Folder and provide your preferred output folder. By default, builds will exist under your project folder.
  • If you wish to customize the name of your main setup executable, enter it in the Output filename field. Leave this field empty to use the default name, which is the same as your project file name.
  • If you wish to automatically update the revision code every time you build (excluding batch builds), check Change revision code automatically upon rebuild. This setting must be unchecked when debugging your setup. Checking it will enable seamless, automatic upgrades of your product.
  • If you wish to generate file hashes for your non-versioned application files, check Calculate file hashes for Windows Installer. To improve build speeds, uncheck this setting. Checking it will enable Windows Installer to better identify changes made to your already-installed application files, but will slow processing.


AddCommand

This method adds an installation command to the in-memory installation script.

Example:

Set IA = Server.CreateObject("mAutoWeb.CoInstallAware")
IA.AddCommand "Set Variable","PREREQ","FALSE"

Command

Provides the name of the command to add. The command may be a built-in or plug-in defined command.

Parameters

Provides the parameters for the command. Each command has a unique set of parameters.

All command parameters must be combined into a single string value, formatted as COMMATEXT.

If the command does not expect a parameter, pass NULL in this parameter.


Else If

This command is used in conjunction with If commands. It performs another conditional evaluation, following a former if or else if statement.

Variable

Type the name of the variable, according to the value of which the conditional evaluation will be performed.

Comparison

Choose a comparison type from the drop down menu. If both variables contain integer values, a numeric comparison will be performed. If at least one variable contains a non-integer value, a string comparison will be performed.

Reverse Comparison

Check this checkbox if you wish to execute an if not evaluation.

Compare With

Type the name of the second variable for comparison. You may also use a string literal in this field instead of a variable.


InitializeScript

This method initializes in-memory structures for programmatically emitting a new InstallAware script.

Example:

Set IA = Server.CreateObject("mAutoWeb.CoInstallAware")
IA.InitializeScript


MimarSinan InstallAware Professional

Starting a New Project

There are several ways to start a new project. Each of them is described below.