Share via

Browser Definition File Schema (browsers Element)

  • Article

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. ASP.NET control adapters can use this information to adapt the behavior of an ASP.NET Web server control depending on the type of device. For example, a server control might generate different HTML for a graphical browser such as Internet Explorer than it would for a mobile device.

Note

Browser definition files were introduced 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.

<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.

AttributeDescription
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.

AttributeDescription
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.

AttributeDescription
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.

AttributeDescription
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.

AttributeDescription
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.

AttributeDescription
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>

Note

You cannot have a browser definition file in your application that contains a browser element whose parentID attribute refers to a gateway element in the default definition files located in the %SystemRoot\Microsoft.NET\Framework\versionNumber\CONFIG\Browsers directory. However, you can set the parentID attribute to refer to a different browser definition file in the same App_Browsers folder.

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.

AttributeDescription
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.

AttributeDescription
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.

AttributeDescription
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 noteSecurity 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 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 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 Project Folder Structure.

The following code example is 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>
    <browser id="Mozilla" parentID="Default">
        <identification>
            <userAgent match="Mozilla" />
        </identification>
        <capture>
        </capture>
        <capabilities>
            <capability name="browser"
                        value="Mozilla" />
            <capability name="cookies"
                        value="false" />
            <capability name="inputType"
                        value="keyboard" />
            <capability name="isColor"
                        value="true" />
            <capability name="isMobileDevice"
                        value="false" />
            <capability name="maximumRenderedPageSize"
                        value="300000" />
            <capability name="screenBitDepth"
                        value="8" />
            <capability name="supportsBold"
                        value="true" />
            <capability name="supportsCss"
                        value="true" />
            <capability name="supportsDivNoWrap"
                        value="true" />
            <capability name="supportsFontName"
                        value="true" />
            <capability name="supportsFontSize"
                        value="true" />
            <capability name="supportsImageSubmit"
                        value="true" />
            <capability name="supportsItalic"
                        value="true" />
            <capability name="type"
                        value="Mozilla" />
        </capabilities>
    </browser>
</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

HttpRequest.Browser

HttpCapabilitiesBase.Browsers

HttpCapabilitiesBase.Capabilities

System.Web.HttpBrowserCapabilities

Configurable Locations

Machine root level Browsers directory

Application level App_Browsers directory

Requirements

Internet Information Services (IIS) 5.0 or a later version

.NET Framework version 2.0 or a later version

Visual Studio 2005 or a later version

See Also

Tasks

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

Reference

Browsers

Capabilities

HttpCapabilitiesSectionHandler

HttpBrowserCapabilities

deviceFilters Element (ASP.NET Settings Schema)

mobileControls Element (ASP.NET Settings Schema)

browserCaps Element (ASP.NET Settings Schema)

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 Control Behavior

Other Resources

ASP.NET for Mobiles : The Official Microsoft ASP.NET Site

General Configuration Settings (ASP.NET)

ASP.NET Configuration Settings