MSI is the standard file format for application distribution in the Windows environment Somewhat like RPM for Linux). Presently only very few applications are shipped in MSI format by the vendor. Therefore most applications have to be repacked into MSI format before they can be deployed in a Windows 2000 environment.

This document tells you how we package MSIs and gives some general information on the process. We are use Wise for Windows Installer, so some of the things said in this document may be dependent on this particular product.

An MSI is basically a database with a number of relationally linked tables and a set of files either inside or next to the MSI file. The Database contains information about what has to be done to the target Computer in order to install the Application.

The installation process itself is controlled by a list of 'Actions'. Several such lists are predefined in the MSI standard. These action lists can be amended by 'Custom Actions' performing special tasks not covered by normal MSI behavior. Custom actions can even launch scripts and executable to perform special installation chores.

The actual installation itself is performed by a special MSI installer service running on the computer. Because this service runs with system privileges it has all the rights necessary to perform the installation. Depending on the local security policy normal users can be granted the right to make the installer service install certain packages or even any package the user wants.

When creating an MSI for use in our local Win2k environment, there are some special rules to observe for the resulting MSI to fit in with our overall concept. In our local Win2k environment only a few core applications get installed on a workstation by default. All the other applications get published through the Group Policy and can be installed by the local user when required. Windows Installer service allows this installation to happen in a System Context even though users can normally not install applications on a locked down workstation.

Shortcuts Rules

The primary method for starting applications in a windows environment are links in the 'Start' menu.

• ISG MSIs should only install 'necessary' links and not as many as possible.
  
• Link to documentation are only 'permitted' if the documentation can not be accessed directly form the application.
  
• Do not try to force shortcuts into the 'All Users' start menu. In the MSI the shortcuts should appear to be located in Windows\Profiles\Start Menu\Programs. The MSI Service will then move the Shortcuts to their proper location upon installation of the package.
  
• The ISG Win2k Start Menu has a predefined structure. Application shortcuts should be installed into this structure. Only very big application packages are allowed to create their Sub directory.

  Destination Directory: Windows\Profiles\Start Menu\Programs

  MS Office     (Word, Excel, ...)
  Tools         (Acroreader, GsView ...)
  Editors       (PFE Editor, ....)
  Internet      (Eudora, ...)
  Multimedia    (RealAudio, ...)
  Scientific    (Maple, Mathematica, ...)
  Graphics      (XNview, Xara, ...)
  LaTeX         (MiKTeX)
  Programming
  References
  

  
• The shortcuts should be a simple Application name without version number.
  
• Shortcuts should use Advertising, this ensures that Shortcuts always have an Icon, even if users move from machine to machine. The advertised shortcuts also trigger the installation of an application missing on the machine where the user is currently active.
  

MSI Meta Information

Each MSI also stores some Meta information about its content. In Wise for Windows Installer this information can be configured in the Sections Project, Summary and Windows 2000 of the Installation Expert:

• Special Properties for Project:

  Name:

  Product-name Versions-number

  

  Version:

  Product-version-number.Package-version-number

  

  Default Directory:

  c:/Program Files/Application

  

  
• Special Properties for the Windows 2000 Section:

  Display Icon:

  *.ico or *.exe file with appropriate icon for the package Note that the Icon Number must be 0 for the first icon in the exe

  

  Online Info URL:

  http://www.product.website

  

  Contact Person:

  Your Email Address <of@package.author>

  

  

Updates

When you make changes to a package you have two options to re-deploy the package:

• If you have made small changes to the package and you are lucky, then you can keep the version number (in the Project Properties) the same and just save the new package on top of the old package. Important is that you don't change version number !
  
• You make big changes and change the version number (Package-version-number). Do not just overwrite the old package in that case! You probably have to use the "Upgrade" feature in Wise... Nobody didn't this yet.
  

Empty Components

