New WiX feature: Firewall extension

WixFirewallExtension is a new WiX extension that lets you configure the Windows Firewall from your program’s installer. Windows has had a built-in firewall since Windows XP was released in 2001, though it was XP’s Service Pack 2 that introduced a firewall of sufficient power for most people to use it. (It helps that in SP2, the firewall is turned on by default. The same is true on Windows Vista, Server 2003 SP1, and Server 2008.)

Outgoing connections — from the local computer to a server — aren’t blocked. (In fact, the firewall on XP SP2 and Server 2003 SP1 doesn’t support blocking outbound connections. That feature was added to the firewall in Vista and Server 2008.) Incoming connections are blocked unless the firewall is configured to allow them. If your program is any kind of a server, it needs to add itself to the firewall’s exception list or it won’t receive any connections that originate from another machine.

There are two types of firewall exceptions:

  • Application: A particular program for an incoming connection on any port/protocol.
  • Port: A particular port for a particular IP protocol (TCP or UDP). Any program can accept incoming connections from that port/protocol.

For both types of exceptions, the scope of the exception controls which incoming connections are accepted:

  • Any network, including the Internet.
  • Only the local subnetwork.
  • Custom IP addresses.

You can configure your program’s firewall exceptions using the FirewallException element. To configure an application exception, nest the FirewallException element under the program’s File element or under a Component element and specify the program’s file id in the File attribute:

<Wix xmlns=”” xmlns:fire=””>

<Component Id=”MyComponent1″ Guid=”PUT-GUID-HERE”>
<File KeyPath=”yes” Source=”program.exe”>
<fire:FirewallException Id=”FWX1″ Name=”My Program” />

The Id and Name attributes are both required. You can adjust the scope of the exception using the Scope attribute, which takes values any or localSubnet or by using RemoteAddress child elements:

<Wix xmlns=”” xmlns:fire=””>

<Component Id=”MyComponent2″ Guid=”PUT-GUID-HERE”>
<File KeyPath=”yes” Source=”program.exe”>
<fire:FirewallException Id=”FWX2″ Name=”My Program”>

RemoteAddress is a direct line to the firewall API’s support for remote addresses.

There’s also a Program attribute that lets you specify a formatted string that identifies the program that should get the firewall exception. It’s useful if you want to specify an exception for a program installed by a different package.

To specify a port exception, use the Port and Protocol attributes. Port takes an integer value and Protocol takes tcp, udp, or any. Note that any requires Windows Vista and Server 2008; on XP SP2 and Server 2003 SP1, specify two port exceptions, one with Protocol=”tcp” and another with Protocol=”udp” as a workaround.

<Wix xmlns=”” xmlns:fire=””>

<Component Id=”MyComponent3″ Guid=”PUT-GUID-HERE”>
<File KeyPath=”yes” Source=”program.exe”>
<fire:FirewallException Id=”FWX3″ Name=”My Program” Port=”1025″ Protocol=”udp” />

Both types of exceptions also support the IgnoreFailure attribute to specify whether firewall configuration failures should be ignored or cause the installation to roll back.

Sponsored by ACES

The firewall extension is part of the work I’m undertaking to convert ACES Studio’s products from our old script-based installer to a declarative installer built with WiX. Studio management was pleased to contribute the work to the WiX community.

New WiX feature: Gaming extension

The Game Explorer is a new feature in Windows Vista to collect and richly present installed games. Game Explorer is a shell folder that includes detailed information about each game, including box art, content ratings (and parental-control restrictions based on them), and performance requirements (using the Vista performance rating system).

Most of the details shown in Game Explorer come from the game developer in the form of the Game Definition File (GDF) that’s embedded as a resource in your executable. Details and samples on the GDF and Game Explorer are available in the DirectX SDK, especially in Getting Started with Game Explorer.

The WiX Gaming extension is a compiler extension with custom actions to do the following:

  • Register a game in Game Explorer.
  • Create tasks in the context menu of a game in Game Explorer.
  • Register a game on Windows XP so it’s available in Game Explorer after an upgrade to Windows Vista.
  • Register extensions with support for the rich saved-game preview handler.

