浏览器定义文件架构(browsers 元素)

[本文档仅供预览,在以后的发行版中可能会发生更改。包含的空白主题用作占位符。]

浏览器定义文件包含各个浏览器的定义。 在运行时,ASP.NET 使用请求标头中的信息来确定发出请求的浏览器的类型。 随后,ASP.NET 使用 .browser 文件来确定浏览器的功能。 ASP.NET 控件适配器可以使用此信息来适应 ASP.NET Web 服务器控件的行为,具体取决于设备的类型。 例如,服务器控件可能为图形浏览器(例如 Internet Explorer)生成与为移动设备生成的 HTML 不同的 HTML。

备注

在 .NET Framework 2.0 版中引入了浏览器定义文件。在以前版本的 .NET Framework 中,使用 browserCaps 元素在配置文件中定义浏览器定义。

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

特性和元素

元素

说明

adapter

指定 ASP.NET Web 服务器控件与用于在当前浏览器中呈现该控件的适配器之间的映射。 例如,Nokia.browser 文件中包含的 NokiaMobileBrowserRainbow 浏览器的以下定义指定使用 MenuAdapter 控件适配器类来针对浏览器改编 Menu 服务器控件:

    <controlAdapters markupTextWriterType="System.Web.UI.XhtmlTextWriter" >
        <adapter
          controlType="System.Web.UI.WebControls.Menu"
          adapterType="System.Web.UI.WebControls.Adapters.MenuAdapter">
        </adapter>
    </controlAdapters>

下表描述 adapter 元素中包含的必需特性。

特性说明
adapterType 必选的 String 特性。指定类的名称,该类用于更改针对浏览器改编控件的方式。
controlType 必选的 String 特性。指定要映射到适配器的控件的名称。

adapter 元素不包含子元素。

browser

定义一个浏览器定义。

下表描述 browser 元素可以包含的特性。

NoteNote
不要更改 ASP.NET 随附的浏览器定义文件,因为 Service Pack 可能会更新这些文件,从而覆盖您所做的更改。相反,您应该创建新的 .browser 文件,并在新的浏览器定义中使用 parentID 特性来继承设置,或者使用 refID 特性向现有的浏览器定义添加功能。

浏览器定义中必须定义 refID 特性,或者同时定义 id 和 parentID 特性。

特性说明
id String 特性,如果使用了 parentID 特性,则此特性是必需的。指定要定义的浏览器的唯一名称。
parentID String 特性,如果使用了 id 特性,则此特性是必需的。指定要继承其设置的父浏览器定义的唯一名称。可以在当前浏览器定义中覆盖这些设置。父浏览器定义无需位于同一个浏览器定义文件中,但它必须在同一个应用程序或 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中定义。例如,WebTV 浏览器的以下定义在 WebTV.browser 文件中定义,而 IE2 父浏览器的定义在同一目录的 IE.browser 文件中定义。 <browser id=" WebTV " parentID=" IE2 ">
refID
String 特性,如果使用了 id 和 parentID 特性,则不能使用此特性。指定现有的浏览器定义标识符。使用 refID 特性将新功能与现有的浏览器定义相关联。您可以将多个浏览器节点配置为引用相同的 refID。如果指定了 refID 特性,则 browser 元素不能包含 identification 子元素。 refID 特性不会替换目标元素;而会在应用了所有其他特性设置后应用该特性的设置。设置按如下顺序应用:
  • 所有 <gateway parentID> 节点

  • 所有 <gateway refID> 节点

  • 所有 <browser parentID> 节点

  • 所有 <browser refID> 节点

下面的示例定义向 IE.browser 文件中包含的现有 IE 浏览器定义添加新功能。
<browser refID="IE">
    <capabilities>
        <capability name="UseRichTextBox" value="true" />
    </capabilities>
    <controlAdapters>
        <adapter controlType="System.Web.UI.Calendar"
adapterType="ExampleAdapters.ExampleIECalendarAdapter"
        />
    </controlAdapters>
