瀏覽器定義檔結構描述 (browsers 項目)

發行項
08/12/2011

瀏覽器定義檔案包含個別瀏覽器的定義。在執行階段，ASP.NET 使用要求標頭中的資訊來判斷發出要求之瀏覽器的類型。然後 ASP.NET 會使用.browser 檔來決定瀏覽器功能。 ASP.NET 控制項配接器可以使用這項資訊，根據裝置的類型來調整 ASP.NET Web 伺服器控制項的行為。例如，伺服器控制項會為圖形瀏覽器 (例如 Internet Explorer) 產生不同的 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 瀏覽器的定義，會指定 Menu 伺服器控制項要適用於使用 MenuAdapter 控制項配置器類別的瀏覽器： `<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\version\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;\sMSIE (?'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 類別的屬性中列出。值屬性可以在 "${}" 內包含擷取的變數 capability 項目不含子項目。
capability (identification 或 capture 的子項目)	指定來自父瀏覽器類別的功能值要符合規則運算式 (Regular Expression)。例如，下列包含在 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 發行時不可用的新瀏覽器，這會非常有用。若要擷取值，瀏覽器定義可以在任何識別項目的 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 檔案中： `<defaultBrowser id="Default"> <capabilities> <capability name="ecmascriptversion" value="0.0" /> <capability name="javascript" value="false" /> <capability name="jscriptversion" value="0.0" /> </capabilities> </defaultBrowser>` 許多其他瀏覽器定義都會繼承預設瀏覽器定義。例如，下列 Panasonic 瀏覽器的定義包含在 Panasonic.browser 檔案中。 <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>` 注意事項您無法在應用程式中包含瀏覽器定義檔案，此應用程式包含 parentID 屬性的 browser 項目，此屬性會參考 %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\version\CONFIG\Browsers 目錄中。應用程式層級的瀏覽器定義檔案可以放置在應用程式的 App_Browsers 目錄中。在這兩個位置中，瀏覽器定義檔案的副檔名必須是 .browser。不要變更 ASP.NET 隨附的瀏覽器定義檔案，因為 Service Pack 可能會更新這些檔案而覆寫您的變更。而是要建立新的 .browser 檔案，並使用新 browser 定義中的 parentID 屬性來繼承設定，或使用 refID 屬性將功能加入至現有瀏覽器定義。

在執行階段，瀏覽器定義檔案資訊會合併到 BrowserCapabilitiesFactory 物件中的已知瀏覽器集合中。當發出要求時，ASP.NET 會根據要求標頭來識別要求的瀏覽器，並會編譯對應至所要求之瀏覽器類型的 HttpBrowserCapabilities 物件。這可透過先使用空白字典，然後根據瀏覽器定義樹狀目錄套用下列遞迴步驟來完成：

從預設瀏覽器定義開始，其永遠視為成功的符合。
將在這個瀏覽器定義中指定的功能值合併到此瀏覽器的功能字典中。瀏覽器定義中指定的值會覆寫在父代中設定的值。
評估每一子定義以判斷是否符合。針對每一符合的子系，再次從步驟 1 開始。先評估閘道定義，再評估瀏覽器定義。如果使用者代理符合多個瀏覽器定義或多個閘道定義，則會在執行階段擲回例外狀況。

會快取 HttpBrowserCapabilities 物件，並有可能再次使用它處理來自同一類型瀏覽器的不同要求。

Web 應用程式可以使用 HttpRequest.Browser 屬性存取 HttpBrowserCapabilities 物件的目前執行個體。這個物件為唯讀，且包含每個功能的屬性。或者，Web 開發人員可以建構一個繼承自 HttpBrowserCapabilities 類別的自訂類別，並將執行個體儲存在 HttpRequest.Browser 屬性中。

變更位於 App_Browsers 目錄中的 .browser 檔案會使快取失效，且下一個要求將造成重新編譯應用程式。但是，如果對 %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers 目錄中的 .browser 檔案進行變更，您必須使用 %SystemRoot%\Microsoft.NET\Framework\version\aspnet_regbrowsers.exe 工具手動重新編譯應用程式，或者您必須使用 BrowserCapabilitiesCodeGenerator 類別以程式設計方式重新編譯應用程式。

注意事項
在 .NET Framework 2.0 中，使用 Web.config 檔案中的 browserCaps 項目定義瀏覽器會被取代但仍受支援。這個項目中的資料會與來自瀏覽器定義檔案的資訊合併。

當瀏覽器對您的應用程式發出要求時，瀏覽器的功能會被儲存在 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\version\CONFIG\Browsers 目錄中預先定義的瀏覽器定義檔案。您可以在應用程式的 App_Browsers 目錄中建立應用程式層級的瀏覽器定義檔案。如需特殊 ASP.NET 目錄的詳細資訊，請參閱 ASP.NET Web 專案資料夾結構。

下列程式碼範例是 %SystemRoot%\Microsoft.NET\Framework\version\CONFIG\Browsers 目錄中的 Generic.browser 檔案。

注意事項
不要變更 %SystemRoot%\Microsoft.NET\Framework\version\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
可設定的位置	電腦根層次瀏覽器目錄應用程式層級 App_Browsers 目錄
需求	網際網路資訊服務 (IIS) 5.0 版 (含) 以後版本 .NET Framework 2.0 或更新版本 Visual Studio 2005 或更新版本

請參閱

Share via

瀏覽器定義檔結構描述 (browsers 項目)

屬性和項目

備註

功能

預設的組態

範例

項目資訊

請參閱

工作

參考

概念

其他資源

其他資源