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.