</browser>

browser 元素可以不包含下列任何子元素,也可以包含下列子元素中的一个:

  • capabilities

  • capture

  • controlAdapters

  • identification

  • sampleHeaders

browsers

表示 .browser 文件的必需的根元素。

capabilities

定义要为当前的浏览器定义设置的功能值。 若要查看强类型浏览器功能的列表,请参见 HttpCapabilitiesBase 类的属性。 这些属性中的大多数在浏览器定义文件中使用 Camel 大小写格式。 您也可以添加自己的功能值。

capabilities 元素不包含任何特性。

capabilities 元素可以不包含下面的子元素,也可以包含多个该子元素:

  • capability

capability(capabilities 的子元素)

定义要为当前的浏览器定义设置的一个功能值。 例如,IE.browser 文件中为 IE 浏览器定义定义了下列功能: 此示例定义从 Mozilla.browser 文件中的 Mozilla 浏览器定义继承其他功能。 在后面跟有大括号的货币符号 (${}) 内包含文本的值将被替换为从 identification 元素 "^Mozilla[^(]*\([C|c]ompatible;\s*MSIE (?'version'(?'major'\d+)(?'minor'\.\d+)(?'letters'\w*))(?'extra'[^)]*)" 的 userAgent 子元素中的匹配表达式中捕获的值。

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

capability 元素包含下列必需的特性。

特性说明
name 必选的 String 特性。指定功能的名称。若要查看强类型浏览器功能的列表,请参见 HttpCapabilitiesBase 类的属性。这些属性中的大多数在浏览器定义文件中使用 Camel 大小写格式,例如,使用 canSendMail 而不是 CanSendMail。您也可以添加自己的功能值。
value 必选的 String 特性。指定功能的值。HttpCapabilitiesBase 类的属性中列出了每个强类型浏览器功能的可能值。value 特性可以在“${}”内包含捕获的变量。

capability 元素不包含子元素。

capability(identification 或 capture 的子元素)

指定针对正则表达式匹配父浏览器类中的功能值。 例如,IE.browser 文件中包含的 IE5to9 浏览器的以下定义使用 capability 元素来指定:IE 父定义的 majorversion 功能设置必须匹配包含的正则表达式,此浏览器定义才能与客户端浏览器匹配。 此示例浏览器定义包括 capability 元素,这些元素添加到父定义中的元素,或者覆盖父定义中的元素。

    <browser id="IE5to9" parentID="IE">
        <identification>
            <capability name="majorversion" match="^[5-9]" />
        </identification>
        <!-- Capability elements. -->
    </browser>

下表描述 capability 元素包含的特性。 必须定义 match 或 nonMatch 特性,但不能同时定义两者。

特性说明
match String 特性,不能与 nonMatch 特性在同一个元素中使用。指定正则表达式,父功能设置必须匹配此表达式才能满足该标识。有关格式化正则表达式的信息,请参见 .NET Framework 正则表达式
name 必选的 String 特性。指定父功能的名称。
nonMatch String 特性,不能与 match 特性在同一个元素中使用。capture 元素的 capability 子元素中不使用此特性。指定正则表达式,父功能设置不匹配此表达式时才能满足该标识。

capability 元素不包含子元素。

capture

定义以下信息:在捕获有关浏览器的信息时,使用哪些额外的 header、userAgent 或 capability 元素。 这在尝试检测当发布 .NET Framework 2.0 时不可用的新浏览器时非常有用。 为了捕获值,浏览器定义可以在任何 identification 元素的 match 特性中包括正则表达式捕获。 例如,IE.browser 文件中定义的以下 userAgent 元素从用户代理请求标头中捕获屏幕的高度(以像素为单位)。

    <capture>
        <userAgent match="PalmSource; Blazer 3\.0\)\s\d+;(?'screenPixelsHeight'\d+)x(?'screenPixelsWidth'\d+)$" />
    </capture>

