How To Build An Add-In For Windows Media Center Edition 2005


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.

Comments (34)

  1. Roy J. Salisbury @ VsDevCentral says:

    Here I have been waiting for the SDK so that I could write a real app for MCE, but at appears that the PlugIn’s can only pop up dilaogs, and not an entire interface (i.e., RSS Reader). That sucks!

  2. That’s not quite true Roy, if you need a full UI, you can do that using HTML.

  3. Roy J. Salisbury @ VsDevCentral says:

    Correct me if I am wrong, but are ANY of the screens in MCE written using HTML (besides the "Online Spotlight")? Event Microsoft knows that to get a nice looking UI, you can’t do it in HTML (you need DirectX).

    The "Online Spotlight" is a good example. That has got to be the worst looking "out of the box" UI that I have seen come from Microsoft (for MCE 2005).

  4. I rather like the new version of Online Spotlight, but that’s just. There are a few other HTML pages in Media Center, mainly things like the privacy policy.

    It’s possible to create great looking UI using HTML, have a look at some of the new apps on Online Spotlight, I think a lot of the partners have done a great job. We know people would like more options than HTML, but I can’t say much more than that for now.

  5. Roy J. Salisbury @ VsDevCentral says:

    Well, I will once again try to create an HTML based UI for MCE. Please contact me (roys@express-is.net) if MS needs input/testers for something that it may or may not be working on. I have numerous application ideas for MCE, but need a solid UI that can’t really be done in HTML.

  6. Patrick Tsai says:

    I am disappointed that MCE add-in can only use HTML-style UI. 🙁

    I’ve saw other HTML add-ins by some third-party companies and they look slow and bad when compared with DirectX-based UI.

  7. Jeff Atwood says:

    Yeah, the HTML options pretty much suck.

    I built some WinForms controls that adopt the MCE look and feel, and that didn’t work out well either (transparency is HARD in WinForms!) Sample project and screenshot available:

    http://www.thegreenbutton.com/community/shwmessage.aspx?ForumID=30&MessageID=31768&TopicPage=3

    Basically we need access to your DirectX-based UI elements.

  8. Niels Madsen says:

    This is a bit embassing, but i can’t get the hello world to work…

    I use vs.net 2002, have signed the code, installed the dll in the gac and then registered it in MCE. And the "app" shows up – but does absolutly nothing. What am i missing?

    Thanks!

    Niels

  9. Sean McLeod says:

    Talking about DirectX and the MCE interface, what happens with Media Center Extender Devices (MCX)? AFAIK DirectX is still not remoted by RDP, so what did MS do in terms of remoting the UI for MCXs?

    Did they recode the whole MCE interface for MCX sessions and avoid using DirectX, just using plain GDI+?

    Or did they find a way to remote DirectX via RDP? OpenGL is remoted via RDP, afaik in this case a software renderer is used and the bitmap bits produced by the software renderer are then intercepted by the RDP server and remoted. Not sure why MS don’t use the same approach with DirectX and RDP.

    Or maybe they did with MCX devices?

  10. Tim H. says:

    Tried this and the app registers, but it will not launch the dialog.. I also tried using NavigateToPage, neither calls seem to work. Any thoughts?

  11. To all that were having problems, I had an error in the addin parameter of the entrypoint tag in the registration file. I’ve fixed that and it should work, I’ve also just posted a copy of it for download.

  12. Jeff Fansler says:

    I haven’t really played with it much, but I downloaded your sample files and ran the install.bat. When I run the app from media center nothing happens. Am I doing something wrong?

  13. Jeff,

    Hard to say really. My guess would be that gacutil.exe is not in your path when you run install.bat, try running it from a command line and you’ll probably see that gacutil.exe isn’t found.

  14. Jeff Fansler says:

    I suspect you were right Michael. I ran the install again using my visual studio command prompt since it has all the paths defined and everything works. Thanks!