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: |
|---|
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 HttpRequestBrowser()()() 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 HttpRequestBrowser()()() 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.
.gif) 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>