Use this guide to replace the button in the application template with the one from the Z sample application. This is a good example of separation of logic/data from the visuals enabling development of each to remain separate in a distributed development environment.

1.       Start a new application with the Windows Media Center Application template and complete the application as outlined in the readme.htm file.

2.       Using Windows Explorer copy the following files from the Z sample application source folder into the corresponding new application folders, overwriting existing files if present:

a.        \Markup\Button.mcml

b.       \markup\Styles.mcml

c.        \images\ButtonFocus.png

d.       \images\ButtonNonFocus.png

3.       Select the Images folder in Solution Explorer.

4.       Select Project > Add Existing Item from the menu.

5.       In the Add Existing Item dialog:

a.        Select Image Files in the Files of type drop down list.

b.       Navigate to the \Images folder for the project and multi-select ButtonFocus.png and ButtonNonFocus.png by clicking on them with the mouse while holding down the Control key on the keyboard.

c.        Click the Add button.

6.       Open Resources.resx for editing.

7.       In Resources.resx:

a.        Press Control+2 on the keyboard to switch to images.

b.       Drag and drop ButtonFocus.png, ButtonNonFocus.png and ButtonNonFocus.png from the Solution Explorer into Resource.resx to embed these files in the assembly.

8.       Double click \Markup\Button.mcml in Solution Explorer for to open for editing.

9.       Find and replace every instance of "resx://Z/Z" with "resx://[ApplicationName]/[ApplicationName]" where [ApplicationName] is the name of your project. For example: "resx://Z/Z.Resources/Styles" would read "resx://Application1/Application1.Resources/Styles"

10.    Double click \Markup\Styles.mcml in Solution Explorer for to open for editing.

11.    In Styles.mcml:

a.        Delete the following MCML: <Image Name="ContainerImage" Source="resx://Z/Z.Resources/Container" NineGrid="40,40,40,40"/>

b.       Add the following MCML: <Color Name="BackgroundColor" Color="Black"/>

c.        Find and replace every instance of "resx://Z/Z" with "resx://[ApplicationName]/[ApplicationName]" where [ApplicationName] is the name of your project.

12.    Select Compile and test using DevInstall.cmd or create the MSI as outlined in readme.htm to install and test.

19.    Run “DevInstall.cmd /u” from a command prompt with Administrator privileges to perform a development install or uninstall using the MSI. Otherwise you will get a dialog box each time you launch Windows Media Center.

An updated version of the Windows Media Center Software Development Kit is now available for download from http://www.microsoft.com/downloads/details.aspx?familyid=a43ea0b7-b85f-4612-aa08-3bf128c5873e&displaylang=en. This is the same link as before so no need to change your bookmarks. These links also persist in the navigation section at http://blog.mediacentersandbox.com/.

The following is a summary of the key changes to the Windows Media Center Software Development Kit for this version:

• The Windows Media Center Application Step By Step document which helps you create a Windows Media Center application from an empty project using Media Center Markup Language (MCML), C# and Windows Installer XML (WiX).
• The C# project template has been revised and now includes Windows Installer XML (WiX) 3.0 scripts for generating a setup program to install the application. See the Readme.htm file when you create a new application with the template for more information. This application template is the same result you get from working completely through the new Step By Step document.
• The MCML file template has been revised to work better with the C# project template and includes the basic Properties, Locals, Rules, and Content elements typically needed.
• A Visual Studio solution for the MCML Sampler making it easier to search, copy, and paste from the markup and code files.

I'd like to take a moment to thank our community of developers over at http://discuss.mediacentersandbox.com who provided lots of feedback on the Step By Step document to make it a great resource for beginners.

Charlie

A good part of my professional life last year was taken up working with Showtime and Method (among others) to get Showtime Interactive built while we were still creating the Windows Media Center Presentation Layer platform (Media Center Markup Language + .NET 2.0).

Thanks to our friends over in developer envangelism you can learn more about what it took to build this experience at http://www.microsoft.com/casestudies/casestudy.aspx?casestudyid=4000000490.

Charlie

