hat was once known as the Mobile Internet Toolkit is now ASP.NET mobile controls. It’s the only Microsoft technology that enables you to target multiple devices?including Palm devices, Pocket PCs, WAP phones, etc. More than 200 devices and emulators are supported.

Here’s how it works: A single application or Web page with multiple controls renders itself automatically based on the client device. As a developer you only need to write one code base. ASP.NET’s mobile technology, called the Adaptive Rendering Model, manages the complexity of device proliferation for you.

In this article I’ll show you how to create your own direct control from scratch, but first it is important to understand the architecture of the ASP.NET Adaptive Rendering Model. There are three parts that function together to enable rendering to multiple devices: The ASP.NET mobile controls, the device adapter, and the device adapter definition.

Mobile Controls: These are the same types of controls that’d you’d find in standard ASP.NET, including buttons, labels, and text boxes, but designed specifically for handheld devices with small displays.

Device Adapter: Roughly equivalent to device drivers in Windows, device adapters’ job is to generate output from a control. There are various device adapters that are grouped by families that map to markup languages such as HTML 3.3, cHTML, WML (1.1 and 1.2), and XHTML.

Device Adapter Definition: It maps between devices, controls, and device adapters.

These three parts work together in the rendering process. Figure 1 shows a page, Mobile.aspx, with a PhoneCall control. A PhoneCall control when viewed from a mobile phone allows a person to make a call by clicking on the control. However, when a user from a web page accesses it, it just displays alternate-text specified in the control. When a user with a WAP mobile phone accesses the page via a WAP gateway, the MobileCapabilities class is used by the rendering mechanism to determine the browser and the device. Then the page instantiates the control and an appropriate device adapter is selected; in this case the WML Adapter is used, so WML is returned to the device. When that process is complete, the user can dial the phone number specified in the phone call control.

Figure 1. The PhoneCall Control: The MobileCapabilities class determines what device driver to instantiate so that a phone call can be made by clicking the control.

Figure 2. Pocket PC: In the Pocket PC version of the .aspx page from Figure 1, the mobile framework provides the alternate text, as specified for this device when a PhoneCall control is encountered.

In Figure 2 a Pocket PC device is accessing the same page. The same steps are repeated, however Pocket PCs do not support making phone calls. ASP.NET invokes the HTML device adapter and returns the alternate-text specified in the control to the user via HTML. This is the specified action for the Pocket PC with this control.

It is important to note that the .aspx page is compiled only once but depending on the device accessing the page, different adapters are used. Microsoft provides a Mobile Application Architecture animated presentation of this entire rendering model.

Writing Your Own Controls
The mobile controls architecture provides multiple extensibility options via user controls, inheritance controls, and composite controls. In all of these methods you’re using existing controls and adding functionality to them. However sometimes none of the controls suffice, and creation of a new control from scratch is required.

When you write a custom control from scratch you need to do three things:

• Create a new mobile control in an assembly
• Write your own adapters for this control and
• Provide adapter mappings.

Further, there are three principles to keep in mind when writing your controls:

• Your control code should be device-independent
• You need to write specific adapters for each type of device that requires a different type of rendering for the control and
• Your code design should be reusable so that other developers can inherit properties and methods from your control.

You are going to create a new multi-line textbox control that isn’t present in the ASP.NET mobile controls. Building this new control is a four-step process:

• Create a class library project for the control
• Inherit from the MobileControl base class
• Add the necessary methods, properties, and events
• Compile into an assembly

Step 1: Create a Class Library Project for the Control.
The first thing you need to do is create an ASP.NET Mobile Web project. It will create a mobile Web page that will be a test harness for the control. To do it, create a new Visual Studio.NET project; choose ASP.NET Mobile Web Application as the template type. Name the project as “ASP.NET Mobile Controls.” Visual Studio.NET will create the basic project with a default mobile Web form called MobileWebForm1.aspx.

Now add a new project to this solution. Choose Class Library as the Template type and name the project “DirectMobileClassLibrary.” Visual Studion.NET will create a new class file, which you should rename to MultiLineTextBox.vb. Rename the class name as well to MultiLineTextBox.

To the DirectMobileClassLibrary you need to add references to the System.Web and System.Web.Mobile components. Right click the project name in Solution Explorer, choose Add reference, and choose System.Web.dll and System.Web.Mobile.dll.

Add the following Imports statements at the top of the class file MultiLineTextBox.vb:

Imports SystemImports System.Web.UIImports System.Web.UI.MobileControlsImports System.Web.UI.MobileControls.Adapters

