I’m writing a couple of posts that talk about how to use the WiX source repository to view, modify, and patch the WiX source code.

Getting WiX source code

Getting WiX source code out of Mercurial is straightforward using TortoiseHg:

1. Install TortoiseHg.
2. Use Explorer to create a directory where you want to store the source code. I used “wix” in the root of my X: drive.
3. Right-click the directory you created in step 2 and choose TortoiseHg|Clone.
4. In Source path, enter https://hg01.codeplex.com/wix. That’s the Mercurial clone URL, provided by Codeplex. You can see it for your self by going to https://wix.codeplex.com/ then clicking the Source Code tab and clicking Mercurial in the Source Control Setup box in the right bar.

   

5. Click Clone. TortoiseHg will fetch many “chunks” from Codeplex. It’ll take a while, depending on your Internet connection speed.

Your patience is rewarded with a directory that contains one subdirectory and two files (at least as of today). Huh? All you’ve done so far is cloned the WiX Mercurial repository. Next up is updating your working directory with a particular revision of that repository. (The default branch in the WiX repository contains no interesting files; all past and active development is happening on the named branches wix20, wix30, and wix35, shown below in green.)

1. Right-click the directory you created in step 2 and choose Hg Repository Explorer. You’ll get a window that contains the changes that have been committed to the Mercurial repository.

   

2. Right-click the line representing the version you’re interested in and choose Update. To get the latest version, look toward the top for the version with the yellow “tip” box.
3. Click Update to get the version you selected.

   

The directory now contains a WiX source enlistment. Up next: creating patches against a clone of the official repository.

One issue has come up, however: Build failures with customized dialog sets. Fragments that define dialog sets need to include all the UI elements, properties, and WiX bind-time variables used by the dialogs in that set. By referring to the WixUICostingPopupOptOut WiX variable from the individual dialogs, custom dialog sets must also provide a value. You can provide a value for WixUICostingPopupOptOut anywhere in your project but the easiest is to do so in the same fragment with your dialog set. Just add this line:

<WixVariable Id="WixUICostingPopupOptOut" Value="1" Overridable="yes" />

So it’s time to make an guess. Let’s call it an educated guess but as I can’t reproduce the problem, I’m not sure it’s entirely educated.

Coming in the next weekly release of WiX is a mechanism to opt out of the costing popup dialog. And although it’s an opt-out mechanism, for now it’s opted-in by default. The idea is to see quickly if the change fixes the problem. If it does, we’ll keep the opt-in default for WiX v3.5. If not, we can either back out the change or just change the default to opt-out.

So what’s the change? Before, all the dialogs that initiated an install transaction used a SpawnWaitDialog control event with a condition of CostingComplete=1. The dialog would pop up until the condition was met. Now, the condition includes the bind-time WiX variable WixUICostingPopupOptOut. WixUICostingPopupOptOut defaults to 1, so the condition is always true and the popup never appears.

You can override WixUICostingPopupOptOut in your project with a value of 0 to return to the previous behavior:

<WixVariable Id="WixUICostingPopupOptOut" Value="0" />

So, please grab the next release of WiX and try out your previously problematic installers. We want to fix this problem before we start locking down WiX v3.5 for RTM.

Update: You can get the weekly release here.

