WiX goodies: WixCop

WixCop is a WiX v3 command-line tool that serves two main purposes:

• To upgrade WiX authoring to the current schema
• To format WiX authoring according to a set of common formatting

Upgrade your authoring

The biggest reason that WiX v3 is currently marked as “beta” is that the WiX source schema – the set of XML elements and attributes – changed quite a bit from v2 to v3 and we’re not 100 percent sure that we’re done making breaking changes. (In fact, I’d bet good money that we’re done making breaking changes but we might make some more backward-compatible tweaks to simplify common tasks, like we’ve done a few times before.)

Moving from WiX v2 to v3 is a mildly annoying prospect if you’ve done it manually. To avoid that hassle, WixCop was born.

Likewise, moving from early to recent v3 builds would expose the changing schema – especially early on in v3 development, when Derek was busily taking WiX apart and rebuilding it. So WixCop also knows how to translate various versions of the WiX v3 schema to the latest.

Format your authoring

As WiX authoring is plain ol’ XML, formatting it could be accomplished with any XML-savvy text editor. But integrating it into a tool like WixCop means you can automate the formatting, maybe even run it as part of a build. Having consistent formatting makes it easier to see substantive differences in your version control’s differ and, more importantly, minimize “bad merges” when you move setup authoring among the multiple branches in your version control system.

WixCop’s formatting capabilities include my favorite-ever error message:

x:\filename.wxs(17) : error WXCP0007 : The whitespace preceding this node is incorrect. (WhitespacePrecedingNodeWrong)

That’s right – whitespace can be incorrect. Luckily, the definition of incorrect is configurable.

WixCop reference

WixCop’s command-line syntax is:

WixCop.exe [options] sourceFile [sourceFile …]

WixCop takes any number of WiX source files as command-line arguments. Wildcards are permitted. WixCop supports response files containing options and source files, using @responseFile syntax.

WixCop returns the following exit codes:

• 0, when no errors are reported.
• 1, when a fatal error occurs.
• 2, when WixCop violations occur.

The following table describes the switches that WixCop supports.

WixCop settings files

WixCop supports two settings files. Generally, the primary settings file is your “global” settings and the alternate settings file lets you override the global settings for a particular project.

Settings files are XML with the following structure:

<Settings>
  <IgnoreErrors>
    <Test Id="testId" />
  </IgnoreErrors>

  <ErrorsAsWarnings>
    <Test Id="testId" />
  </ErrorsAsWarnings>

  <ExemptFiles>
    <File Name="foo.wxs" />
  </ExemptFiles>
</Settings>

The IgnoreErrors element lists test IDs that should be ignored. The ErrorsAsWarnings element lists test IDs that should be demoted from errors to warnings. The ExemptFiles element lists files that should be skipped.

The following table describes the tests that WixCop supports.