Step 2: Inheriting from the MobileControl Base Class
You need to modify the class definition to inherit from the MobileControl base class. The MobileControl class is the base class for all ASP.NET mobile controls; it contains style and context information common to all controls. You should also provide a namespace for this class as shown below.

NameSpace myMobileControlsPublic Class MultiLineTextBox : Inherits MobileControlEnd ClassEnd NameSpace

Step 3: Add the Necessary Methods, Properties, and Events
For a multi-line text box you need three properties: rows, cols, and text. ViewState is used to store the property values. When using ViewState to store a value you must always check to make sure it’s not null/nothing as otherwise a null exception will be raised (see Listing 1).

Step 4: Compile into an assembly
Hit Ctl+Shift+F5. This will build the entire solution file and generate the control assembly.

Your control is now ready. Now you need to create the control adapter and then create the mapping between the control and the adapter.

Creating the Control Adapter
There are two different control adapter classes, HTMLControlAdapter and WMLControlAdapter. They contain the basic adapter functionality. You need to create one control adapter per adapter family. Here you are going to create an HTML control adapter for the MultiLineTextBox control. You need to create a class library project (alternatively define the class in the same file) and inherit from the HTMLControlAdapter class.

You have to override the render method and put in your custom rendering code. To simplify things here, I’ve added the control adapter code to the same file (MultiLineTextBox.vb) just after the class definition of the MultiLineTextBox control, but within the same namespace (see Listing 2).

First you need to get a reference to the instance of the mobile control, which is done via the helper property “Control” which shadows the base control property. You need to overload and override the Render method and provide the output implementation. The reason one doesn’t just override but also overloads is because the Render method in the base class is overloaded.

You use an HTMLMobileTextWriter to write your text output. Start off with the EnterStyle method and then use the Write method. In HTML, a TextArea tag is similar to a MultiLineTextBox, hence within the Render method you need to write the output starting with a TextArea tag as it allows multiple lines of text to be written. Then specify the row and column for the TextArea and finally write the Text. Once that is done you close the TextArea tag. The “>” tag in the middle is to close the initial TextArea tag once the row and cols have been specified.

Mapping the Control and Adapter
The final step is to provide the control mapping. At the top level, Machine.Config contains the various mappings between devices and controls and is the place where you put global mappings. The Web.Config file does it at an application level.

You need to edit the Web.Config file in the “ASP.NET Mobile Controls” project and replace the default section with the code below:

The device tag is used to specify a new adapter called exHTMLDeviceAdapters(this could be any name you choose), this inherits from the base HTMLDeviceAdapters. You specify the fully qualified control class name followed by the control namespace. Lastly, specify the control adapter you’ve just created. Once again you specify the adapter’s fully qualified class name and the Namespace. This completes the mapping.

Using the Control in your Application
Add a reference to the control assembly by right clicking the “ASP.NET Mobile Controls” project, choose Add Reference, select the Projects tab, select the “DirectMobileClassLibrary,” and click OK. Next open the “MobileWebForm1.aspx” page. The blank ASP.NET mobile form comes up. Select the HTML view at the bottom to view the HTML associated with this ASP.NET page. You need to register the control on the page by adding the following code at the top of the file “MobileWebForm1.aspx.”

<%@ Register TagPrefix="myControl" Namespace="DirectMobileClassLibrary.myMobileControls" 
Assembly="DirectMobileClassLibrary" %>

ASP.NET mobile controls have a TagPrefix of mobile, however because you have a new control you need to specify the TagPrefix(any name), and provide the Namespace and Assembly in which the control resides. The TagPrefix would be used to pre-fix your control on the page. Next you need to place the actual control on the page within the form tag.

You can also set the controls properties by specifying the rows, cols, and text as shown above.

Testing the Application
Hit F5 to run the application. The MobileWebForm1.aspx page loads, the control within it loads, and the adapter code kicks in to render the control as a TextArea control in your default browser. If you load up the PocketPC emulator that comes with VS.NET 2003 and try the application, it works beautifully even there as the emulator supports HTML rendering.

The ASP.NET mobile environment and the rendering technology is the most extensible technology from the Redmond stable. You can easily build any kind of controls and adapters from scratch, as I’ve done in this article. And, there are options to extend existing controls and support new devices. As a best practice, always check if the existing controls within ASP.NET can be extended to support any new requirement you may have.

This same rendering and extensibility technology is going to be available in all the new .NET controls in Whidbey, thereby allowing you to peacefully use any control, knowing it will render automatically to any device and enabling you build/extend a control for multiple devices. And that is something big to look forward to.