IgnoranceIsBliss continues his series on creating a Windows Media Center application using managed code (C#) and Media Center Markup Language (MCML). In his most recent post Stage 10 - Installing It he has the following to say about writing registry keys directly instead of using the Registration API:

1. Charlie, the Microsoft product director for Media Center extensibility (IE. the Media Center SDK) has informed me that MS won't guarantee that the method of registering plugins will remain the same. Of course, I then asked 'OK - then why do you TELL us to register them that way?' and there wasn't much of a response. I'm yet to see if this is still true in the newer version of the Media Center SDK.

2. If you run a 32 bit installation on a 64 bit version of Windows, your registry entries are placed in an entirely different tree. So the 64 bit version of Media Center can't actually see the keys you've created.. This means you MUST produce both a 64 and 32 bit version of your installer.

Microsoft themselves suggest you use WiX, which is an open source product of theirs that allows you to create installers - but since it's a complicated platform and I want to be able to take you through the basics without needing any additional software, I'm going to take you through the easy, but perhaps not officially supported method of adding registry keys directly.

In response...

A) The reason we provide an abstraction layer for the registry keys is simple: We can change the underlying methodologies for registering experiences without breaking the apps (or their installers). For example, suppose we change where Windows Media Center looks in the registry for applications. By writing registry keys yourself they may end up in a location we aren't polling -- and therefore the app won't appear. Using the API will always work even if we change things under the covers. Abstraction is good -- it helps you maintain forward compatibility.

B) There are a very few select OEM scenarios where writing the registry keys directly makes sense. Specifically, where you are using a single image for thousands of preinstalled machines. Outside of this specific scenario (i.e. if you aren't an OEM using this to prep machine images) there is no good reason to write the registry keys themselves, and to do so only increases the risk the installer will be possibly broken at some later date. I've even advised OEMs to use the Registration API during the preinstall phase rather than write registry keys.

C) We include writing the registry keys directly for those who are committed to only using a Visual Studio setup project. Effectively, the Windows Media Center Platform team does not recommend using the Visual Studio setup project because of it's inherent limitations (which are more than just this singular issue). As a bonus, using WiX also makes the installation solution accessible to folks using free tools (Visual C# 2005 Express Edition) as well.

D) WiX does carry a higher learning curve. Along with that comes much more granular control over the installer and, perhaps more importantly, a fundamental understand of what is happening when the user installs the application. FWIW, I personally found it difficult at first, but now that I've got a pretty good understanding of the pattern in the WXS file it's much more 'friendly' to me compared to a Visual Studio setup project -- which abstracts everything out too much in my opinion, and I'm not even a setup guru and love the abstraction to make it easier (just ask Aaron).

D) If you do follow IgnoranceIsBliss logic, just remember it's pretty unfriendly to force a user to figure out which installer to use (32 bit or 64 bit) -- especially given the actual library is identical for both (you don't need to compile for each in the context of a Windows Media Center application). Make it simple -- have a single installer. That means using the Registration API and WiX.

