Building setup packages for Media Center add-ins

  • Article

Windows XP Media Center Edition supports two types of add-ins - hosted HTML applications and Media Center add-ins (also known as background add-ins). I will cover hosted HTML applications separately. I will focus on creating setup packages for Media Center add-ins in this article.

I have created an example setup package for a Media Center add-in using WiX that I will describe in more detail in the rest of this article. You can find a downloadable example of the WiX source file for a Media Center add-in setup that I will use in the rest of this article at this location. I tried to create this example using what appear to be the steps that would be needed for a "typical" Media Center add-in, so hopefully this will be useful for most add-ins that you might need to create setup packages for.

Payload contained in an add-in setup package

A Media Center add-in is a managed code assembly that can call Media Center extensibility APIs to interact with and control Media Center. There are a few types of files that comprise a background add-in:

  • A managed assembly
  • An XML file that is used to register the add-in so that Media Center knows how to launch it
  • A bitmap that is displayed in the Media Center UI that can be clicked on to launch the add-in
  • Other resource files used by the add-in

Actions performed in an add-in setup package

The setup for the example Media Center add-in that I have created consists of the following activities:

  1. Validate that the user launching setup has administrative privileges
  2. Validate that the OS being installed on is Windows XP Media Center Edition, contains the correct version of Media Center and contains the file %windir%\ehome\RegisterMceApp.exe that will be needed later
  3. Install the files - the example installs a managed DLL, an XML file and a PNG file
  4. Launch %windir%\ehome\RegisterMceApp.exe as a custom action to register the add-in with Media Center

More details about the design of an add-in setup package

There are a few important design considerations that have been applied while creating this example setup package for a Media Center add-in.

1. Media Center add-in assemblies should be installed to the GAC

The Media Center SDK states that add-in assemblies must be installed in the global assembly cache (GAC) or to %windir%\ehome (the local directory where Media Center files are installed to) in order for Media Center to be able to load them. As a best practice, add-ins should be installed to the GAC as opposed to %windir%\ehome. This is accomplished in the sample add-in by adding the attribute Assembly=".net" to the File element that represents the add-in assembly:

<File Id="myaddin.dll" Name="myaddin.dll" KeyPath="yes" src="myaddin.dll" Checksum="yes" Vital="yes" Assembly=".net" />

2. The way that RegisterMceApp.exe is run is important

As I previously described in this blog post, RegisterMceApp.exe will return non-zero values (which indicate failure to Windows Installer) if an application that is already unregistered is unregistered again or if an application that is already registered is registered again. Because of this, the example setup package runs RegisterMceApp.exe /u and ignores the return code and then runs RegisterMceApp.exe in installation mode and checks the return code during initial installation and repair. During uninstall, it runs RegisterMceApp.exe /u and ignores the return code.

3. An add-in setup package should check for its prerequisites

An add-in should check and make sure that the OS it is installed on is a valid Media Center OS and that it is running the version of Media Center that the add-in is designed for. The Media Center SDK does not document any official ways of detecting Media Center OS versions, so I chose to use the registry-based method that Media Center hotfixes use for the example add-in. The following registry key/value can be used to identify Media Center version:

[HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Media Center]
Ident = REG_SZ

  • Ident value 2.8 represents Media Center 2004
  • Ident value 3.0 represents Media Center 2005
  • Ident value 3.1 represents Media Center 2005 with Update Rollup 1
  • Ident value 4.0 represents Media Center 2005 with Update Rollup 2
  • Ident value 5.0 represents Media Center on Windows Vista

The example add-in package checks that the OS is in the Windows XP family by validating that VERSIONNT = 501 and also checks for Media Center 2005 with Update Rollup 2.

The example add-in setup package also validates that the file %windir%\ehome\RegisterMceApp.exe exists on the system at the beginning of setup because it is needed later in the setup process.

Finally, the add-in setup package has a launch condition that checks for administrative rights by using the Privileged property and blocks setup from running if the user running setup does not have administrative rights.

Using the example to create other add-in setup packages

You can use the following steps to create an MSI-based setup package for your Media Center add-in using my example as a template:

1. Download the latest build of version 2.0 of the WiX toolset and save it to your local hard drive

2. Download the example WiX source file for a Media Center add-in that I posted and save it to your local hard drive

3. Update the WiX source file as appropriate for your add-in:

  • Provide real product name/description/version information at the top
  • Provide the real names of the files you need to install
  • Use a tool such as GuidGen to create GUIDs for the product code, upgrade code and any components you will be installing
  • Update the prerequisite checks if necessary so that your setup will support the appropriate Media Center version for your add-in

4. Compile your add-in MSI using the following command lines and WiX tools:

  • candle.exe <full path to your WXS file> -out <your WIXOBJ file>
  • light.exe <your WIXOBJ file> WixUI.wixlib -loc WixUI_en-us.wxl -out <your MSI file>

Note: the files candle.exe, light.exe, WixUI.wixlib and WixUI_en-us.wxl are all included in the WiX toolset. The toolset also includes a help file (named wix.chm) that you can use as a reference if you want to create more advanced MSI packages using the above example and information as a basis.