Getting Started with \"WPF/E\" (Code Name)

Article
04/10/2007

Laurence Moroney

Microsoft Corporation

Updated March 2007

Applies to:
"WPF/E" (code name) [February CTP]
Microsoft Visual Studio 2005

Summary: This white paper provides a high-level overview into "WPF/E" and how it fits into the development stack for the next generation of Web applications. (28 printed pages)

What Is "WPF/E"?
The Evolution of Web Development: Moving to Web.Next
Building a Simple "WPF/E" Application
Preparing a Graphic Design File for "WPF/E"
Using Visual Studio 2005 to Build a "WPF/E" Project
Preparing a Visual Studio 2005 Project for "WPF/E"
Editing Your Web Page to Render "WPF/E" Content
Understanding the JavaScript
Editing the XAML to Add Text
Editing the XAML for Simple Animation
Editing the XAML for Simple Interaction
Adding Media to the Mix
Conclusion
Appendix I: The Install Experience
Appendix II: Configuring Server MIME Types

What Is "WPF/E"?

"WPF/E" is a code name for a new Web presentation technology that is created to run on a variety of platforms. It enables the creation of rich, visually stunning, and interactive experiences that can run everywhere; within browsers and on multiple devices and desktop operating systems (such as the Apple Macintosh). In accordance with Windows Presentation Foundation (WPF), eXtensible Application Markup Language (XAML) is the foundation for "WPF/E" presentation capability. XAML is the presentation technology in Microsoft .NET Framework 3.0 (Windows programming infrastructure).

This white paper will guide you through the basics of "WPF/E" and how you can use the Microsoft stack of tools, including the Microsoft Expression Graphic Designer, Microsoft Visual Studio 2005, and XAML to build rich graphical sites. First, let's take a primer on the background leading up to "WPF/E" and where it stands on the development landscape.

The Evolution of Web Development: Moving to Web.Next

When the modern Web was invented by Tim Berners-Lee at CERN, it was intended to allow static documents to be stored and linked on a network-based system. The next logical step was "active" documents generated at the time they were requested with time-specific or user-specific information. Technologies such as CGI empowered this. Over time, the ability to generate documents on the Web became paramount and the technology evolved through CGI, Java, ASP, and then ASP.NET.

A great barrier in Web applications proved to be the user experience, where technical constraints prevented Web applications from delivering the same richness of user experience that a client application with local data would provide.

The XMLHttpRequest object—released by Microsoft as part of Internet Explorer 5 in 2000—became an important function for the Asynchronous JavaScript and XML (AJAX) technique. By employing AJAX, Web applications provided a more dynamic response to user input; refreshing small parts of a Web page without requiring a complete reload of content. Innovative solutions built on AJAX took Web applications a step further in being able to have a client-like user experience.

For both application developers and designers, "WPF/E" is the next step towards creating a potentially rich user experience. It allows designers to express their creativity and save their work in a format that will work directly on the Web. In the past, a designer would design a Web site and experience using tools that provided a rich output, but the developer would meet Web platform constraints when implementing the design. In the "WPF/E" model, designers can build their desired user experience using XAML. A developer can then directly incorporate the XAML document into a Web page using the "WPF/E" runtime. Thus, the two can work more closely than before to provide a rich user experience.

Because XAML is XML, it is-text based and thus provides a firewall-friendly, easy-to-inspect description of the rich contents. While other technologies—such as Java Applets, ActiveX, and Flash—can be used to deploy richer content than DHTML, CSS, and JavaScript, they all send binary content to the browser. Sending binary content to the browser is not only difficult to audit for security but also difficult to update. Any changes require the entire application to be reinstalled, which is not the most user-friendly experience and can lead to stagnation in pages. When "WPF/E" is used to change the rich content, a new XAML file is generated server-side. The next time the user views the page, this XAML is downloaded and the experience is updated without any reinstallation.

At the heart of "WPF/E" is the browser-enhancement module that renders XAML and draws the resulting graphics on the browser surface. It is a small download (under 2 MB) that can be installed when the user hits the site containing the "WPF/E" content. This module exposes the underlying framework of the XAML page to JavaScript developers, so interaction with the content on the page level becomes possible, and thus the developer can—for example—write event handlers, or manipulate the XAML page contents using JavaScript code.

