通过

浏览器定义文件架构（browsers 元素）

  • 项目

更新：2007 年 11 月

浏览器定义文件包含各个浏览器的定义。在运行时，ASP.NET 使用请求标头中的信息来确定发出请求的浏览器的类型。随后，ASP.NET 使用 .browser 文件来确定浏览器的功能，以及如何向该浏览器呈现标记。对于希望创建可以在移动设备上查看的应用程序的 Web 开发人员，这很有用。因为这样可以利用控件适配器根据设备类型改编 ASP.NET Web 服务器控件的行为。有关更多信息，请参见请参见部分中的链接。

说明：

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

browsers 元素使用下面的结构。

<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 元素可以包含的属性。

说明：

不要更改 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.Html32TextWriter、System.Web.UI.HtmlTextWriter、System.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>
说明：

应用程序中的浏览器定义文件包含的 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 元素不包含子元素。

备注

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

安全说明：

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

预定义的浏览器定义文件存储在 %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 网站布局。

下面的代码示例摘自 %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>
</browsers>

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

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

示例

下面的代码示例是一个空的 .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、IIS 5.1 或 IIS 6.0

.NET Framework 2.0 版

Visual Studio 2005

请参见

任务

如何：在 ASP.NET 网页中检测浏览器类型

概念

ASP.NET Web 服务器控件和浏览器功能

保证浏览器定义文件的安全

ASP.NET 配置方案

ASP.NET 设备筛选概述

自适应控件行为的结构概述

ASP.NET 移动 Web 开发概述

参考

Browsers

Capabilities

HttpCapabilitiesSectionHandler

HttpBrowserCapabilities

deviceFilters 元素（ASP.NET 设置架构）

mobileControls 元素（ASP.NET 设置架构）

browserCaps 元素（ASP.NET 设置架构）

其他资源

常规配置设置 (ASP.NET)

ASP.NET 配置设置