Walkthrough: Adding Support for Devices

Article
09/14/2006

ASP.NET has an extensibility model that allows you to add support for new mobile devices. This support can be added in two ways.

Because different devices often share the same browsers, you might be able to provide support for the device with minimal developer effort by adding device information to the Web.config file for the application or to the Machine.config file for the server. The default Machine.config configuration file is stored in the following location:

systemroot\Microsoft.NET\Framework\version number\CONFIG

This file contains a <filter> element for every browser that is supported. For example, the section that detects the Microsoft Internet Explorer for the Pocket PC begins with "". Within this section is a <case> element that has a match attribute. The match attribute is set to the user agent that is sent from the device.

If there is not a corresponding match for your device in the Machine.config file, you can add device-specific rendering for the device by modifying the adapter files. The device adapters are available as C# source (.cs) files that ship with the product. These device adapter files can be recompiled to add additional support for devices.

The adapter files are responsible for the actual rendering of a particular control. For each mobile control, there is a corresponding HTML, WML, and cHTML adapter.

Note In some cases, the cHTML adapters inherit from the HTML adapter, so there is not always a one-to-one mapping with the controls. For more information, see Device Adapter Code.

Always attempt to add information to the configuration files before modifying the adapter files; it is much easier to add entries than to create a new adapter set. If you do need to create a new adapter set, you will need to create entries in the Machine.config and Web.config files so that the adapters can identify the new device.

The following walkthrough is designed to help get you started with creating new adapters.

Working with the WmlMobileTextBox Adapter

Every mobile control maps to an adapter file that provides the necessary information to render the correct markup language to a mobile device. For instance, a TextBox control uses the WmlTextBoxAdapter class to render the correct markup to a WML device. This adapter file contains a Render method that can be modified to change the type of markup sent to a client. The Render method normally contains a call to the WmlMobileTextWriter adapter that contains helper methods. In this walkthrough, the WmlMobileTextWriter helper Writer.RenderTextBox method helps you create an <input> tag to send to the client.

This walkthrough also illustrates how to use the GetAttribute method to read the testAttribute ** custom attribute, as shown in the following example.

<mobile:textbox id="TextBox1" testAttribute="First Name:" runat="server" />)

This test attribute can be set on a control at design time to generate a WML <input> tag at run time, as shown below.

<input  name="TextBox1" testAttribute="FirstName"/>

To modify the adapter file

Download the adapter source files from https://go.microsoft.com/fwlink/?LinkId=6350.
Open the copy of the WmlTextBoxAdapter.cs file for editing.
Locate the Render method in this file, and add the following code before the call to the Writer.RenderTextBox method.

[C#]
```
String myAttribute = ((IAttributeAccessor)Control).GetAttribute("testAttribute");
```

Add myAttribute as the last argument of the Writer.RenderTextBox call found in the Render method.

[C#]

writer.RenderTextBox(
   Control.ClientID, 
   value,
   format, 
   Control.Title,
   Control.Password, 
   Control.Size, 
   Control.MaxLength, 
   Control.BreakAfter,
   myAttribute
);

Because the previous procedure adds a new argument that is passed to the RenderTextBox method of the WmlMobileTextWriter, the RenderTextBox function must be modified to accept and use that argument. The following procedure illustrates how to modify this function for the additional argument, and also how to identify which device the new control attribute needs to be sent to by using an if statement.

To identify the device, the MobileDeviceModel property of the MobileCapabilities class is used. The MobileDeviceModel value is created in the Machine.config file when a device makes a request. If the correct device has made the request, then the WriteAttribute method of the WmlMobileTextWriter class is called to create the new markup.

To modify the WmlMobileTextWriter.cs file

Open the WmlMobileTextWriter.cs file.

Add the myAttribute string argument to the RenderTextBox method, as shown in the following example.

[C#]

public virtual void RenderTextBox(
   String id, 
   String value,
   String format,
   String title,
   bool password, 
   int size, 
   int maxLength, 
   bool breakAfter,
   String myAttribute
)

Add the following code to the RenderTextBox method before the WriteLine(" />"); code.

[C#]

string type = Device.MobileDeviceModel;   
if(type == "Generic Simulator")
{
   if(myAttribute!=null && myAttribute.Length > 0)
   {
      WriteAttribute("testAttribute", myAttribute);
   }
}

In some cases, other adapters have dependencies on an adapter that you have modified. For example, the UPWmlMobileTextWriter class is specifically designed for the Openwave UP.Browser and inherits from the WmlMobileTextWriter class. This requires the developer to also modify the RenderTextBox method in the inherited class using the following steps.

To modify the UPWmlMobileTextWriter.cs file

Open the UPWmlMobileTextWriter.cs file.

Add a string argument called myAttribute to the RenderTextBox method, as shown in the following example.

[C#]

public override void RenderTextBox(
   String id, 
   String value,
   String format, 
   String title,
   bool password, 
   int size, 
   int maxLength, 
   bool breakAfter,
   String myAttribute
)

Modify the call to base.RenderTextBox that is found in the RenderTextBox method to pass the myAttribute argument.

[C#]
```
base.RenderTextBox(id, value, format, title, password, size, maxLength, false, myAttribute);
```

After the adapter files have been modified, create a new assembly that can be used in your mobile Web applications.

To create a new assembly

Open a Microsoft Visual Studio .NET command prompt by clicking the Start button. Next, select the Programs menu, select the Microsoft Visual Studio .NET menu, select the Visual Studio .NET Tools menu, and then click Visual Studio .NET Command Prompt.
In the Visual Studio .NET Command Prompt window, enter the following command with the location of the new adapter files that was created in the first procedure in this walkthrough.
```
cd hdd:\new adapter folder location
```

Enter the following command to compile and create a new adapter DLL.

Csc /target:library
/out:System.Web.UI.MobileControls.ShippedAdapterSource.dll
/r:System.Web.Mobile.dll
/debug+
/D:COMPILING_FOR_SHIPPED_SOURCE
/nowarn:0679
*.cs

After the new adapter assembly has been created, it must be referenced in the Web application. The Web.config file must also be updated to override the Machine.config settings so that the new assembly is used. If you are using custom attributes, you need to set the AllowCustomAttributes property in the Web.config file.

To configure the Web application

In Visual Studio .NET, right-click the project name in Solution Explorer and select Add Reference.
Click the Browse button, navigate to the new adapter assembly, and then click Open. Click OK.
Add support for the new adapter assembly by copying the code in the Web.config-shippedAdapaters file you downloaded into your project Web.config file.

Note Omit the opening and closing <system.web> tags because they are already in the Web.config file that Visual Studio .NET generates.
In the Web.config file, add support for custom attributes by setting the AllowCustomAttributes property of the existing <mobileControls> tag equal to true, as shown in the following example.
```
<mobileControls allowCustomAttributes="true">
</mobileControls>
```
Recompile your Visual Studio .NET project.

Walkthrough: Adding Support for Devices

Working with the WmlMobileTextBox Adapter

See Also

Additional resources