NetInverse Developers Blog

If your MSI doesn’t work properly, how do you troubleshoot? The easiest way is to turn on tracing to get the setup log file. The command line is:

            msiexec /i product.msi /L*v log.txt

‘L’ means generating a log file; ‘v’ means verbose. Open log.txt file, you can see detailed information of the setup process. For example, if you run product.msi like below:

            msiexec /i product.msi MYPARAM=cool /l*v "c:log.txt"

Open log.txt, you will see MYPARAM has been added to the properties:

     MSI (c) (D8:58) [01:12:36:093]: PROPERTY CHANGE: Adding MYPARAM property. Its value is 'cool'.
     ...
     Property(S): MYPARAM = cool

For detailed command line options of msiexec, you can check out MSDN.

This simple WiX tutorial teaches you how to use Windows Installer XML(WiX) to create an installer MSI from scratch.

1. Download Windows Installer XML Toolset

WiX is an open source project, originally developed by Microsoft. You can download the binary and source code from Sourceforge. Navigate to http://sourceforge.net/projects/wix.

• Download the latest WiX toolset binary and source code package.
• Create a folder on your local driver, like c:\WiX.
• Unzip the downloaded file into the folder you just created: c:\WiX.
• Go to c:\WiX, you will see WiX compiler: candle.exe, WiX linker: light.exe, and some other files.
• Refer to the WiX.chm for WiX Schema, help and documentations.

Take a look at the available elements from the WiX schema in the WiX Help file (under the WiX Help | Authoring | Wix Schema node). As you can see, with over 230 elements available, there is some complexity associated with creating installers. The good news is that you typically only need to use a small subset of these elements when creating an installer.

2. Create Your First WiX File

Create an xml file: product.wxs (copied from wix.chm)  as below
This WiX file will create an MSI file to copy readme.txt into %sysdrv%/program files/test program/

<?xml version='1.0'?>
<WiX xmlns='http://schemas.microsoft.com/wix/2003/01/wi'>
   <Product Id='12345678-1234-1234-1234-123456789012' Name='Test Package' Language='1033'
            Version='1.0.0.0' Manufacturer='Microsoft Corporation'>
      <Package Id='12345678-1234-1234-1234-123456789012'
                Description='My first Windows Installer package'
                Comments='This is my first attempt at creating a Windows Installer database'
                Manufacturer='Microsoft Corporation' InstallerVersion='200' Compressed='yes' />

      <Media Id='1' Cabinet='product.cab' EmbedCab='yes' />

      <Directory Id='TARGETDIR' Name='SourceDir'>
         <Directory Id='ProgramFilesFolder' Name='PFiles'>
            <Directory Id='MyDir' Name='TestProg' LongName='Test Program'>
               <Component Id='MyComponent' Guid='12345678-1234-1234-1234-123456789012'>
                  <File Id='readme' Name='readme.txt' DiskId='1' src='readme.txt' />
               </Component>
            </Directory>
         </Directory>
      </Directory>

      <Feature Id='MyFeature' Title='My 1st Feature' Level='1'>
         <ComponentRef Id='MyComponent' />
      </Feature>
   </Product>
</WiX>

3. Play It with Candle and Light

Candle is the compiler used to compile the XML documents to object files that contain symbols and references to symbols. Light is a linker takes one or more object files and links the references in the object files to the appropriate symbols in other object files. Light is also responsible for collecting all of the binaries, packaging them appropriately, and generating the final MSI or MSM file.

Now you can compile and link your WiX file.

1. Compile it with WiX compiler - Candle:

   c:\WiX\candle product.wxs

2. Link wixobj with WiX Linker - Light:

   c:\WiX\light product.wixobj

3. Test your first MSI:

   c:\WiX\msiexec /i product.msi

Microsoft Installer, an installer system written by Microsoft for Windows platforms.

MSI files are basically relational database files that contain all the information that the Windows Installer requires to install or uninstall an application and to run the setup user interface. Installation packages are organized like the diagram above. Each package has one or more independent features. Each feature can have one or more components. The installer always installs or removes a component from a user’s computer as a coherent piece. A component can be a single file, or a group of files, a registry setting, COM objects, resources, etc.

Installation Mechanism

There are two phases to a successful installation process: acquisition and execution. If the installation is unsuccessful, a rollback phase may occur.

Acquisition

At the beginning of the acquisition phase, an application or a user instructs the installer to install a feature or an application. The installer then progresses through the actions specified in the sequence tables of the installation database. These actions query the installation database and generate a script that gives a step-by-step procedure for performing the installation.

Execution

During the execution phase, the installer passes the information to a process with elevated privileges and runs the script.

Rollback

If an installation is unsuccessful, the installer restores the original state of the computer. When the installer processes the installation script it simultaneously generates a rollback script. In addition to the rollback script, the installer saves a copy of every file it deletes during the installation. These files are kept in a hidden, system directory. Once the installation is complete, the rollback script and the saved files are deleted. For more information, see Rollback Installation.

Some Other MSI Related Links

The Windows Installer XML toolset (WiX) is a free, open-source toolset that builds Windows Installer (MSI) packages from an XML document. It supports a command-line environment that developers may integrate into their build processes to build MSI and MSM setup packages. This software is released by Microsoft under an open-source license called Common Public License.

On April 5, 2004, WiX was the first Microsoft project to be released under an externally created Open Source licence, the Common Public License. It was also the first Microsoft Shared Source project to be hosted externally on SourceForge.

Rob Mensching, the original author and lead developer of WiX, works on WiX in his spare time. You can read an introduction here: A live one hour Windows Installer XML introduction by Rob Mensching. As of 2006, several other Microsoft employees from various product divisions of the company work on WiX with Mensching, meeting after business hours once a week to co-ordinate development efforts and write code. WiX has proven to be so popular with Microsoft development teams that most of Microsoft’s software products are either already packaged using WiX (as is the case with SQL Server 2005), or will be for their next version (eg. Office 2007).

In a nutshell, to create MSI packages, you just need to create WiX XML files, and then simply run a few WiX tools to compile them to MSIs.

Benefits are: