Using the WURFL API with Microsoft Web Pages

A lightweight alternative to ASP.NET MVC, Web Pages is the underlying platform for creating ASP.NET-based web sites outside of Visual Studio. Some parts of the Web Pages infrastructure are also shared with ASP.NET MVC—specifically the Razor view engine—but for the most part Web Pages is born to be the runtime engine behind WebMatrix—an alternate and totally free IDE for authoring ASP.NET sites. The difference between WebMatrix and Visual Studio is not limited to costs. As you may know, Visual Studio also has a free version—Visual Studio Express. Visual Studio Express, however, is simply the shrink wrapped version of the full-blown Visual Studio and offers the same development experience of its bigger brothers; WebMatrix instead offers a different programming experience and extensively relies on ad hoc components and widgets. Overall writing a Web site using Web Pages results in a different type of experience when compared to using ASP.NET Web Forms or ASP.NET MVC.

In this article, I’ll show you how to integrate the WURFL ASP.NET API in a web site developed using the Web Pages infrastructure and authored using WebMatrix in lieu of Visual Studio. I am also assuming that you are already all set with binaries and that both WebMatrix and Web Pages are correctly installed on your machine. If not, you can visit  http://www.asp.net/web-pages and  follow the (few) instructions listed to get started.

WURFL for ASP.NET

Once you have opened up WebMatrix and arranged a new blank project, the first thing you do is bringing up the Nuget window and add the WURFL package to the project. The Nuget setup adds some entries to the web.config file and binds a couple of executables to the project. It also downloads the most recent publicly available chunk of the WURFL database.

Take some time to review the license agreement WURFL comes with; essentially, you are free to use WURFL in open-source projects, but you may need to acquire a license from ScientiaMobile for any commercial use. Once you get a subscription, you gain access to database updates on a weekly basis. This ensures that you are always up-to-date with fixes and new devices as they hit the market.

Tweaking the web.config

The Nuget package setup adds a couple of lines to web.config. One adjustment being made regards the working mode of the WURFL library. In particular, you find the following:

<wurfl mode="Performance">
   <mainFile path="~/App_Data/wurfl-latest.zip" />
</wurfl>

The ZIP file is the database to replace once you’ve got a subscription; what you get by default is the latest public snapshot of the WURFL database at the time the Nuget package was released. Nothing here is set in stone, meaning that you can move the ZIP file to any location on the web server that you like and you can also freely rename the file. The WURFL library recognizes the database as plain XML file or compressed as a ZIP or GZIP file.

The mode attribute indicates the expected behavior of the library as far as device detection is concerned. The default value of Performance indicates that performance is privileged; however, you can trade performance for accuracy as well.

<wurfl mode="Accuracy">
   <mainFile path="~/App_Data/wurfl-latest.zip" />
</wurfl>

For mobile devices, you won’t notice any difference; for devices that happen to be desktop computers the Performance mode takes a shortcut and always identifies the user agent as a generic web browser. In other words, in Performance mode you won’t be able to distinguish say Internet Explorer 9 from Google Chrome or any version of Firefox. However, you always get full information about tablets or smartphones.

Adding global.asax

WURFL needs some bootstrapping code to be run only once per application start. To achieve this in ASP.NET, you might want to add a global.asax file to the project. In WebMatrix, you right-click to add a new file to the project, switch to the All view and then pick up the ASAX file for the language of choice. (See Figure 1.)

Ensure the global.asax file contains the following:

<%@ Application Language="C#" %>
<%@ Import Namespace="WURFL" %>
<%@ Import Namespace="WURFL.Aspnet.Extensions.Config" %>

<script runat="server">
    void Application_Start(object sender, EventArgs e) 
    {
        // Code that runs on application startup
        RegisterWurfl();
    }

    public static void RegisterWurfl()
    {
        MyApp.WurflContainer = WURFLManagerBuilder.Build(new ApplicationConfigurer());
    }
</script>

The WURFLManager.Build method uses a newly created instance of the ApplicationConfigurer class to detect the location of the database and then parses the content into memory. The returned object—known as the WURFL container—holds a cache of the WURFL data. You need to make this object global throughout the application so that you can query it for device details on every subsequent request. A good option is assigning the WURFL container object to a public static property of a global application object. For this reason, you add the App_Code folder to the project and create a new file in it named MyApp. (Note that the name MyApp is arbitrary.) Here’s the code for the MyApp.cshtml file:

@using WURFL;

@functions{
    public static IWURFLManager WurflContainer;
}

At this point, you are entitled to invoke MyApp.WurflContainer from every page in your application.

Querying for Device Capabilities

A Web Pages web site is a collection of pages written using the Razor syntax and saved to a CSHTML files. The pattern of using WURFL can be summarized as below:

1)      You run a query against the WURFL database using the user agent string as the key; you receive back from the library an object of type IDeviceInfo;

2)      You use the methods on the IDeviceInfo interface to know about specific capabilities of devices associated with the given user agent string;

3)      Based on the detected capabilities you intelligently serve ad hoc markup to the requesting browser.

In the sample project, I have just one page—default.cshtml—that is expected to perform a sort of a x-ray diagnostic exam on your browser. Here’s the code that queries WURFL about the operating system of the device:

@{
    // Grab WURFL info for a given UA
    var deviceInfo = MyApp.WurflContainer.GetDeviceForRequest(Request.UserAgent);

    // Query for some capabilities
    var cap_OperatingSystem = String.Format("{0} {1}",
              deviceInfo.GetCapability("device_os"),
              deviceInfo.GetCapability("device_os_version"));
}

WURFL provides over 400 capabilities for several thousands of different mobile devices, including tablets, smartphones, legacy phones, smart TVs, console boxes and regular desktop PCs. Full reference about supported capabilities can be found at http://www.scientiamobile.com/wurflCapability/tree. Any of the strings you documented at the URL can be passed to the GetCapability method.

Note that as of the current API (version 1.4.3.1) the GetCapability method always returns a string. In a future version, though, we plan to add a few extension methods that return strongly typed values for easier programming in both WebMatrix and Visual Studio.

Making Use of WURFL Data

Using WURFL in web sites means essentially two, non-exclusive things:

1)      You use WURFL to know the class of the device, whether it is a tablet, a smartphone or perhaps a smart TV. Next, armed with this knowledge you route the request to different class-specific views;

2)      You use WURFL to know about specific capabilities which take you to enable or disable certain features you expect to have in the page. For example, if the browser doesn’t support video streaming you may want to render some friendly messages or if the browser doesn’t support, say, RSTP streaming you might want to configure the streaming widget to use an ad hoc URL.

Once you know how to access the IDeviceInfo object for a given user agent string, you’ll almost done. All that remains to do is just rendering the page in the most appropriate way. Figure 2 shows the sample application in action. It takes a snapshot of the current device and renders it out. The sample application is available online for testing at http://www.expoware.org/wurfl.