But, enough with the theory! Let's get hands-on and take a look at our first "WPF/E" project.

Building a Simple "WPF/E" Application

Let's start by taking a look at the Microsoft Expression Graphic Designer to create a very simple graphic in XAML for "WPF/E." Figure 1 shows the product in action.

Figure 1.The Expression Graphic Designer tool

Expression Graphic Designer is a new tool from Microsoft that brings together the best of vector-based and pixel-based graphic design tools, allowing designers to explore new creative possibilities. It enables graphics from other applications and export design elements to be incorporated into a variety of software tools, including XAML for WPF and "WPF/E."

Preparing a Graphic Design File for "WPF/E"

With Expression Graphic Designer, open the Popcan.xpr file. It is located in Program Files\Microsoft Expression\Design Beta 1\Samples. (Popcan.xpr is the graphic file used in Figure 1.)

When you've opened the file, you'll see that—when measured in pixels—it's pretty big. Using the vertical and horizontal rulers, you can see that it is 1280 by 1024 pixels. Figure 2 shows the horizontal ruler demonstrating the width of the image.

Figure 2. Horizontal ruler in Expression Graphic Designer

You can also see this on the Document Size dialog box (located in the File menu), as shown in Figure 3.

Figure 3. Document Size dialog box

Using the Document Size dialog box, change the image dimensions to be 300 pixels by 150 pixels. You do this by typing 300 into the Width text box and 150 into the Height text box in the Document Size dialog box, as shown in Figure 4.

Figure 4. Setting the dimensions to be 300 by 150 pixels

When you click OK in this dialog box, the image will be resized. The can now looks distorted; appearing short and squat as shown in Figure 5.

Figure 5. The document resized to 300 by 150 pixels

As the graphic is vector-based, you can resize without losing fidelity. When you are in the design surface, press CTRL+A to select all elements in the graphic. A green outline will appear and show the selected elements, as shown in Figure 6.

Figure 6. All image elements selected (Click on the picture for a larger image)

You can now drag the image around the frame, or pull the corners to resize it until you get a pleasing aspect ratio. Figure 7 shows that the can has been resized to look more realistic and placed in the top left-hand corner of the document.

Figure 7. Resizing the can to have a better aspect ratio

You are now ready to export this as a "WPF/E" XAML image.

On the File menu, click Export, and then XAML. You may also type CTRL+ALT+X. The Common Save dialog box will appear, allowing you to specify where you want to export the XAML file. Name the file Popcan.xaml and select Save. The Xaml Export dialog box will appear. This dialog box allows you to do some further specification on the export file, including specifying that you want to export "WPF/E"–compatible XAML, as shown in Figure 8.

Figure 8. Exporting "WPF/E" XAML

The right side of the screen has a Preview pane in which you can inspect your image to make sure that it looks OK before you proceed. On the right-hand side, the tabs allow you to switch between inspecting the image and the XAML code that represents the image. If you are new to XAML, it is a good idea to take a look at the XAML Code tab, so you can correlate how it applies to the image.

The drop-down options on the right allow you to specify attributes of the export, including how rasterized images should be handled, whether they should be vectorized or just output to a specific directory. For now it is OK to keep the defaults, but make sure that "WPF/E" is selected under Document Format, as shown in Figure 8.

When you are ready, click the Export button and the "WPF/E" XAML code will be written to disk. You will use this later in your Visual Studio 2005 Web project. In the next step, you'll see how to set up a Web project and prepare it for XAML.

Using Visual Studio 2005 to Build a "WPF/E" Project

The "WPF/E" SDK includes a template for Visual Studio 2005 that allows you to build "WPF/E" projects. In order to use this template in Visual Studio 2005, you will need service pack 1 of Visual Studio 2005.

Next, you will need the Update to Support Web Application Projects, which can be downloaded and installed from Microsoft.

Visual Studio is now ready to create "WPF/E" projects. Launch the Visual Studio IDE. Then select the File menu and click New Project. Select "WPF/E" in the left-hand Project Types box. Under Templates on the right-hand side, you will see the "WPF/E" JavaScript Application template that is used to create a new "WPF/E" application (Figure 9).

Figure 9. Using the Visual Studio template

Click OK and a new project containing a single HTML page and an XAML file representing a simple button will open. It's a good idea to take a look through the HTML to see how it uses JavaScript to set up the "WPF/E" control (more on this later), as well as how the XAML exposes an event that can be trapped and handled in JavaScript.

Preparing a Visual Studio 2005 Project for "WPF/E"

While you can create an application using the template from the previous section, it's also a good idea to understand how "WPF/E" works and is delivered. You can see how easy an existing Web site can be configured to deploy the "WPF/E" module to the browser. In this section, you'll see how to configure your Web site manually to be a "WPF/E" site.

When writing this white paper, I used Visual Studio 2005 and the "Orcas" CTP Preview. You don't need "Orcas," but if you have it installed it makes XAML code easier to type because of IntelliSense and the ability to preview finished XAML in the "Cider" XAML designer.

Note Cider is designed for WPF instead of "WPF/E," so it should not be used to develop your XAML code for "WPF/E" at this time.

To get started, launch Visual Studio 2005 and create a new Web site by using the New Web Site dialog box under File, as shown in Figure 10.

Figure 10. Creating a new Web site in Visual Studio 2005

Using the New Web Site dialog box will create a new solution containing a simple Default.aspx ASP.NET page that, when executed, generates HTML that will be rendered on the browser. This will provide the basis for your first "WPF/E" page.

Next, you should add the aghost.js file to your Web site. Again, you can do this by dragging it from Windows Explorer and dropping it into your solution. It’s a good idea to keep it (and all other JavaScript files) in a separate folder.

Finally, create another new folder in your solution named XAML, and copy into it the Popcan.xaml file that you created earlier.

Editing Your Web Page to Render "WPF/E" Content

Next, you will edit your Web page to handle embedded "WPF/E" content. This is very straightforward as it only involves adding a single JavaScript reference and a call to a JavaScript object defined in aghost.js. The JavaScript libraries and "WPF/E" installers do the rest.

First, edit your page so that is looks like Listing 1: The title was changed from Untitled Page to My first "WPF/W" Page!; a JavaScript reference to aghost.js was added to the head; and a new div containing the call to the agHost object was added to the body of the page.

Listing 1. The default.aspx HTML code

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="Default.aspx.cs" 
Inherits="_Default" %> 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>
<head id="Head1" runat="server">
    <title>My first "WPF/E" Page!</title>
    <script type="text/javascript" src="agHost.js "></script>
</head>
<body>
    <form id="form1" runat="server">
        <div id="AgControl1Host">
            <script type="text/javascript">
                new agHost("AgControl1Host", "AgControl1", "400", "400",
                "#00000000", null, "xaml/Popcan.xaml", "True", "30",
                null,0,8,5);
            </script>
        </div>
    </form>
</body>
</html>

Note The JavaScript call to "new AgHost" might look a little obscure, but don't worry: You'll look into that later.

You are now ready to run your application and have ASP.NET generate the page containing the "WPF/E" content. Press F5 in Visual Studio 2005 to start the application. The first time you run an application, the browser will detect whether or not "WPF/E" is installed. If it is not installed, when your page launches you'll get a dialog box asking if you want to install the "WPF/E" module. Appendix I details the install experience for Internet Explorer and Mozilla Firefox running on Windows.

In the next sections, you'll first take a look at the experience in running this application under Internet Explorer and Mozilla Firefox. After that, you'll look into the JavaScript object that controls "WPF/E," as well as adding animation to your graphic.

Understanding the JavaScript

The JavaScript code that embedded this XAML into the page using "WPF/E" follows.

new agHost("AgControl1Host", "AgControl1", "400", "400", "#00000000", 
null, "xaml/Popcan.xaml", "True", "30", null,0,8,5);

This creates a new instance of the "WPF/E" plug-in, using a list of parameters that can be used to create it. These parameters are (in order):

hostElementID
This is the name of the HTML element in which the plug-in control will be hosted. So, if you have a <div> on the page that contains the plug-in, give the <div> a name and use that name here.
controlID
This is the ID of the plug-in itself.
height
This is the desired height of the control in pixels.
width
This is the desired width of the control in pixels.
backgroundColor
This is the desired background color for the control.
sourceElement
This is the name of the page element that contains XAML for the control. This is one way of configuring the XAML for the control—where the XAML is on the page—contained within a <script> element. Should you use this approach, put the ID of the <script> element in this parameter, and the control will pick it up from there.
sourceURL
This is the location of an external XAML file.
isWindowless
This is Boolean. Set it to True if you want the "WPF/E" control to be Windowless. This means that in a HTML page, the "WPF/E" control will be inline with the HTML, and, for example, if you set it to be transparent, the HTML will be displayed "behind" it. If it is not Windowless (in other words, if this is set to False), the "WPF/E" content will be in a distinct region of the page, and HTML markup will flow around it.
maxFrameRate
This is a number specifying the maximum frame rate at which "WPF/E" will render animated content.
loadHandler
This is the name of a <script> element on the page to fire when the control is loaded
errorHandler
This is the name of a <script> element on the page to fire when an error occurs on the control.

When you create a new instance of an agHost control using these parameters, a call is made to agHost.js (so, you will need a script reference to this file in your HTML), which generates the <object> tag that houses the control. So, in the previous case, the following <object> tag is generated, if you are using Internet Explorer.

<object id="AgCotnrol1" height="400" width="400"
    Codebase="install/xcpctrl.cab"
    classid="CLSID:32C73088-76AE-40F7-AC40-81F62CB2C1DA">
    <param name="Source" value="xaml/Popcan.xaml" />
    <param name="MaxFrameRate" value="30" />
    <param name="BackgroundColor" value="#00000000" />
    <param name="WindowlessMode" value="True" />
</object>

If you prefer, you could always use this code directly in your page. However, using the JavaScript object is a lot more verbose and doesn't bog down your HTML page in the <object> tag implementation details.

Editing the XAML to Add Text

You can edit the XAML directly from within Visual Studio 2005 to make additions. In this example, you'll add a TextBlock control to the XAML to contain some basic text: "Hello, World.”

Open the XAML file in Visual Studio 2005. If you have the "Orcas" CTP installed, you can preview the XAML in the "Cider" editor, as shown in Figure 11.

Note You will not be able to use the toolbox to add controls to "WPF/E" XAML, as the "Cider" designer is for WPF applications only. Otherwise, you'll just have the XML editor open.

Figure 11. Using Visual Studio 2005 to edit the XAML (Click on the picture for a larger image)

To add a text block to your XAML, scroll to the bottom and add the following code, just before the closing <Canvas> tag:

<Canvas x:Name="Layer_3">
    <TextBlock x:Name="MyLink" Canvas.Left="150" Canvas.Top="0"
    FontFamily="Verdana" FontSize="18"
    Width="250" TextWrapping="Wrap">
        Drink some of this yummy WPFE soda! Much better than a 
        Hello, World App, right?
    </TextBlock>
</Canvas>

You can see the effect this has on your Web page in Figure 12.

Figure 12. XAML containing text block

Editing the XAML for Simple Animation

XAML specifies storyboards for animation. In this example, you'll add a simple animation to the "WPF/E" page that makes the text bounce off the top and bottom of the screen. This is enabled by adding an event that triggers when the canvas is loaded. This event can contain an action: The action specified for this example begins a storyboard that contains a DoubleAnimation. This type of animation is used to manipulate a range of numbers starting with From and ending with To. It can be set to repeat forever and auto-reverse itself, allowing you to specify that it "bounce" the text. You animate its Top from 0 to a specified amount, automatically reversing the animation when it is done and repeating forever. The storyboard to achieve this is the following:

<Storyboard Storyboard.TargetName="MyLink" 
Storyboard.TargetProperty="(Canvas.Top)">
    <DoubleAnimation AutoReverse="True" RepeatBehavior="Forever" 
    BeginTime="0" Duration="0:0:1" From="0" To="90"> </DoubleAnimation>