• Some attributes are optional, really. Rob and I have blogged before about the language enhancements sneaking into WiX v3.5. Those enhancements focus on simplifying authoring, by collapsing elements (MajorUpgrade) or providing smart attributes (Component). I suspect many people rely on IntelliSense in Visual Studio when authoring their WiX source files. IntelliSense is pretty close to sliced bread on the greatness scale of inventions, but it has a significant downside in the current implementation in Votive: It lists all possible elements and attributes in the WiX schema, with no “intelligence” behind which are most important. So you get the positive IntelliSense feedback of providing values for every attribute. It’s addicting but you can fight it. (To be fair to IntelliSense, it’s just using the default XSD schema support in the XML language service; if someone were to add a WiX language service to Votive, IntelliSense could be much better.)
• Manually marking package and component bitness. MSI doesn’t support platform-neutral packages or components: They’re either 32-bit (x86) or 64-bit (x64 or IA64). In your authoring, you can specify a package’s platform using the Package/@Platform attribute. Components are 32-bit by default; you can specify that they’re 64-bit by specifying “yes” as the Component/@Win64 attribute value. In a package full of 64-bit components, you have to specify @Win64=”yes” for every component. It’s typical to want to produce both 32-bit and 64-bit packages from the same WiX source, so a common approach is to make the @Win64 attribute value a preprocessor variable. Or, just let WiX handle it for you: Specify the –arch switch at the candle.exe command line or the <InstallerPlatform> property in a .wixproj MSBuild project. When you specify x64 or intel64, Candle automatically sets the package and components in the file being compiled as 64-bit. It’s still useful to be able to say “Win64=’no’” for those components that are 32-bit even in 64-bit packages. Of course, that’s also legal in 32-bit packages, so it’s safe to hard-code.
• Unnecessarily nuking registry keys. The RegistryKey/@Action attribute lets you specify some of the “special” Registry table functionality that MSI supports. Specifying create lets you create an empty registry key; createAndRemoveOnUninstall tells MSI to delete the key and all values during uninstall. That’s useful functionality if your application creates additional values at runtime—but for per-machine registry keys (under HKEY_LOCAL_MACHINE) most apps don’t create additional values because it would require elevation. (The not-quite invisible hand of UAC gently guides developers toward good app behavior.) If you omit the @Action attribute or specify none, MSI will still delete the registry key if it deletes all the values in it (and so on, recursively down the registry key hierarchy). That’s the default; you don’t have to ask MSI to remove the registry entries it writes. So if you need to nuke your keys, go ahead, but otherwise, don’t bother.

By the way, all of these things work in WiX v3.0 rtm.

Here’s the problem: I don’t think it’s a bug in WiX or WixUI. MSI owns the costing process and as costing works almost all the time, there isn’t a simple answer like “oh yeah, a rich-edit control on the first dialog breaks costing.” I suspect that there’s a bug in MSI but before I go to the MSI team, bug in hand, I need more data. Here’s where you come in: Help us gather more data to narrow down the bug.

1. Logs. It’s a reflexive request that verbose MSI logs are a vital part of figuring out any setup bug. In this case, they might not be that helpful, as the logs I’ve seen, including those attached to the bug, just show a lot of time passing between log entries.
2. OS version. Which version of the OS? Which edition? x86 or x64? Which service pack?
3. Virtuality. Does the bug occur in virtual machines or on “real” machines? Which virtual machine technology (e.g., Virtual PC, Hyper-V, VMware, VirtualBox)?
4. MSI version. If it is a bug in MSI, narrowing down which versions are afflicted the worst would be key. (For example, I’ve never seen the bug occur on MSI 5.0 in Windows 7.)
5. Frequency. How often does the bug occur?
6. .msi package data. How big? How many files? How many components?
7. WiX and WixUI data. Which version of WiX are you using? Which WixUI dialog set? How have you customized it?
8. Packages. If you can provide packages that demonstrate the problem, please do so. Obviously, you might not be able to share your actual package content but does the bug still reproduce if you replace your actual files with zero-byte replacements?

If you’ve seen this problem, please help: Add your comments to the bug on SourceForge and attach your logs and packages.

Help us WiX community, you’re our only hope.

Update, 5 April 2010: Added Virtuality – I got a report that the bug occurs most often on Virtual PC virtual machines and it seems to be a common issue on various blogs.

One of the challenges of developing data-driven custom actions is testing all the combinations of state that affect the custom action data immediate custom actions pass to deferred and rollback custom actions. Because Lux test packages don’t modify the machine, testing the full set of possible states is difficult. Providing known state is a strength of traditional unit-testing techniques, however; if your custom action code is well factored, it should be a simple task to provide a test double that arranges hard-coded state information that you can then test against.

Naturally, I wanted to figure out how I could provide the best of both worlds in Lux. Here’s what I came up with: test mutations. From the doc:

Test mutations let you author unit tests with different expected results. The mutation id is passed as the value of the WIXLUX_RUNNING_MUTATION property. Your custom action, typically in an ‘#ifdef DEBUG’ block, retrieves the WIXLUX_RUNNING_MUTATION property and mock different behavior based on the mutation. To author test mutations, use the Mutation element with UnitTest elements as children. For example:

