Link to information about upgrading WiX v2.0 projects to WiX v3.0

  • Article

Now that WiX v3.0 has officially released, you may want to start looking at upgrading your existing setup authoring from WiX v2.0 to WiX v3.0 to take advantage of some of the new WiX v3.0 features.  There are some breaking changes in v3.0, so you cannot simply re-use the same WiX source files from v2.0 with the v3.0 toolset.  Fortunately, there is a tool named WixCop in the WiX v3.0 toolset that will allow you to migrate v2.0 .wxs files to v3.0.

Rob Mensching wrote a helpful post on his blog last week that introduces WixCop and explains steps that you can use to run WixCop and then update your build scripts to pass in the new WiX extensions that were added in WiX v3.0 so your builds will work correctly.

You can find Rob’s blog post at https://robmensching.com/blog/posts/2009/7/7/Tips-on-how-to-upgrade-from-WiX-v2-to-WiX-v3.  If you’ve got a WiX v2.0 project that you’re planning to upgrade to WiX v3.0, I encourage you to take a look at Rob’s blog post before you get started with the upgrade project because it will save you a lot of manual migration effort.

To summarize that blog post, there are 3 main migration steps:

  1. Run %ProgramFiles%\Windows Installer XML v3\bin\WixCop.exe -s –f *.wxs to convert your existing WiX v2.0 source files

    This step assumes that you have WiX v3.0 installed to the default path and that you are running from the directory that your WiX v2.0 source files are located.  You may need to adjust it as appropriate on your system.

  2. Add -ext command line switches and pass in the WiX v3.0 extensions used by your setup authoring when you run candle.exe and light.exe in your build process.

    The easiest way to figure out what extensions you need to pass in for your builds is to try to build and observe any errors you receive related to unhandled extension elements.

  3. If you use WixUI in your WiX v2.0 projects, update your light.exe command line to use the -ext command line switch to pass in the WixUIExtension instead of linking to wixui.wixlib.

There may be a few migration issues that are not handled by WixCop, but the above steps should get you most of the way there.  Hopefully, the error messages you encounter for any issues not handled by WixCop will be useful enough to lead you to the right solution.  If not, then the WiX user group is a great resource, and so is the WiX v3.0 documentation.