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=”http://schemas.microsoft.com/wix/2006/wi” xmlns:fire=”http://schemas.microsoft.com/wix/FirewallExtension”>

<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=”http://schemas.microsoft.com/wix/2006/wi” xmlns:fire=”http://schemas.microsoft.com/wix/FirewallExtension”>

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

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=”http://schemas.microsoft.com/wix/2006/wi” xmlns:fire=”http://schemas.microsoft.com/wix/FirewallExtension”>

<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=”http://example.com” />
<gaming:SupportTask Name=”Cheat codes” Address=”http://example.com” />
<gaming:SupportTask Name=”Get P0wned” Address=”http://example.com/1337″ />
<gaming:SupportTask Name=”Get owned” Address=”http://example.com/non1337″ />
<gaming:PlayTask Name=”Show no mercy” Arguments=”-cutenfluffy” />
<gaming:SupportTask Name=”Forums” Address=”http://example.com” />
</gaming:Game>

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” />
</ProgId>

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 http://www.joyofsetup.com/. 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:

<util:InternetShortcut
Id=”Home”
Directory=”DesktopFolder”
Name=”Joy of Setup”
Target=”http://joyofsetup.com” />

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

<util:InternetShortcut
Id=”ARP”
Directory=”ProgramMenuFolder”
Name=”ARP”
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.

WixUI extensibility

There’s been an increase lately in the number of questions on the wix-users mailing list and elsewhere about extending the WixUI dialog library.

WixUI extensibility past

In WiX v2, WixUI is a simple .wixlib of UI authoring fragments. Navigation between pages of the wizard is handled by properties that contain the previous and next dialog names for each dialog. You can extend the stock dialog sets by inserting custom dialogs into the wizard sequence; set the back and next properties for the dialogs before and after the one you’re inserting. To customize one of the stock dialogs always requires you to copy that dialog’s source file and modify it. You also need to copy the fragment containing the properties for the dialog set; otherwise you’d end up with duplicate properties.

WixUI extensibility present

In WiX v3, WixUI is built as an extension. All the standard dialog fragments, bitmaps, and custom action DLL (to print the EULA) are embedded in it. WixUI v3 takes advantage of several features added to WiX v3:

  • WiX variables to point to bitmaps and the license RTF file, to override those included in the extension.
  • “Floating” Publish elements move dialog behavior out of the dialog fragments and into the dialog set fragment. That makes it easier to reuse a dialog and still give it different behavior.

Adding a dialog into the wizard sequence means copying the dialog set fragment and changing the floating Publish elements for the existing dialogs and adding new ones for the new dialog.

It’s possible to more easily re-use the stock dialogs but still not possible to modify their appearance. That still requires copying the dialog into your own project. You can still refer to the dialogs you don’t modify from their copies in WixUIExtension.dll and the linker will find them there.

Compare and contrast

If you’ve used one of several “name-brand setup authoring tools” (hereinafter NBSATs), you’ve seen a very different approach:

  1. Create a new project.
  2. See shiny, happy dialogs listed in your NBSAT IDE.
  3. Edit the aforementioned dialogs to your heart’s content.

In general, what’s happening is that the NBSAT is copying its set of dialogs directly into your NBSAT project file. As the NBSAT IDE is the preferred (or only) way of seeing the project, it can hide all those dialogs until you need to edit them.

The WixUI model is different: You don’t get copies of the WixUI dialogs; when you build your project with a UIRef element to a WixUI dialog set, the WiX linker is pulling those dialogs directly from the .wixlib (that in WiX v3 is embedded in WixUIExtension.dll).

WiX could offer the same always-copy model NBSATs use (via a Votive template, for example). The downside is that you’d have all this UI code in your project. Lacking (for the moment) a WiX IDE, there’s no way to hide any code in your project file: It’s always visible in all its XML angle-bracket glory. Keeping the UI authoring in a library keeps it hidden, at the cost of more painful customization.

WixUI extensibility future

That’s another article, coming soon.<g>