Frequently Asked Questions About Windows Installer

Windows Installer is a system service for installing and managing applications. It provides a standard method for developing, customizing, installing, and updating applications.

Windows Installer provides the following basic functions:

Version 2.0 of Windows Installer includes a number of new features and improvements over previous versions, including the following:

More information on Windows Installer can be found in the Windows Installer software development kit (SDK).

Further information on Windows Installer is available in the following white papers:

Microsoft Windows 2000, Windows Millennium Edition (Windows Me), and Windows XP include Windows Installer. Windows 2000 includes version 1.1 of Windows Installer, Windows Me includes version 1.2, and Windows XP includes version 2.0. Windows 2000 SP3 also contains version 2.0 of Windows Installer.

This table details the operating systems that each released version of Windows Installer supports.

You can obtain the latest Windows Installer redistributable from the Microsoft Platform SDK Redistributables site. There are two different versions of the Windows Installer redistributable: one for Windows 95, Windows 98, and Windows Me; and one for Windows NT and Windows 2000.

Microsoft merge modules are provided with Microsoft Visual Studio .NET. Their default installation location is [ProgramFilesFolder]\Common Files\Merge Modules. Note that not all Microsoft redistributable components have merge modules available.

To hide an application from Add/Remove Programs, set the ARPSYSTEMCOMPONENT property to 1. This property can be set within the Property table of the package, on the command line, or by means of a transform. On operating systems earlier than Windows 2000, setting the ARPNOREMOVE property to 1 will hide the application from Add/Remove Programs. On the Windows 2000 and Windows XP operating systems, ARNOREMOVE disables the Remove button of Add/Remove Programs.

The .msi package database format is based upon OLE structured storage. Frequent editing of the database over time can result in fragmentation and wasting of space. You can reduce the size of the .msi package by using the SaveAs command in Orca or alternatively by exporting all of your tables with msidb.exe from your package and then re-importing them into a newly created database.

Both the Orca and msidb.exe tools are available in Windows Installer SDK.

Beginning with Windows Installer 2.0, there is a command-line option, that makes it possible to hide the Cancel button during basic user interface (UI) installations. The following command-line script demonstrates how to use the new option:

msiexec /i {path to package} /qb!

You can also hide the Cancel button by using the MsiSetInternalUI Win32 API to combine INSTALLUILEVEL_HIDECANCEL with INSTALLUILEVEL_BASIC. Alternatively, the same can be accomplished through Windows Installer automation by combining msiUILevelHideCancel with msiUILevelBasic when using the read-write UILevel property of the Windows Installer object.

During an installation, the presence of the Cancel button can be changed through a DLL or script custom action that sends an INSTALLMESSAGE_COMMONDATA message. DLL custom actions would use the MsiProcessMessage Win32 API to send an INSTALLMESSAGE_COMMONDATA message where field 1 of the record is set to 2 and field 2 of the record is set to 0. To unhide the Cancel button, the same message would be sent, but with field 2 set to a value of 1. Script custom actions would use the equivalent Message method of the Session object.

The ADDLOCAL, ADDSOURCE, and ADVERTISE properties can be used to install only a certain number of known features. The following command-line script would be used to install the "Sports" and "News" features of the example.msi package locally on the machine.

msiexec /i example.msi ADDLOCAL=Sports,News /qb

The following command-line script would advertise the "Sports" feature and install the "News" feature to run from source.

Msiexec /i example.msi ADVERTISE=Sports ADDSOURCE=News /qb

Another important thing to remember is that feature names are case-sensitive.

You can "force-update" an unversioned file during an upgrade by authoring a version number for that file in the File table. Based on Windows Installer file-versioning rules, a versioned file will overwrite an unversioned file. The caveat to this approach is that all subsequent reinstallations will require access to the source, since all subsequent version checking will indicate the file needs to be reinstalled.

Directory property values end with a directory separator. Authoring a path string therefore does not require the use of the directory separator.

Incorrect: [DirectoryProperty]\someLocation

Correct: [DirectoryProperty]someLocation

For products with different versions, either due to language or other differences between products, use different product codes. To indicate a direct, familiar relationship among the products, have the products share the same upgrade code.

A managed application is an application where the system administrator exerts some level of control over the installation and maintenance of the product. Managed applications are often used to deploy software to large numbers of users or machines. Managed applications are a way for system administrators to allow users to install authorized software in locked-down environments where users generally do not have the rights to install software.

An application is considered managed if it is:

