Creating a Simple Setup

The goal of this tutorial is to help you to get familiar with WiX and the fundmental building blocks in order to build a simple installable .msi package using WiX. We will start with the basic WiX code to create an .msi package that installs one file.

Step 1: Create the WiX source file

To get started, pick your favorite XML editor (such as Notepad or Visual Studio) and create a new file called product.wxs. Nothing about that name is special, but the .wxs extension lets us know that this is a Windows Installer XML source file. Next, add the three lines of text that all .wxs files must contain:

<?xml version='1.0'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
</Wix>

That forms the outer skeleton for our source file. Save the file in the same directory as where the WiX tools are installed (e.g. C:\test).

Step 2: Author the content of the package

Okay, now that we've created an empty source file, let's create an installable Windows Installer package. Add the following content to your product.wxs file:

<?xml version='1.0'?>
<Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
   <Product Id='PUT-GUID-HERE' Name='Test Package' Language='1033' 
            Version='1.0.0.0' Manufacturer='Microsoft Corporation' UpgradeCode='PUT-GUID-HERE' >
      <Package 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' />

      <Directory Id='TARGETDIR' Name='SourceDir'>
         <Component Id='MyComponent' Guid='PUT-GUID-HERE' />
      </Directory>
      <Feature Id='MyFeature' Title='My 1st Feature' Level='1'>
         <ComponentRef Id='MyComponent' />
      </Feature>
   </Product>
</Wix>

Replace PUT-GUID-HERE with a GUID value. This will allow you to create an .msi with a ProductCode of "{PUT-GUID-HERE}" with a ProductLanguage of "1033" and a ProductVersion of "1.0.0.0". All of that information is taken from the <Product> element. The <Package> element defines all of the information that goes in our .msi's summary information stream. Finally, a simple <Directory> and <Feature> tree is created with a single <Component>. This is enough to get our .msi registered on the machine.

Step 3: Adding a file to the package

Now that we have the directory authored, let's put a file in the folder. Create a new text file called readme.txt in the same directory as the product.wxs file and type a message such as "Hello, World!" in the file. Then, we need to modify product.wxs to tell it about the file:

<?xml version='1.0'?><Wix xmlns='http://schemas.microsoft.com/wix/2006/wi'>
   <Product Id='PUT-GUID-HERE' Name='Test Package' Language='1033'
            Version='1.0.0.0' Manufacturer='Microsoft Corporation' UpgradeCode='PUT-GUID-HERE'>
      <Package 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='Test Program'>
               <Component Id='MyComponent' Guid='PUT-GUID-HERE'>
                  <File Id='readme' Name='readme.txt' DiskId='1' Source='readme.txt' />
               </Component>
            </Directory>
         </Directory>
      </Directory>
 
      <Feature Id='MyFeature' Title='My 1st Feature' Level='1'>
         <ComponentRef Id='MyComponent' />
      </Feature>
   </Product>
</Wix>

Step 4: Build the package

Now let's build the package using the following instructions:

C:\test> candle product.wxs
Microsoft (R) Windows Installer Xml Compiler version 1.0.1220.15022
Copyright (C) Microsoft Corporation 2003. All rights reserved
 
product.wxs
 
C:\test> light product.wixobj
Microsoft (R) Windows Installer Xml Linker version 1.0.1220.15022
Copyright (C) Microsoft Corporation 2003. All rights reserved

Step 5: Verify the package

We can now try installing the resulting package and look at the result. Note that msi packages requires administrative privileges in order to install correctly. If will fail silently if you are not installing as an Administrator.

 C:\test> msiexec /i product.msi

You can now go to Add/Remove Programs in the Control Panel and see "Test Package" listed there. You can also see that it creates a directory called "Test Program" in your system's "Program Files" folder. The file readme.txt will be installed in the "Test Program" directory. After verifying that installation works as expected, remember to uninstall the .msi so you can rebuild it and install a new version again later.

That's all there is to creating a Windows Installer package. You can do many more advanced things, such as adding setup UI to your .msi, but we've covered the basics. Everything just comes down to filling in the right XML elements.