Windows Presentation Foundation Windows Media Center-Hosted Applications Overview

Microsoft Windows Media Center (WMC) is a digital media entertainment application that is installed with Windows Vista Home Premium Edition, Windows Vista Ultimate, and with Microsoft Windows XP Media Center Edition 2005. WMC allows users to manage and use a wide variety of media, including television (digital and high-definition), DVDs, music, video, radio, and photos.

Out of the box, a WMC personal computer (PC) can be used to view and play digital media. This is known as the 2' user experience, because users operate WMC at the PC, using mouse, keyboard, and monitor.

However, a WMC PC can be configured to support remote control or remote keyboard input. In this arrangement, users don't have to be situated at the WMC PC to operate it. This is known as the 10' user experience, and suits WMC configurations that include large monitors, and traditional home entertainment hardware such as televisions and sound systems.

The core functionality that is offered by WMC is composed of a set of applications for managing and playing digital media. However, you can use WPF to create your own custom applications for the Windows Vista versions of WMC.

This topic provides an introduction to the development of WPF applications for WMC, and covers the following:

• Building and deploying a simple WPF game application.

• Targeting both 2' and 10' WMC user experiences.

• Customizing WPF controls to support WMC.

• Using new WMC -specific controls for WPF.

• Leveraging support in the .NET Framework 3.0.

• Integrating with WMC through managed APIs.

• Using Visual Studio 2005 to enhance the development process.

For comprehensive information on developing applications for WMC, see the Windows Media Center Software Development Kit (WMC SDK).

This topic contains the following sections.

• Hosting WPF Applications in WMC
• Launching a WPF Application for WMC
• The WMC User Experience
• Updating WPF Controls for WMC
• Additional WPF Controls for WMC
• Using the .NET Framework 3.0 Class Libraries
• Integrating with the WMC Managed APIs
• Developing with Visual Studio
• Installing a WPF Application for WMC
• Related Topics

Hosting WPF Applications in WMC

WPF allows the development of two types of applications: standalone and browser-hosted. Standalone applications provide their own windows and dialog boxes to host application content. There are two types of browser-hosted applications, loose XAML applications and XBAPs, both of which are hosted by Internet Explorer 7. However, Internet Explorer 7 doesn't know anything about WPF; to enable the ability for Internet Explorer 7 to host WPF content, WPF provides applications like Internet Explorer a hosting proxy. This proxy can host WPF content on behalf of other applications, and is built using the same common Windows infrastructure that Internet Explorer itself knows how to host.

WMC is also capable of hosting this proxy and, consequently, can host WPF browser-hosted applications. This means that you can take advantage of the WPF application development platform, in general, and the navigation and security features of browser-hosted applications, specifically.

The rest of this topic uses the WordGame! application for WMC (see WordGame! for Windows Media Center Demo).

Launching a WPF Application for WMC

The WordGame! application consists of the following three files (the minimum for all The XBAPs):

• wordgamewmc.exe. The XBAP.

• wordgamewmc.exe.manifest. The ClickOnce application manifest.

• wordgamewmc.xbap. The ClickOnce deployment manifest.

XBAPs are launched using ClickOnce, which requires the application to be configured with the application and deployment manifest files (see Building a Windows Presentation Foundation Application). Specifically, an XBAP is launched when its .xbap file is browsed to or double-clicked. When launched, the default behavior is for ClickOnce to download the application on behalf of WPF, after which WPF launches Internet Explorer and navigates it to the application, as shown in the following figure:

To launch a WMC application, however, users browse to or double-click a WMC link file (.mcl). A .mcl file is an XML configuration file that is configured in Windows to be opened by the WMC host, (ehshell.exe) when either browsed to or double-clicked (see WMC SDK).

Note:
.mcl files are convenient during the development process, but are not recommended as the mechanism for installing and launching WMC applications. See Installing a WPF Application for WMC.

When a .mcl file is opened, the WMC host will parse and process the configuration instructions contained by the .mcl file, the most important of which is the name of the application to open. You use this mechanism to create a .mcl file that is configured to launch an XBAP:

<application>
  url="https://localhost/wordgamewmc/wordgamewmc.xbap"
</application>

When the WMC host processes this .mcl file, WMC host will navigate to the .xbap file. This causes ClickOnce to launch the application into the WMC host itself, as shown in the following figure:

Note:
If you wanted WMC to host a loose XAML application, you would configure the .mcl file with a .xaml file, like so:

<application>
  url="https://localhost/loosexamlapplication/loosexamlpage.xaml"
</application>

Without any change to the XBAP itself, and with the addition of a single configuration file, a WPF browser-hosted application can be hosted by WMC, as is.

However, the WMC user experience is quite specific and, for consistency and style, XBAP WMC applications should be designed to integrate with the WMC user experience. The rest of this topic covers the key aspects of the WMC user experience and how to build XBAPs to be sensitive to it.

The WMC User Experience

Providing a consistent user experience is a core part of any application development. With respect to WMC users, an application should attempt to be consistent in the following ways:

• Theme. The overall style of an application's user interface.

• Layout. Control positioning and size.

• Navigation. Using the keyboard, mouse, and remote control to navigate an application's user interface.

While a detailed discussion on WMC user experience can be found in the WMC SDK, the following topics provide a high-level overview.

Theme

As you can see from the following figure, the WMC theme has several distinct elements:

The most distinct of these include a blue, glassy background, and large rounded fonts that are light in color. The result is to create an appearance that can be easily discerned by both 2' users, who are right in front of a monitor, and 10' users who may be any distance away from a television. While WPF applications should follow this general approach to appearance, WMC doesn't natively expose this information for WPF applications to use. Fortunately, WPF does provide a rich infrastructure for styling and theming that can be leveraged to easily replicate the WMC appearance, if that is desired. Alternatively, you can use WPF to create a wholly new and visually rich user experience, although you should keep layout and navigation considerations in mind.

For example, to create a WMC-style background for pages, you could do the following:

<Application
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
    StartupUri="HomePage.xaml">
  <!--MediaCenterThemes.xaml-->
  <Application.Resources>
    <LinearGradientBrush x:Key="PageGlassyBackground"  StartPoint="0,0.5" EndPoint="1,0.5">
      <GradientStop Color="#ff2B6680" Offset="1.5" />
      <GradientStop Color="#569dc2" Offset="0" />
    </LinearGradientBrush>
    ...
  </Application.Resources>
</Application>

Because themes are typically composed of more than one element, you should consider using a custom resource dictionary to encapsulate the styles of the WMC theme:

<ResourceDictionary>
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" />
  <LinearGradientBrush x:Key="PageGlassyBackground"  StartPoint="0,0.5" EndPoint="1,0.5">
    <GradientStop Color="#ff2B6680" Offset="1.5" />
    <GradientStop Color="#569dc2" Offset="0" />
  </LinearGradientBrush>
  ...
</ResourceDictionary>

To incorporate a resource dictionary into an application, you configure the Application.Resources element of your application definition to refer to the resource dictionary .xaml file:

<Application
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    StartupUri="HomePage.xaml">
  <!--MediaCenterThemes.xaml-->
  <Application.Resources>
    <ResourceDictionary>
      <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="MediaCenterTheme.xaml" />
      </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
  </Application.Resources>
</Application>

The following figure shows WordGame! updated with a full complement of styles and resources for the WMC theme.

WMC doesn't restrict you from developing application themes that incorporate application-specific and brand-specific elements. However, there several aspects of an application's theme should be considered when designing any application for the WMC user experience, including:

• Television-safe colors: Do not use bright colors that may be susceptible to bleeding (eg, green, red).

• Contrast: To keep text visually distinct from the background, ensure that the choice of foreground and background colors for your visual elements have an appropriate level of contrast.

• Fonts: You can enhance readability by using larger sized fonts without serifs. Additionally, removing unnecessary wording from your content can help to create text areas that are easier to read.

• Buttons: Keep the appearance of your buttons simple.

• Images: When creating images, consider display quality and size and download size.

• Animation: Use animation when appropriate.

See the WMC SDK for detailed information regarding WMC application themes.

Layout

One issue that may not be readily apparent occurs when a user hovers the mouse over the WMC host, which causes the WMC host to display additional navigation UI elements for mouse-driven navigation, as shown in the following figure:

From this figure, you can see the top-left and bottom-right portions of the application's UI are covered by the navigation chrome. In this situation, you can update the layout of your UI to take the navigation UI into account. For WordGame!, this involved moving the application title to the right of the UI, and adding a 50 pixel high row to the bottom of the Grid element that hosts the content on the home page:

<Grid>
    ...
    <Grid.RowDefinitions>
        <RowDefinition Height="5" />
        <RowDefinition Height="Auto" />
        <RowDefinition Height="20" />
        <RowDefinition Height="Auto" />
        <RowDefinition />
        <RowDefinition Height="50" />
    </Grid.RowDefinitions>
    <!-- Game title -->
    <TextBlock ... TextAlignment="Right">Word Game!</TextBlock>
    ...
