Michael Creasy's blog : How To

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

mcreasy — Tue, 12 Oct 2004 21:26:00 GMT

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.

Using FindService and PlayMedia to change the TV channel in Media Center

mcreasy — Tue, 09 Mar 2004 19:04:00 GMT

If you've used the MSN TV pages on Online Spotlight in Media Center you might have noticed buttons on some pages to tune to MSNBC or to The Weather Channel. The page uses the Media Center API FindService to find which channel MSNBC is in your particular channel line up and then uses PlayMedia to change the channel (including starting TV if it is not currently in use). Here's a script sample that shows how it works:

function watchMSNBC()
{
    var rgServiceIDs = MCE.FindService("msnbc", ""); 
    if (rgServiceIDs.Length == 1) 
    { 
         MCE.PlayMedia(0, rgServiceIDs(0));
    }
    else 
    {
        // MSNBC isn't in the channel listing (or there are multiple channels called MSNBC)
    } 
}

First of all the code calls FindSerivce with the callsign of the channel, in this case "msnbc", the second parameter is used to find a term in the description of the channel - you'd use this if you wanted to tune to a channel that you didn't know the callsign of - for example you might want to tune to the local ABC channel without having to know the callsign for the channel in each local market. FindService returns an array of channels that match the required attributes; in this case we're assuming that only one channel will be found. Finally we start the channel playing using PlayMedia. The first parameter is the type of media we want to start playing, in this case 0 for TV. The second parameter is the ID of the channel that we want to tune to. Instead of tuning to a particular channel using FindService it's possible to tune to a particular show if it is currently playing using FindProgram, but more on that another time.

This posting is provided "AS IS" with no warranties, and confers no rights.

Hello World - Media Center Dialogs

mcreasy — Tue, 02 Mar 2004 18:45:00 GMT

The Media Center API has a function to displays dialogs, similar to the ones Media Center uses itself. An HTML application can take advantage of these to ask the user a question, or simply display a notification. Here's a simple example of how to create one:

<HTML>
<BODY BGColor="#0121BA">
<SCRIPT>

    function IsMCEEnabled()
    {
        return true
    }
    
    var MCE, Message, Caption, Timeout, Buttons, Modal, ReturnValue
    MCE = window.external.MediaCenter();
    Caption = "Hello World";
    Message = "This is a Media Center Dialog";
    Timeout = 10;
    Buttons = 1;
    Modal = true;

    ReturnValue = MCE.Dialog(Message, Caption, Buttons, Timeout, Modal);
</SCRIPT>
</BODY> 
</HTML>

Lets take a look at what this does. First I've implemented a function called IsMCEEnabled, this lets Media Center know that the page was designed for Media Center. Next I've declared the variables I'll be using to create my dialog and finally I've created the dialog itself. The usage of most of the parameters in the Dialog function are obvious, but some need a little bit of explanation. "Buttons" is a number that corresponds to the buttons to be displayed on the dialog in the following way:

Value	Button
1	OK button
2	Cancel button
4	Yes button
8	No button

Combining the values allows you to specify multiple buttons, for example if "Buttons" had a value of 3 then an OK button and a Cancel Button would be created on the dialog, 5 would put an OK button and a Yes button on the dialog.

"Timeout" is a value in seconds that the dialog is displayed for, in this case ten seconds. Setting the value to 0 will display a modal dialog until it's dismissed by the user, for a non-modal (also called modeless and semi-modal) dialog it will disappear five seconds. Whether a dialog is modal (center of the display and blocks access to the page behind it and prevents and navigation) or non-modal (appears at the bottom of the display and doesn't prevent access to the page or navigation) is controlled by a boolean which in this case I've named "Modal" - true creates a modal dialog and false a non-modal dialog.

Finally there's the return value of the Dialog function - this lets the page know what button a user pressed on the dialog, or if the dialog closed as a result of the timeout - note this only applies to modal dialogs, non-modal dialogs always return the same value because they are displayed asynchronously - so the return value will be created while the dialog is still on the screen, for this reason non-modal dialogs are best used for notification purposes. Modal dialogs on the other hand block further script execution on the page until the user responds to them or the timeout occurs. The return values fall into the following categories:

Value	Action
0	OK button was pushed
1	Cancel button was pushed
2	Yes button was pushed
3	No button was pushed
5	The dialog closed due to the timeout
6	Dialog displayed (non-modal dialogs)

That's all there is to it!

Creating a web page that's designed for Media Center (part one)

mcreasy — Mon, 23 Feb 2004 22:35:00 GMT

Previously I wrote about creating a MCL file to point to a web page so it could be viewed in Media Center. This time I'm going to explain how to create a web page that is designed for use in Media Center.