浏览器定义可能还需要通过扫描并非用于区分浏览器类的请求标头来捕获其他信息。 例如,下面的 capture 元素捕获 OpenWave 移动电话的软键的数目。 当您在基于 Windows Mobile 的 SmartPhone 上按硬件按钮时,软键会显示相应的菜单和命令:

    <capture>
        <header name="HTTP_X_UP_DEVCAP_NUMSOFTKEYS" 
                match="(?'softkeys'\d+)" />
    </capture>

capture 元素不包含任何特性。

capture 元素可以不包含下列任何子元素,也可以包含其中的多个子元素:

  • header

  • userAgent

  • capability

controlAdapters

定义用于改编浏览器上服务器控件的控件适配器。

下表描述 controlAdapters 元素包含的特性。

特性说明
markupTextWriterType 可选的 String 特性。指定要使用的标记文本编写器的 .NET Framework 类型。默认类型为 System.Web.UI.XhtmlTextWriter。该特性的其他可能值为 System.Web.UI.Html32TextWriterSystem.Web.UI.HtmlTextWriterSystem.Web.UI.ChtmlTextWriter,或从这些类中的某一个派生的任何自定义类。

controlAdapters 元素可以不包含下面的子元素,也可以包含多个该子元素:

  • adapter

defaultBrowser

在 Default.browser 文件中定义默认的浏览器功能。 Default 浏览器定义不匹配任何特定的物理浏览器,而是由其他定义用于继承设置。 例如,Default.browser 文件中包含下面的 Default 浏览器定义:

    <defaultBrowser id="Default">
        <capabilities>
            <capability name="ecmascriptversion"   value="0.0" />
            <capability name="javascript"          value="false" />
            <capability name="jscriptversion"      value="0.0" />
        </capabilities>
    </defaultBrowser>

Default 浏览器定义供许多其他浏览器定义继承。 例如,Panasonic.browser 文件中包含 Panasonic 浏览器的以下定义。

<browser id="Panasonic" parentID="Default">

下表描述 defaultBrowser 元素包含的特性。

特性说明
id 必选的 String 特性。指定浏览器的唯一名称。

defaultBrowser 元素可以与 browser 元素一样包含相同的子元素。

gateway

指定一个网关定义。 某些移动浏览器通过网关连接到 Web 服务器,而网关可以添加它自己的功能。 多个网关元素可以引用同一个 refID 特性。

gateway 元素可以与 browser 元素一样包含相同的特性和子元素。 例如,IE3AK 网关的以下定义来自 IE.browser 文件。

    <gateway id="IE3AK" parentID="IE3">
        <identification>
            <capability name="extra" match="; AK;" />
        </identification>
        <capture>
        </capture>
        <capabilities>
            <capability name="ak"  value="true" />
        </capabilities>
    </gateway>
NoteNote
应用程序中的浏览器定义文件包含的 browser 元素的 parentID 特性不能引用位于 %SystemRoot\Microsoft.NET\Framework\versionNumber\CONFIG\Browsers 目录中的默认定义文件中的 gateway 元素。不过,可以设置 parentID 特性以引用同一 App_Browsers 文件夹中的其他浏览器定义文件。

header(identification 或 capture 的子元素)

指定一个表达式,将根据该表达式来匹配或捕获请求中的特定 HTTP 标头。 例如,Default.browser 文件中包含的 Wml 浏览器的以下定义通过将 Accept 标头与两个正则表达式进行比较来标识匹配的浏览器。

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

下表描述 header 元素包含的特性。 match 或 nonMatch 特性必须存在一个,但两者不能同时存在。

特性说明
match String 特性,不能与 nonMatch 特性在同一个元素中使用。指定正则表达式,请求标头值必须匹配此表达式才能满足该标识。有关格式化正则表达式的信息,请参见 .NET Framework 正则表达式
name 必选的 String 特性。指定标头的名称。
nonMatch String 特性,不能与 match 特性在同一个元素中使用。capture 元素的 capability 子元素中不使用此特性。指定正则表达式,请求标头值不匹配此表达式时才能满足该标识。

