Chapter 2: Windows Installer Service

Install and uninstall issues are some of the most common sources of application interoperability problems. These requirements help to ensure that the user has successful installation and uninstallation experiences, and that the application co-exists in a friendly way with other applications.

The Windows Installer service is an operating system component that centrally manages application installation configuration, as well as application uninstall. Using the Windows Installer service allows the operating system to manage application setup and configuration, which enables the following:

• Management of reference counting and version checking of shared components, which helps ensure that applications better co-exist with one another
• Robust installations and self-repairing applications
• Reliable and complete uninstall, including correct handling of shared components.
• Ability to perform installation on secure systems (for non-administrators and non-power users)
• Enables applications to make full use of Windows 2000 IntelliMirror™ functionality for policy-based deployment, update, and uninstallation over a network

The Windows Installer service enables all of this functionality using packages that describe application configurations. The Windows Installer ships in Windows 2000 and is also available for redistribution on Windows NT 4, Windows 98, and Windows 95.

Customer Benefits

End users gain these benefits when your application uses the Windows Installer service:

• Fewer problems during application setup: installation and uninstallation of applications is less likely to affect the performance of another application because reference counting and version checking are properly implemented
• Self-repair of damaged applications at runtime: When the application is launched, the Windows Installer will check to ensure that the application is properly installed, and if it is not, will automatically repair the application on-the-fly
• Transacted install: In the event that the installation is not completed (for example, if there is a network failure), the Windows Installer can roll back to the earlier installed version of the application without error
• On-demand install of your application

System administrators in corporate environments also gain these benefits when your application uses the Windows Installer service:

• Ability to perform installation on secure systems (for non-administrators and non-power users) without having to visit the PC
• A Windows Installer-based package (.msi file) allows the administrator to easily determine what files, and what versions of those files, are being installed. This is especially beneficial for corporations that maintain a list of "known good versions" of shared DLLs and allow installation of applications that require a shared DLL only on the basis of this list
• The Windows Installer service management APIs can be used with management tools that allow files and application integrity to be remotely checked
• Application installation more readily supports roaming users via install on demand and indirection of file paths through the installer API's (reduced dependence on hard paths that may change across machines)
• Application installation more readily supports mass deployment in organizations using Win2000 software management, and as a result of standard support for customization and unattended install

Requirements

2.1  Install using a Windows Installer-based package that passes validation testing

2.2  Observe rules in componentization

2.3  Identify shared components

2.4  Install to Program Files by Default

2.5  Support Add/Remove Program Files properly

2.6  Ensure that your application supports advertising

2.7  Ensure correct uninstall support

References

• Microsoft Platform SDK: Windows Installer Programmer’s Reference
• Windows Installer SDK (includes msival2.exe and logo.cub file): https://www.microsoft.com/msdownload/platformsdk/WinInst.htm

How to Comply with Windows Installer Requirements

2.1  Install using a Windows Installer-based package that passes validation testing

Your application must install itself using the Windows Installer service. To do this, your install must be in the form of a Windows Installer-based package. You must validate that the package is properly constructed by running an Internal Consistency Evaluation tool (such as msival2.exe, available in the Windows Installer SDK) in conjunction with the suite of ICEs contained in the file named logo.cub. These are available from the Windows Installer SDK at: https://www.microsoft.com/msdownload/platformsdk/WinInst.htm. You can also use the logo.cub file in conjunction with ICE tools provided by leading install tool vendors.

Leading vendors of install tools have new versions of their tools to enable easy authoring of Windows Installer-based packages. Contact your tools vendor for more details. You can also create your own Windows Installer-based package. The Microsoft Platform SDK provides a detailed example for implementing a Windows Installer-based package.

2.2  Observe rules in componentization

The Windows Installer service always installs and removes an application as monolithic pieces of information referred to as components. A component can consist of a collection of files, registry keys, shortcuts, or any other information that must be written to the user's computer during the installation. The installer identifies a component by its unique component code GUID. The installer locates the component using a keypath file that belongs to the component. Because components are commonly shared by more than one application or product, developers must correctly organize their applications into a set of components to ensure their application can be managed by the installer. For more details, see "Organizing Applications into Components" in the Windows Installer documentation in the Platform SDK.

To ensure that the removal of one program does not harm any other programs on the system and that the Windows Installer service correctly removes all resources connected with that program, your application must adhere to the following rules:

• A single resource must not be shipped as a member of multiple components across multiple products, unless it is isolated as its own component and is flagged as shared in the component table

• All files in a given component must be installed to the same directory

  This means files in different directories must be in different components.

• All files that are the targets of advertisable shortcuts must be the KeyPath of a component

  This means there can only be one advertised file per component, although many different shortcuts can point to that single file.

• COM servers must be the KeyPath of a component

  This means there can only be one COM server per component. A single file, which can only be in one component, may serve multiple CLSIDs. However, two files serving different CLSIDs must be in separate component. Extension servers must be the KeyPath of the component. This means there can only be one Extension server per component.

2.3  Identify shared components

• If the Windows Installer service determines that a component is shared, it will automatically handle the incrementing and decrementing of reference counting, and if appropriate, removal of components when no other application depends on them
• The Windows Installer service will automatically determine if components are shared with other applications that also use the Windows Installer service
• For components that are to be shared with applications that don’t use Windows Installer service, you must flag these components in the component table, so the Windows Installer service knows to also reference count them in a manner that is compatible with legacy install methods; this helps ensure that your application interoperates properly with other applications that do not use the Windows Installer service
• Components that are shared with applications that don't use Windows Installer service need to properly implement the DLLRegisterServer and DLLUnregisterServer entry points if they need to do any registration at install time (DLLs which use the Windows Installer should use the registration services provided by the Windows Installer)