<lux:Mutation Id="SimulateDiskFull">
  <lux:UnitTest … />
</lux:Mutation>

Nit runs the test package once for each mutation, setting the WIXLUX_RUNNING_MUTATION property to one mutation id at a time. Tests that aren’t children of a mutation are run every time.

Test mutations are a fairly simple change but one I hope simplifies combining traditional unit-testing techniques with declarative assertions.

Lux’s test mutations will ship in the next weekly release of WiX.

Creating the x64 .msi package isn’t a huge burden on us but it’s led to some confusion, so we’d like to get rid of it. If you use 64-bit MSBuild 2.0 and the x64 WiX .msi package, please respond in the comments. If you use MSBuild 3.5 or the .zip WiX package or by checking WiX in to your source-control system, you’re not affected and can use the x86 WiX .msi package.

1. The v3.0 schema was changing routinely. Going months between picking up new builds would expose bigger, possibly backward-incompatible changes. New builds once a month limited a team’s exposure to whatever we could do in four weeks.
2. When you need a bug fix, you want as small a fix as possible. Bug fixes came frequently throughout the toolset so the longer between builds, the more churn a team would pick up. That complicates validating the packages produced by a new WiX build.
3. Output changes could complicate (or break) patching. Changes in the things WiX writes to MSI tables affect your ability to create patches. The rules governing patches are a superset of the dread component rules, adding rules about changes that make patches not uninstallable.

In effect, you increase stability by taking smaller changes at any one time.

For WiX v3.5, reason #1 doesn’t apply: We aren’t making any backward-incompatible schema changes though we’re making additive changes to simplify authoring. Reasons #2 and #3 still apply—and keep applying.

Long-term relationships

Eventually there comes a time in every project’s life to settle down in a committed relationship. For WiX users, that time is when you’re nearing a release that you intend to service. It might be a public beta, it might be RTM, it might be a weekly release of your Web app. If you intend to service it, especially with patches, you want the stability of a known build of WiX—Reason #3 applies in earnest when you start servicing.

New product releases can pick up new versions of WiX, but on the source-control branch you’re using to service old releases, stick with one version of WiX. We encourage teams to ship products using the released, RTM builds of WiX. So far, we haven’t released a service pack for WiX, but it’s safe to assume we wouldn’t include any changes in one that broke patching.

Youthful indiscretions

I was reminded of reason #3 today: Bug 2965405 demonstrated a hole in the logic that generates default component ids. The fix is simple: give a better default id used in constructing the stable short filename. Unfortunately, it changes every short filename that’s generated when you omit the Component/@Id attribute and the filename doesn’t fit within the 8.3 short filename syntax. Fixing the bug would complicate patching from prior builds of WiX v3.5.

As WiX v3.5 hasn’t even gone to beta yet, I believe we should fix the bug even with the patching problem it introduces. Other folks on the WiX Virtual Team will get to weigh in, as can you by commenting below.

The latest release of Mercurial and TortoiseHg, a set of Windows shell extensions and GUI tools for Mercurial, was just released. This latest version (v1.5 and v1.0, respectively) includes both tools integrated into an MSI installer built with WiX. Previous versions were built with (the excellent but non-MSI-based) Inno Setup toolset. The WiX-based installer has the advantage of using a merge module for TortoiseOverlays (login as guest with an empty password), an icon overlay handler shared by shell extensions for several different version control systems: TortoiseHg for Mercurial, TortoiseSVN for Subversion, TortoiseCVS for CVS, TortoiseBZR for Bazaar, TortoiseGit for Git, and probably others.

As usual, I opened the TortoiseHg .msi in Orca before installing it on my workstation. I was pleasantly surprised by the low number of custom actions. I ran it through WiX v3.0’s Smoke.exe to run ICE validation; there were lots of errors and warnings but all but a few were from TortoiseHg’s use of the Visual C++ runtime libraries merge modules. (Is it ironic or just plain sad that they have so many ICE errors? Maybe both.)

Though we don’t use Mercurial for WiX version control—yet, anyway—both SourceForge.net and Codeplex support Mercurial for a project’s VCS.

• Read the Mercurial v1.5 release notes.
• Read the TortoiseHg v1.0 release notes.
• Download the combined Mercurial and TortoiseHg installer.

