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 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.
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: The following table describes the required attributes that are contained in the adapter element.
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.
The browser element can contain zero or one of the following child elements:
|
||||||||||
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 (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'[^)]*)". The capability element contains the following required attributes.
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. The following table describes the attributes that the capability element contains. Either the match or nonMatch attribute must be defined, but not both.
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. 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: The capture element contains no attributes. The capture element can contain zero or more of the following child elements:
|
||||||||||
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.
The controlAdapters element can contain zero or more of the following child element:
|
||||||||||
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: 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.
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. 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. The following table describes the attributes that the header element contains. Either the match or nonMatch attribute must be present, but not both.
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.
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:
|
||||||||||
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:
|
||||||||||
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. The following table describes the attributes that the userAgent element contains. Either the match or nonMatch attribute must be present, but not both.
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.
.gif "Security note") 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:
Start at the default browser definition, which is always considered a successful match.
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.
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 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 |
|
Configuration Members |
|
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
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
ASP.NET Mobile Web Development Overview
Reference
HttpCapabilitiesSectionHandler
deviceFilters Element (ASP.NET Settings Schema)
mobileControls Element (ASP.NET Settings Schema)
browserCaps Element (ASP.NET Settings Schema)