Browser Definition File Schema (browsers Element)

Browser definition files contain definitions for individual browsers. At run time, ASP.NET uses the information in the request header to determine what type of browser has made the request. Then ASP.NET uses .browser files to determine the capabilities of the browser, and how to render markup to that browser. This is useful to Web developers who want to create applications that can be viewed on mobile devices, making use of control adapters that adapt the behavior of an ASP.NET Web server control depending on the type of device. For more information, see the links in the See Also section.

Note

Browser definition files are new in the .NET Framework version 2.0. In earlier versions of the .NET Framework, the browserCaps element was used to define browser definitions in configuration files.

The browsers element uses the following structure.

<browsers>
    <browser id="browser name"
             parentID="parent browser name"
             refID="reference ID">
        <identification>
            <userAgent match="regular expression"
                       nonMatch="regular expression" />
            <header match="regular expression"
                    name="header name"
                    nonMatch="regular expression" />
            <capability match="regular expression"
                        name="capability name"
                        nonMatch="regular expression" />
        </identification>
        <capture>
            <userAgent match="regular expression" />
            <header match="regular expression"
                    name="header name" />
            <capability match="regular expression"
                        name="capability name" />
        </capture>
        <capabilities>
            <capability name="capability name"
                        value="capability value" />
        </capabilities>
        <controlAdapters markupTextWriterType="type name">
            <adapter adapterType="name of adapter class"
                     controlType="name of control class" />
        </controlAdapters>
        <sampleHeaders>
            <header name="header name"
                    value="header value" />
        </sampleHeaders>
    </browser>
    <gateway id="gateway ID"
             parentID="parent browser ID">
        <!-- Same child elements as for <browser>.
        <identification></identification>
        <capture></capture>
        <capabilities></capabilities>
        <controlAdapters></controlAdapters>
        <sampleHeaders></sampleHeaders>
         -->
    </gateway>
    <defaultBrowser id="Default" 
                    parentID="parent browser ID"
                    refID="reference ID" >
        <!-- Same child elements as for <browser>.
        <identification></identification>
        <capture></capture>
        <capabilities></capabilities>
        <controlAdapters></controlAdapters>
        <sampleHeaders></sampleHeaders>
         -->
    </defaultBrowser>
</browsers>

Attributes and Elements

Element	Description
adapter	Specifies a mapping between an ASP.NET Web server control and the adapter used to render it in the current browser. For example, the following definition for the NokiaMobileBrowserRainbow browser contained in the Nokia.browser file specifies that Menu server controls be adapted to the browser using the MenuAdapter control adapter class: <controlAdapters markupTextWriterType="System.Web.UI.XhtmlTextWriter" > <adapter controlType="System.Web.UI.WebControls.Menu" adapterType="System.Web.UI.WebControls.Adapters.MenuAdapter"> </adapter> </controlAdapters> The following table describes the required attributes that are contained in the adapter element. Attribute Description adapterType Required String attribute. Specifies the name of the class that is used to change the way the control is adapted to the browser. controlType Required String attribute. Specifies the name of the control to map to the adapter. The adapter element contains no child elements.
browser	Defines a single browser definition. The following table describes the attributes that the browser element can contain. Note Do not change browser definition files that come with ASP.NET because service packs might update those files, overwriting your changes. Instead, create new .browser files and use the parentID attribute in a new browser definition to inherit settings, or use the refID attribute to add capabilities to an existing browser definition. A browser definition must define either the refID attribute, or both the id and parentID attributes. Attribute Description id String attribute, required if the parentID attribute is used. Specifies the unique name for the browser that is being defined. parentID String attribute, required if the id attribute is used. Specifies the unique name of the parent browser definition from which to inherit settings. These settings can be overwritten in the current browser definition. The parent browser definition does not have to be in the same browser definition file, but it must be defined in the same application or in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory. For example, the following definition for the WebTV browser is defined in the WebTV.browser file. The definition for the IE2 parent browser is defined in the IE.browser file in the same directory. <browser id="WebTV" parentID="IE2"> refID String attribute, can not be used if the id and parentID attributes are used. Specifies an existing browser-definition identifier. Use the refID attribute to associate new capabilities with an existing browser definition. You can configure multiple browser nodes to refer to the same refID. If the refID attribute is specified, the browser element can not contain an identification child element. The refID attribute does not replace the targeted element; instead its settings are applied after all of the other attribute settings have been applied. The order the settings are applied is: all <gateway parentID> nodes all <gateway refID> nodes all <browser parentID> nodes all <browser refID> nodes The following example definition adds new capabilities to the existing IE browser definition contained in the IE.browser file. <browser refID="IE"> <capabilities> <capability name="UseRichTextBox" value="true" /> </capabilities> <controlAdapters> <adapter controlType="System.Web.UI.Calendar" adapterType="ExampleAdapters.ExampleIECalendarAdapter" /> </controlAdapters> </browser> The browser element can contain zero or one of the following child elements: capabilities capture controlAdapters identification sampleHeaders
browsers	Represents the required root element of a .browser file.
capabilities	Defines capability values to set for the current browser definition. For a list of strongly-typed browser capabilities, see the properties of the HttpCapabilitiesBase class. Most of these properties use camel casing in browser definition files. You can also add your own capability values. The capabilities element contains no attributes. The capabilities element can contain zero or more of the following child element: capability
capability (child element of capabilities)	Defines a single capability value to set for the current browser definition. For example, the following capabilities are defined for the IE browser definition in the IE.browser file. This example definition inherits other capabilities from the Mozilla browser definition in the Mozilla.browser file. The values that contain text inside of a dollar sign followed by braces (${}) are replaced with the captured values from the match expression in the userAgent child element of the identification element "^Mozilla[^(]*\([C|c]ompatible;\s*MSIE (?'version'(?'major'\d+)(?'minor'\.\d+)(?'letters'\w*))(?'extra'[^)]*)". <capabilities> <capability name="browser" value="IE" /> <capability name="extra" value="${extra}" /> <capability name="isColor" value="true" /> <capability name="letters" value="${letters}" /> <capability name="majorversion" value="${major}" /> <capability name="minorversion" value="${minor}" /> <capability name="screenBitDepth" value="8" /> <capability name="type" value="IE${major}" /> <capability name="version" value="${version}" /> </capabilities> The capability element contains the following required attributes. Attribute Description name Required String attribute. Specifies the name of the capability. For a list of strongly-typed browser capabilities, see the properties of the HttpCapabilitiesBase class. Most of these properties use camel casing in browser definition files, for example, canSendMail instead of CanSendMail. You can also add your own capability values. value Required String attribute. Specifies the value of the capability. Possible values for each of the strongly-typed browser capabilities are listed in the properties of the HttpCapabilitiesBase class. The value attribute can contain captured variables inside "${}" The capability element contains no child elements.
capability (child element of identification or capture)	Specifies that the value of a capability from the parent browser class be matched against a regular expression. For example, the following definition for the IE5to9 browser contained in the IE.browser file uses a capability element to specify that the majorversion capability setting of the IE parent definition must match the included regular expression in order for this browser definition to be matched to the client's browser. This example browser definition includes capability elements that add to or overwrite the elements in the parent definition. <browser id="IE5to9" parentID="IE"> <identification> <capability name="majorversion" match="^[5-9]" /> </identification> <!-- Capability elements. --> </browser> The following table describes the attributes that the capability element contains. Either the match or nonMatch attribute must be defined, but not both. Attribute Description match String attribute, can not be used in the same element as the nonMatch attribute. Specifies the regular expression that the parent capability setting must match to satisfy this identification. For information about formatting regular expressions, see .NET Framework Regular Expressions. name Required String attribute. Specifies the name of the parent capability. nonMatch String attribute, can not be used in the same element as the match attribute. This attribute is not used in the capability child element of the capture element. Specifies the regular expression that the parent capability setting must not match to satisfy this identification. The capability element contains no child elements.
capture	Defines information about what additional header, userAgent or capability elements to use to capture information about the browser. This is useful when trying to detect new browsers that were not available when the .NET Framework 2.0 was released. To capture values, a browser definition can include regular expression captures in the match attribute of any identification element. For example, the following userAgent element defined in the IE.browser file captures the height of the screen in pixels from the user agent request header. <capture> <userAgent match="PalmSource; Blazer 3\.0\)\s\d+;(?'screenPixelsHeight'\d+)x(?'screenPixelsWidth'\d+)$" /> </capture> A browser definition might also need to capture additional information by scanning request headers that are not used to distinguish the browser class. For example, the following capture element captures the number of soft keys for an OpenWave cellular phone. Soft keys display menus and commands when you press corresponding hardware buttons on Windows Mobile-based SmartPhones: <capture> <header name="HTTP_X_UP_DEVCAP_NUMSOFTKEYS" match="(?'softkeys'\d+)" /> </capture> The capture element contains no attributes. The capture element can contain zero or more of the following child elements: header userAgent capability
controlAdapters	Defines a control adapter to use to adapt the server control on the browser. The following table describes the attribute that the controlAdapters element contains. Attribute Description markupTextWriterType Optional String attribute. Specifies the .NET Framework type of the markup text writer to use. The default type is System.Web.UI.XhtmlTextWriter, but other possibilities values for this attribute are System.Web.UI.Html32TextWriter, System.Web.UI.HtmlTextWriter, System.Web.UI.ChtmlTextWriter, or any custom class derived from one of these classes. The controlAdapters element can contain zero or more of the following child element: adapter
defaultBrowser	Defines default browser capabilities in the Default.browser file. Default browser definitions do not match any specific physical browser but are used by other definitions to inherit settings. For example, the following Default browser definition is contained in the Default.browser file: <defaultBrowser id="Default"> <capabilities> <capability name="ecmascriptversion" value="0.0" /> <capability name="javascript" value="false" /> <capability name="jscriptversion" value="0.0" /> </capabilities> </defaultBrowser> The Default browser definition is inherited by many other browser definitions. For example, the following definition for the Panasonic browser is contained in the Panasonic.browser file. <browser id="Panasonic" parentID="Default"> The following table describes the attribute that the defaultBrowser element contains. Attribute Description id Required String attribute. Specifies the unique name for the browser. The defaultBrowser element can contain the same child elements as the browser element.
gateway	Specifies a single gateway definition. Some mobile browsers are connected to the Web server through a gateway, which can add its own capabilities. It is possible for multiple gateway elements to refer to the same refID attribute. The gateway element can contain the same attributes and child elements as the browser element. For example, the following definition for the IE3AK gateway is from the IE.browser file. <gateway id="IE3AK" parentID="IE3"> <identification> <capability name="extra" match="; AK;" /> </identification> <capture> </capture> <capabilities> <capability name="ak" value="true" /> </capabilities> </gateway>
header (child element of identification or capture)	Specifies an expression against which to match or capture a specific HTTP header in the request. For example, the following definition for the Wml browser contained in the Default.browser file identifies a matching browser by comparing the Accept header to two regular expressions. <identification> <header name="Accept" match="text/vnd\.wap\.wml|text/hdml" /> <header name="Accept" nonMatch="application/xhtml\+xml; profile|application/vnd\.wap\.xhtml\+xml" /> </identification> The following table describes the attributes that the header element contains. Either the match or nonMatch attribute must be present, but not both. Attribute Description match String attribute, can not be used in the same element as the nonMatch attribute. Specifies the regular expression that the request header value must match to satisfy this identification. For information about formatting regular expressions, see .NET Framework Regular Expressions. name Required String attribute. Specifies the name of the header. nonMatch String attribute, can not be used in the same element as the match attribute. This attribute is not used in the capability child element of the capture element. Specifies the regular expression that the request header value must not match to satisfy this identification. The header element contains no child elements.
header (child element of sampleHeaders)	Specifies a single sample header for this browser. This element is optional, and for informative purposes only. A simulator or debugging tool can use this set of headers to emulate the browser for a request. The following table describes the attributes that the header element contains. Attribute Description name Optional String attribute. Specifies the name of the header. value Optional String attribute. Specifies the value of the header. The header element contains no child elements.
identification	Defines information about how to identify this browser from the incoming request. The identification element contains no attributes. The identification element can contain one or more of the following child elements: header userAgent capability
sampleHeaders	Specifies a set of sample headers for this browser. This element is optional, and for informative purposes only. A simulator or debugging tool can use this set of headers to emulate the browser for a request. The sampleHeaders element contains no attributes. The sampleHeaders element can contain zero or more of the following child element: header
userAgent	Specifies an expression against which to match the user agent header of a request. For example, the following definition for the IE4 browser contained in the IE.browser file uses the "MSIE 4" string to identify the browser by the user agent header that it sends with the request. <identification> <userAgent match="MSIE 4" /> </identification> The following table describes the attributes that the userAgent element contains. Either the match or nonMatch attribute must be present, but not both. Attribute Description match String attribute, can not be used in the same element as the nonMatch attribute. Specifies the regular expression that the user agent must match to satisfy this identification. For information about formatting regular expressions, see .NET Framework Regular Expressions. nonMatch String attribute, can not be used in the same element as the match attribute. Specifies the regular expression that the user agent must not match to satisfy this identification. This attribute is not used in the capability child element of the capture element. The userAgent element contains no child elements.