Unit-testing custom actions with Lux

Custom actions are a frequent cause of installation failures so it’s important to test them thoroughly. Custom actions themselves usually aren’t tested. The traditional testing approach is to run functional tests on an entire installer and to cover as many scenarios and platform combinations as possible.

Custom action patterns

WiX compiler extensions provide one way of improving custom action quality: Because compiler extensions run at build time instead of install time, they can perform all sorts of data validation and conversion on strongly-typed authoring before converting it to rows and columns of custom tables in the MSI package.

Immediate custom actions then read those custom tables, check current state (for example, component action state, the state of the machine itself), and serialize the resulting data into a custom action data property. Immediate custom actions are the place to do the logic that needs live state and cannot be determined at build time by a compiler extension. Because immediate custom actions run in the security context of the installing user and outside an installation transaction, they generally do not have permissions to modify the machine and if they fail, the installation simply ends without the need to do any cleanup or rollback.

Deferred custom actions read the custom action data property set by immediate custom actions to know what to do. One way to improve custom action reliability is to make as few decisions as possible in deferred custom actions; instead, implement all the logic in compiler extensions and immediate custom actions and have deferred custom actions simply read the custom action data property in a loop to modify the machine.

The WiX custom actions that modify the machine use this pattern. For example, XmlConfig authoring is validated by the WixUtilExtension compiler extension and translated to rows and columns in the XmlConfig table. The SchedXmlConfig immediate custom action reads the XmlConfig table, constructs a custom action data property based on the XmlConfig table and machine’s state (including checking component state and storing existing file data to support rollback), then schedules the ExecXmlConfig deferred custom action to execute the XML changes and the ExecXmlConfigRollback rollback custom action to roll back the changes.

Testing with Lux

Lux is a WiX extension (and associated tools) that let you write data-driven unit tests for your custom actions. The executive summary: Lux runs your immediate custom actions then validates they set properties to the values you expect.

While it’s a simple approach, if your custom actions are factored as discussed above, validating the properties set by immediate custom actions can validate all the interaction between your custom actions, the MSI package, and MSI itself.

If your custom actions aren’t factored as discussed–for example, if your deferred custom actions expect only an installation directory and have logic to construct file paths from it–then it’s likely that your immediate custom actions don’t have a lot of logic that’s useful to test.

Lux does not help you test the custom action code that actually modifies the machine; for that, continue to use other unit-test frameworks and automated tests. By working only with immediate custom actions, Lux can let MSI run the custom actions as-is, eliminating the need to write custom test doubles for the MSI API. Lux runs from a per-user package so unless you run the tests from an elevated command prompt, none of the custom actions get elevated privileges and therefore cannot modify the machine.

Here’s how Lux works:

1. You write your unit tests using XML in WiX source files.
2. The Lux extension converts the XML to a table in a test .msi package.
3. The Lux custom action runs after all other immediate custom actions and evaluates your unit tests.

Authoring unit tests

Lux supports the following unit tests:

• Property values
• Expressions
• Multi-value properties
• Name/value-pair properties

Note that you should always author unit tests in fragments separate from your custom action authoring or any other product authoring. If you mix unit tests with other authoring, WiX includes the unit-test data in your "real" installers.

Property value tests

A simple test lets you specify a property to test, a value to test against, and the operator to compare with (which defaults to "equal").

<Fragment>
  <lux:UnitTest CustomAction="TestCustomActionSimple" Property="SIMPLE" Value="[INSTALLLOCATION]" Operator="equal" />
</Fragment>

When the test runs, Lux compares the value of the SIMPLE property against the (formatted) value [INSTALLLOCATION]. If the two match (because the operator is "equal"), the test passes. Legal values of the Operator attribute are:

equal

(Default) Compares Property to Value and succeeds if they are equal.

notEqual

Compares Property to Value and succeeds if they are NOT equal.

caseInsensitiveEqual

Compares Property to Value and succeeds if they are equal (ignoring case).

caseInsensitiveNotEqual

Compares Property to Value and succeeds if they are NOT equal (ignoring case).

Test conditions

Conditions let you validate code paths in your custom action. For example, if your custom action behaves differently on Windows XP than it does on Windows Vista and later, you can create two tests with mutually exclusive conditions:

<Fragment>
  <lux:UnitTest CustomAction="TestCustomActionSimple" Property="SIMPLE" Value="[INSTALLLOCATION]">
    <lux:Condition><![CDATA[VersionNT < 600]]></lux:Condition>
  </lux:UnitTest>
  <lux:UnitTest CustomAction="TestCustomActionSimple" Property="SIMPLE" Value="[INSTALLLOCATION]">
    <lux:Condition><![CDATA[VersionNT >= 600]]></lux:Condition>
  </lux:UnitTest>
</Fragment>

If a test has a condition, the test runs only if its condition is true.

Expression tests

Expression tests let you test any valid MSI expression. If the expression is true, the test passes. If the expression is false or invalid, the test fails.

<Fragment>
  <lux:UnitTest CustomAction="TestCustomActionSimple">
    <lux:Expression>NOT MsiSystemRebootPending AND SIMPLE</lux:Expression>
  </lux:UnitTest>
</Fragment>

Multi-value property tests

Because deferred custom actions can access only a single custom-action data property, custom actions that need more than one piece of data encode it in a single string. One way is to have the immediate custom action separate multiple elements with a known separator character, then have the deferred custom action split the string at those separate characters. Lux supports such separators using the ValueSeparator and Index attributes.

<Fragment>
  <lux:UnitTest CustomAction="TestCustomActionMultiValue" Property="MULTIVALUE" ValueSeparator="*">
    <lux:Condition>VersionNT</lux:Condition>
    <lux:UnitTest Index="0" Value="1" />
    <lux:UnitTest Index="1" Value="[INSTALLLOCATION]">
      <lux:Condition>NOT Installed</lux:Condition>
    </lux:UnitTest>
    <lux:UnitTest Index="2" Value="WIXEAST" />
  </lux:UnitTest>
</Fragment>

A condition under the parent UnitTest element applies to all individual unit tests. Override it with a Condition child element.

Name/value-pair property tests

Another way of providing multiple values to a deferred custom action is to combine name/value pairs into a single string. Lux supports name/value-pair properties using the NameValueSeparator and Index attributes.

<Fragment>
  <lux:UnitTest CustomAction="TestCustomActionNameValuePairs" Property="NAMEVALUEPAIRS" NameValueSeparator="#">
    <lux:UnitTest Index="InstallationRoot" Value="[INSTALLLOCATION]" />
    <lux:UnitTest Index="Developers" Operator="caseInsensitiveNotEqual" Value="WIXEAST" />
  </lux:UnitTest>
</Fragment>

Building test packages

Lux unit tests run from a minimal package that includes just your unit tests and the resources they need to run. Because Lux runs only immediate custom actions, it doesn’t need a full, per-machine package that includes all the files and other resources to be installed. Such a minimal package saves build time but does require that your WiX source code be well modularized with fragments. For example, you should always author unit tests in fragments separate from any other authoring. If you mix unit tests with other authoring, WiX includes the unit-test data in your "real" installers. Likewise, any other WiX authoring included in unit-test fragments is included in test packages.

Lux comes with a tool that simplifies the creation of test packages. Its name is lux.exe. To use lux.exe:

1. Compile the source file containing your unit tests.
2. Run lux.exe on the .wixobj file and specify a source file for the test package.
3. Compile the test package source.
4. Link the test package .wixobj with the unit tests .wixobj.

For example:

candle -ext WixLuxExtension CustomActions.wxs
lux CustomActions.wixobj -out LuxSample1_test.wxs
candle -ext WixLuxExtension LuxSample1_test.wxs
light -ext WixLuxExtension LuxSample1_test.wixobj CustomActions.wixobj -out LuxSample1_test.msi

Lux also includes an MSBuild task and .targets file to let you build test packages from the same .wixproj you use to build your installers. To build a test package, build the BuildTestPackage target using MSBuild 3.5:

%WINDIR%\Microsoft.NET\Framework\v3.5\MSBuild.exe /t:BuildTestPackage

Running unit tests

After building the test package, you can run it with logging enabled to capture test results:

msiexec /l test1.log /i bin\Debug\LuxSample1_test.msi

Search the log for WixRunImmediateUnitTests to see test results and other logging from the Lux custom action.

Nit: The Lux test runner