</Storyboard>

And the complete Canvas specification containing the text and the triggers to fire the animation is the following:

<Canvas x:Name="Layer_3">
  <Canvas.Triggers>
    <EventTrigger RoutedEvent="Canvas.Loaded">
      <EventTrigger.Actions>
        <BeginStoryboard>
          <Storyboard Storyboard.TargetName="MyLink"
          Storyboard.TargetProperty="(Canvas.Top)">
            <DoubleAnimation AutoReverse="True" RepeatBehavior="Forever"
            BeginTime="0" Duration="0:0:1" From="0" To="90">
            </DoubleAnimation>
          </Storyboard>
        </BeginStoryboard>
      </EventTrigger.Actions>
    </EventTrigger>
  </Canvas.Triggers>
  <TextBlock x:Name="MyLink" Canvas.Left="150" Canvas.Top="0"
  FontFamily="Verdana" FontSize="18" Width="250" TextWrapping="Wrap">
    Drink some of this yummy "WPF/E" soda! Much better than a Hello, World
    App, right?
  </TextBlock>
</Canvas>

Now, when you see your Web site in action, the text will be "bouncing" up and down the right-hand side.

Editing the XAML for Simple Interaction

"WPF/E" allows JavaScript coders to interact with the XAML. In this example, you'll see how to handle an event raised when the user interacts with the XAML file. The "bouncing" text from the previous example will become a hyperlink that you then use to link to another page.

To achieve this, you will specify the event handler in the TextBlock declaration. You will be capturing a click of the mouse, so you use the MouseLeftButtonDown event handler to specify the JavaScript function that will handle the click. Here's how the text block will look, with a declaration for a JavaScript handler called hyperlink_MouseLeftButtonDown:

<TextBlock MouseLeftButtonDown="javascript:hyperlink_MouseLeftButtonDown" 
x:Name="MyLink" Canvas.Left="150" Canvas.Top="0" FontFamily="Verdana" 
FontSize="18" Width="250" TextWrapping="Wrap">
    Channel 9 is cool!
</TextBlock>

Now you can handle this event using JavaScript on the hosting page (or in an external library that the page references), as follows:

<script language="javascript">
    function hyperlink_MouseLeftButtonDown(sender, args) {
        window.open("https://channel9.msdn.com");
    }
</script>

So now when you run your page, you'll have an animated, moving hyperlink that you click to browse to the MSDN Channel 9 site!

Adding Media to the Mix

"WPF/E" brings best-of-breed Windows Media to the Web developer. You can easily add media content to "WPF/E" applications using the <MediaElement> tag in XAML, as follows:

<Canvas x:Name="Layer_4">
    <MediaElement x:Name="VideoLayer" Source="Butterfly.wmv"
        Canvas.Top="0" Canvas.Left="130"
        Height="200" Width="200">
    </MediaElement>
</Canvas>

Note The <MediaElement> exposes methods that can be used to start, stop, pause, or seek the video. Check the "WPF/E" documentation and samples for more information.

Figure 13 is depicts the above example of the "WPF/E" application with embedded video.

Figure 13. "WPF/E" with embedded video

Note You will need to have the Butterfly.wmv file in your root Web site for the above example to work. This WMV file is one of the "Sample Videos" that come with Windows Vista and can be found in your Documents folder. If you don't have this one, replace it with any WMV file.

Conclusion

In this white paper, you were given a high-level overview into "WPF/E" and how it fits into the development stack for the next generation of Web applications. You saw how XAML is used as the glue that binds the specifications of the designer with the tools of the developer and the delivery to the user. You took a look at Expression Graphic Designer and how it can be used to define graphics for your Web page, and how these can be exported to "WPF/E" XAML. You then imported this XAML into a Visual Studio 2005 Web project and saw how to configure it to deploy the XAML runtime to Internet Explorer and Firefox, in order to render the "WPF/E" XAML from the designer. Finally, you looked at how you can manipulate the XAML to add animation, interaction, and media.

What you did in this article was only scratching the surface of what is possible with "WPF/E." There is a wealth of functionality within this technology that you can use to start building the next Web today. It should be a fun ride; so hop aboard!

