Tips on how to upgrade from WiX v2 to WiX v3.

Code Migration via WixCop.exe

There are a number of changes to the WiX language (the wix.xsd) in v3. Our goal was to reduce duplication in the language and generally make it easier to work with. Of course, we know that language changes make the migration process very difficult for you. So we created a tool called WixCop that will fix your .wxs files.

WixCop.exe is very easy to use. Just give it the file you want updated. If you want WixCop to fix the file for you then add the “-f” switch. If you want WixCop to fix all of your files in the directory then use a wildcard like “*.wxs”. If you want WixCop to fix all of your files in all of your directories add the “-s” switch.

For example, to fix an entire tree of .wxs source code then check out the files and run the following command:

C:\src> WixCop.exe -s -f *.wxs

It is very likely that if you try to compile now things will fail with errors like “The Component element contains an unhandled extension element ‘util:XmlFile’. Please ensure that the extension for elements in the http://schemas.microsoft.com/wix/UtilExtension namespace has been provided.” That brings us to the second second new WiX v3 concept.

Extension to the Windows Installer

The WiX toolset provides a library of custom actions that extend the Windows Installer to support things like IIS Web Sites, SQL Server databases, file shares and many other things. In WiX v2 those elements are part of the wix.xsd. That made it very difficult to tell what functionality was natively supported by the Windows Installer and what functionality came from custom actions.

In WiX v3 we separated all of the non-native functionality into separate XML namespaces so there would be no confusion. Then we created “extensions” that plug into the compiler and linker to parse the elements in the other namespaces and incorporate the required custom actions. In WiX v2 you were used to providing .wixlibs to the linker for the custom actions, extensions take care of all of that for you.

Using the same example from above, the error mentions that we need the extension that supports the “wix/UtilExtension”. We call that the “WiX Util Extension” and you refer to it on both your compile and link lines like so:

C:\src> candle.exe my.wxs -ext WixUtilExtension
C:\src> light.exe my.wixobj -ext WixUtilExtension

The “-ext” switch looks for the WixUtilExtension.dll in the same directory as the compiler and loads it. The extension takes care of the rest of the work.

Extensions as the new UI

One last thing. The WiX v2 UI .wixlibs and .wxl files are now all part of the WiXUIExtension. That means you just need to reference the new UI extension. Below compares the how to use WiX v2 to link in WiX UI the how to do the same with WiX v3:

C:\src> C:\path\to\wixv2\light.exe my.wixobj %WIXUI_PATH%\wixui.wixlib
                                   -loc %WIXUI_PATH%\WixUI_en-us.wxl

C:\src> C:\path\to\wixv3\light.exe my.wixobj -ext WixUIExtension

If you have any other questions about the examples above, please read through the WiX v3 Manual. If you find other things that aren’t migrating well, drop me a note and I’ll figure out the necessary changes. Good luck with WiX v3!