An installation package cannot declare itself "managed." Whether or not an application is managed is controlled by the system administrator.

Note that "managed" is different from "elevated." An elevated application is an application that can run with system privileges when installing. All managed applications are elevated, but applications can be elevated without being managed by means of the AlwaysInstallElevated policy. Due to its security implications, this policy is disabled by default and requires careful consideration before use.

The AdminUser property is set when the user performing the installation is an administrator; the Privileged property is set when the user is allowed to install with elevated privileges. A user can install with elevated privileges if the user is an administrator, both the per-user and per-machine AlwaysInstallElevated policies are set, or the application has been assigned by the system administrator.

If the user is an administrator, then both the AdminUser and Privileged properties are set. If the user is not an administrator, then AdminUser is never set. In that case, Privileged is only set if the user has been given permission by the administrator through assignment or policy to install the application as elevated.

In many cases, it is recommended that launch conditions or similar conditions use Privileged instead of AdminUser to allow for installation of applications assigned by administrators.

Those with user-level privileges can install managed applications if the system administrator has enabled the installation. Otherwise, the user will only be able to install MSI applications provided the user has permission to write files, create directories, and write registry keys in the locations where the installation typically writes those resources. If the user cannot write to a location, then the installer will only be able to write to that location if the administrator has given permission for the installer to do so.

Deferred custom actions should be used when the custom action must make a change to the system or call another system service. Additionally, only deferred custom actions can run in an elevated context. If your custom action requires elevated privileges in order to run, your custom action needs to be marked as deferred.

Note: Custom actions marked to run in the system context (msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate) will only run in the system context if the installation itself is elevated.

Additionally, when making a change to the system by means of a custom action, you should also include a rollback custom action that can undo the change.

Deferred custom actions have limited access to the installation session. If your deferred custom action requires information about the installation that it cannot obtain through its limited access, then you can provide that information to the deferred custom action through the CustomActionData property. This method is only available to script and DLL deferred custom actions. This is how it works:

An immediate custom action can trigger a reboot by calling MsiSetMode with a run mode of MSIRUNMODE_REBOOTATEND or MSIRUNMODE_REBOOT and a state value of TRUE. Since MsiSetMode requires an hInstall handle, only DLL and script custom actions can trigger a reboot. Script custom actions would use the Mode property of the Session object. Alternatively, an immediate custom action can call MsiDoAction with szAction equal to "ScheduleReboot."

Deferred custom actions cannot call MsiSetMode. A deferred custom action would need to set a value in a location in the registry that an immediate custom action, sequenced after InstallFinalize would read. That immediate custom action could then schedule the reboot using MsiSetMode. If this method is required, a rollback custom action should also be provided that will delete the registry value that triggers the reboot if the installation is cancelled.

DLL and script custom actions can add information to the verbose log file by sending INSTALLMESSAGE_INFO messages using the MsiProcessMessage API. Script custom actions would use the Message method of the Session object.

A number of MSIExec processes can be running during an installation. The reason for this is that Windows Installer uses a client-server model for performing installations. Additionally for security reasons, Windows Installer hosts DLL and script custom actions in a "sandbox" process. Depending on how the install was initiated, one of the MSIExec processes can be the client process. Another MSIExec process is Windows Installer service. Any remaining MSIExec processes are usually sandbox processes for hosting custom actions. The determination as to which MSIExec process will serve as the sandbox process for a script or DLL custom action depends in part on whether the custom action will run elevated or impersonated and whether the custom action is 32-bit or 64-bit.

A small update is a product update that changes a few files or possibly adds some new content. A minor update is a product update that makes enough changes to warrant changing the product version for the product, whereas a major update is a product update with a large number of changes that warrants a change in the product code. This table summarizes what changes in each update and the possible distribution vehicles for each.

It's sometimes easier to think of a small update as a "hotfix" or Quick Fix Engineering (QFE) update, a minor update as a service pack, and a major update as a product upgrade.

Small and minor updates can be considered almost equal in that the only real difference is that a minor update has a change to the ProductVersion whereas a small update does not. The rules that they follow and application of the patch are the same. Application of small and minor update patches requires explicit reinstallations. Major updates are not subject to that limitation and a reinstallation is not required for patch application. Additionally small and minor update patches are limited in the changes that can be made to the feature-component structure for the package. Significant changes can be made to the feature-component structure in the scope of a major update.