Lux also includes Nit, a console program that monitors the logging messages emitted by unit tests and reports success or failure. To use Nit on your test packages, just specify their filenames as arguments to nit.exe. For example:

nit LuxSample1_test.msi

Lux also lets you run Nit on your test packages from the same .wixproj you use to build your installers. To run a test package under Nit, build the Test target using MSBuild 3.5:

%WINDIR%\Microsoft.NET\Framework\v3.5\MSBuild.exe /t:Test

The test package will be built before the tests are run, if necessary. The output looks like the following, with failing tests highlighted in red as build errors:

Test:
  Microsoft (R) Windows Installer Xml Unit Test Runner version 3.5.1204.0
  Copyright (C) Microsoft Corporation. All rights reserved.

  Test luxB21F0D12E0701DBA30FFB92A532A5390 passed: Property 'SIMPLE' matched expected value '[INSTALLLOCATION]'.
  Test TestConditionBeforeVista passed: Property 'SIMPLE' matched expected value '[INSTALLLOCATION]'.
  Test TestConditionVistaOrLater passed: Property 'SIMPLE' matched expected value '[INSTALLLOCATION]'.
  Test TestExpressionTruth passed: Expression 'NOT MsiSystemRebootPending AND SIMPLE' evaluated to true.
nit.exe : error NIT8103: Test luxA6D27EC5903612D7F3786FF71952E314 failed: Property 'MULTIVALUE' expected value '2' but actual value was '1'.
  Test lux210257649C16AFA33793F1CDDF575505 passed: Property 'MULTIVALUE' matched expected value '[INSTALLLOCATION]'.
nit.exe : error NIT8103: Test lux402940A90D3ADAD181D599AB8C260FA0 failed: Property 'MULTIVALUE' expected value 'xxxWIXEAST' but actual value was 'WIXEAST'.
  Test lux453EC8DB458A8F66F0D22970CFF2AE99 passed: Property 'NAMEVALUEPAIRS' matched expected value '[INSTALLLOCATION]'.
  Test lux20CB4F88795F22D15631FD60BA03AFEB passed: Property 'NAMEVALUEPAIRS' matched expected value 'WIXWEST'.
nit.exe : error NIT8102: 2 tests failed. 7 tests passed.
Done Building Project "C:\Delivery\Dev\wix35\src\lux\samples\LuxSample1\LuxSample1.wixproj" (Test target(s)) -- FAILED.

Build FAILED.

"C:\Delivery\Dev\wix35\src\lux\samples\LuxSample1\LuxSample1.wixproj" (Test target) (1) ->
(Test target) ->
  nit.exe : error NIT8103: Test luxA6D27EC5903612D7F3786FF71952E314 failed: Property 'MULTIVALUE' expected value '2' but actual value was '1'.
  nit.exe : error NIT8103: Test lux402940A90D3ADAD181D599AB8C260FA0 failed: Property 'MULTIVALUE' expected value 'xxxWIXEAST' but actual value was 'WIXEAST'.
  nit.exe : error NIT8102: 2 tests failed. 7 tests passed.

    0 Warning(s)
    3 Error(s)

Time Elapsed 00:00:07.87

FAQ

Are these really unit tests? They look a lot like Fit tests.

Fit tests are tabular and data-driven, so they have a lot in common with Lux’s unit tests. But fit tests are focused on high-level outputs, whereas unit tests are low-level developer tests.

Using the custom action code as-is sounds good, but are there any limitations with that approach?

Yes. Because you are running the actual custom action, any code paths that rely on machine state reflect the state of the machine you run the tests on. For example, code that has different behavior on different versions of Windows runs only one way, just like it does in a normal installer. You can add debug code that looks for the presence of the WIXLUXTESTPACKAGE property; it’s set to 1 in a test package.

I have unit tests that fail because directory properties are being returned as empty strings. Why?

The most likely cause is that your directories are defined as children of your installer’s Product element. Lux.exe builds its own Product element to product a minimal test package, so none of the resources defined in your Product are available to the unit tests. The simplest solution is to move those resources to their own Fragment.

Do I have to write my custom actions in C++?

No, Lux works with any immediate custom actions, regardless of the language they’re written in, including MSI type 51 property-setting custom actions.