header 元素不包含子元素。

header(sampleHeaders 的子元素)

指定此浏览器的一个示例标头。 此元素是可选的,仅用于提供信息。 模拟器或调试工具可以使用这组标头来模拟请求的浏览器。

下表描述 header 元素包含的特性。

特性说明
name 可选的 String 特性。指定标头的名称。
value 可选的 String 特性。指定标头的值。

header 元素不包含子元素。

identification

定义有关如何从传入请求识别此浏览器的信息。

identification 元素不包含任何特性。

identification 元素可以包含一个或多个下列子元素:

  • header

  • userAgent

  • capability

sampleHeaders

指定此浏览器的一组示例标头。 此元素是可选的,仅用于提供信息。 模拟器或调试工具可以使用这组标头来模拟请求的浏览器。

sampleHeaders 元素不包含任何特性。

sampleHeaders 元素可以不包含下面的子元素,也可以包含多个该子元素:

  • header

userAgent

指定作为请求的用户代理标头的匹配依据的表达式。 例如,IE.browser 文件中包含的 IE4 浏览器的以下定义使用 "MSIE 4" 字符串,并根据随请求发送的用户代理标头来识别浏览器。

        <identification>
            <userAgent match="MSIE 4" />
        </identification>

下表描述 userAgent 元素包含的特性。 match 或 nonMatch 特性必须存在一个,但两者不能同时存在。

特性说明
match String 特性,不能与 nonMatch 特性在同一个元素中使用。指定正则表达式,用户代理必须匹配此表达式才能满足该标识。有关格式化正则表达式的信息,请参见 .NET Framework 正则表达式
nonMatch String 特性,不能与 match 特性在同一个元素中使用。指定正则表达式,用户代理不匹配此表达式时才能满足该标识。capture 元素的 capability 子元素中不使用此特性。

userAgent 元素不包含子元素。

备注

如果您发现没有任何现有的浏览器定义文件符合您的条件,则可以通过使用下面的示例部分中的代码创建新的浏览器定义文件。

安全说明安全说明

不要下载或安装来第三方的浏览器定义文件,除非您信任其来源。检查新的浏览器定义文件,以查看是否引用了任何不熟悉的命名空间。有关更多信息,请参见 Securing Browser Definition Files

预定义的浏览器定义文件存储在 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中。 应用程序级别的浏览器定义文件可以放在应用程序的 App_Browsers 目录中。 在这两个位置中,浏览器定义文件都必须具有 .browser 文件扩展名。 不要更改 ASP.NET 随附的浏览器定义文件,因为 Service Pack 可能会更新这些文件,从而覆盖您所做的更改。 相反,您应该创建新的 .browser 文件,并在新的browser定义中使用 parentID 特性来继承设置,或者使用 refID 特性向现有的浏览器定义添加功能。

在运行时,浏览器定义文件信息将合并到 BrowserCapabilitiesFactory 对象中的已知浏览器的集合内。 发出请求时,ASP.NET 根据请求标头标识请求的浏览器,并编译一个与请求的浏览器类型相对应的 HttpBrowserCapabilities 对象。 这一步是这样完成的:在开始时使用一个空字典,然后对浏览器定义树应用以下递归步骤:

  1. 从默认浏览器定义开始,默认浏览器定义始终被认为是一个成功的匹配。

  2. 将此浏览器定义中指定的功能值合并到此浏览器的功能字典中。 浏览器定义中指定的值会重写父浏览器定义中设置的值。

  3. 计算每个子定义以确定是否匹配。 对于每个匹配的子定义,重新从步骤 1 开始。 在网关定义之后计算浏览器定义。 如果用户代理匹配多个浏览器定义或多个网关定义,将会在运行时引发异常。

HttpBrowserCapabilities 对象被写入缓存,可以被来自同一类型的浏览器发出的其他请求再次使用。