Windows Installer 2.0 has a number of improvements in the area of patching to minimize original source requirements. However, there are still some circumstances in which the original source may be required:

At this point, you can't completely prevent a patch from requiring the source. However, the following steps could help eliminate a number of those instances:

Most likely you simply double-clicked a small or minor update patch. Application of a small or minor update patch requires an explicit reinstallation to be performed for the files to be updated. This can be accomplished using the MSIExec command line and including the REINSTALL and REINSTALLMODE properties (that is: msiexec /p {path to my patch.msp} REINSTALL=ALL REINSTALLMODE=omus). Another option would be to include a custom action in the patch that will set the REINSTALL and REINSTALLMODE properties appropriately. You should make sure that you conditionalize this custom action appropriately so that it only runs on first application of the patch. Subsequent reinstalls of the product should not result in execution of the custom action, otherwise your product may no longer be uninstallable. Other options include using a bootstrap executable that calls MsiApplyPatch with the appropriate property settings or using Windows Installer automation object to script the patch application.

Yes, you can update a custom action using a patch. If the custom action is included in the Binary table, then simply update the custom action in the update installation image. When you generate the patch between the original and update installation images, the patch will contain a database transform that will transform the old binary data stream to the new binary data stream.

There are three good troubleshooting methods for tracking down package installation problems. The first method is to ensure that your package is valid by running validation. Validation helps catch common installation authoring problems by identifying errors and warnings. Two tools can be used for validating an installation package, both are available in the Windows Installer SDK: MsiVal2 and Orca. MsiVal2 is a command line utility for validating a package. Orca provides a graphical user interface for validation and will also highlight invalid entries in the package.

The second method is to use the application event log. Windows Installer will record successful and failed installation information in the application event log.

The final method is to generate a verbose log file, and then analyze the verbose log file looking for the source of the error. A helpful utility for analyzing verbose log files is the WILogUtl.exe tool provided in the Windows Installer SDK. Logging can be enabled via Windows Installer logging policy or by appending "/L*v path to logfile" to your MSIExec command line.

To generate a detailed verbose log file through policy, use the following registry key:

Log files generated through the policy key will be of the form msiXXXXX.log in the user's %temp% folder.

Note: Logging through the command line overrides any logging policy settings.

An easy way to determine the cause of an on-demand installation is to look in the application event log for MsiInstaller log messages of the form:

Event Type: Warning
Event Source: MsiInstaller
Event ID: 1001
Description:
Detection of product '{000C1109-0000-0000-C000-000000000046}', feature 'Example' failed during request for component '{00030829-0000-0000-C000-000000000046}'
Event Type: Warning
Event Source: MsiInstaller
Event ID: 1004
Description:
Detection of product '{000C1109-0000-0000-C000-000000000046}', feature 'Example', component '{00030829-0000-0000-C000-000000000046}' failed. The resource 'C:\Progam Files\example\example.exe' does not exist.

The first message (with event ID 1001) states which component was being installed. The component listed here is the component named in the Component_ column of the Shortcut table for the particular shortcut.

The second message (with event ID 1004) indicates which component failed detection. Improved event logging in Windows Installer 2.0 has updated the message so that in most cases, the message identifies the actual resource that resulted in the failed detection. The component with the missing or damaged keypath is the component that is triggering the reinstallation.

In the example above, the reinstallation is triggered because the resource 'c:\Program Files\example\example.exe' does not exist. You would then need to find out why the keypath does not exist—in this case, the user deleted it.

Determining whether Windows Installer installed a particular feature or component is fairly easy. The answers can be found in a Windows Installer verbose log file. The first thing to look for is the logging of the InstallValidate action. This action will log the installed, request, and action states of each feature and component in the installation package.

MSI (s) (5C:F4): Doing action: InstallValidate
Action start 1:51:18: InstallValidate.
MSI (s) (5C:F4): Feature: Example; Installed: Absent; Request: Local; Action: Local
MSI (s) (5C:F4): Component: Example; Installed: Absent; Request: Local; Action: Local
Action ended 1:51:18: InstallValidate. Return value 1.

In the log file snippet shown above, the "Example" feature will be installed locally since its action state is local. Furthermore, the component "Example" will also be installed locally given its action state.

There are four common reasons for why files may not be removed during uninstallation:

Folders are not removed during uninstallation because of one of the following reasons:

The most common causes for leaving behind registry keys during uninstallation are:

Windows Installer calculates two types of space consumption: the space consumed with rollback, and the space consumed without rollback. The space consumed without rollback is the actual disk space conumed by the installation. The space consumed with rollback will include the space of the backup files necessary for supporting rollback during the installation. Additionally, Windows Installer calculates some of the overhead required for performing the installation. Included in the overhead is the space required for the installation script and the space requirements of the cached package. Furthermore, the installer runs from a temporary copy of the installation package during the installation. Both the space requirements of the installation script and the space requirements of the running copy of the package are temporary. These files are cleaned up after installation. Consider the following example where your installation package is around 80 kilobytes (KB) in size and you are installing a 4 KB file (Note: your numbers may vary depending on the cluster size of your hard drive):

89120 bytes (cached MSI, rounded to nearest cluster size of 4 KB)
89120 bytes (temporary working copy of MSI)8192 bytes (estimated script size)
4096 bytes (small file, rounded to disk cluster size of 4 KB)
----------------------
176128 bytes = 172 KB

Windows Installer may prompt for a reboot if it installs over a file that is in use or the package explicitly requests that the installer reboot. It is easy to determine if Windows Installer prompts for a reboot because it installed over a file that is in use. The first step is to generate a verbose log file. In the verbose log file, look for the presence of the ReplacedInUseFiles property in the property dump. If this property is present with a value of 1, then the Installer will require a reboot because it overwrote an in-use file.

To determine which file was in-use, scan the log file for "Info 1603" and "Info 1903" messages. The 1603 message will be logged by the InstallValidate action. For example:

MSI (s) (DC:DC): Doing action: InstallValidate
Action start 19:55:42: InstallValidate.
…
Info 1603. The file d:\test\sample.exe is being held in use by the following process: Name: sample.exe, Id: 4068, Window Title: 'Sample'. Close that application and retry.

Normally, this message coincides with the presentation of the FilesInUse dialog box. In silent UI cases, this dialog box will not be presented. Additionally, not all files that are in use will show up in the FilesInUse dialog box. The FilesInUse dialog box may not be displayed if the files in use are not executables, the process holding the files is the process invoking the installation, or the process holding those files is one that does not have a window title associated with it.

The FileCopy opcode in the install script can also log the 1603 info message. In the above example, the log file contains:

MSI (s) (DC:DC): Executing op: FileCopy(SourceName=sample.exe, SourceCabKey=sample.exe, DestName=sample.exe, Attributes=0, FileSize=2044928, PerTick=32768, , VerifyMedia=1, , , , , CheckCRC=0, Version=2.0.2600.0, Language=0, InstallMode=59244544, , , , , , )
…
Info 1603. The file D:\test\sample.exe is being held in use. Close that application and retry.

At the end of the script during cleanup, the following log file message identifies the culprit for the reboot:

Info 1903. Scheduling reboot operation: Deleting file D:\Config.Msi\12544a31.rbf. Must reboot to complete operation.

While the file is named 12544a31.rbf, it is the Sample.exe file. In order to install the file, the in-use file was renamed to the .rbf file and will be deleted upon reboot.

The error ERROR_INSTALL_PACKAGE_VERSION means that the version of Windows Installer on the machine does not support the schema of the package. The package schema is indicated by the PID_PAGECOUNT property in the summary information stream of the package. If the schema number of the package is greater than the maximum supported schema by Windows Installer, you will need to update your version of Windows Installer or re-author the package to be compatible with an earlier schema.

The minimum supported schema for all versions of MSI is 30.

The maximum supported schema for each version of MSI is:

Launching an installation from a system account, like the scheduler service, may result in the 2103 error. This can occur if you are initiating a per-user installation. Only per-machine installations are permitted from the system account because the system account does not have all of the necessary per-user profile folders.

Windows 2000 and earlier operating systems do not support passing mapped drive letter information between terminal server sessions. Since Windows Installer service runs as a service in the console session, mapped drive letters established in remote sessions are not visible to Windows Installer service, resulting in this error. This only applies when running the service in Application Server mode, not Remote Admin mode.

Note that this limitation no longer exists in Windows XP and later operating systems.

The security warning dialog is presented because of a problem in the way the Web download bootstrap (Setup.exe) performs the digital signature verification. This problem has been fixed in the latest available sample code provided with the Windows Installer SDK available in the Microsoft Download Center. Simply re-build the Setup.exe using the PSDK build environment and the provided sample code. Then re-configure the Setup.exe using the MSIStuff.exe utility. You can download the fixed sample code from the SDK Update site.