Remarks

If you find that none of the existing browser-definition files meets your criteria, you can create new browser-definition files by using the code in the Example section below.

Security Note
Do not download or install browser-definition files from third-parties unless you trust their source. Examine a new browser definition file to see if any unfamiliar namespaces are referenced. For more information, see Securing Browser Definition Files.

Predefined browser definition files are stored in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory. Application-level browser-definition files can be placed in the application's App_Browsers directory. In both locations, browser definition files must have a .browser file name extension. Do not change browser definition files that come with ASP.NET because service packs might update those files, overwriting your changes. Instead, create new .browser files and use the parentID attribute in a new browser definition to inherit settings, or use the refID attribute to add capabilities to an existing browser definition.

At run-time, browser-definition file information is merged into a collection of known browsers in a BrowserCapabilitiesFactory object. When a request is made, ASP.NET identifies the requesting browser by the request header, and compiles an HttpBrowserCapabilities object that corresponds to the type of the requested browser. This is done by starting with an empty dictionary, and applying the following recursive steps against the browser definition tree:

1. Start at the default browser definition, which is always considered a successful match.

2. Merge capability values specified in this browser definition into the capabilities dictionary for this browser. Values specified in a browser definition override values set in a parent.

3. Evaluate each child definition to determine a match. For each matching child, start at step 1 again. Browser definitions are evaluated after gateway definitions. If the user agent matches more than one browser definition or more than one gateway definition, an exception is thrown at run-time.

The HttpBrowserCapabilities object is cached and might be used again for a different request from the same type of browser.

A Web application can access the current instance of the HttpBrowserCapabilities object using the System.Web.HttpRequest.Browser property. This object is read-only, and contains properties for each capability. Alternatively, a Web developer can construct a custom class that inherits from the HttpBrowserCapabilities class and store an instance in the System.Web.HttpRequest.Browser property.

Changes to .browser files located in the App_Browsers directory invalidate the cache, and the next request will cause the application to recompile. However, if changes are made to .browser files in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory, you must manually recompile the application by using the %SystemRoot%\Microsoft.NET\Framework\version\aspnet_regbrowsers.exe tool, or you must programmatically recompile it by using the BrowserCapabilitiesCodeGenerator class.

Note

Using the browserCaps element in the Web.config file to define browsers is deprecated in the .NET Framework 2.0 but still supported. The data in this element is merged with the information from the browser definition files.

When a browser makes a request to your application, the capabilities of the browser are stored in the Browser property. The identity of the browser is stored in the UserAgent property. ASP.NET Web server controls query the list of capabilities to make decisions about how to adapt the behavior of controls appropriately for different browsers.

Capabilities

For a list of strongly-typed browser capabilities, see the properties of the HttpCapabilitiesBase class. These properties use camel casing in browser definition files. For example, if you want to specify the BackgroundSounds capability in your browser definition file, type it in as backgroundSounds.

You can also define your own capabilities.

A Web application can retrieve capability values from the HttpBrowserCapabilities object in one of the following two ways:

• By accessing the dictionary of capabilities. You can use this method for custom capabilities.

  For example, to obtain the value of the ECMAScript (JavaScript) capability for the current client's browser, you can use the following code:

  String cap_javascript = Request.Browser["javascript"];
  

• By calling a strongly typed property that wraps a capability.

  For example, to obtain the value of the ECMAScript capability for the current client's browser, you can use the following code:

  String cap_javascript = Request.JavaScript;
  

Default Configuration

The .NET Framework comes with predefined browser definition files in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory. You can create application-level browser definition files in the App_Browsers directory of your application. For information about special ASP.NET directories, see ASP.NET Web Site Layout.

The following code example is an excerpt from the Generic.browser file in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory.

Note

Do not change existing browser definition files in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory. These are maintained by the .NET Framework.

