Doctor Deploys Blog

File this tidbit under documented but cryptic and missing an error message. I was recently creating 32-bit and 64-bit MSIs using the WiX toolset. The very helpful -arch command line switch to candle made it easy to build for both architectures with the same codebase. Maybe a little too easy.

The 32-bit MSI worked great. However, trying to do anything with the 64-bit package (including validation) always gave the error message:

This installation package could not be opened. Contact the application vendor to verify that this is a valid Windows Installer package.

That stumped me for a while. For some reason, I kept coming back to the Package element in my .wxs file. Something didn’t seem quite right. It looked like this:

<Package InstallScope="perMachine" Compressed="yes" />

See anything wrong? I’m building a per-machine install with all the files compressed so that’s all good. The -arch command line switch is going to handle setting the Package/@Platform attribute for me correctly so I don’t need that attribute.

I ended up reading the documentation again and again before I came across this little gem in the Package element documentation that I had totally forgotten.

InstallerVersion - The minimum version of the Windows Installer required to install this package. Take the major version of the required Windows Installer and multiply by a 100 then add the minor version of the Windows Installer. For example, "200" would represent Windows Installer 2.0 and "405" would represent Windows Installer 4.5. For 64-bit Windows Installer packages, this property must be set to 200 or greater.

That last bit is my emphasis. Of course! 64-bit packages were not supported until Windows Installer v2.0 so you need to mark the package as such. The fix? Easy.

<Package InstallScope="perMachine" Compressed="yes" InstallerVersion="200" />

I was happy to have a fix in hand but disappointed the WiX toolset didn’t catch this for me. I opened a bug to track the issue and will fix it sometime in WiX v3.5.

In the meantime, remember when creating a 64-bit package, be sure to mark your package to require Windows Installer 2.0 or better.

Original post by Rob Mensching

In my previous blog post where I introduced some of the features of Burn the question whether Burn would work as a single self extracting executable was asked a few times. The answer is, "Of course!" but there is actually more to it than that.

I debated listing "containers" as a feature in the previous blog post. Looking at the comments, it’s pretty clear I should have. The "container" concept is still under some design tweaks but it is shaping up to be quite a powerful concept (and it addresses the question many asked).

So let me walk you through the list of primitives that Burn will process and how they stack together.

Packages

A package is a unit of change (install, repair, patch, uninstall) for the bootstrapper. Packages are members of a chain that the bootstrapper manages. There must be at least one package or the bootstrapper has no work to do. Each package has an implicit payload that is the entry point for the change (for example, an .MSI file or .EXE file). Additional payloads and containers may be referenced by a package.

Payloads

A payload is a file that contains data required by a package. The bootstrapper treats payloads as opaque blobs therefore there are no bootstrap related requirements for payloads. Payloads may be found as loose files outside the bootstrapper or combined with zero or more payloads in a container.

Containers

Containers are a way of combining one or more payloads into a single file. Usually containers are used compress the contained payloads to make the total distribution size smaller. Sometimes containers are used simply to minimize the number of files that must be distributed with the bootstrapper. The bootstrapper controls the format of the containers and is responsible for extracting payloads out of the containers during the cache phase.

The ideal container file format will optionally compress various file types well, support digital signatures and scale to very large file sizes while containing many payloads.

Attached container

An attached container is found at a specified offset in the bootstrapper itself. The container is called attached instead of embedded because it is found at the end of the bootstrapper, after all of the executable code and resources. There can be only one attached container. When the bootstrapper is signed the attached container is included in that signature.

It is expected many small products (< 300 MB when compressed) will distribute a single file bootstrapper where all of the product’s payloads are compressed into the attached container.

Detached containers

A detached container exists as a file outside the bootstrapper. The bootstrapper manifest can reference any number of detached containers. Detached containers are highly recommended when the combined size of the bootstrapper plus attached container would exceed 300 MB. Larger executable files experience poor start up performance on Windows leading to a less than ideal user experience.