[Update: WixGamingExtension will be available in the next weekly release of WiX v3.]

Registering games

To register a game, add a Game element and specify its instance ID in its Id attribute as a child of the File element for the game executable. For example:

<File Id=”MyGameExeFile” Name=”passenger_simulator.exe” KeyPath=”yes”>
<gaming:Game Id=”985D5FD3-FC40-4CE9-9EE5-F2AAAB959230″>

The DirectX SDK suggests letting the Game Explorer COM object create a new GUID for every installation. It then suggests writing the new GUID to the registry or file system to persist it or to use WMI to query Game Explorer for the GUID. The prior release of Flight Simulator used WMI, which was a fairly regular source of failures during uninstall and repair operations. Following the mantra of minimizing runtime dependencies during setup, I chose to let the setup author specify a static ID. No persistence or runtime dependencies required.

Creating tasks

Game Explorer tasks are simply shortcuts shown on the context menu on the game icon in Game Explorer. Play tasks are plain ol’ shortcuts to the game executable with optional command-line arguments. Support tasks are shortcuts to URLs. The shortcuts must be created in specific directories for Game Explorer to find them.

WixGamingExtension translates strongly-typed PlayTask elements into rows in the Shortcut table; the Name attribute is the name of the shortcut and Arguments are the command-line arguments. WixGamingExtension translates SupportTask elements into WixUtilExtension InternetShortcuts; the Name attribute is the name of the shortcut and Address is the URL.

<File Id=”MyGameExeFile” Name=”passenger_simulator.exe” KeyPath=”yes”>
<gaming:Game Id=”985D5FD3-FC40-4CE9-9EE5-F2AAAB959230″>
<gaming:PlayTask Name=”Play” />
<gaming:PlayTask Name=”Play in Deity Mode” Arguments=”-deity” />
<gaming:SupportTask Name=”Help!” Address=”” />
<gaming:SupportTask Name=”Cheat codes” Address=”” />
<gaming:SupportTask Name=”Get P0wned” Address=”″ />
<gaming:SupportTask Name=”Get owned” Address=”″ />
<gaming:PlayTask Name=”Show no mercy” Arguments=”-cutenfluffy” />
<gaming:SupportTask Name=”Forums” Address=”” />

Registering for OS upgrades

When you install a game on Windows XP and later install Windows Vista as an upgrade, the Vista upgrade can automatically register the game in Game Explorer. All that’s required is writing the task shortcuts and a few registry values. WixGamingExtension does that automatically; no extra authoring is required.

Rich saved games

Vista includes a special preview handler for file extensions registered as a saved-game file. Most of the effort required to support rich preview is in the game itself; the burden on setup is just to register the extension for the preview handler. WixGamingExtension supports this registration as a simple yes/no attribute on the standard WiX Extension element:

<ProgId Id=”MyGameProgId”>
<Extension Id=”MyGameSave” gaming:IsRichSavedGame=”yes” />

Sponsored by ACES

The gaming extension is part of the work I’m undertaking to convert ACES Studio’s products from our old script-based installer to a declarative installer built with WiX. Studio management was pleased to contribute the work to the wider WiX community.

If you happen to publish a cool game that uses WixGamingExtension, feel free to send a copy my way. 😀

New WiX feature: Internet shortcuts

A common request on wix-users is how to create shortcuts to a Web site. MSI’s Shortcut table and CreateShortcuts action don’t support targets that point to URLs like A shortcut’s target can point only to a feature (for advertised shortcuts) or a file or directory (for unadvertised shortcuts).

You can fake a shortcut to a URL by using the IniFile table to create a .url file. It’s a bit of a hack, given that the format of .url files isn’t explicitly documented and is therefore subject to change. (Granted, it’s not likely to change, because that would break a lot of existing applications.)

I needed URL shortcuts for Train Simulator so I wrote a custom action to create them. I then added authoring support to the WixUtilExtension compiler extension. With reviews from Heath and Peter, I checked in the work today. You’ll see it in the next weekly build of WiX v3.

The authoring is similar to, but simpler than, a standard shortcut. Here’s the attribute schema reference from WiX.chm:

