Building Microsoft ASP.NET Applications for Mobile Devices, Second Edition [Electronic resources] نسخه متنی

Supporting a New Client

ASP.NET's XML-based configuration files make adding support for a new client relatively simple. You can modify the machine.config file or DeviceUpdate.config file to provide support for a new client in all your applications on that system. To provide support on an application-by-application basis, you can use an application's Web.config file.

Regardless of the configuration file you use, you must take three steps to add support for a new device:

Provide a regular expression that allows the runtime to identify the device.

Identify the capabilities of the device.

Enter these capabilities into the configuration file.

After you complete these steps, you of course will have to perform tests to ensure that the runtime correctly identifies your device and that the controls are rendered on the client as you expect.

Identifying the Device

The most common way to identify a device is to test the HTTP User-Agent request header with a regular expression. However, you can use any valid HTTP request header when determining the type of a new client. For example, some devices host dual-mode browsers that can handle both WML and HTML, so filtering on the User-Agent header is sufficient to distinguish between them. However, if the User-Agent string is the same, you can first use the User-Agent header to determine the type of device and then filter on the Accept-Type header to establish which type of content the browser is requesting.

In a mobile Web application, the value of the User-Agent header is accessible through the MobilePage.Request property. Of course, to find out the value of the User-Agent header for a new device, you can't just write an application that displays the value of MobilePage.Request in a Label control because your ASP.NET mobile controls application won't run because the client remains unsupported. However, you can use an ASP.NET application that uses the Trace facility to provide output—as demonstrated in the WhoAmI application we examined in Chapter 16. As an alternative to WhoAmI, you can write a simple mobile Web Forms page that has no graphical representation. The sample project WriteHTTPHeaders writes the value of the relevant headers to a local log file, as shown in Listing 19-2.

The code in Listing 19-2 writes the value of the User-Agent request header to the Header.log file. You'll need to ensure that the NTFS permissions on the application directory grant write access to the account that is used to run the application, which for a default application is the ASPNET account.

In this chapter, we'll use the EZOS EzWAP 2.1 browser to demonstrate the entire process of supporting a new client. (Go to http://www.ezos.com for a trial download.) EzWAP is a WML browser that's available for many devices, including the Pocket PC and the Palm personal digital assistant (PDA). When EzWAP accesses the application shown in Listing 19-2, the value of the User-Agent header is found to be EZOS – EzWAP 2.1 for Pocket PC.

Listing 19-2: Writing HTTP header values to a local file

<%@ Import Namespace="System.IO" %>
<%@ Page language="c#" Inherits="System.Web.UI.MobileControls.MobilePage"%>
<%@ Register TagPrefix="mobile" 
Namespace="System.Web.UI.MobileControls" 
Assembly="System.Web.Mobile" %>
<script runat="server" language="C#">
public void Page_Load(object sender, System.EventArgs e)
{
FileStream fs = new FileStream(Request.PhysicalApplicationPath + 
"header.log",
FileMode.Append,
FileAccess.Write);
StreamWriter log = new StreamWriter(fs);
//Write the user agent to the log file.
log.WriteLine(Request.UserAgent);
log.Flush();
log.Close();
}
</script>
<mobile:Form id="Form1" runat="server">
</mobile:Form>

After you've found the value of the User-Agent request header, you must construct a regular expression in your Web.config file that you'll use to identify a client that uses this particular User-Agent identification. Although you use regular expressions, the syntax is quite simple in most cases. For example, to test whether a device is an EzWAP browser, you first instruct the runtime to use the User-Agent header and then provide a regular expression using the match attribute of the <case> element. Here's the syntax:

<browsercaps>
<use var="HTTP_USER_AGENT"/>
<filter>
<case match="EZOS – EzWAP 2.1 for Pocket PC">
 
</case>
</filter>
</browsercaps>

However, you can expand the regular expression to capture the browser version information, which you can then use to populate the properties of the MobileCapabilities object. The following code identifies that the browser is EzWAP and captures information about the major and minor versions of the browser:

  <case match=
"EZOS - EzWAP (?'majorVersion'\d+)(?'minorVersion'\.\d+)(\w*)"
>

If you aren't familiar with regular expressions, Figure 19-2 will help you understand how the runtime uses the information in the User-Agent header. For details on the syntax of regular expressions, consult the .NET Framework SDK documentation.

Figure 19-2: Identifying a device by using a regular expression

After you add the regular expression to your configuration file, ASP.NET can identify the new device. However, ASP.NET can't render the correct content to the device. To enable this, you must provide values, which the runtime uses to populate the properties of the MobileCapabilities object. You must define these capability values as accurately as possible because the runtime and device adapter classes use them to provide the correct markup for that client device.

Identifying Device Capabilities