</Grid>

The effect of adding these rows is shown in the following figure:

For this reason, XBAPs for WMC need to be sensitive to the various layout behaviors and consistencies of WMC.

Key layout considerations that you should make include:

• Application Layout: The layout of your applications should be simple and consistent, to make it easier for users to develop and retain familiarity with your application's user interface.

• WMC Layout: The layout of your applications should, where pragmatic, retain consistency with the general WMC user experience. This allows users who are familiar with WMC to more quickly become comfortable with your application.

• Video: If your application displays video using the WMC managed APIs, WMC will play the video in the bottom-left of the screen. Consequently, your user interface should be laid out to take this into account.

• Resolution: Your application's user interface and layout should target a resolution of 1024x768. WPF offers layout support to assist you in both laying out your user interface to target 1024x768 and ensuring the layout is retained as the user interface is resized (See The Layout System for more information).

See the WMC SDK for detailed information regarding WMC layout.

Navigation

Essentially, theme and layout dictate how the controls that comprise your application's user interface are arranged. Navigation, on the other hand, dictates how your users get to and move between those controls.

The control that is currently receiving user input is said to have the focus. To place the focus on a specific control when a page in your XBAP application is displayed, you can use markup:

<!-- Set focus on guess character text box -->
<Page ... FocusManager.FocusedElement="{Binding ElementName=guessedChar}">
    ...
</Page>

You should do this to support both 2' and 10' modes of operation.

To enable users to navigate your controls in a WMC application in both 2' and 10' modes, your application must handle navigation using a mouse, a keyboard (attached or remote), and a remote control. By default, navigation with a mouse and keyboard is the same as it is for any WPF application, including:

• Clicking controls to shift the focus to them.

• Tabbing through controls to move the focus.

• Using the IsDefault property of a button to specify it is clicked by default when the Return key is pressed.

• Using the IsCancel property of a button to specify it is clicked by default when the Escape key is pressed.

To support remote controls, you need to support directional navigation, which means to allow users to move control focus by clicking the up, down, left, and right buttons on the remote control. You don't have to write any special code to support directional navigation, as long as you use a specific subset of WPF controls.

Updating WPF Controls for WMC

Although WPF offers a host of controls, only a subset of those controls is suitable for use in WMC applications by default. The determining factor is whether or not they can be navigated to, manipulated, and navigated from using a remote control. The following figure shows a subset of WPF controls that support input from a remote control (using WMC styles):

These limitations don't preclude the use of other WPF controls, although you will need to perform additional work to make them work for WMC. For example, consider the Slider control, which is shown hosted in WMC in the following figure:

By default, a Slider can be displayed and navigated to using the mouse, the keyboard, or the remote control. However, a Slider cannot be navigated from using the remote control - Slider interprets Up, Down, Left, and Right remote control button clicks as attempts to increase or decrease the value of the Slider.

In these situations, one solution is to create a composite control that contains the desired control plus additional remote control-friendly controls to manipulate it. For example, the Slider can still be used with two buttons, one to decrement the value of the Slider, and one to increment the value of the Slider, using the following code:

<Page x:Class="SliderPage"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">

  <!-- Custom Slider -->
  <StackPanel Margin="50" Orientation="Horizontal" VerticalAlignment="Top">
    <Button 
      Name="decrementButton" 
      Click="decrementButton_Click"
      Margin="10" 
      FontSize="10" 
      HorizontalContentAlignment="Center" 
      VerticalContentAlignment="Center" 
      Width="40" Height="40">
      -
    </Button>
    <Slider 
      Name="slider" 
      Focusable="False" 
      Width="100" Margin="0,15,0,0" 
      Minimum="0" Maximum="10" Value="50" 
      Interval="1" TickFrequency="1" TickPlacement="BottomRight" />
    <Button 
      Name="incrementButton" 
      Click="incrementButton_Click"
      Margin="10" 
      FontSize="10" 
      HorizontalContentAlignment="Center" 
      VerticalContentAlignment="Center" 
      Width="40" Height="40">
      +
    </Button>
  </StackPanel>
  
</Page>
using System.Windows;
using System.Windows.Controls;
public partial class SliderPage : System.Windows.Controls.Page
{
    //</SnippetSliderPageCodeBehind1>
    public SliderPage()
    {
        InitializeComponent();
    }