Name Type Description Required
Id String Unique identifier in your installation package for this Internet shortcut. Yes
Directory String Identifier of the directory where the shortcut should be created. Yes
Name String The name of the shortcut file, which is visible to the user. (The .lnk extension is added automatically and by default, is not shown to the user.) Yes
Target String URL that should be opened when the user selects the shortcut. Windows opens the URL in the appropriate handler for the protocol specified in the URL. Note that this is a formatted field, so you can use [#fileId] syntax to refer to a file being installed (using the file: protocol). Yes

Here’s what a simple http shortcut looks like:

Name=”Joy of Setup”
Target=”” />

You can also create shortcuts to resources using non-http protocols:

Target=”file://[%WINDIR]\Help\addremov.chm” />

Internet shortcuts are needed, among other reasons, for Vista’s Game Explorer. More on that in a future entry.

Flight Simulator X Service Pack 2 available–and how to work around common problems

We shipped Service Pack 2 for Flight Simulator X on Friday. (Get the downloads from; see Phil Taylor’s blog entries for more details.) Service Pack 2 contains the same set of fixes as in Acceleration, without Acceleration‘s new aircraft or missions.

We’re seeing a common problem come up: A message from the installer: “Microsoft Flight Simulator X Service Pack 2 requires the English version of Flight Simulator X.”

So far, the immediate cause is the same: missing data in the registry. During testing, the root cause was also the same: Copying the installed files from another partition or machine rather than using the installer. That’s not officially supported, of course, but given the size of Flight Simulator, it’s fairly common to want to move the installed files (to a bigger partition, for example) without reinstalling.

Service Pack 2 requires the registry data that the original RTM and SP1 installers write. (It uses the data in the registry to find the installation directory and the language.dll file. It checks the version information in language.dll to make sure it has the same language as the SP2 installer; otherwise, you’d end up with a broken mix of localized content.)

Unfortunately, the original RTM installer doesn’t rewrite those registry values when you do a repair, so what works is to uninstall and reinstall RTM, then SP1, then SP2.

That said, here’s a shortcut. Note that it involves editing the registry, which can be hazardous to your computer’s health. If you don’t feel comfortable doing this, uninstall and reinstall is a safe choice.

  1. Start RegEdit.
  2. On 32-bit operating systems, open the HKEY_LOCAL_MACHINE\ SOFTWARE\ Microsoft\ microsoft games\ flight simulator\ 10.0 key in the left pane.
    On 64-bit operating systems, open the HKEY_LOCAL_MACHINE\ SOFTWARE\ Wow6432Node\ Microsoft\ Microsoft Games\ Flight Simulator\ 10.0 key in the left pane.
  3. Choose Edit|New|String Value.
  4. Replace New Value #1 by typing SetupPath.
  5. Double-click SetupPath and in the Value data box, type the full directory path where you installed or copied Flight Simulator X.

The SP2 installer should then be able to find language.dll and verify that it’s the right language for the version of SP2 you’re trying to install.

That’s the only common problem we’ve seen — as of today, anyway. I’ll update this blog entry with additional items if/when they come up.

Update #1, 17-Dec-07: Added registry key for x64 OSes.

Flight Simulator X: Acceleration releases to manufacturing

My second project at ACES Studio, the Flight Simulator X: Acceleration expansion pack, has gone gold. Well, 12.5 percent of it has: We sent the English release to manufacturing but we have seven more languages we’re shipping over the next couple of weeks. So while the extra-long days are a bit more normal now, the weekends are still fairly busy, coordinating builds and releases with our international folks in Dublin and Tokyo.

Acceleration was a “small” release, but only by the standards of a 14GB, two-DVD Flight Simulator X. Here are some mildly interesting statistics:

Number of DVDs 1
Number of files 7121
Compressed byte count 2,567,158,638
Uncompressed byte count 4,014,683,859
WiX version used to build installer 3.0.3304.0
Visual C++ version used to build setup UI and custom actions 8.0
Number of new custom actions 5 (plus rollback and scheduling CAs)
Number of new custom tables for data-driven deferred custom actions 2
Number of WiX custom actions consumed 2
Percentage of WiX custom action enhanced for Acceleration where enhancements were contributed back to WiX 100

Seven more languages to go!