Note   Applications are not allowed to update files that are protected by Windows File Protection on Windows 2000. See: Requirement 3.3 for more details.

2.4  Install to Program Files by default

By default, your application must install into an appropriate subdirectory where the current user’s program files are stored. This folder is represented by the ProgramFilesFolder property in the Windows Installer-based package. (The ProgramFilesFolder property is a variable that exposes the path to the Program Files folder, and the Windows Installer sets that variable appropriately on all Windows platforms.) On English systems, this folder is often "C:\Program Files". However, do NOT hardcode that path, as it is not universal.

**Exception   **If you are upgrading a previously installed version of your application, it is acceptable to default to the directory where that version exists.

Note   Considerations for shared components: In some cases shared component must be placed in locations other than the application directory. See "Chapter 3: Component Sharing" for full details.

2.5  Support Add/Remove Programs properly

Your application must supply all the information in the following table so that Add/Remove Programs in the Control Panel can obtain information about the application as needed. You can set these values using properties in the Windows Installer-based package. Setting these properties will automatically write the corresponding values in the registry under:

HKEY_LOCAL_MACHINE
  \Software
    \Microsoft
      \Windows
        \CurrentVersion
          \Uninstall
            \{ProductCode}

You can also provide additional properties to present in Add/Remove Programs if you like, such as product ID, online support information, etc. See the platform SDK for full details.

2.6  Ensure that your application supports advertising

"Advertisement" is the notion of application availability in the absence of the application’s files being installed. Advertising allows the application to be deployed using software management tools.

All Windows Installer-based packages of your core application must be advertisable in a manner that operating system entry points, such as shortcut activation and file activation, can trigger install on demand. In order to support advertisement at the operating system level, the following tables in the Windows Installer-based package must be populated with advertising data: shortcut, extension, icon, and Verb. It is recommended that you also populate class, MIME, ProgID, and TypeLib.

**Note   **This does not mean your application must support feature-level advertising, (e.g. enabling the spell-checker to install on demand). The intent of this requirement is to ensure that your overall application can be installed on demand using the IntelliMirror features of Windows 2000.

2.7  Ensure correct uninstall support

Your application’s Windows Installer-based package must correctly and fully uninstall the application. In a package that follows component rules and uses only native Windows Installer actions to modify the computer, this capability is provided automatically.

However, if your Windows Installer-based package includes custom actions, you will need to proactively ensure that your application properly uninstalls. Except as noted below, your application must remove the following:

• All non-shared application files and folders
• Shared application files whose refcount reaches zero
• Registry entries, except for keys that might be shared by other programs
• All shortcuts from the Start menu that the application created at install-time
• The uninstaller itself

The following should remain on the hard disk:

• User data files.
• Shared application files that have a non-zero refcount.
• "Core" files. These files must be left behind to ensure compatibility with legacy applications. See: https://www.veritest.com/ftp/core.htm for the most up-to-date, complete list. The core component list exists for historical reasons and is maintained to ensure compatibility with legacy applications that did not properly implement refcounting. Microsoft expects to add no new files to this list. On Windows 2000 and later, applications should rely on Windows File Protection for information on what system files to update or uninstall. See "Chapter 3: "Component Sharing" for more details.
• Other resources that other programs use, sharable fonts, and sharable registry entries. If you are not sure whether removing a DLL might harm other applications, it is better to leave it behind.

Important   You must explain in the Vendor Questionnaire everything you leave behind.

**Tip   **If your application creates temporary files that should be removed during uninstallation, create a zero-length (0) file with the same name at installation time. Examples of such files would be .gid files created by Help.

How to Pretest Applications for Windows Installer Service Requirements

To Pretest a Windows Installer-Based Package

• Use an Internal Consistency Evaluation tool with the logo.cub file to check the validity of your application’s Windows Installer-based package; the logo.cub file is available in the Windows Installer SDK
• Use Windows 2000 software management tools to deploy the application to both users and to machines; verify all the activation paths work correctly when the application is advertised

To Pretest Correct Setup Actions

• Use the Windows 2000 application deployment tools to publish the application. Verify the application can be installed from Add/Remove Programs, Add from the corporate network.
• Use the Windows 2000 application deployment tools to assign the application to a user. Log on as that user to a machine that did not previously have the application installed. Verify after the user logs on that the application is correctly advertised, i.e., it looks like it is fully installed on the machine and all activation paths (shortcuts and file extensions, for example) trigger an installation.
• Use the Windows 2000 application deployment tools to assign the application to a machine that does not currently have the application installed. Verify after the machine is booted the application is fully installed.
• Undeploy the application in the tests above. Verify Windows 2000 software management can silently uninstall the app from the user/machine.
• Install the application for more than one user on a given machine. Verify each user can have their own settings and also uninstalling the application for one user does not affect the others.
• Test the install and uninstall of your package under each of these Windows Installer UI modes:
  • Full
  • Basic (Simple progress and error handling)
  • None (completely silent installation, no UI)

You can activate different UI modes by launching your package with the /q switch. (Default is mode full. Specify b=basic, n=none)

To Pretest Uninstallation

1. Take a snapshot of a computer’s directory tree, install the application, uninstall the application, and take another snapshot.
2. Verify that the snapshots before the install and after the uninstall are the same, except for the following which should be left on the machine: user created files, core files, and shared components that are still required by other programs.

To Pretest Interop with Other Apps that Share Components

To ensure that your application interoperates well with other applications (that do not use the Windows Installer) that share some of the same components that your application uses, you should test and verify each of the following scenarios: