How to build an Add-in for Windows Media Center Edition 2005

First, the basics...

What is an Add-in?  Add-ins are applications written in managed code (.NET Framework 1.0) that run inside Media Center.  They have access to the Media Center API as well as the usual .NET libraries.

What do I need to build an Add-in?  Not much really, you could build an add-in using notepad and then compile on the command line.  If you want to use a GUI for building an add-in then Visual Studio .NET is the way to go.  Note that I recommend using the original version of Visual Studio .NET if you have it not the 2003 release.  This is because Media Center uses the 1.0 version of the .NET framework and so you need to compile your add-in to the 1.0 framework as well.  Visual Studio .NET 2003 allows you to compile applications against an older framework but not assemblies which is what add-ins are.  If you only have the 2003 release of Visual Studio .NET you can still use it to build add-ins but you'll have to use the command line to compile the add-in so you can use the 1.0 version of the compiler.

Creating a very basic add-in

First a warning.  This add-in does nothing but display a dialog, you can do a lot more than display dialogs; I encourage you to try and avoid displaying dialogs as much as possible as they can be a distraction to the user, especially if they're watching TV.  That said, here's the code:

using System; 
using System.Collections;
using Microsoft.MediaCenter.AddIn;
namespace MediaCenter.Sample.AddIn
{
public class HelloWorldAddIn : MarshalByRefObject, IAddInModule, IAddInEntryPoint
{
void IAddInModule.Initialize(IDictionary dictAppInfo, IDictionary dictEntryPoint)
{
// Write any initialization code here
}
void IAddInModule.Uninitialize()
{
// Write any clean up code here
}
void IAddInEntryPoint.Launch(AddInHost host)
{
Object[] oButtons = new Object[1];
oButtons[0] = 1;
host.HostControl.Dialog("Hello World", "My First Add-In",
oButtons,10,false,null,null );
}
}
}

That's how simple it is!

Let me explain the different sections of the code.  The add-in implements three interfaces, MarshalByRefObject, IAddInModule and IAddInEntryPoint.  The last two are what make an add-in an add-in.  You'll need to implement three methods in your add-in as you can see above:

  • IAddInModule.Initalize - this gets called when the add-in is intialized.  When it gets called you're provided with two dictionaries which contain information from the registry - more on those another time.
  • IAddInModule.Unitialize - as you've probably guess from the name, this gets called when the add-in has finished execution it's Launch method and will be shortly before the add-in is unloaded.
  • IAddInModule.Launch - this is where the fun stuff happens - it's the equivalent of "main" in a normal app.  When it gets called you're handed an AddInHost object, this object is what lets you access all the Media Center APIs.

This add-in makes use of dialogs that are new to this release of Media Center, the main difference being the ability to include a picture or icon in the dialog - something that I'm not doing in this example.  See the documentation for full details of the API call (note I'm using the overloaded version which is docuemented on the lower half of the linked page).

OK, so that's an add-in but that's still not quite everything you'd need to do to build it.  Assuming you're using Visual Studio.NET...  Use the wizard to create a new C# Class Library (File, New, C#, Class Library) and copy and paste the above code into the file it creates. 

The add-in needs to be signed so you'll have to specify a path to a key pair in Assembly.cs, see the docs for the details if you're not familiar with the process.

Now you need to include a reference to the Microsoft.MediaCenter.dll file in order to build the add-in.  In the solution explorer right click on References and select "Add Reference..." then browse to c:\windows\ehome and select Microsoft.MediaCenter.dll.

You should now be able to build your add-in.  If you need to compile from the command line there are instructions here.

Now that your add-in is built you need to register it with Media Center.

Registering an add-in

Registering an add-in is handled by an XML file which contains the registration info and a command line tool called RegisterMCEApp.exe

Here's the XML to register this application:

<application title="Hello World Add In" id="{CCA64374-182E-43d8-9F7A-6DBBC4AEA4F0}"> 
   <entrypoint id="{CCA64374-182E-43d8-9F7A-6DBBC4AEA4F1}" addin="MediaCenter.Sample.AddIn.HelloWorldAddIn, HelloWorldAddIn, Version=1.0.0.0, Culture=neutral, PublicKeyToken=43525660dcbb828f, Custom=null" title="Hello World Add In" description="A sample add in for Media Center" > 
      <category category="More Programs"/> 
   </entrypoint> 
</application>

There are a couple of parts to the registration file:

  • Application tag - The application tag has in this example two attributes - title which is the name of the application and an id, this is a GUID which serves as a unique identify for the application.
  • Entrypoint tag - Each application can have multiple entrypoints.  An entrypoint corresponds to a place in Media Center that the application can be launched from as specified by the category tag.  Each entrypoint must have an id, which is another GUID, but this time is a unique identify of the entrypoint.  The entrypoint specifies the full strong name of the assembly which contains the add-in (NOTE: you will need to change the public key token to your public key token for this example to work) and in addition the title of the entrypoint and a description are specified.
  • Category tag - this specifies where in Media Center the application will appear from.  This example is launched from More Programs, specifying a category of "Background" would let the add-in be launched automatically when Media Center starts up.

See the docs for more details.

Add your add-in to the GAC using gacutil (note when deploying an add-in you should register the assembly in the GAC at install time using an MSI) - the command line is "gacutil /i <path to assembly>".

The last step is to register the add-in with Media Center.  Take the XML sample above and save it as an XML file.  Now from a command line run RegisterMCEApp.exe like this:

RegisterMCEApp.exe <path to xml file>

Start-up Media Center and go to More Programs, you should see a generic look icon labeled "Hello World Add In", click the icon and the "Hello world" dialog will appear.

That's all there is to it :-)

Download this sample. ("Use of included script samples are subject to the terms specified at http://www.microsoft.com/info/cpyright.htm" )

See http://msdn.microsoft.com/mce for more info on developing for Media Center.