Appendix I: The Install Experience

In order to view Web pages that have "WPF/E" content, you need to enhance the browser with "WPF/E." You can either use an object tag method that will prompt the user for the installation, or you can detect whether the browser is enhanced with "WPF/E" and point the user to the appropriate download page:

For PC: https://go.microsoft.com/fwlink/?LinkID=77792\&clcid=0x409
For Macintosh: https://go.microsoft.com/fwlink/?LinkID=77793\&clcid=0x409

With our application, we are using an object tag that prompts the user to install the appropriate "WPF/E" module if it is not already installed. That way, the first time a user runs an application, the browser will detect whether or not the "WPF/E" is installed. If “WPF/E” is not installed, when the user launches the page a dialog box will appear asking if the user would like to install “WPF/E.” The following sections detail the user experience when following this workflow using Microsoft Internet Explorer and Mozilla Firefox, respectively.

Running the Page in Internet Explorer

The Internet Explorer Security Warning dialog box shown in Figure 14 will appear. If you select Install, the plug-in will download and install as detailed in the following sections.

Figure 14. Browser security warning for "WPF/E" install
Select Install, and the installer Wizard will launch, as shown in Figure 15.

Figure 15. Starting the "WPF/E" setup
Read the End-User License Agreement carefully; and if you are good to continue, select I Accept. The WPFE Installation will then begin, as shown in Figure 16.

Figure 16. Installing "WPF/E"
When the installation completes successfully, you'll see the Installation Complete dialog box, as shown in Figure 17.

Figure 17. Installing WPF/E
Press Finish, and you're ready to go. In fact, your XAML will render straight away, as shown in Figure 18.

Figure 18. Your XAML, rendered in the browser

In the next section, you'll look at the experience of installing the plug-in on the Mozilla Firefox browser.

Running the Page in Mozilla Firefox

In the previous section, you saw how the "WPF/E" enhanced Internet Explorer. But "WPF/E" is a multibrowser, multiplatform technology. In this section, you'll see how it works within Mozilla Firefox running on Microsoft Windows Vista.

If "WPF/E" isn't installed, and you are using FireFox, you’ll be prompted to download the ‘install.msi’ file from the Microsoft site.

Figure 19. Downloading WPF/E Installer on FireFox
Once it is downloaded, you can run it, and you’ll follow the same install experience as the IE user.
When you are done, execute your page; the XAML will be rendered by "WPF/E" within Mozilla Firefox, as shown in Figure 20.

Figure 20. Rendering the XAML in Mozilla Firefox

Appendix II: Configuring Server MIME Types

Configuring IIS 6.x

It is very straightforward to configure IIS for the MIME types that are necessary to deliver "WPF/E" applications. If you are getting a blank page instead of the rendered XAML, it might be that you haven't configured XAML to be a recognizable XML type in IIS. To do this, call up your Web site Properties dialog box and select the HTTP Headers tab, as shown in Figure 21.

Figure 21. IIS 6.x configuration

At the bottom of this dialog box is a button that allows you to specify these types.

Note IIS-only server files with extensions are registered on this list; so, if .xaml isn't registered, you will not be able to serve these files and will not get XAML into your "WPF/E" control. Figure 22 shows how this should be configured. Use the New button on this dialog box to add it, if necessary.

Figure 22. Configuring the MIME type in IIS

Note While Figure 23 doesn't show it, if you want your application to be installable on the Macintosh, you should use application/octet-stream as the MIME type for the .DMG file extension.

Configuring IIS 7.x

To configure IIS 7.x in Windows Vista, you should first right-click Computer on the Windows Start menu, and select Manage. This will launch the Computer Management console, from where you can select IIS, as shown in Figure 23.

Figure 23. Computer Management console in Windows Vista (Click on the picture for a larger image)

Scroll down the list of items down until you see the MIME Types applet. Launch this to configure MIME types, as shown in Figure 24.

Figure 24. IIS 7 MIME types configuration (Click on the picture for a larger image)

You can use the Action pane to add the needed MIME types.

.XAML : text/xml
.DMG: application/octet-stream