    void decrementButton_Click(object sender, RoutedEventArgs e)
    {
        this.slider.Value--;
    }
    void incrementButton_Click(object sender, RoutedEventArgs e)
    {
        this.slider.Value++;
    }
}

The result is shown in the following figure.

Additional WPF Controls for WMC

Another problematic control is the TextBox, shown in the following figure. Using a remote control, it is not possible to actually enter characters into the TextBox. What's needed is a control that allows a remote control user to select one or more characters. A common technique already in use in mobile devices whose form factor prevents them from having a full keyboard is to display a keyboard in the user interface and allow them to select the characters they need.

The sample includes a soft keyboard control for WPF applications that target WMC, which is shown in the following figure:

This is implemented as the SoftKeyboardTextBox class in the Keyboard.dll assembly that comes with the sample, and resides in the MCEControls namespace. To use it, you:

1. Add a reference to the Keyboard assembly that comes with the MCEControls.

2. Add an XML namespace declaration to the assembly in your content.

3. Add the XAML to declare and configure a SoftKeyboardTextBox.

The result is shown in the following code:

<Page 
  ... 
  xmlns:MCEControls="clr-namespace:MCEControls;assembly=Keyboard" >
  ...
  <MCEControls:SoftKeyboardTextBox 
    Name="guessedChar" 
    Grid.Column="0" 
    Margin="0,0,5,0" 
    Width="80" 
    MaxLength="1" />
  ...
</Page>

Using the .NET Framework 3.0 Class Libraries

A WPF application for WMC is not limited to controls. A WPF application can also leverage the breadth of the .NET Framework 3.0 for additional functionality, allowing you to use the same code you would for standalone or browser-hosted WPF applications.

For example, the code to save and load data from an application that is hosted by WMC is the same as for non-WMC applications, and likewise for security constraints (see Windows Presentation Foundation Security); depending on where the application is launched from depends on whether or not a WMC-hosted application can write to the local disk.

To be safe, an application can use isolated storage to persist files:

using System;
using System.ComponentModel;
using System.IO;
using System.IO.IsolatedStorage;
using System.Xml;
using System.Xml.Serialization;
...
public static PlayerScore Load()
{
    try
    {
        // Load the playerscore.xml file from isolated storage
        using (IsolatedStorageFile isf = IsolatedStorageFile.GetUserStoreForApplication())
        using (Stream stream = new IsolatedStorageFileStream("playerscore.xml", FileMode.Open, isf))
        {
            XmlSerializer xmlSerializer = new XmlSerializer(typeof(PlayerScore));
            return (PlayerScore)xmlSerializer.Deserialize(stream);
        }
    }
    catch (FileNotFoundException ex)
    {
        return new PlayerScore();
    }
}

public static void Save(PlayerScore playerScore)
{
    // Save the playerscore.xml file to isolated storage
    using (IsolatedStorageFile isf = IsolatedStorageFile.GetUserStoreForApplication())
    using (Stream stream = new IsolatedStorageFileStream("playerscore.xml", FileMode.Create, isf))
    {
        XmlSerializer xmlSerializer = new XmlSerializer(typeof(PlayerScore));
        xmlSerializer.Serialize(stream, playerScore);
    }
}

Integrating with the WMC Managed APIs

WPF applications for WMC can also integrate with the capabilities of WMC itself through a set of managed APIs that are installed with the operating system, and located in two assemblies: Microsoft.MediaCenter.dll, and Microsoft.MediaCenter.UI.dll.

Using these APIs, you can integrate with a wide range of WMC services, including inspecting, configuring, and playing media content. More information on these can be found in the WMC SDK.

One aspect of these capabilities is to further integrate the user experience of your application with WMC. For example, if a WPF application needs to notify the user with a message box, they could display something like the following:

However, the appearance of a standard WPF message box is inconsistent with the experience of WMC. Fortunately, though, the WMC managed APIs provide their own, WMC-style message box that you can use with code like the following:

using Microsoft.MediaCenter;
...
// Get media center host and show dialog box
MediaCenterEnvironment mce = Microsoft.MediaCenter.Hosting.AddInHost.Current.MediaCenterEnvironment;
mce.Dialog(msg, "WordGame!", DialogButtons.Ok, 1000, true);

This will cause an WMC dialog box like the following to be displayed:

The WMC SDK should be referred to for in-depth understanding of the WMC Managed APIs.