Detached containers can also be used to optimize download scenarios because the bootstrapper will only request the containers referenced by packages being cached. For example, a very small bootstrapper would provide the optimal download + start up user experience then provide a custom user interface while the minimal number of detached containers are downloaded from the Internet.

Also note that if there are very few payloads and they are already compressed, it may be optimal to forego the use of detached containers completely. Containers do add overhead because they must first be downloaded before the payloads are extracted which requires more disk space and file I/O than simply caching the payloads directly.

Summary

The goal in Burn is to provide enough flexibility to meet everyone’s needs. The WiX toolset will ship the tools necessary to create and bundle these primitives together. Ultimately, the decision how to organize your content into packages, payloads and containers is up to you.

I know there are many other questions about Burn. I’ll get to them as soon.

Original post by Rob Mensching

It was almost ten years ago that I started a little project inside the firewalls of Microsoft called the WiX toolset. I called it a "Community Source" project because inside Microsoft the words "Open Source" only had negative connotations. I never would have guessed that 5 years later I would help reshape Microsoft’s approach to Open Source by releasing my little project. Now 5 more years later, Microsoft takes another big step and contributes to the most famous Open Source project of all, Linux.

Mary Jo Foley (who originally broke the news about the WiX toolset) references flying pigs. Todd Bishop (whose write up about WiX printed in the Seattle PI I still have) tosses in a little more historic context. However as I read those blog posts then others then comments all around, I felt like a few key questions were never asked and thus never answered. I thought they were interesting and captured some of my opinions on this topic.

Please note that I’m not on Sam Ramji’s team and cannot speak to Microsoft’s Open Source strategy. These are just my views of how Microsoft has changed over the years.

Q: Everyone is making this out to be a big deal. Jim Zemlin said this isn’t that big of deal, "they’re not saving the whales here." Why is this a big deal?

A: Code wise, maybe this isn’t that big of a deal. Microsoft is just adding a few drivers to Linux so it will run better on Hyper-V. Anybody could have done that. It’s just code right?

Sure, but what is different here is that Microsoft is meeting the Linux community on the community’s terms. Linux is released under the GPLv2. Okay, Microsoft licenses these drivers under the GPLv2. Linux has established leaders for the major sub-systems. Okay, Microsoft works with the driver people to understand their requirements. Linux has coding standard that everyone must follow. Okay, Microsoft works on the code to meet those standards.

That’s why this is a big deal. Microsoft is participating in the Linux community in a way its never done. Sure, other companies have done this already but I believe this demonstrates how Microsoft continues to learn how to approach Open Source communities and collaborate appropriately. Less than 10 years ago, the interaction could only be summed up as fist shaking and name calling. Now it’s about participation for cooperation, competition and co-opetition.

Q: But isn’t Microsoft contributing these drivers because they help Hyper-V?

A: In the narrowest view of the circumstances, yes. But if you look at this from a business perspective then I expect that you’ll find this is more about making customers happy. If no customers wanted to run Linux on Windows then I’m pretty sure that Microsoft would not have done this work.

What I’m excited about is the fact that Microsoft finally found a way to work with the Linux community to meet a customer request. Instead of saying, "That’s Linux’s problem, have them sort it out." Microsoft joined the Linux community to solve the problem. Can you see the shift in thinking that occurred here?

Q: But don’t you think Microsoft should have done more sooner?

A: Probably. But educating an organization as large as Microsoft about something as subtle as Open Source takes time. I do my small part by working to make my "relatively insignificant geekware" project successful. Announcements like today’s recognize the larger efforts made by others.

There’s certainly more work to do but in 5 years I think Microsoft has come a long way. I only hope the progress continues (and maybe a little bit faster). <smile/>

Original post by Rob Mensching

If you follow me on Twitter (@robmen), you know I’ve become a huge Seattle Sounders FC fan. I haven’t played soccer since I was a kid but after K invited Jenny and I to a match early this season we became hooked. Now we’re season ticket holders (jumped in when they opened more seats mid-season) and follow away games regularly.

Today (er, technically, yesterday) the Sounders came to practice on "the yard" at Microsoft.  Peter, K and I had unfettered viewing of the whole thing.