The MobileCapabilities object has a large number of properties that describe the characteristics of a mobile device. Table 19-1 shows the properties you'll use most frequently when providing the minimum set of capabilities for a new device. For a full list of properties, refer to the .NET Framework SDK documentation.

If these values are set correctly in the device configuration, ASP.NET Mobile Controls applications will be rendered acceptably on your new device. However, the MobileCapabilities object has many other properties that are not listed in Table 19-1, and you might want to set them as well to optimize the support for your new device. These include the CanRender* and Renders* categories of properties (for example, CanRenderPostBackCards and RendersBreaksAfterWMLAnchor), which define specific behaviors related to WML rendering; the Requires* category of properties (for example, RequiresLeadingPageBreak), which define specific requirements of a particular browser; and the Supports* category of properties (such as SupportsIModeSymbols), which define unique capabilities of the browser. In most cases, the default values for these properties will be suitable, although in some cases you might need to set some of them to optimize rendering on your device. The majority of these properties are required by code in the device adapter classes to fine-tune the markup that is sent to the client.

To support your new device, you must identify the capabilities it possesses so that you can define the correct values for these properties. There are three ways you can do this. First, you can refer to your device's documentation. You can determine many of the capabilities of your device from this information. For example, you might determine whether the device supports color and discover the type of markup language it supports.

Second, you can write an application in a markup language that the device supports. You can then use this application to test the device's capabilities. Of course, you must know the syntax of the markup language to use this approach. Third, you can list all the mobile capabilities of your device in your configuration file. Then, one by one, change the values of the capabilities and view the results in your browser. Although effective, this approach can be quite time consuming.

In reality, you'll use a combination of at least two of the approaches we just described, as well as a little of your own knowledge. For example, you might know that a device supports compact HTML (cHTML) and color without referring to the product documentation. But you might refer to the documentation to discover the size of the device's screen and the features specific to the device, such as whether it can send e-mail and initiate a voice call. Finally, you might determine the device's additional capabilities either by using native markup or by adjusting the values and viewing the results in your browser.

Using Markup to Identify Capabilities

Earlier in this section, you learned how to use a regular expression to test whether a browser was an EzWAP browser. Now you'll use WML code to test some of the capabilities of an EzWAP browser.