Note:
You cannot run an XBAP that references the WMC Managed APIs unless the XBAP is hosted by from WMC.

Developing with Visual Studio

So far, this topic has covered the breadth of the core programming issues you'll need to address when building XBAPs for WMC, including:

• Creating a typical XBAP application.

• Using a .mcl file to launch an XBAP into WMC.

• Creating a WMC theme for an XBAP.

• Referencing the WMC managed APIs.

These are issues that you'll likely need to address with each XBAP you build for WMC. Rather than recreate these elements yourself each time you build an XBAP for WMC, you can use the Media Center Application (WPF) project template for Microsoft Visual Studio 2005 that is installed with the WMC SDK.

Note:
The WMC project templates are only installed if both Visual Studio 2005 and "Fidalgo" are installed.

The Media Center Application (WPF) project template will create a Visual Studio 2005 project that has these elements included, by default.

To create a new Media Center Application (WPF):

1. Open Visual Studio 2005.

2. Choose Microsoft Visual Studio | File | New | Project | Visual C# | .NET Framework 3.0 | Media Center Application (WPF).

The following list shows the key items that are generated by the project template by default:

• A readme.txt file includes some helpful text about building and debugging XBAPs for WPF.

• References to the WMC managed assemblies.

• A MediaCenterTheme.xaml file is a resource dictionary that contains a complete set of WMC styles that are, by default, applied to the default page, Page1.xaml.

• A .mcl file that is generated along with the standard XBAP output.

Note that there is an equivalent project template for Microsoft Visual Basic.

Debugging a Project

To debug an XBAP within the WMC host from Visual Studio 2005, you need to do the following:

1. Right-click the project in Solution Explorer and Properties | Debug.

2. Set Start Program to c:\windows\system32\presentationhost.exe.

3. Set Command Line Arguments to -debug.

4. Run the application by choosing Microsoft Visual Studio | Debug | Start Debugging (or by pressing F5).

5. Double-click the .mcl file that is generated during the build process (\bin\debug\assemblyname.mcl).

The application specified in the .mcl file will be launched and hosted in WMC.

Installing a WPF Application for WMC

One of the advantages of using WMC is its ability to help create Microsoft Windows Installer applications (.msi files). .msi files are a useful way to distribute your WPF application to WMC client machines.

The following steps were followed to create a simple Windows Installer application for WordGame!:

1. In Visual Studio 2005, right-click on the XBAP solution in Solution Explorer, and choose Add | New Project.

2. In the Project types list, select Other Project Types | Setup and Deployment.

3. In the Templates list, select either Setup Project or Setup Wizard (the latter guides you through the initial configuration of the Windows Installer setup project that is created).

4. Right-click the new Windows Installer project, and choose Add | File, and choose the following files:

   1. WordGameWMC.mcl

   2. WordGameWMC.exe

   3. WordGameWMC.exe.manifest

   4. WordGameWMC.xbap

   5. WordList.txt

   6. Keyboard.dll

5. In the File System tab, choose User's Desktop.

6. In the file list, right-click and select Create Shortcut to User's Desktop.

7. Select Application Folder | WordGameWMC.mcl.

8. Rebuild the Windows Installer project.

When the Windows Installer project is built, a .msi file is generated to the build output folder. This is then copied to the client machine and run to install the application. The default installation is to create a folder that conforms to the following format:

c:\program files\CompanyName\ApplicationName\Application Files

All the files that were selected during the configuration of the Windows Installer project are copied to this folder, along with any dependent assemblies that were selected by the Windows Installer project.

Additionally, a shortcut icon to WordGameWMC.mcl is placed on the desktop, and can be double-clicked or browsed to start the application inside WMC.

Note:
The project file for the application itself needs to be manually updated to ensure the path to the .xbap file that is added to the generated .mcl file is accurate for installation.

This installation is a demonstration that you can use to see the basics of creating a Windows Installer for a WPF application for WMC.

For real-world WPF applications for WMC, your installation techniques should be different.

First, your application should install an HTML file that provides a link to the actual web server-hosted WPF application. Hosting on a web server allows new versions of the application to be created, published, and picked up by the client machine without the user having to re-install the application.

Second, you should not use .mcl files. Instead, you should create a windows installer that calls the WMC MediaCenter.RegisterApplication API, or should run the RegisterMceApp.exe command-line utility. See the WMC SDK for further details.

See Also

Concepts

Windows Presentation Foundation Browser-Hosted Applications Overview

Other Resources

Windows Media Center Software Development Kit