Here are some personal highlights:

• Watching something like 16 players split in two teams pass the ball around in such a tiny space before warming up.
• Watching Sigi stalk around calmly watching and directing. After being congratulated by the President.
• Watching Freddy Montero warm up with the ball. Amazingly effortless footwork.
• Hearing the voices and, more interestingly, the accents of the players. They are essentially silent from my perch the stands.
• Hearing Keller yell out short snippets of Spanish to direct Freddy. English for everyone else.
• Watching Freddie Ljungberg move the ball down the field. He really is brilliant at moving and placing the ball.
• Watching Keller get scored on then holler, "Awwww, shhhhhh–oot." He kept it family friendly in the last syllable. Heh.
• Having Nate Jaqua sign my Sounders FC scarf! I like the way Jaqua plays.

Anyway, it was a fantastic way to spend a couple hours this morning.

Original post by Rob Mensching

A long while ago, Bob wrote a short blog entry about the WiX toolset’s upcoming bootstrapper adoringly named Burn. We made some early progress back then but refocused our energy on finishing WiX v3.0 which recently released. Now I’m back to Burn which will release with WiX v3.5.

What is Burn?

Burn is a bootstrapper/chainer. Because Burn is both, I tend to use the term "bootstrapper" and "chainer" interchangeably. I know some people like to have some distinction between the terms. However, I’ve found nobody agrees on the distinctions. I tend to lean towards the use of the word "bootstrapper" because it starts with the letter "b" and Burn was a cool name for the next WiX tool.

What is the purpose of Burn?

As you might expect from the name, a bootstrapper is responsible for getting the setup process started. You might expect that this should be unnecessary. Double clicking an MSI file should be sufficient to get the installation process going. Unfortunately, due to several design decisions in the Windows Installer there are a plethora of work items for a bootstrapper.

Burn also chains multiple setup packages to create a single installation experience. The original design of the Windows Installer expected that a product and all of its prerequisites would be installed via a single MSI file. That is why Merge Modules were developed. Unfortunately, Merge Modules do not meet the needs of all types of prerequisites and have some pretty serious deficiencies, particularly in relation to patching.

Thus the purpose of Burn is to provide a unified experience for initiating and applying one or more setup packages to the machine.

What are the features of Burn?

Let me just list the features planned for the first version of Burn. The complete list of features to implement in a bootstrapper is very long. Our first release is a balance of features vs. time to completion. As always, I welcome feedback. Particularly, if you think something important is missing.

• Size - you might not think of the size of the bootstrapper as a feature but it is very important to Burn. The goal is to keep the Burn overhead under 256 KB. Why? Well, we’ve found that with a broadband connections 256 KB equates to an almost instantaneous download and launch experience via Internet Explorer.
• Elevation - every bootstrapper I’ve seen gets elevation (aka: UAC) wrong or not-quite-right. The really bad bootstrappers prompt for elevation multiple times while others prompt before showing some branded UI. The real unfortunate part is that these bootstrappers cannot correctly handle per-user setup packages. There is a lot to elevation and I’ll talk more about how Burn handles it in the future.
• UI - let’s face it the Windows Installer user interface was designed in 1997 and it still looks like it. Burn on the other hand does not restrict the user interface at all. Setup developers provide a UX.DLL that has full control over the user interface and interaction (that’s why we call it user experience, or UX). In the WiX toolset we will ship a couple standard Burn UX.DLLs (just like we provide standard UI for MSI files). A stretch goal for WiX v3.5 is to allow the UX.DLLs to be written in managed code (think WPF).
• Progress - progress is one of the most visible aspects of setup and one of the hardest to get right. Burn does a lot of work to create a seamless progress system so it is easy for developers to create a unified user experience across multiple setup packages. For those of you familiar with the Windows Installer, this means the progress bar no longer resets twice during the install. I can’t tell you how pretty that is. <smile/>
• Download - redistributables (think .NET Framework and SQL Express) that are larger than the applications which use them are unfortunately really common right now. If you are distributing your application over the Internet (and how many people today aren’t?) shipping those redistributes in your setup is expensive. Burn has the ability to only download what the user needs and/or chooses to install. That means if the .NET Framework is already installed, no need to download it again. Also, when your product is broken up into multiple MSI files it becomes possible to optimize the distribution further. Oh, and did I mention Burn will support resume if the download server supports HTTP 1.1?

