How to use WiX to create an MSI-based installer that will install the DirectX 9.0 redistributable

Artigo
08/01/2008

As noted in the Highlights of WiX v3.0.4311.0 post on Bob Arnson's blog, Neil Enns recently contributed several how-to topics to the WiX v3.0 documentation. One of these how-to topics describes how to include DirectX 9.0c runtime files in an MSI-based installer by authoring the DirectX setup files into the MSI and then creating a custom action to run dxsetup.exe. These steps are particularly useful for developers creating MSI-based installers for XNA Framework-based games. Since the WiX documentation is not currently available in HTML format on the Internet, I decided to re-print this how-to topic here in order to help developers more easily find this information and utilize it in their installers if it makes sense.

I had to make a couple of small modifications to the topic that is in the WiX documentation because the topic includes links to other documentation topics, but the rest is a verbatim reprint of the documentation topic written by Neil. This how-to requires some basic WiX authoring knowledge in order to fully comprehend and use. If anyone tries out these steps and runs into any issues, please feel free to leave a comment at the end of this post or contact me and I can try to help get you unblocked.

Also, as a side note - the steps listed below are essentially the same way that XNA Game Studio setup (which uses WiX v3.0 as described here) installs the parts of the DirectX 9.0c runtime files that are needed for XNA Framework-based games.

How To: Install DirectX 9.0 With Your Installer

Applications that require components from DirectX 9.0 can benefit from including the DirectX 9.0 Redistributable inside their installer. This simplifies the installation process for end users and ensures the required components for your application are always available on the target user's machine.

DirectX 9.0 can be re-distributed in several different ways, each of which is outlined in MSDN's Installing DirectX with DirectSetup article. This how to describes using the dxsetup.exe application to install DirectX 9.0 on a Vista machine assuming the application being installed only depends on a specific DirectX component.

Prior to redistributing the DirectX binaries you should read and understand the license agreement for the redistributable files. The license agreement can be found in the Documentation\License Agreements\DirectX Redist.txt file in your DirectX SDK installation.

Step 1: Add the installer files to your WiX project

Adding the files to the WiX project follows the same process as described in the topic How To: Add a file to your installer in wix.chm. The following example illustrates a typical fragment that includes the necessary files:

DirectoryRef Id="APPLICATIONROOTDIRECTORY">
<Directory Id="DirectXRedistDirectory" Name="DirectX9.0c">
<Component Id="DirectXRedist" Guid="PUT-GUID-HERE">
<File Id="DXSETUPEXE"
Source="MySourceFiles\DirectXMinInstall\dxsetup.exe"
KeyPath="yes"
Checksum="yes"/>
<File Id="dxupdate.cab"
Source="MySourceFiles\DirectXMinInstall\dxupdate.cab"/>
<File Id="dxdllreg_x86.cab"
Source="MySourceFiles\DirectXMinInstall\dxdllreg_x86.cab"/>
<File Id="dsetup32.dll"
Source="MySourceFiles\DirectXMinInstall\dsetup32.dll"/>
<File Id="dsetup.dll"
Source="MySourceFiles\DirectXMinInstall\dsetup.dll"/>
<File Id="DEC2006_d3dx9_32_x86.cab"
Source="MySourceFiles\DirectXMinInstall\DEC2006_d3dx9_32_x86.cab"/>
</Component>
</Directory>
</DirectoryRef>

The files included are the minimal set of files required by the DirectX 9.0 install process, as described in the MSDN documentation. The last file in the list, DEC2006_d3dx9_32_x86.cab contains the specific DirectX component required by the installed application. These files are all included in a single component as, even in a patching situation, all the files must go together. A Feature element is used to create a feature specific to DirectX installation, and its Display attribute is set to hidden to prevent the user from seeing the feature in any UI that may be part of your installer.

Step 2: Add a custom action to invoke the installer