E) We revised this SDK documentation with the last release (see http://msdn2.microsoft.com/en-us/library/bb189827.aspx) which quickly vectors the reader back to 'use the Registration API'. We will make further clarifying changes in the future.

IgnoranceIsBliss has done a pretty good job of giving you a guide to creating a Windows Media Center application -- just make sure you use his documents as a supplement to the information in the Software Development Kit -- not in lieu of.

Charlie

Matt Ivers has a pretty good article on Code4Fun titled Control Windows Media Center using a Windows Mobile 5 Device. I haven't tried it out yet, but looks like a solid tutorial on how to create a background application.

Charlie

An updated version of the Windows Media Center Software Development Kit is now available both online via MSDN at http://msdn2.microsoft.com/en-us/library/aa286546.aspx and download from http://www.microsoft.com/downloads/details.aspx?familyid=a43ea0b7-b85f-4612-aa08-3bf128c5873e&displaylang=en. These are the same links as before, so no need to change your bookmarks. These links also persist in the navigation section at http://blog.mediacentersandbox.com/.

This update was primarily designed to consolidate some whitepapers and technical articles and take into consideration some of the feedback we've been hearing over at http://discuss.mediacentersandbox.com/forums/.

The following is a summary of the key changes to the Windows Media Center Software Development Kit:

• Incorporation into CHM of previously separate MSDN technical articles and team blog postings.
• The MCML Preview Tool Launcher power toy is now included ‘out of the box’ (no separate install).
• Q and Z setup projects now based on WiX 3.0 (was WiX 2.0).
• Shortcuts for the MCML Preview Tool have been added to the Windows Vista Start Menu: One launches standalone, the other within Windows Media Center.
• Registry files (*.reg) added to the \Tools folder to enable / disable of launch debugging and error details.
• MCML Sampler source C# files (*.cs) files added.
• Minor fixes and tweaks to the Z sample application.
• Installs to the same c:\Program Files\Microsoft SDKs\Windows Media Center\v5.0 folder.
• Setup UI and the entry in Add/Remove Programs both refer to Windows Media Center Software Development Kit 5.1.

In addition, we've heard many times over the past few months that MCMLSampler is wonderful for demonstrating the individual pieces and parts of MCML, and the Q and Z applications are really helpful as well. The feedback concludes they are good resources -- for the advanced developer. What we've been missing is something to bridge the gap for the novice or intermediate developer. So a couple of us sat down and created the Windows Media Center Application Step By Step whitepapers.

These documents take you step by step through creating a simple Windows Media Center Application with Media Center Markup Language (MCML) for the visuals leveraging managed code and the Windows Media Center object model. Each major section is prefaced by an explanation of what will be accomplished in that section as well as links back to the online version of the SDK. We've also put together a second whitepaper which shows you how to use Windows Installer XML (WiX) to build a setup program for the application. Finally, we are making source code for both available which is the end result after working through both whitepapers.

Windows Media Center Application Step By Step

Word Format: http://play.mediacentersandbox.com/docs/WindowsMediaCenterApplicationStepByStep.zip
Adobe Acrobat Format (PDF): http://play.mediacentersandbox.com/docs/WindowsMediaCenterApplicationStepByStep.pdf

Windows Media Center Application Step By Step -- WiX Installer

Word Format: http://play.mediacentersandbox.com/docs/WindowsMediaCenterApplicationStepByStep.WiX.zip
Adobe Acrobat Format (PDF): http://play.mediacentersandbox.com/docs/WindowsMediaCenterApplicationStepByStep.WiX.pdf

Windows Media Center Application Step By Step -- Source Code

http://play.mediacentersandbox.com/docs/WindowsMediaCenterApplicationStepByStepSource.zip

As always, feedback is welcome either in comments here or in the forums at http://discuss.mediacentersandbox.com/forums/.

Update: I'm adding a mini-FAQ at the bottom as the comments and feedback arrives.

As part of the documentation updates for the upcoming revision of our Windows Media Center Software Development Kit I have been writing some topics on how to effectively use the MCML Preview Tool (MCMLPad.exe) during development. Since I've seen a few blog posts and discussion forums on the topic I thought I would preview this documentation for you, and ask for feedback and / or additional areas which need coverage. So, try this on for size...

Editing UI
The MCML Preview Tool is designed to assist in the development of individual pieces of UI and as such is specifically designed to NOT scale the MCML content you view therein when run in standalone mode. When run in Windows Media Center the MCML Preview Tool inherits the proportional scaling applied to all applications which run within Windows Media Center. There are some good reasons for this, among which my favorite is the the authoring and preview cycle when creating pieces of UI. You want to see your UI at full size, especially if working on some very nuanced / small feature of that UI. Because Windows Media Center scales the content proportionally to the window, the visual elements can get quite small when you want to switch quickly between your MCML authoring environment and the MCML Preview Tool. Compare the size of the button in each of the windows to the right of IDE window in this screenshot:

The MCML Preview Tool running in Windows Media Center is on the top and the standalone version is on the bottom (note: you can click on most of the images in this post for a life size view). As you can see, when editing the styling of the UI you want to be working at 100% -- otherwise it's just too small when you are fine tuning.

Evaluating Layout and Behavior
When run standalone, the MCML Preview Tool gives you the ability to see how your layout works and looks given different sizes and aspect ratios. Windows Media Center runs with two main aspect ratios in mind: 16:9 and 4:3. You can always set the monitor to some other resolution (example: 1920x1200 for 16:10) and run Windows Media Center at full screen to get different aspect ratios -- but this is rather tedious to do during development of the UI pieces. By contrast, you can run MCMLPad with a completely arbitrary size. For example, here I am testing the snowflake virtualization sample gallery at a 4:1 aspect ratio:

As I increase the overall size, the gallery grows to accomodate more rows and columns of data, and I can observe how it handles this scenario (including and Show or Hide animations). This is without having to change the panel which defines the 'gallery' holding the snowflakes in my application, and avoiding recompiling, installing to the GAC and registering in Windows Media Center as I edit. Here is the result -- note the item sizes don't change because there is no proportional scaling -- we simply see more snowflakes:

Page Variables
The MCML Preview Tool has a page concept, but it is distinctly different (and much more simple) than the one provided by Windows Media Center (the PageSession and HistoryOrientedPageSession classes). Granted, a 'page' is really <UI Name=Page> -- but the underlying functionality for what you expect a page to do within the overall platform is provided by Windows Media Center. A good way to think about this: The MCML Preview Tool is designed to work with the visual layer of the platform only. Once you get far enough along to test page behaviors it's time to switch over to testing the pieces / parts of the application with Windows Media Center as the host rather than the MCML Preview Tool. An even better approach is to test the page behavior very early in the application development cycle using wireframe resources. The simple button from MCML Sampler is a great example of UI to use to implement and test the layout and databinding which involves your page variables. Later on you replace Simple Button with the more beautiful, fully realized design.

Testing UI
When run standalone, the MCML Preview Tool allows you the flexibility to create a test harness for your UI. To demonstrate, I have created a simple test harness (download the sample solution here) for a button. Here is a screen shot:

Windows Media Center (top right) has the application (a compiled assembly) running which loads Menu.mcml allowing me to test the functionality of the button -- in this case, it makes a method call to display a Windows Media Center dialog. The standalone MCML Preview Tool window (bottom right) is the result of pressing F5 in Visual Studio which loads Test.mcml, designed to show all the different ways to instantiate the button using it's settable properties (again, the non-scaling is quite desireable here).

Taking this a large step further: Throughout the creation and testing of the Z sample application we used the power of layouts and rules in MCML to provide a mechanism to step through all of the the UI for Z. Here is what it looks like:

On the right we have each UI which defines an individual page within the Z sample application. You can select these items to load that 'page' (again, it's really a <UI> which, when combined with the HistoryOrientedPageSession becomes a bonified page in the application) into the larger, 4:3 constrained area on the left. This test harness is defined by Default.mcml in the sample code which ships in the SDK if you wish to adapt for use in your own applications.

To gain the Visual Studio F5 test harness functionality with the Z sample solution...

If you haven't previously done so...

• Launch a command prompt with administrator privileges.
• Navigate to C:\Program Files\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Z\.
• Run Command.CreateDevEnvironment.cmd.

...otherwise MCMLPad will report an exception and close when you use F5 in Microsoft Visual C# 2005 Express Edition because the Z test harness can't find the data.

Then make the following changes in Microsoft Visual C# 2005 Express Edition:

• Select Solution 'Z' (2 Projects) in Solution Explorer.
• Select Project > Set StarUp Projects... from the menu.
• Select Startup Project in the Solution 'Z' Property Pages.
• Select the Single Startup Project option.
• Select 'Z' in the drop down list.
• Click OK.

Finally, select Debug > Start Debugging or press the F5 key to launch the Z test harness.

Note we set everything up to work this way by default for you in the Visual Studio template which ships with the SDK. Here are the basics of how this works if you want to modify to fit your workflow:

In order to launch MCMLPad from within Microsoft Visual C# 2005 Express Edition you have to manually edit the .csproj file for the solution because the Start Action setting isn't available in the Express SKUs user interface -- but it still works if you add some XML. For the purposes of this example let's take a look at the snippet which provides this functionality from the Z.csproj file:

  <PropertyGroup>
    <UseVSHostingProcess>true</UseVSHostingProcess>
    <StartWorkingDirectory>$(windir)\eHome</StartWorkingDirectory>
    <StartArguments>-load:"resx://Z/Z.Resources/Default" -assemblyredirect:"$(FullyQualifiedOutputPath)" -markupredirect:"resx://Z/Z.Resources/,file://$(MSBuildProjectDirectory)\Markup\,.mcml"</StartArguments>
    <StartAction>Program</StartAction>
    <StartProgram>$(windir)\eHome\McmlPad.exe</StartProgram>
  </PropertyGroup>

Most of these should be self explanatory and I'll break down <StartArguments> for you as it's the most complex but most important (read the Media Center Markup Language Preview Tool SDK topic for more information)

-load:"resx://Z/Z.Resources/Default"

Tells MCMLPad to load the Z assembly and navigate to the resource named Default (which is Default.mcml) contained therein. Default.mcml is never used by the application once installed -- its only purpose is to provide this <UI> test harness.

-assemblyredirect:"$(FullyQualifiedOutputPath)"

Tells MCMLPad to load the assembly from a specific location. When $(FullyQualifiedOutputPath) is evaulated it returns something like this: C:\Program Files\Microsoft SDKs\Windows Media Center\v5.0\Samples\Windows Media Center Presentation Layer Samples\Z\bin\Debug\. Note this won't work if the assembly is registered to the Global Assembly Cache, so be mindful of when you run Command.InstallAndRegister.cmd contained in the sample solution.

-markupredirect:"resx://Z/Z.Resources/,
 file://$(MSBuildProjectDirectory)\Markup\,
 .mcml"

This one is broke up into its three constituent parts on different lines for ease of readability. This tells the MCML Preview Tool to replace instances of 'resx://...' with 'file://...' and append .mcml to the end. This allows you to build the assembly once, load the test harness (Default.mcml) into the tool, make changes to the source MCML and test the results of those changes by refreshing MCMLPad without having to rebuild the assembly -- what I call interactive editing.

Interactive Editing
You can also create a compiled assembly and open MCML files directly in the MCML Preview Tool using the same -load, -assemblyredirect and -markupredirect switches as in the Visual Studio .csproj file. This allows you to edit / tweak UI and avoid recompiling, installing to the GAC and registering in Windows Media Center as noted earlier. You can use the command line for this, or the MCML Preview Tool Launcher power toy. Using this approach you can edit and preview your changes in real time by refreshing the MCML Preview Tool after you make markup changes. For example:

In this screenshot we see the power toy defining the proper switches for the MCML Preview Tool, and the launched MCML Preview Tool window with our markup loaded. I've edited the Styles.mcml resource to change the focused button text color to red. I can continue to tweak all of Button.mcml resources (anything referenced with xmlns in the opened markup file, including those downstream) and returning to the MCML Preview Tool and pressing the F5 key to refresh and see my changes without a need to recompile. This allows me to make as many changes as I wish to the UI without committing them to my compiled assembly.

There are also other ways to leverage the power of the MCML Preview Tool -- with a little experimentation  -- so dig in...!

Mini-FAQ

How do I get proportional scaling in the MCML Preview Tool?
Use <ScaleLayout MaintainAspectRatio="true" AllowScaleUp="true" AllowScaleDown="true"/> in your test harness. For an example look at Default.mcml in the Z sample application, specifically <UI Name="TestWrapper">.

How can I easily switch between 16:9 and 4:3 aspect ratios?
The MCML Preview Tool defaults to 4:3 aspect ratio. Select the top or bottom window frame, hold down the CTRL key and size the window up or down -- the window will eventually 'snap' to the 16:9 aspect ratio. To reverse, select the right or left window frame, hold down the CTRL key and size the window up or down.

How can I test pieces of UI which are wired up to Windows Media Center APIs?
Generally speaking, you shouldn't (or rather, wouldn't). If the individual <UI> pieces are hard coded like this you probably aren't architecting your application properly -- even in a web / codeless scenario. In a properly architected application you should almost *always* be able to test your individual pieces of <UI> in the MCML Preview Tool without hooking them up to the Windows Media Center API. Follow the example in Button.mcml provided in the sample code for this post. When you run the application in Windows Media Center it loads Menu.mcml which uses the <Command> model item and <Rules> to wire up the functionality (in this case a C# method). When you are designing or testing the visuals for Button.mcml you load Test.mcml in the MCML Preview Tool. Test.mcml contains several <Command> model items but no <Rules> to perform the binding -- therefore the buttons behave visually as they will in the application, but have no functionality.