Esquema de archivos de definición de explorador (Elemento browsers)
[Esta documentación se proporciona solo para fines preliminares y está sujeta a cambios en versiones posteriores. Se incluye temas en blanco como marcadores].
Los archivos de definición del explorador contienen definiciones para exploradores individuales. En tiempo de ejecución, ASP.NET utiliza la información del encabezado de la solicitud para determinar qué tipo de explorador ha realizado la solicitud. A continuación, ASP.NET utiliza archivos .browser para determinar las capacidades del explorador. Los adaptadores de control ASP.NET pueden utilizar esta información para adaptar el comportamiento de un control de servidor web ASP.NET dependiendo del tipo de dispositivo. Por ejemplo, un control de servidor podría generar HTML diferente para un explorador gráfico como Internet Explorer que para un dispositivo móvil.
Nota
Los archivos de definición del explorador se introdujeron en la versión 2.0 de .NET Framework.En versiones anteriores de .NET Framework, se utilizaba el elemento browserCaps para especificar las definiciones del explorador en archivos de configuración.
<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>
Atributos y elementos
Elemento |
Descripción |
|---|---|
adapter |
Especifica una asignación entre un control de servidor Web ASP.NET y el adaptador que se utiliza para representarlo en el explorador actual. Por ejemplo, la definición siguiente para el explorador NokiaMobileBrowserRainbow, que está incluida en el archivo Nokia.browser, especifica que los controles de servidor Menu se ajustarán al explorador mediante la clase de adaptador de control MenuAdapter: En la tabla siguiente se describen los atributos necesarios incluidos en el elemento adapter.
AtributoDescripción
adapterType El atributo String es obligatorio.Especifica el nombre de la clase que se utiliza para cambiar la manera en que el control se adapta al explorador.
controlType El atributo String es obligatorio.Especifica el nombre del control que se asigna al adaptador.
El elemento adapter no contiene elementos secundarios. |
browser |
Establece una definición del explorador única. En la tabla siguiente se describen los atributos que puede contener el elemento browser. .gif "Note") Note
No cambie los archivos de definición de explorador que vienen con ASP.NET porque los Service Pack podrían actualizar esos archivos y sobrescribir sus cambios.En su lugar, cree nuevos archivos .browser y utilice el atributo parentID en una nueva definición de explorador para heredar la configuración o utilice el atributo refID para agregar funciones a una definición de explorador existente.
Una definición de explorador debe definir el atributo refID o los atributos id y parentID.
AtributoDescripción
id Atributo de tipo String; es necesario si se utiliza el atributo parentID.Especifica el nombre único para el explorador que se define.
parentID Atributo de tipo String; es necesario si se utiliza el atributo id.Especifica el nombre único de la definición de explorador primaria de la que se hereda la configuración.Esta configuración se puede sobrescribir en la definición de explorador actual.La definición de explorador primaria no tiene por qué estar en el mismo archivo de definición de explorador, pero tiene que definirse en la misma aplicación o en el directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers.Por ejemplo, la definición siguiente para el explorador WebTV se establece en el archivo WebTV.browser.La definición para el explorador primario IE2 se establece en el archivo IE.browser en el mismo directorio. <browser id=" WebTV " parentID=" IE2 ">
refID
Atributo de tipo String; no se puede utilizar si se utilizan los atributos id y parentID.Especifica un identificador de definición de explorador existente.Utilice el atributo refID para asociar las nuevas funciones a una definición de explorador existente.Puede configurar varios nodos de explorador para hacer referencia al mismo atributo refID.Si se especifica el atributo refID, el elemento browser no puede contener un elemento secundario identification.El atributo refID no reemplaza el elemento de destino, sino que su valor se aplica después de que se hayan aplicado los demás valores de atributo.El orden de aplicación de los valores es el siguiente:
El elemento browser puede contener cero o varios de los siguientes elementos secundarios:
|
browsers |
Representa el elemento raíz necesario de un archivo .browser. |
capabilities |
Define los valores de función que se establecen para la definición de explorador actual. Para obtener una lista de roles de explorador fuertemente tipados, vea las propiedades de la clase HttpCapabilitiesBase. La mayoría de estas propiedades utiliza una combinación de mayúsculas y minúsculas en los archivos de definición del explorador. También puede agregar sus propios valores de función. El elemento capabilities no contiene atributos. El elemento capabilities puede contener cero o varios de los siguientes elementos secundarios:
|
capability (elemento secundario de capabilities) |
Establece un valor de función único para la definición de explorador actual. Por ejemplo, las funciones siguientes se establecen para la definición del explorador IE en el archivo IE.browser. Esta definición de ejemplo hereda otras funciones de la definición del explorador Mozilla incluida en el archivo Mozilla.browser. Los valores que contienen texto en un signo de dólar seguido de paréntesis (${}) se reemplazan por los valores capturados de la expresión coincidente en el elemento secundario userAgent del elemento identification "^Mozilla[^(]*\([C|c]ompatible;\s*MSIE (?'version'(?'major'\d+)(?'minor'\.\d+)(?'letters'\w*))(?'extra'[^)]*)". El elemento capability incluye los siguientes atributos necesarios.
AtributoDescripción
name El atributo String es obligatorio.Especifica el nombre de la función.Para obtener una lista de roles de explorador fuertemente tipados, vea las propiedades de la clase HttpCapabilitiesBase.La mayoría de estas propiedades utiliza una combinación de mayúsculas y minúsculas en los archivos de definición del explorador, por ejemplo, canSendMail en lugar de CanSendMail.También puede agregar sus propios valores de función.
value El atributo String es obligatorio.Especifica el valor de la función.Los valores posibles para cada uno de los roles del explorador fuertemente tipados se muestran en las propiedades de la clase HttpCapabilitiesBase.El atributo de valor puede contener las variables capturadas dentro de "${}"
El elemento capability no contiene elementos secundarios. |
capability (elemento secundario de identification o capture) |
Especifica que el valor de una función de la clase de explorador primaria se compare con una expresión regular. Por ejemplo, la definición siguiente del explorador IE5to9 contenida en el archivo IE.browser utiliza un elemento capability para especificar que la configuración de la función majorversion en la definición primaria de IE tiene que compararse con la expresión regular y la definición del explorador tiene que coincidir con el explorador del cliente. Esta definición de explorador de ejemplo incluye elementos capability que se agregan a los elementos de la definición primaria o los reemplazan. En la tabla siguiente se describen los atributos que contiene el elemento capability. Se debe definir el atributo match o nonMatch, pero no ambos.
AtributoDescripción
match El atributo String no se puede utilizar en el mismo elemento que el atributo nonMatch.Especifica la expresión regular con la que debe coincidir la configuración de la función primaria para satisfacer esta identificación.Para obtener información sobre cómo dar formato a las expresiones regulares, vea Expresiones regulares de .NET Framework.
name El atributo String es obligatorio.Especifica el nombre de la función primaria.
nonMatch El atributo String no se puede utilizar en el mismo elemento que el atributo match.Este atributo no se utiliza en el elemento secundario capability del elemento capture.Especifica la expresión regular con la que no debe coincidir la configuración de la función primaria para satisfacer esta identificación.
El elemento capability no contiene elementos secundarios. |
capture |
Define información sobre qué elementos header, userAgent o capability adicionales se utilizan para capturar información del explorador. Esto es útil cuando se intenta detectar nuevos exploradores que no estaban disponibles cuando se publicó .NET Framework 2.0. Para capturar los valores, una definición de explorador puede incluir capturas de expresiones regulares en el atributo match de cualquier elemento de identificación. Por ejemplo, el elemento userAgent siguiente definido en el archivo IE.browser captura el alto de la pantalla en píxeles especificado en el encabezado de solicitud del agente de usuario. Una definición de explorador también podría necesitar que se capture información adicional examinando los encabezados de solicitud que no se utilizan para distinguir la clase de explorador. Por ejemplo, el elemento capture siguiente captura el número de teclas programables de un teléfono celular OpenWave. Las teclas programables presentan menús y comandos cuando se presionan los botones de hardware correspondientes en dispositivos SmartPhone basados en Windows Mobile: El elemento capture no contiene atributos. El elemento capture puede contener cero o varios de los siguientes elementos secundarios:
|
controlAdapters |
Define un adaptador de control que se utiliza para adaptar el control de servidor en el explorador. En la tabla siguiente se describe el atributo que contiene el elemento controlAdapters .
AtributoDescripción
markupTextWriterType Atributo String opcional.Especifica el tipo de .NET Framework del escritor de texto de formato que se utiliza.El tipo predeterminado es System.Web.UI.XhtmlTextWriter, pero otros valores posibles de este atributo son System.Web.UI.Html32TextWriter, System.Web.UI.HtmlTextWriter, System.Web.UI.ChtmlTextWriter o cualquier clase personalizada derivada de una de estas clases.
El elemento controlAdapters puede contener cero o varios de los siguientes elementos secundarios:
|
defaultBrowser |
Define las funciones de explorador predeterminadas en el archivo Default.browser. Las definiciones de explorador predeterminadas no coinciden con un explorador físico concreto, sino que las utilizan otras definiciones para heredar la configuración. Por ejemplo, la definición de explorador Default siguiente está incluida en el archivo Default.browser: Muchas otras definiciones de explorador heredan la definición de explorador Default. Por ejemplo, la definición siguiente para el explorador Panasonic está incluida en el archivo Panasonic.browser. <browser id="Panasonic" parentID="Default"> En la tabla siguiente se describe el atributo que contiene el elemento defaultBrowser.
AtributoDescripción
id El atributo String es obligatorio.Especifica el nombre único para el explorador.
El elemento defaultBrowser puede contener los mismos elementos secundarios que el elemento browser. |
gateway |
Especifica una definición de puerta de enlace única. Algunos exploradores móviles se conectan al servidor Web a través de una puerta de enlace, que puede agregar sus propias funciones. Es posible que varios elementos de puerta de enlace hagan referencia al mismo atributo refID. El elemento gateway puede contener los mismos atributos y elementos secundarios que el elemento browser. Por ejemplo, la definición siguiente para la puerta de enlace IE3AK proviene del archivo IE.browser.
No puede tener un archivo de definición del explorador en su aplicación que contenga un elemento browser cuyo atributo parentID haga referencia a un elemento gateway en los archivos de definición predeterminados que se encuentran en el directorio %SystemRoot\Microsoft.NET\Framework\versionNumber\CONFIG\Browsers.Sin embargo, puede establecer el atributo parentID para que haga referencia a un archivo de definición del explorador diferente en la misma carpeta App_Browsers.
|
header (elemento secundario de identification o capture) |
Especifica una expresión con la que se compara o captura un encabezado HTTP concreto de la solicitud. Por ejemplo, la definición siguiente del explorador Wml contenida en el archivo Default.browser identifica un explorador coincidente comparando el encabezado Accept con dos expresiones regulares. En la tabla siguiente se describen los atributos que contiene el elemento header. Tiene que estar presente el atributo match o nonMatch, pero no ambos.
AtributoDescripción
match El atributo String no se puede utilizar en el mismo elemento que el atributo nonMatch.Especifica la expresión regular con la que debe coincidir el valor de encabezado de la solicitud para satisfacer esta identificación.Para obtener información sobre cómo dar formato a las expresiones regulares, vea Expresiones regulares de .NET Framework.
name El atributo String es obligatorio.Especifica el nombre del encabezado.
nonMatch El atributo String no se puede utilizar en el mismo elemento que el atributo match.Este atributo no se utiliza en el elemento secundario capability del elemento capture.Especifica la expresión regular con la que no debe coincidir el valor de encabezado de la solicitud para satisfacer esta identificación.
El elemento header no contiene elementos secundarios. |
header (elemento secundario de sampleHeaders) |
Especifica un encabezado de ejemplo único para este explorador. Este elemento es opcional y sólo sirve para propósitos informativos. Un simulador o herramienta de depuración puede utilizar este conjunto de encabezados para emular el explorador en una solicitud. En la tabla siguiente se describen los atributos que contiene el elemento header.
AtributoDescripción
name Atributo String opcional.Especifica el nombre del encabezado.
value Atributo String opcional.Especifica el valor del encabezado.
El elemento header no contiene elementos secundarios. |
identification |
Define información sobre cómo identificar este explorador en la solicitud entrante. El elemento identification no contiene atributos. El elemento identification puede contener uno o varios de los siguientes elementos secundarios:
|
sampleHeaders |
Especifica un conjunto de encabezados de ejemplo para el explorador. Este elemento es opcional y sólo sirve para propósitos informativos. Un simulador o herramienta de depuración puede utilizar este conjunto de encabezados para emular el explorador en una solicitud. El elemento sampleHeaders no contiene atributos. El elemento sampleHeaders puede contener cero o varios de los siguientes elementos secundarios:
|
userAgent |
Especifica una expresión con la que tiene que coincidir el encabezado de agente de usuario de una solicitud. Por ejemplo, la definición siguiente del explorador IE4 incluida en el archivo IE.browser utiliza la cadena "MSIE 4" para identificar el explorador mediante el encabezado del agente de usuario que envía con la solicitud. En la tabla siguiente se describen los atributos que contiene el elemento userAgent. Tiene que estar presente el atributo match o nonMatch, pero no ambos.
AtributoDescripción
match El atributo String no se puede utilizar en el mismo elemento que el atributo nonMatch.Especifica la expresión regular con la que debe coincidir el agente de usuario para satisfacer esta identificación.Para obtener información sobre cómo dar formato a las expresiones regulares, vea Expresiones regulares de .NET Framework.
nonMatch El atributo String no se puede utilizar en el mismo elemento que el atributo match.Especifica la expresión regular con la que no debe coincidir el agente de usuario para satisfacer esta identificación.Este atributo no se utiliza en el elemento secundario capability del elemento capture.
El elemento userAgent no contiene elementos secundarios. |
Comentarios
Si ninguno de los archivos de definición de explorador se ajusta a sus criterios, puede crear nuevos archivos de definición de explorador utilizando el código de la sección de Ejemplo siguiente.
.gif "Nota de seguridad") Nota sobre la seguridad |
|---|
No descargue o instale archivos de definición de explorador de otros fabricantes a menos que confíe en su origen.Examine los nuevos archivos de definición de explorador para ver si se hacen referencia a cualquier espacio de nombres poco conocido.Para obtener más información, vea Securing Browser Definition Files. |
Los archivos de definición de explorador predefinidos se encuentran almacenados en el directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers. Los archivos de definición de explorador del nivel de aplicación se pueden colocar en el directorio App_Browsers de la aplicación. En ambas ubicaciones, los archivos de definición de explorador deben tener la extensión de nombre de archivo .browser. No cambie los archivos de definición de explorador que vienen con ASP.NET porque los Service Pack podrían actualizar esos archivos y sobrescribir sus cambios. En su lugar, cree nuevos archivos .browser y utilice el atributo parentID en una nueva definición browser para heredar la configuración o utilice el atributo refID para agregar funciones a una definición de explorador existente.
En tiempo de ejecución, la información del archivo de definición de explorador se combina en una colección de exploradores conocidos en un objeto BrowserCapabilitiesFactory. Cuando se realiza una solicitud, ASP.NET identifica el explorador solicitante mediante el encabezado de la solicitud y compila un objeto HttpBrowserCapabilities que corresponde al tipo del explorador solicitante. Para hacer esto, se empieza con un diccionario vacío y se aplican los pasos recursivos siguientes contra el árbol de definición del explorador:
Empiece en la definición de explorador predeterminada, que siempre se considera una coincidencia correcta.
Combine los valores de función especificados en la definición de explorador con el diccionario de funciones del explorador. Los valores especificados en una definición de explorador reemplazan a los valores establecidos en un elemento primario.
Evalúe cada definición secundaria para determinar una coincidencia. En cada elemento secundario coincidente, comience de nuevo en el paso 1. Las definiciones de explorador se evalúan después que las definiciones de puerta de enlace. Si el agente de usuario coincide con más de una definición de explorador o más de una definición de puerta de enlace, se inicia una excepción en tiempo de ejecución.
El objeto HttpBrowserCapabilities se almacena en memoria caché y se podría utilizar de nuevo para una solicitud diferente del mismo tipo de explorador.
Una aplicación Web puede tener acceso a la instancia actual del objeto HttpBrowserCapabilities utilizando la propiedad HttpRequest.Browser. Este objeto es de sólo lectura y contiene las propiedades de cada función. Alternativamente, un desarrollador de Web puede construir una clase personalizada que se hereda de la clase HttpBrowserCapabilities y almacenar una instancia en la propiedad HttpRequest.Browser.
Los cambios en los archivos .browser ubicados en el directorio App_Browsers invalidan la caché y la solicitud siguiente hará que la aplicación vuelva a compilarse. Sin embargo, si los cambios se realizan en los archivos .browser del directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers, hay que volver a compilar la aplicación con la herramienta %raízDelSistema%\Microsoft.NET\Framework\versión\aspnet_regbrowsers.exe o mediante programación, utilizando la clase BrowserCapabilitiesCodeGenerator.
Nota
El uso del elemento browserCaps en el archivo Web.config para definir los exploradores ha quedado desusado en .NET Framework 2.0 pero todavía se admite.Los datos de este elemento se combinan con la información de los archivos de definición del explorador.
Cuando un explorador realiza una solicitud a una aplicación, las funciones del explorador se almacenan en la propiedad Browser. La identidad del explorador se almacena en la propiedad UserAgent. Los controles de servidor Web ASP.NET consultan la lista de funciones para tomar decisiones sobre cómo adaptar apropiadamente el comportamiento de controles a diferentes exploradores.
Funciones
Para obtener una lista de roles de explorador fuertemente tipados, vea las propiedades de la clase HttpCapabilitiesBase. Estas propiedades utilizan una combinación de mayúsculas y minúsculas en los archivos de definición de explorador. Por ejemplo, si desea especificar la función BackgroundSounds en un archivo de definición de explorador, escriba backgroundSounds.
También puede definir sus propias funciones.
Una aplicación Web puede recuperar los valores de función del objeto HttpBrowserCapabilities en una de las dos maneras siguientes:
Acceso al diccionario de funciones. Puede utilizar este método para las funciones personalizadas.
Por ejemplo, para obtener el valor de la función ECMAScript (JavaScript) para el explorador del cliente actual, puede utilizar el código siguiente:
String cap_javascript = Request.Browser["javascript"];Llamada a una propiedad fuertemente tipada que ajusta una función.
Por ejemplo, para obtener el valor de la función ECMAScript para el explorador del cliente actual, puede utilizar el código siguiente:
String cap_javascript = Request.JavaScript;
Configuración predeterminada
.NET Framework incluye archivos de definición de explorador predefinidos en el directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers. Puede crear archivos de definición de explorador del nivel de aplicación en el directorio App_Browsers de la aplicación. Para obtener información sobre los directorios de ASP.NET especiales, vea ASP.NET Web Site Layout.
El ejemplo de código siguiente pertenece al archivo Generic.browser que se encuentra en el directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers.
Nota
No cambie los archivos de definición de explorador existentes en el directorio %raízDelSistema%\Microsoft.NET\Framework\versión\CONFIG\Browsers,ya que los mantiene .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>
Ejemplo
El ejemplo de código siguiente es un archivo .browser vacío en el que puede compilar su propio código. Tenga cuidado de no crear referencias circulares en sus archivos de explorador.
<?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>
Información del elemento
Controlador de secciones de configuración |
|
Miembros de la configuración |
|
Ubicaciones configurables |
Directorio Browsers del nivel de raíz del equipo Directorio App_Browsers del nivel de aplicación |
Requisitos |
Internet Information Services (IIS) versión 5.0 o posterior .NET Framework versión 2.0 o posterior Visual Studio 2005 o una versión posterior |
Vea también
Tareas
How to: Detect Browser Types in ASP.NET Web Pages
Referencia
HttpCapabilitiesSectionHandler
deviceFilters (Elemento, Esquema de configuración de ASP.NET)
mobileControls (Elemento, Esquema de configuración de ASP.NET)
Elemento browserCaps (Esquema de configuración de ASP.NET)
Conceptos
ASP.NET Web Server Controls and Browser Capabilities
Securing Browser Definition Files
ASP.NET Device Filtering Overview
Architectural Overview of Adaptive Rendering
Otros recursos
ASP.NET for Mobiles: The Official Microsoft ASP.NET Site