As described, some properties of the MobileCapabilities class relate to the way a specific markup language is rendered on a given device. An example of this is the RendersBreaksAfterWMLAnchor property. The default value for this property is false. When the ASP.NET mobile controls generate the markup code for the mobile Link control on WML devices, they generate a WML anchor element. On some WML browsers, such as the Nokia browser on the 7110 mobile phone, the browser automatically renders a break after an anchor, so on these devices, RendersBreaksAfterWMLAnchor is set to true. Other browsers don't automatically render a break. The rendering logic in the System.Web.UI.MobileControls.Adapters.WMLLinkAdapter device adapter class checks this property in the MobileCapabilities object for the requesting device and inserts a break into the output stream after an anchor only if RendersBreaksAfterWMLAnchor is false and the BreakAfter property of the Link control is true. You can easily ascertain the values of such properties by writing code in the native markup language that tests the properties. However, unless you're proficient in the markup language, it's quicker and simpler to establish a device's capabilities through testing. (You'll learn how to use this approach momentarily.)

In this example, you'll write WML code to test five properties: MaximumSoftkeyLabelLength, RendersBreaksAfterWMLAnchor, RendersBreaksAfterWMLInput, RendersWMLDoAcceptsInline, and RendersWMLSelectAsMenuCards. To test these properties, write a WML deck that contains two cards. The first card displays an input box and two ways to navigate to the second card, which contains a selection list. To link to the second card, provide a normal link using an anchor and then provide the second link using a <do> element. Listing 19-3 shows an Active Server Pages (ASP) page containing the WML code for these two cards.

Listing 19-3: TestBrowserCapabilities.asp sends raw WML to test browser capabilities.

<% Response.ContentType= "text/vnd.wap.wml" %>
<?xml version="1.0"?> 
<!DOCTYPE wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" 
"http://www.wapforum.org/DTD/wml_1.1.xml"> 
<wml> 
<card id="card1" title="Card #1" newcontext="true">    
<do type="accept" label="Softkey label">
<go href="#card2"/>
</do> 
<p align="center">
<input type="text" name="test"/>
Text after input box.
<br/>
<a href="#card2" title="anchor label">Next</a>
Text after anchor
</p>
</card> 
<card id="card2" title="Card #2"> 
<p align="center"> 
<select>
<option>One</option>
<option>Two</option>
<option>Three</option>
</select>
</p> 
</card> 
</wml>

Figure 19-3 shows the EzWAP browser displaying the two WML cards.

Figure 19-3: EzWAP browser displaying two WML cards that test a device's mobile capabilities

The browser renders a break after the input box but not after the anchor. In addition, the label attribute of the <do> element is displayed at the foot of the screen, like a softkey. The maximum length of the softkey's label is longer than the string you supplied. In fact, the EzWAP browser supports a very long string as its softkey label value. However, a value of 20 is suggested for ASP.NET mobile Web applications to maintain usability. When you access the second card, a link is displayed. When selected, this link displays a pop-up window that lists the select options. Thus, this simple piece of WML code establishes the values for the MobileCapabilities class properties listed in Table 19-2.

Although this example uses WML, you can just as easily test another device by using cHTML or HTML. The most important factor in using markup to identify device capabilities is that you carefully consider which capabilities you want to determine and then design your test code to exercise those capabilities.

Establishing Capabilities Through Testing

As mentioned, another way to establish a device's capabilities is to change the value of each property within the configuration file and view the results in the device's browser. Although subject to a little trial and error, this approach is simple, and it doesn't require any knowledge of specific markup languages.

You'll now establish some of the capabilities of the EzWAP browser through testing. In this particular instance, you find the values of the RendersBreaksAfterWMLAnchor and RendersBreaksAfterWMLInput properties. To do this, you must start with a configuration section in the application's Web.config file that supplies at least the bare minimum of details the runtime needs to identify the device and then attempt to render output. Listing 19-4 shows an example that starts configuration for the EzWAP browser.

Listing 19-4: Configuration through testing

<browserCaps>
<use var="HTTP_USER_AGENT" />
<filter>                    
<case 
match=
"EZOS - EzWAP (?'majorVersion'\d+)(?'minorVersion'\.\d+)(\w*)"
>
<!—start with previously established properties -->
browser="EzWAP"
type="EzWAP"
version= ${majorVersion}.${minorVersion }
majorVersion= ${majorVersion}
minorVersion =${minorVersion }
isMobileDevice="true"
mobileDeviceModel="Pocket PC"
preferredRenderingType="wml12"
preferredRenderingMIME="text/vnd.wap.wml"
preferredImageMIME="image/vnd.wap.wbmp"
inputType="virtualKeyboard"
<!—Test with default values for these properties first -->
rendersBreaksAfterWMLAnchor="false"
rendersBreaksAfterWMLInput="false"
</case>
</filter>
</browserCaps>

Now you must create a mobile Web Forms page for the new device to access. Because you're currently testing only the display characteristics of anchors and input dialog boxes, the mobile Web Forms page can be simple. Listing 19-5 shows an example of such a mobile Web Forms page.

Listing 19-5: Mobile Web Forms page to test new device configuration

<%@ Register TagPrefix="mobile" 
Namespace="System.Web.UI.MobileControls" 
Assembly="System.Web.Mobile" %>
<%@ Page language="c#" Codebehind="MobileWebForm1.apsx.cs"
Inherits="MSPress.MobWeb.TestBrowserCapabilities.MobileWebForm1"
AutoEventWireup="false" %>
<mobile:Form id="Form1" runat="server">
<mobile:TextBox id="TextBox1" runat="server"/>
<mobile:Label id="Label1" runat="server">
Text After Input
</mobile:Label>
<mobile:Link id="Link1" runat="server">
Link
</mobile:Link>
<mobile:Label id="Label2" runat="server">
Text After Link
</mobile:Label>
</mobile:Form>

Figure 19-4 shows the output the browser renders. Notice that a blank line appears between the text box and the text following it. From this, you can deduce that the browser does render a break after an input box. The text after the anchor appears on the very next line—clearly the browser doesn't automatically insert a break after anchors. Thus, you can deduce that the RendersBreaksAfterWMLInput property must be changed to true and the RendersBreaksAfterWMLAnchor property should stay set to false.

Figure 19-4: EzWAP browser displaying output from Listing 19-5

Configuration File Inheritance

When you define the capabilities of a device in a configuration file, you don't have to repeat the process for every application that the client will use. This is because Web.config files inherit and override settings, which you define in either a Web.config file, a machine.config file, or if present, a DeviceUpdate.config file. Remember, you'll only have a DeviceUpdate.config file if you are running .NET framework 1.1, and you have installed Device Update 2 or later.

When the runtime receives a request from a client, it determines the MobileCapabilities settings by searching each of the configuration files for a regular expression that matches for the requesting device. If the device is found in more than one file, the MobileCapabilities settings from each match are merged together. If any properties are defined in more than one file, the order of precedence is, from lowest to highest machine.config, DeviceUpdate.config, and then Web.config. As always Web.config files inherit from each other, so if you have a child folder that has a Web.config, it inherits settings from any Web.config file in the parent folder.

For example, you include a <browserCaps> section within the Web.config file for your application, and that section provides support for the EzWAP 2.1 browser. When an EzWAP browser makes a request, the runtime checks your application's Web.config file. It finds a match for the EzWAP browser, and so it uses that entry. If you use Microsoft Internet Explorer to make a subsequent request, the settings for Internet Explorer are taken from machine.config.