<browsers>
    <browser id="GenericDownlevel" parentID="Default">
        <identification>
            <userAgent match="^Generic Downlevel$" />
        </identification>

        <capture>
        </capture>

        <capabilities>
            <capability name="cookies"                     value="false" />
            <capability name="ecmascriptversion"           value="1.0" />
            <capability name="tables"                      value="true" />
            <capability name="type"                        value="Downlevel" />
        </capabilities>
        <controlAdapters>
            <adapter controlType="System.Web.UI.WebControls.Menu"
            adapterType="System.Web.UI.WebControls.Adapters.MenuAdapter" />
        </controlAdapters>
    </browser>
</browsers>

The following code example is an excerpt from the WebTV.browser file in the %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers directory.

<browsers>
    <browser id="WebTV" parentID="IE2">
        <identification>
            <userAgent match="WebTV/(?'version'(?'major'\d+)(?'minor'\.\d+)(?'letters'\w*))" />
        </identification>

        <capture>
        </capture>

        <capabilities>
            <capability name="backgroundsounds"    value="true" />
            <capability name="browser"             value="WebTV" />
            <capability name="cookies"             value="true" />
            <capability name="isMobileDevice"      value="true" />
            <capability name="letters"             value="${letters}" />
            <capability name="majorversion"        value="${major}" />
            <capability name="minorversion"        value="${minor}" />
            <capability name="tables"              value="true" />
            <capability name="type"                value="WebTV${major}" />
            <capability name="version"             value="${version}" />
        </capabilities>

        <controlAdapters markupTextWriterType="System.Web.UI.Html32TextWriter">
        </controlAdapters>
    </browser>

    <browser id="WebTV2" parentID="WebTV">
        <identification>
            <capability name="minorversion" match="2" />
        </identification>

        <capture>
        </capture>

        <capabilities>
            <capability name="css1"                value="true" />
            <capability name="ecmascriptversion"   value="1.0" />
            <capability name="javascript"          value="true" />
        </capabilities>
    </browser>

    <gateway id="WebTVbeta" parentID="WebTV">
        <identification>
            <capability name="letters" match="^b" />
        </identification>

        <capture>
        </capture>

        <capabilities>
            <capability name="beta"    value="true" />
        </capabilities>
    </gateway>
</browsers>

Example

The following code example is an empty .browser file that you can build on. Be careful not to create circular references in your browser files.

<?xml version="1.0" encoding="utf-8"?>

<browsers>
    <browser id="NewBrowser" parentID="Mozilla">
        <identification>
            <userAgent match="Unique User Agent Regular Expression" />
        </identification>

        <capture>
            <userAgent match="NewBrowser (?'version'\d+\.\d+)" />
        </capture>

        <capabilities>
            <capability name="browser" value="My New Browser" />
            <capability name="version" value="${version}" />
        </capabilities>
    </browser>

    <browser refID="Mozilla">
        <capabilities>
            <capability name="xml" value="true" />
        </capabilities>
    </browser>
</browsers>

Element Information

Configuration Section Handler	System.Web.Configuration.HttpCapabilitiesSectionHandler
Configuration Members	System.Web.HttpRequest.Browser System.Web.Configuration.HttpCapabilitiesBase.Browsers System.Web.Configuration.HttpCapabilitiesBase.Capabilities System.Web.HttpBrowserCapabilities
Configurable Locations	Machine root level Browsers directory Application level App_Browsers directory
Requirements	Internet Information Services (IIS) 5.0, IIS 5.1, or IIS 6.0 .NET Framework version 2.0 Visual Studio 2005

See Also

Tasks

How to: Detect Browser Types in ASP.NET Web Pages

Reference

deviceFilters Element (ASP.NET Settings Schema)
mobileControls Element (ASP.NET Settings Schema)
browserCaps Element (ASP.NET Settings Schema)
Browsers
Capabilities
HttpCapabilitiesSectionHandler
HttpBrowserCapabilities

Concepts

ASP.NET Web Server Controls and Browser Capabilities
Securing Browser Definition Files
ASP.NET Configuration Scenarios
ASP.NET Device Filtering Overview
Architectural Overview of Adaptive Rendering
ASP.NET Mobile Application Development Overview

Other Resources

General Configuration Settings (ASP.NET)
ASP.NET Configuration Settings