Those are the big features. I’m sure I’ve left out a lot of little things. Again, remember this is the first version. We’ll be back for more.

When is Burn available?

Burn is one of two key features in WiX v3.5. Votive support for Visual Studio 2010 is the other. We are planning to be done around a month after Visual Studio 2010 releases. Of course, the code to Burn is available right now but it is under a lot development and not at all stable. So, I would not recommend trying to use Burn too much until I get the WiX v3.5 install using it. Once WiX v3.5 is installing with Burn then you’ll know the core functionality is in place. That plus there will be a working example of how to create your own UX.DLL.

I hope we’ll be at that point by the end of July. A lot of that depends on how busy real life gets. Go, Sounders! <smile/>

Original post by Rob Mensching

Now that the WiX v3 toolset is released, I thought I’d share a couple tips for those users upgrading from WiX v2. WiX v3 is obviously a major upgrade from WiX v2 and there are a few breaking changes as a result. Fortunately, WiX v3 ships with a tool to help with the code migration (WixCop.exe) and then you only need to understand one new concept (extensions).

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:pathtowixv2light.exe my.wixobj %WIXUI_PATH%wixui.wixlib
-loc %WIXUI_PATH%WixUI_en-us.wxl

C:src>C:pathtowixv3light.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!

Original post by Rob Mensching

It is my pleasure to announce that WiX toolset v3.0 is now officially declared Production/Stable. The final build number is 3.0.5419.0. You can download it from here or here.

The journey to release WiX v3.0 started about four and a half years ago. While WiX v2.0 was locking down and getting ready for it’s release, we had a lot of ideas how to improve the language and better build integration with Visual Studio. Obviously, those ideas would destabilize WiX v2 so we decided to spin up an independent WiX v3 effort.

Early in the project it was clear that WiX v3 was a major improvement over WiX v2. Developers flocked to it for the file and directory short name generation feature alone. MSBuild integration in Votive was also a huge hit. Additionally features like @Id and Component/@Guid generation, smart cabbing, heat, and the best Windows Installer patch generation tools on the planet make WiX v3.0 a very important release.

When Visual Studio team members joined the WiX v3 effort it became clear that WiX v3 was also going to be the most stable release of the WiX toolset ever. There were over 900 bugs resolved during the course of the project. But a more important number to me is that we’ve postponed fewer than 10 bugs and each of them have a workaround. Comparatively, WiX v2 released with over 100 known issues all of which were fixed in WiX v3. All of this makes WiX v3.0 the most reliable set of tools you can use today to create Windows Installer databases.

We have also faced our fair share challenges while working to release WiX v3.0. We had to make a painful cut and remove Burn from the WiX v3.0 roadmap. That also prevented ClickThrough from reaching its true potential. Many of you probably also remember the in-the-box then out-of-the-box decisions by Visual Studio. That morale boost and breaker led to the decision that WiX v3.0 was ready now and could be released on America’s Independence Day. Finally, a less visible but possibly the most difficult challenge that I faced was the complete turn over in the core developers. In fact, one of the things that excites me most about this release, is that everyone is coming back for the ship party.

Which brings me to my closing remarks. We’re going to have a party. Tonight all over the United States there will be firework displays of varying scales and grandeur. While watching those pyro.exe.technic events light.exe up the dark.exe night sky with gigantic roman candle.exes celebrate with the team that brings you the WiX toolset.

We have a great time working on the WiX toolset and we hope you enjoy the efforts. WiX v3.0 isn’t the end for us. It’s just the most useable and stable release until we bring you the next one.

And until then keep coding. You know I am.

Original post by Rob Mensching