To run the DirectX 9.0 installer a custom action is added that runs before the install is finalized. The <CustomAction>, <InstallExecuteSequence> and <Custom> elements are used to create the custom action, as illustrated in the following sample.

CustomAction Id="InstallDirectX"
FileKey="DXSETUPEXE"
ExeCommand="/silent"
Execute="deferred"
Impersonate="no"
Return="check"/>

The CustomAction element creates the custom action that runs the setup. It is given a unique id, and the FileKey attribute is used to reference the installer application from Step 1. The ExeCommand attribute adds the /silent flag to the installer to ensure the user is not presented with any DirectX installer user interface. The Execute attribute is set to deferred and the Impersonate attribute is set to no to ensure the custom action will run elevated, if necessary. The Return attribute is set to check to ensure the custom action runs synchronously.

The Custom element is used inside an InstallExecuteSequence to add the custom action to the actual installation process. The Action attribute references the CustomAction by its unique id. The Before attribute is set to InstallFinalize to run the custom action before the overall installation is complete. The condition prevents the DirectX installer from running when the user uninstalls your application, since DirectX components cannot be uninstalled.

Step 3: Include progress text for the custom action

If you are using standard WiX UI dialogs you can include custom progress text for display while the DirectX installation takes place. The <UI> and <ProgressText> elements are used, as illustrated in the following example.

UI>
<ProgressText Action="InstallDirectX">Installing DirectX 9.0c</ProgressText>
</UI>

The ProgressText element uses the Action attribute to reference the custom action by its unique id. The value of the ProgressText element is set to the display text for the install progress.

Note: When you build an MSI using the above steps, you will see ICE03 warnings reported for a couple of the DirectX 9.0c setup files. The warnings will look like the following:

warning LGHT1076 : ICE03: String overflow (greater than length permitted in column); Table: File, Column: Language, Key(s): DXSETUP.exe
warning LGHT1076 : ICE03: String overflow (greater than length permitted in column); Table: File, Column: Language, Key(s): dsetup32.dll

These warnings are caused by the language metadata for these files being too long for one of the column definitions in Windows Installer. These warnings will not cause any installation problems for the MSI that you create, so you can safely ignore these warnings.

<update date="11/26/2008"> Added a note about ICE03 warnings that will occur when building an MSI using the steps in this blog post. </update>

Comments

Anonymous
November 24, 2008
This was a very helpful post but I did run into one issue that's more annoying than harmful. When I run the WiX build, it throws two ICE warnings: warning LGHT1076 : ICE03: String overflow (greater than length permitted in column); Table: File, Column: Language, Key(s): DXSETUPEXE warning LGHT1076 : ICE03: String overflow (greater than length permitted in column); Table: File, Column: Language, Key(s): dsetup32.dll I suspect these warnings are because there are multiple language localizations available for both dxsetup.exe and dsetup32.dll but after extensive searching and reviewing the WiX documentation, I couldn't find anything about how to prevent these warnings from appearing. I was hoping you might know how to get rid of these warnings or know somebody who does.
Anonymous
November 26, 2008
Hi Ianderson - The default Windows Installer schema for the File table allows 20 characters for the Language column. Those 2 DirectX setup files are intended to be multi-lingual, but the way their meta-data is configured, the language information is reported as a comma-delimited list of language IDs that ends up being longer than 20 characters. This ICE03 warning isn't going to hurt anything, and you can't avoid it without changing the DirectX setup files (which I don't recommend). I'd suggest doing one of the following:

Noting that this warning is benign and not worrying about it in your build process.
Suppressing ICE03 for your build process to avoid being informed of this warning every time you build. This has the drawback of also masking any other ICE03 issues that you might have in your MSI, and the other issues could be more serious because ICE03 covers a range of issues that cause varying degrees of problems. You can see the types of issues that ICE03 checks for in the MSDN topic at http://msdn.microsoft.com/library/aa368798.aspx. I'll add a note to this blog post about the ICE03 warning for others who read this in the future.

Partilhar via