Web 应用程序可以使用 HttpRequest.Browser 属性访问 HttpBrowserCapabilities 对象的当前实例。 此对象是只读的,并包含每个功能的属性。 或者,Web 开发人员可以构建一个从 HttpBrowserCapabilities 类继承的自定义类,并在 HttpRequest.Browser 属性中存储一个实例。

对位于 App_Browsers 目录中的 .browser 文件所做的更改会使缓存无效,并且下一次请求将导致应用程序重新编译。 但是,如果对 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中的 .browser 文件做出了更改,您必须使用 %SystemRoot%\Microsoft.NET\Framework\版本\aspnet_regbrowsers.exe 工具手动重新编译应用程序,或者使用 BrowserCapabilitiesCodeGenerator 类以编程方式重新编译应用程序。

备注

使用 Web.config 文件中的 browserCaps 元素来定义浏览器的行为在 .NET Framework 2.0 中被否决,但仍受支持。此元素中的数据与浏览器定义文件中的信息合并在一起。

浏览器对应用程序发出请求时,浏览器的功能存储在 Browser 属性中, 浏览器的标识则存储在 UserAgent 属性中。 ASP.NET Web 服务器控件查询功能列表,以决定如何针对不同的浏览器适当地改编控件的行为。

功能

若要查看强类型浏览器功能的列表,请参见 HttpCapabilitiesBase 类的属性。 这些属性在浏览器定义文件中使用 Camel 大小写格式。 例如,如果您希望在浏览器定义文件中指定 BackgroundSounds 功能,则键入 backgroundSounds。

您也可以定义自己的功能。

Web 应用程序可以通过下列两种方式之一检索 HttpBrowserCapabilities 对象中的功能值:

  • 访问功能字典。 对于自定义功能,可以使用此方法。

    例如,若要获取当前客户端的浏览器的 ECMAScript (JavaScript) 功能值,可以使用下面的代码:

    String cap_javascript = Request.Browser["javascript"];
    
  • 调用包装功能的强类型属性。

    例如,若要获取当前客户端的浏览器的 ECMAScript 功能值,可以使用下面的代码:

    String cap_javascript = Request.JavaScript;
    

默认配置

.NET Framework 随附有预定义的浏览器定义文件,这些文件位于 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中。 您可以在应用程序的 App_Browsers 目录中创建应用程序级别的浏览器定义文件。 有关特殊的 ASP.NET 目录的信息,请参见 ASP.NET Web Site Layout

下面的代码示例是 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中的 Generic.browser 文件。

备注

不要更改 %SystemRoot%\Microsoft.NET\Framework\版本\CONFIG\Browsers 目录中现有的浏览器定义文件。这些文件是由 .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>

示例

下面的代码示例是一个空的 .browser 文件,您可以用它为基础进行进一步的构建。 注意不要在您的浏览器文件中创建循环引用。

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

元素信息

配置节处理程序

System.Web.Configuration.HttpCapabilitiesSectionHandler

配置成员

HttpRequest.Browser

HttpCapabilitiesBase.Browsers

HttpCapabilitiesBase.Capabilities

System.Web.HttpBrowserCapabilities

可配置的位置

计算机根级别的 Browsers 目录

应用程序级别的 App_Browsers 目录

要求

Internet 信息服务 (IIS) 5.0 或更高版本

.NET Framework 2.0 或更高版本

Visual Studio 2005 或更高版本

请参见

任务

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

参考

Browsers

Capabilities

HttpCapabilitiesSectionHandler

HttpBrowserCapabilities

deviceFilters 元素(ASP.NET 设置架构)

mobileControls 元素(ASP.NET 设置架构)

browserCaps 元素(ASP.NET 设置架构)

概念

ASP.NET Web Server Controls and Browser Capabilities

Securing Browser Definition Files

Configuration Inheritance

ASP.NET Device Filtering Overview

Architectural Overview of Adaptive Rendering

其他资源

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

常规配置设置 (ASP.NET)

ASP.NET 配置设置