Before you store an MSI, make sure that it does not contain ANY empty components. If the MSI does contain such components, then the installer will pop up whenever a user launches an advertised shortcut to the program. Unfortunately the Wise installer does not automatically identify such components as problematic. So you have to hunt them down on your own by going into the component tab of the Setup Editor screen in Wise for MSI and opening each component in the package and verifying that it is not empty ... (as of Wise 3.01 such components will have no (+) sign after they have been highlighted once ... so it is sufficient to scroll through the component list to see the offender.

Constant Reinstallation

Sometimes an msi attempts to self-heal (aka reinstall) whenever it is started. This happens when a component of the msi can not find its keypath. In such a case, check the Application Log in the EventViewer. It will contain the GUID of the component which is being reinstalled. Open the msi in wise and search for the component GUID and look at the components keypath. If the keypath can not be fixed to just set it to none and thus disable the self-heal function.

Formatted Fields

In many places throughout an MSI you can enter specially formated text which will get parsed and replaced on installation of the MSI. This is especially useful to refer to path names of files or components. For extended information on this topic, search for 'Formatted' in the official MSI documentation.

[$cvs.exe1]

Directory where the cvs.exe1 component will be installed

[!cvs.exe]

Full 'short' path for the cvs.exe file. Note that cvs.exe is not the actual filename but the filename assigned to the file by wise. This is often the same name, but can occasional be something like cvs.exe1... check the file property dialog to check.

[#cvs.exe]

Full path for the cvs.exe file. See note above

[ProgramFilesFolder]

Formerly known as C:\Program Files

Making an Application available in Open With Desktop Menu

The Registry key HKLM\SOFTWARE\Classes\Application determines the list of applications shown in the "Open With" list.

Example:

Key:   HKLM\ 
         SOFTWARE\Classes\Applications\ 
              gvim.exe\shell\open\command

Value: <Default>   = "[!gvim.exe]" "%1"

Registering a File Extension

If your application uses special file extensions, you might want to register them so that the application gets started when the file gets double clicked, and that there is an icon associated with the file. There are special tables for this in the msi structure (Extension and ProgId) their contents is also used for advertising. In Wise 3.5 there is even a GUI for editing the Contents of the Extensions table. No gui though for the ProgID table which sets up icons for file extensions.

You can also make your own registry entries to create application to file extension relations. The example shows how to register the .dvi extensions to be opened with the yap.exe program.

Link the extension .dvi to the DVI.Document class:

Key:   HKLM\SOFTWARE\Classes\.dvi
Value: <default> = "DVI.Document"

Describe the DVI.Document class:

Key:   HKLM\SOFTWARE\Classes\DVI.Document
Value: <default> = "DVI Document"

Select Icon #0 from yap.exe which is in the MSI:

Key:   HKLM\SOFTWARE\Classes\DVI.Document\DefaultIcon
Value: <default> = "[!yap.exe],0"

How to open the .dvi file if it is double clicked in the Explorer:

Key:   HKLM\SOFTWARE\Classes\DVI.Document\shell\open\command
Value: <default> = "[!yap.exe]" "%1"

Path without a Path

Windows can find your application even when it is not registered in the path, you just have to add some registry keys in the appropriate places.

The Registry contains a list of 'well known' applications under: HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths

Example:

Key:    HKLM\SOFTWARE\Microsoft\Windows\ 
              CurrentVersion\App Paths\gvim.exe

Values: <No Name>   = [!gvim.exe]
        Path        = [$gvim.exe] ( will add the directory where
                                    gvim.exe is stored to the
                                    Path env. var of this app. )

Selecting the Proper Keypath

Each component in an MSI requires a Keypath. This is one file or registry entry which is marked as the key element of the component. The Windows Installer Service seems to verify the availability of the keypath element on occasion. If it has changed it will be reinstalled from the msi. If you have components which install files in the Users Area (eg Application Data) make sure you set the keypath to a Registry Entry in the same component and not to the file. The user or an application could modify or remove the file which would trigger unwanted activity with the Installer.

Setting the PATH

It is possible to add your application to the PATH variable by adding an environment section to one of the application components. If you configure this appropriately you can have the new PATH element added to an already existing PATH. This works quite well. Mind you though do not select the Set on Install and Remove on Uninstall function. This has the unfortunate effect of removing the PATH variable altogether upon uninstall. Use the Create Value on Install function instead. This will not remove the PATH when you uninstall, but this is less tragic than loosing the PATH entirely.

Use one Feature and not many

Unless you know what you are doing refrain from creating packages with multiple features. When you do capturing with Wise you will end up with packages that do have multiple features (one for each shortcut). This is bad, because normally the application will not work unless it is completely installed. But the windows installer assumes that a feature on its own can work as well. As long as you stay on one machine this has all no effect. But when you roam and use advertising to get the application installed on your new workstation, only the features will get installed which are linked to the particular icon in the Start menu you have clicked.

The most simple way for turning your package into a single feature package is to go into Setup Editor->Tables view and edit the Components table and assign all components to the Complete feature. In the Shortcuts table there are also links you have to adjust.

The Home-Directory

Our windows setup makes the users home directory available under the drive letter W:. This has the advantage, that we can get some applications to work even though they want an absolute path to store their configuration ... Netscape 4 is such a case. In order to not spread the specific drive letter all across the package, it is sensible to create a special Property for this. Go into the Setup Editor tab:

• Create a Property called HOME and set it's value to W:\
  
• In the Shortcut Table set the WkDir of the shortcut to HOME
  
• In other places use [HOME] instead of W:
  

The notorious HKEY_CLASSES_ROOT registry section

The HKEY_CLASSES_ROOT section of the registry does not actually exits. It is a merge between HKLM/Software/Classes and HKCU/Software/Classes. This merging works on a key by key basis. If a key exists in both HKLM/Software/Classes and HKCU/Software/Classes, the key in HKCU will override the key in HKLM. Depending on the way you are installing an application (All Users / Current User Only) its keys will end up either in the user or in the machine part of the registry. When deploying applications via GPO this does apply too. User Assigned / Published applications end up in HKCU/Software/Classes. Machine assigned apps go into HKLM/Software/Classes.

Many programs try to add or edit values in keys under HKCR at runbtime. If they run with user privileges and the key is in HKLM/Software/Classes then this will not work as users have no right to edit keys there. The same is true if the application tries to create a new key under HKCR. Then windows seems to try to create this key under HKLM/Software/Classes which fails. If on the other hand, the key exists in HKCU/Software/Classes, and the application tries to write to it even when it goes to HKCR.

When creating MSIs, I suggest to keep all HKCR entries which are relevant for the user of the application under HKCU/Software/Classes and only the bits which are required by drivers and services under HKLM/Software/Classes. You can move entries around by editing the registry table in Wise. In this way, when a user launches an application for the first time (though its advertised icon) all necessary entries in his HKCU/Software/Classes will get created and if the application later tries to edit HKCR there will be no problems. Otherwise applications which get machine assigned will have all their registry entries in HKLM/Software/Classes.

Note: If the registry settings should be available to a system service (eg. the printer spooler), they must be in HKLM/Software/Classes. If Registry entries are written to HKCR they may go to HKCU/Software/Classes when the package is installed by a User and will thus not be available to the printing system.

HKCU/Software/Classes and Roaming.

Even with roaming enabled the contents of HKCU/Software/Classes does not to roam. This is because its contents is stored in \Documents and Settings\USERNAME\Local Settings\Application Data\Microsoft\Windows\UsrClass.dat, a registry file which does not roam. This means when you have the system delete local profiles on logout all these settings in this region will be gone, once the user logs off. In other words don't do it, or else users will see installers popping up whenever they start applications for the first time after logging in if the application has any entries in HKCU/Software/Classes.

Hardware Check

When capturing a package, wise gives you the option to check for hardware changes. Use this function if you want to capture things like the installation of printer drivers or other hardware related component. Otherwise these things will not get noticed by wise.

Less is more for Complex Packages

Wise for Windows installer tries to add all sorts of Self Registration and Advertising stuff to captured MSIs in an attempt to automagically produce fully compliant MSIs. It seems though that it sometimes fails to do this properly. So if you have trouble capturing a package, go into the Options setup Panel of The Wise installer (Prior to starting any Capturing) and DISABLE the Automatically Add Advertising function and maybe even the automatically add self registration settings.

The capturing should now result in a less complex MSI. It should nevertheless still contains all the necessary registry settings, as the original setup program will have created them and the capturing process will have stored them in the MSI.

Modifying Directory and Registry ACLs

Some packages can only work when they are allowed to write into protected files/directories or registry keys. Modifying ACLs permissions supported in MSIs through the LockPermissions table.

Since Wise for Windows Installer Version 3.5 there is even a GUI interface for setting up permissions.

For directories you can do it manually. It is necessary that the directories exist in CreateFolders table. To set registry key permission you can create a blank value with the name + (this means the registry key will be created during installation) and set permissions for that value.

It looks simple, but there are a few things you should observe:

The right users

Use builtin\Users and builtin\Administrators for the User column and leave the Domain column empty. If you pick a user which does not exist or one the Installer does not know, then the installation will fail with a friendly error message: "1332".

ACLS get overridden

Even though the official MSI documentation claims that the installer will add ACLS from the MSI into existing ones, it is likely that your file will end up only getting ACLS for SYSTEM and the users you have explicitly specified. This means that it is a good idea to specify at least ACLS for Users and Administrators.

It is possible to run an external program to set ACLS where necessary. Initially we created a visual basic script which can modify the ACLs using functions from two special dlls available from Microsoft. In the meantime we found the much superior SetACL tool to solve this problem: http://setacl.sourceforge.net/.

Cut your Losses

When repackaging complex applications, you may find yourself in a situation where certain thing with your MSI do not work. You get Internal Error messages when you try to install the MSI, or everything appears to work, but the items in the Start menu come without Icons, the possibilities are endless. Often Wise can help you if you go into the Setup Editor screen and look at the components and tables tab. Both will show you where there are problems in your msi when you press [F4]. There is also a Wizard for testing MSI consistency.

All said, at the end of the day, your MSI may still be broken and Wise does not tell you why. In these cases I found that the quickest way to create a new MSI. And just add all the necessary files by hand. For the registry entries you can cut and paste from the broken MSI (you will have to adjust the component association for the registry entries, but this quite easy. As for the other elements of your average repackaged application they can also be copied by going to their respective table. The whole operation is a surprisingly quick and has helped me repeatedly in getting out of seemingly hopeless MSI debug sessions.

Automating MSI Creation

So if you have to package the same application twice or if you want to be really sure packaging happens the way you want, check out http://users.cyberone.com.au/dbareis/ Dennis Bareis. This does just use base Windows Installer functionality, so you do not need Wise or anything like it installed. Another option is to work with Microsoft's very own Windows Installer XML (WiX) toolset http://sourceforge.net/projects/wix/

Stub MSI

Some applications is not possible to pack or at least not in reasonable amount of time. In that case I use custom action which installs setup.exe or MSI.exe (application which are originally MSIs, like Adobe Photoshop, Corel DRAW, but are not working properly if you put them directly in Active Directory, or it is even not possible to place them there). In that case MSI will have one install.bat file which is going to install package with command line: msiexec /i package option. Here there is one small problem, that is you are not able to run 2 installations at the same time. Therefore you need to click OK in order to continue installation which is given in your install.bat file. For these purposes you can use Autoit (http://www.autoitscript.com/AutoIt/downloads.php) script which will click OK button instead of user. For just OK click it will look something like this:

;Click OK for installing Corel 12
WinWait ( "CorelDRAW 12.0", "CorelDRAW 12.0 Setup completed" )
WinActivate ( "CorelDRAW 12.0", "CorelDRAW 12.0 Setup completed" )
Send("{ENTER}")
EXIT

Since this is not real MSI user can not uninstall it. By uninstalling will be removed only the install.bat file. That is why in this case there is a need for removal tool which will the same way with custom action and command line in remove.bat: msiexec /x package option uninstall the application.