In this tutorial I am going to give an overview of a basic WIX project. I won't go into the compiling and linking however. For that information refer to the WiX site directly. Directly after this I will past the entire project that would be used to install an executable and it's resources in both English and German. This is going to be pretty bare bones (meant more as an introduction than as a template for use). After the code I will go through and explain what everything is doing.
<?xml version="1.0" encoding="UTF-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"> <Product Id="*" Name="Demo Project" Language="1033" Version="126.96.36.199" Manufacturer="Adkins-Software.com" UpgradeCode="af7a8797-0075-4ad0-9c7a-e53ed083eb99"> <Package Description="Demo Project Installer" InstallerVersion="405" Manufacturer="Adkins-Software.com" Compressed="yes" /> <Media Id="1" Cabinet="media1.cab" EmbedCab="yes" /> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFilesFolder"> <Directory Id="INSTALLDIR" Name="Demo"> <Component Id="MainExecutable" Guid="YOUR-GUID-HERE"> <File Id="MainExecutable" Name="Demo.exe" KeyPath="yes" Source="C:\VS Projs\Demo\bin\Release\Demo.exe" /> </Component> <Directory Id="en"> <Component Id="EnglishResource" Guid="YOUR-GUID-HERE"> <File Id="EnglishResource" Name="Demo.resource.dll" KeyPath="yes" Source="C:\VS Projs\Demo\bin\Release\en\Demo.resource.dll" /> </Component> </Directory> <Directory Id="de"> <Component Id="GermanResource" Guid="YOUR-GUID-HERE"> <File Id="GermanResource" Name="Demo.resource.dll" KeyPath="yes" Source="C:\VS Projs\Demo\bin\Release\de\Demo.resource.dll" /> </Component> </Directory> </Directory> </Directory> </Directory> <Feature Id="ProductFeature" Title="WixProject1" Level="1"> <ComponentRef Id="GermanResource"/> <ComponentRef Id="EnglishResource"/> <ComponentRef Id="MainExecutable"/> </Feature> </Product> </Wix>
That may seem like a lot just to install 3 files, but I assure you, most of it is just basic stuff that is required for every installation package. For my personal use, I have a template that takes care of all that for me so that I only have to worry about what I am trying to install and the registry settings ect. that is required for it. That is a different story though.
The first element that you will notice, after the XML declaration, is the Wix element. This is used so that the compiler knows where to start. The only namespace that is included with this project is the basic WiX namespace. Nothing fancy here so no need for any of the other namespaces that are available for more advanced functionality.
The next element to pop up is the Product element. This tells the compiler that you are creating a source file for a product, not for a merge module, an include, localization, or a fragment. This is used 90% of the time anyways, and the best place to start learning as it gives you a complete MSI when finished. This element has several attributes:
- Id: this is a GUID that will describe this version of this product. I have left as a wild card, because a new GUID is needed for each new version in order for an upgrade to work. This wild card tells the compiler to dynamically create a GUID when this package is compiled.
- Name: The name of the product to be installed.
- Language: The language that this product is. This is a required attribute, and is normally used to show the default language.
- Version: The version of the product that is included in this package.
- Manufacturer: The manufacturer of the product you are installing.
- UpgradeCode: The upgrade code. This will never change for this product line.
One point that I need to reiterate from the list is the GUID's. The Product ID is the GUID for this particular release of the product. If you want an upgrade to work, then the new version needs a new ID. The Upgrade Code on the other hand is how Windows Installer knows that an upgrade is needed. This value is normally left the same so that an upgrade will work no matter how old the other version is. I will do another tutorial later on about how to do an upgrade, but this is still a good thing to have whether you plan on doing upgrades or not.
The next element is the Package element. This element has details about the MSI itself rather than the product that is contained within it.
- Description: A description of the package. My personal default for this is the product name plus "Installer" or "Setup".
- InstallerVersion: This is the minimum version of Windows Installer that is needed to install this package. I picked version 4.5 just to make a point. The version is listed as a 3 digit number. The first place is the main version number for Windows Installer. The next two are the used for the minor part of the version number. It is explained as the major part times 100 plus the minor part.
- Manufacturer: This is the manufacturer of the MSI package itself. This is not required, but can be added none the less.
- Compressed: This states whether or not compressed files are included in the MSI. It defaults to yes, and I have found no benefit in setting it to no.
The Media element I will describe in a later tutorial, but just take not that it is there for all your packages. There has to be at least one, but there can be several more.
The Directory elements represent directories on the machine after the product has been installed. If a directory element is nested inside another, that means that the child directory will be installed in the parent element. In my example above you will see that "en" is located under "INSTALLDIR". That means that the "en" folder will be created in the INSTALLDIR and along with it's contents.
INSTALLDIR and TARGETDIR are two of many predefined variables that are available in WiX. INSTALLDIR refers to the location that the product will be installed to and TARGETDIR refers to the the drive that it will be installed to (C: or D:). ProgramFilesFolder is another keyword that is used with directories. It refers to the Program Files folder (32bit). There are several of these keywords that are used as ID's to target specific windows folders. StartMenuFolder and WindowsFolder are two more that are seen relatively often.
The component element, at its most basic, is simple to understand. It needs an Id that is unique among components, and it needs a Guid that is unique among Guids. Explaining this in more detail would require a lesson in Windows Installer technology that would go outside the realm of this intro tutorial, but if there is an interest I can do that in another tutorial.
Next comes the File elements. These elements have a lot of different attributes that can be set. I have used just a few to show what is best to include. As with (almost) all elements in WiX each one needs a unique Id among its peers. The file and components can have the same Id, it only matters that each Id is only used once per element type. Next comes the name attribute, which states the name of the file once it is installed on the clients machine. The KeyPath attribute means that in order for this component to be successfully installed, this element needs to be successfully installed. Also this element will be used to check for an update. If it doesn't change nothing that is included in the component will be changed. That is why the standard of one file per component is so important in this new age of installers.
The last two elements that you will find in the sample code are Feature and ComponentRef. The first (Feature) is used to group together files that fit together. A feature is a sub section of the program that can be chosen from a GUI or the command line for installation. In order for this feature to be useful you have to tell it what to install if it is selected. That is what the ComponentRef is used for. It is simply a reference to a component that is included with this feature.
I think I have covered all the important concepts for a bare bones WiX installer. If you are interested in more of these tutorials let me know (along with a specific topic if known) and I will see what I can do.