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

Defining Mobile Devices in Configuration Files

To add support for a new client, you must understand how the runtime identifies a client and renders the markup most suitable for it. Figure 19-1 illustrates the process the runtime undertakes to determine the client type and to make the client identification available to your application.

Figure 19-1: Identifying a client

In Figure 19-1, the client makes a request for a mobile Web Forms page. When the runtime receives the request, it creates an instance of the HttpRequest class. This object exposes a MobileCapabilities object (through the Browser property), which the runtime uses to store information about the capabilities of the requesting device. The runtime then checks the application configuration file (Web.config) and the system configuration file (machine.config) for <browserCaps> sections. If you have installed Device Update 2 or later and you are running .NET Framework 1.1, there is also a <browserCaps> section in the file DeviceUpdate.config. The files machine.config and DeviceUpdate.config (if present) are in the /Microsoft.NET/Framework/version/CONFIG directory under the system root directory /WINNT or /Windows.

Listing 19-1 provides an extract from one of these files. In this listing, the <browserCaps> section contains a large number of <case> sections, one for each supported client browser. These sections use a regular expression to match the HTTP_USER_AGENT environment variable, which the requesting browser originally passes as an HTTP request header. If a match occurs, the runtime successfully identifies the device type. The runtime then uses the information in the <case> section of the configuration file to populate the MobileCapabilities object.

Listing 19-1: Sample <case> section for a Nokia 7110 within the Browser Capabilities section of an ASP.NET configuration file

<browserCaps>
<use var="HTTP_USER_AGENT" />
<filter>                    
<!-- Nokia -->
<case
match="Nokia.*">
browser = "Nokia"
mobileDeviceManufacturer = "Nokia"
preferredRenderingType = "wml11"
preferredRenderingMime = "text/vnd.wap.wml"
preferredImageMime = "image/vnd.wap.wbmp"
defaultScreenCharactersWidth = "20"
defaultScreenCharactersHeight = "4"
defaultScreenPixelsWidth="90"
defaultScreenPixelsHeight="40"
screenBitDepth = "1"
isColor = "false"
inputType = "telephoneKeypad"
numberOfSoftkeys = "2"
hasBackButton = "false"
rendersWmlDoAcceptsInline = "false"
rendersBreaksAfterWmlInput = "true"
requiresUniqueFilePathSuffix = "true"
maximumRenderedPageSize = "1397"
canInitiateVoiceCall = "true"
requiresPhoneNumbersAsPlainText = "true"
rendersBreaksAfterWmlAnchor = "true"
canRenderOneventAndPrevElementsTogether = "false"
canRenderPostBackCards = "false"
canSendMail = "false"
<filter>
<case
match="Nokia7110/1.0 \((?'versionString'.*)\)">
type = "Nokia 7110"
version = ${versionString}
<filter
with="${versionString}"
match=
"(?'browserMajorVersion'\w*)(?'browserMinorVersion'\.\w*).*">
majorVersion = ${browserMajorVersion}
minorVersion = ${browserMinorVersion}
</filter>
mobileDeviceModel = "7110"
optimumPageWeight = "800"
screenCharactersWidth="22"
screenCharactersHeight="4"
screenPixelsWidth="96"
screenPixelsHeight="44"
</case>
</filter>
</case>
</filter>
 
</browserCaps>

If the runtime doesn't successfully match the requesting device to one of the <case> sections, it populates the MobileCapabilities object with the default settings, which are found at the beginning of the <browserCaps> section in machine.config, which classifies the requesting device as an HTML 3.2 browser of type Unknown.

In most instances, you can successfully add support for a new client by adding a new <case> section in the <browserCaps> element. This element defines a suitable regular expression to match the HTTP_USER_AGENT string the device sends, and it contains information defining the device's capabilities. You'll learn how to identify the characteristics of a new device and provide support for it in the section "Supporting a New Client," later this chapter.

When the runtime searches for a device in the <browserCaps> sections, it does so in the following order: machine.config, then DeviceUpdate.config, and then Web.config (the application configuration file). If there are duplicate device definitions in any of these files, the runtime merges the different sections together so that the resulting MobileCapabilities object combines the settings for that device in each of the files. If there are duplicates for individual settings for a particular device in different configuration files (for example, maximumRenderedPageSize is set to 1397 for the Nokia 7110 in machine.config, but set to a different value in Web.config), the value that is used is the last one the runtime reads (the value in Web.config in this example).

Device Configuration Files in .NET Framework 1.1

In the first release of the .NET Framework, version 1.0, when you installed the Mobile Internet Toolkit to add support for ASP.NET mobile controls, all the device configuration XML was inserted into machine.config. When Device Update 1 was released, these definitions too went into machine.config. If you install Device Update 2 or later into a .NET Framework 1.0 installation, these updates also go into machine.config.

The machine.config file is of critical importance to a .NET Framework installation and defines many crucial settings in addition to device capabilities. Many companies like to keep this file under tight version control, so it's better to remove the comparatively volatile device update configuration to another file.

If you install Device Update 2 or later onto a .NET Framework 1.1 system and then examine the machine.config file, you'll still find the device definitions that were in the Mobile Internet Toolkit 1.0, but at the head of that section of the file is the following XML:

<browserCaps>
<result type="System.Web.Mobile.MobileCapabilities, System.Web.Mobile,
Version=1.0.5000.0, Culture=neutral, 
PublicKeyToken=b03f5f7f11d50a3a" /> 
<file src="deviceupdate.config" />
<use var="HTTP_USER_AGENT" />
 

The line <file src="deviceupdate.config" /> is a link to the separate file containing device updates. When you install Device Update 2 on a system that has .NET Framework 1.1 installed, it places its browser definitions into this file, and it's recommended that you add any custom definitions to DeviceUpdate.config also. Be aware that the contents of this file will be replaced when you install future device updates, so be sure to keep a copy of any custom definitions and reapply them to DeviceUpdate.config after future upgrades.