Registering an Add-in with Media Center

Registering your add-in can be accomplished in one of two ways: your add-in's installation program can register the add-in by invoking the RegisterMCEApp.exe command-line utility, or a previously registered add-in or HTML application can call the ApplicationInfo.RegisterApplication or MediaCenter.RegisterApplication method on the add-in's behalf. Unless you already have a registered HTML application or add-in that can call RegisterApplication on behalf of the new add-in, using RegisterMCEApp.exe is the most appropriate way to register an add-in.

Both registration methods involve using XML to define your add-in and its entry points. The RegisterMCEApp.exe utility takes the XML code in the form of a file, while the RegisterApplication method takes the XML code as a string.

The XML code used to register an add-in consists of one application element, one or more entrypoint elements, and one or more category elements. The application element specifies the title of your add-in and its globally unique identifier (GUID).

The entrypoint elements define the entry points for your add-in. For an on-demand add-in, the XML code must contain one entrypoint element for each entry point that the add-in supports. The entrypoint element must include the addin, id, and title attributes.

The addin attribute specifies several pieces of information about the add-in, including the following:

• The full name of the add-in's class that inherits from the IAddInModule interface.
• The name of the add-in's assembly.
• The strong-name information for the add-in. This information must be an exact match with the strong-name information stored in the add-in's assembly. For more information, see Creating Strong-Named Add-ins.

The id attribute specifies the GUID for the entry point, and the title attribute specifies a descriptive string used to identify the add-in. Finally, each entrypoint element must include one or more category elements. For an on-demand add-in, the category elements identify the locations in the Media Center shell where the entry point is to appear.

The following example shows XML for registering an on-demand add-in that has one entry point in the More With This\Audio\Album category.

<application title="My MC Application" id="{A0E0DD28-6C4C-40c4-A8A1-F7B686786940}" CompanyName="Microsoft">
    <entrypoint id="{A0E0DD28-6C4C-40c4-A8A1-F7B686786941}" 
            addin="MediaCenter.Sample.AddIn.MWTAddIn, MWTAddIn,Version=1.0.1000.0,PublicKeyToken=374543c4fed4eeb0,Culture=Neutral"
            title="My Album Item" 
            description="Item 1" 
            ImageUrl=".\Item1.png">
        <category category="More With This\Audio\Album"/>
    </entrypoint>
</application>

The XML registration code for a background add-in is similar to the code for on-demand add-ins, except that the category attribute of the entrypoint element must be set to "Background".

The following example shows XML code for registering a background add-in.

<application title="Sample Add-In" id="{7121989D-47C4-4e9b-9B12-7DDCDAC15020}">
    <entrypoint id="{7121989D-47C4-4e9b-9B12-7DDCDAC15021}" 
            addin="MediaCenter.Sample.AddIn.SampleAddIn, SampleAddIn,Version=6.0.3000.0,PublicKeyToken=26266fd5edc3ffc0,Culture=Neutral" 
            title="Sample AddIn" 
            description="My sample add-in">
        <category category="Background" />
    </entrypoint>
</application>

The GUIDs used in the id attribute of the application and entrypoint elements are standard GUIDs. To generate GUIDs for your add-in, use a GUID-generating utility such as guidgen.exe from Microsoft. Debugging an add-in typically involves examining the add-in's registry entries. To make debugging easier, consider using consecutively numbered GUIDs for your add-in. That way, the GUIDs appear as adjacent entries in the registry.

To register an add-in by using RegisterMCEApp.exe, you must first store the XML registration code in an XML file. Then, you can pass the file to the utility, as shown in the following example, where %windir% is the path to your computer's Windows directory and <regFile.xml> is the name of the XML file that contains the application, entrypoint, and category elements.

%windir%\ehome\RegisterMCEApp.exe <regFile.xml>

Using the ApplicationInfo.RegisterApplication or MediaCenter.RegisterApplication method is similar to using RegisterMCEApp.exe, except that you pass the XML elements to the method as a string instead of a file. If you call the RegisterApplication method for an add-in that is already registered, Media Center will remove the previous registration before re-registering the add-in.

An add-in or HTML application can unregister from Media Center by calling the ApplicationInfo.RegisterApplication or MediaCenter.RegisterApplication method, setting the fUnRegister parameter to true. The setup program for your add-in can also unregister the add-in by running RegisterMCEApp.exe with the /u command-line switch. Either way, unregistering removes information about the add-in from the system registry, and causes the add-in's entry points to be removed from the Media Center UI. Unregistering an add-in does not delete any of the add-in's files or remove any of its registry entries other than those related to its entry points.

See Also

• Installing and Registering an Add-in