Web pages for Media Center need to be designed with a number of factors in mind:

The page will be viewed from 10', not 2' foot like a normal page
The user may not have a keyboard and mouse - they may just have a remote control
The display device might be a TV not a monitor, so the user may be unable to see the edges of your page due to overscan

Lets start by creating a basic page. Use Notepad (or your text editor of choice) to create a new HTML file that looks like this:

<HTML>
    <SCRIPT>
    function IsMCEnabled()
    {
        return true;
    }
    </SCRIPT>
    <P>Hello Media Center</P>
</HTML>

Now create a MCL file that points to this new page and place it in "c:\documents and settings\all users\start menu\programs\accessories\media center\media center programs\". Start up Media Center and in More Programs you should find a link to your page. Click the link and you'll see your page. You'll have noticed that you didn't get a warning message about the page not being designed for Media Center when the page was displayed. That's because we included that little fragment of script. When Media Center loads the page it checks to see if a function called IsMCEEnabled is defined and calls it to see if it returns true. If the function returns true then Media Center knows the page has been designed for Media Center and if not it displays that warning message.

So now we have a page that Media Center can easily display. It doesn't look very good from a distance though, so lets do something about that. Edit the file and change

<P>Hello Media Center</P>

<P style="FONT-SIZE: large">Hello Media Center</P>

Now when viewing the page in Media Center the text should be readable from a distance, it's still stuck in the top left corner of the page and might not be visible to a user viewing the page on a TV. Move it down and to the right slightly by changing the line to be:

<DIV style="DISPLAY: inline; LEFT: 30px; WIDTH: 208px; 
POSITION: absolute; TOP: 30px; HEIGHT: 32px">
<P style="FONT-SIZE: large">Hello Media Center</P></DIV>

Suddenly it looks much more complex, but all we've done is add a <DIV> tag the specifies a region on the page and displays the text there. If you use an editor such as Visual Studio you can create these elements automatically by using the HTML Label component in the toolbox. FrontPage has similar functionality. View this page in Media Center now and you'll see the text has moved and should be easier to see.

That's enough for part one for now. The SDK has some samples of HTML pages if you can't wait for part two which will include steps to enable the use of the remote control to navigate a page.

Creating links to web pages to view in Media Center

mcreasy — Tue, 03 Feb 2004 20:49:00 GMT

In Media Center there's a page called “More Programs” that contains links to applications that have been installed for use in Media Center. It's easy to add a link on that page to a web page that you might want to view from Media Center, perhaps the current traffic conditions (very useful in Seattle) or the weather forecast (normally rain in Seattle).

Links are stored as MCL files that contain a small bit of XML that looks like this:

<application url="http://server/path/page.html" name="Name of the page"
bgcolor="RGB(1,33,186)"
startimage=".\StartImage.png"
thumbnailImage=".\thumbnailImage.png"
sharedviewport="false">
</application>

Set the url to the page you want to use and change the name to the name you want to appear in “More Programs” - You can also specify a path to a PNG file to use as a thumbnail in the thumbnailImage and startimage attributes. The image referenced by thumbnailImage will appear in “More Programs“ as the link your page and the one referenced by startimage will appear on the Media Center start page if your link appears there. bgcolor specifies the background colour of Media Center (in this case a shade of blue similar to the one Media Center uses) - this will appear around the shared view port and around the transport controls that appear when you move your mouse - you can set it to any RGB value. The shared view port is the area of the display that video and music appear in when they are not the primary experience - it appears in the lower left corner of the display. You can tell Media Center to show or hide the shared view port while you are viewing the page you are linking to by setting the property to true or false. In this case false is probably the best option as the page you are linking to will not be designed for Media Center and so the shared view port will hide some of the information on the page. Don't worry though, your media will continue to play.

Now that you've created your MCL file you need to place it somewhere that Media Center can find it That place is “c:\documents and settings\all users\start menu\programs\accessories\media center\media center programs\“. You can also get to this folder from the Start menu by clicking the Start button, then All Programs, Accessories, Media Center and then right clicking on “Media Center Programs“ and clicking “Open“.

You can now view the page you've linked to by starting Media Center and going to “More Programs“ from the start page and you should see a link with the thumbnail image you specified (if you specified one - you don't have to). Click the link to go to the page. You'll probably be presented with a dialog saying that the page isn't designed for Media Center. If you click “View Now“ you'll see the page right away, and if you click “View Later“ a link will be created on your desktop so you can go to the page later. Pages that aren't designed for Media Center may not display very well when using a TV as a display and may be difficult to read from a distance. I'll cover how to design a page for Media Center in a future post.