Atributos de metadatos para controles de servidor personalizados
Actualización: noviembre 2007
Los atributos de metadatos se aplican a los controles de servidor y a sus miembros para proporcionar información que es utilizada por las herramientas de diseño, el analizador de páginas de ASP.NET, el motor en tiempo de ejecución de ASP.NET y Common Language Runtime. Los atributos en tiempo de diseño mejoran la experiencia del desarrollador en tiempo de diseño cuando un desarrollador de páginas utiliza el control en un diseñador visual. Los atributos sólo en tiempo de diseño no afectan a la funcionalidad del control durante la solicitud de una página. El analizador de páginas de ASP.NET utiliza los atributos de tiempo de análisis del control cuando lee la sintaxis declarativa de un control en una página. Los atributos en tiempo de análisis y en tiempo de ejecución son esenciales para el funcionamiento de un control en una página.
En este tema se describen los atributos de metadatos que se suelen aplicar a los controles y a sus propiedades y eventos públicos.
Atributos aplicados a un control
Atributo |
Ejemplo |
|---|---|
AspNetHostingPermissionAttribute Atributo de seguridad de acceso a código en tiempo de compilación JIT. Es necesario para garantizar que el código que se vincula al control tenga los permisos de seguridad correspondientes. La clase Control se marca con dos atributos de seguridad de acceso a código en tiempo de compilación JIT: AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal) y AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal). Debe aplicar el primer atributo al control, pero no tiene que aplicar el segundo porque una petición de herencia es transitiva y permanece vigente en las clases derivadas. Para obtener más información, vea SecurityAction. |
[AspNetHostingPermission(SecurityAction.LinkDemand, Level=AspNetHostingPermissionLevel.Minimal)] Se aplica al control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de análisis. Asocia un generador de controles personalizados al control. Este atributo sólo se debe aplicar si se va a emplear un generador de controles personalizados para modificar la lógica predeterminada que utiliza el analizador de páginas para analizar la sintaxis declarativa del control. Si sólo desea especificar si el contenido incluido en las etiquetas de un control corresponde a propiedades o a controles secundarios, utilice ParseChildrenAttribute (que se describe más adelante en esta tabla) en lugar de utilizar un generador de controles personalizados. |
[ControlBuilder(typeof(MyControlBuilder))] |
|
Atributo en tiempo de diseño y en tiempo de ejecución. Especifica la propiedad que se utiliza como valor predeterminado de un control. Al aplicar este atributo se permite utilizar el control como parámetro en una consulta en tiempo de ejecución y se define el valor predeterminado al que un objeto ControlParameter se enlaza en tiempo de ejecución. |
[ControlValueProperty("Text")] |
|
Atributo en tiempo de diseño. Especifica el evento predeterminado del control en un diseñador visual. En muchos diseñadores visuales, cuando el desarrollador de páginas hace doble clic en el control en la superficie de diseño, el editor de código se abre con el cursor situado en el controlador de eventos del evento predeterminado. |
[DefaultEvent("Submit")] Se aplica al control de ejemplo Register que aparece en Ejemplo de control Web compuesto. |
|
Atributo en tiempo de diseño. La propiedad especificada en este atributo aparece resaltada en el examinador de propiedades de un diseñador visual cuando el desarrollador de páginas selecciona el control en la superficie de diseño. |
[DefaultProperty("Text")] Se aplica al control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica la clase de diseñador que está asociada al control. La clase de diseñador de un control es responsable de la apariencia y el comportamiento del control asociado en la superficie de diseño del diseñador visual. |
[Designer(typeof(SimpleCompositeControlDesigner))] Se aplica a los controles de ejemplo de Tutorial: Crear un diseñador de controles básico para un control de servidor Web |
|
Atributo en tiempo de análisis. Especifica si el contenido de las etiquetas de un control corresponde a propiedades o a controles secundarios. La clase Control se marca como ParseChildren(false), lo que significa que el analizador de páginas interpreta el contenido de las etiquetas del control como controles secundarios. La clase WebControl se marca como ParseChildren(true), lo que significa que el analizador de páginas interpreta el contenido de las etiquetas del control como propiedades. Sólo es necesario aplicar este atributo si se va a modificar la lógica especificada en el atributo ParseChildrenAttribute de la clase WebControl. |
[ParseChildren(true, "Contacts")] Se aplica al control de ejemplo QuickContacts que aparece en Ejemplo de propiedad Collection de controles Web. |
|
Atributo en tiempo de diseño. Especifica si el diseñador visual debe conservar controles secundarios o propiedades en las etiquetas de un control cuando éste se utiliza mediante declaración en una página. La clase Control se marca como PersistChildren(true), lo que significa que el diseñador conserva los controles secundarios en las etiquetas del control. La clase WebControl se marca como PersistChildren(false), lo que significa que el diseñador conserva propiedades como atributos en las etiquetas del control. |
[PersistChildren(false)] Se aplica a la clase WebControl y es adecuado para la mayoría de los controles que se derivan de esta clase. Sin embargo, los controles contenedores como Panel que conservan controles secundarios en sus etiquetas se marcan como PersistChildren(true) y ParseChildren(false). |
|
Atributo en tiempo de análisis. Especifica si los temas o máscaras de controles pueden afectar a un control. Si un tipo de control está marcado para indicar que no se le pueden aplicar temas, todos los miembros del control tampoco se verán afectados por los temas. |
[Themeable(false)] Aplique el atributo mostrado en el ejemplo anterior para evitar que un control y todos sus miembros se vean afectados por los temas o máscaras de controles. |
|
Atributo en tiempo de diseño. Especifica el formato del marcado creado para la etiqueta por el diseñador visual cuando el control se crea en el cuadro de herramientas. |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] Se aplica al control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica si un diseñador visual debe mostrar un control o un componente en el cuadro de herramientas. De forma predeterminada, los controles siempre se muestran en el cuadro de herramientas. Este atributo sólo debe aplicarse a los controles (como el propietario de una propiedad de plantilla) que no se desea mostrar en el cuadro de herramientas. |
[ToolboxItem(false)] Se aplica al control TemplateOwner de Ejemplo de control de servidor con plantilla. |
|
Atributo en tiempo de diseño. Especifica el nombre de la propiedad que un control de validación comprueba. Normalmente ésta es la propiedad cuyo valor suministran los usuarios en tiempo de ejecución, como la propiedad Text de un control TextBox. En un diseñador visual, el cuadro de diálogo que permite a los desarrolladores de páginas seleccionar el destino de un control de validación muestra las propiedades especificadas con ValidationPropertyAttribute en los controles de la página. |
[ValidationProperty("Text")] |
Atributos aplicados a las propiedades públicas
Atributo |
Ejemplo |
|---|---|
|
Atributo en tiempo de diseño. Especifica si tiene sentido enlazar datos a una propiedad. En un diseñador visual, el examinador de propiedades puede mostrar las propiedades enlazables de un control en un cuadro de diálogo. (Por ejemplo, en Visual Studio, las propiedades enlazables se muestran en el cuadro de diálogo DataBindings.) Cuando la propiedad no está marcada con este atributo, el examinador de propiedades infiere que el valor es Bindable(false). |
[Bindable(true)] Se aplica a la propiedad Text del control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica si una propiedad se debe mostrar en el examinador de propiedades de un diseñador visual. Aplique Browsable(false) a una propiedad que no desea mostrar en el examinador de propiedades. Cuando la propiedad no está marcada con este atributo, el examinador de propiedades infiere el valor predeterminado, Browsable(true). |
[Browsable(false)] Se aplica a la propiedad Template del control de ejemplo VacationHome que aparece en Ejemplo de control de servidor con plantilla. |
|
Atributo en tiempo de diseño. Especifica en qué categoría se debe situar la propiedad en el examinador de propiedades del diseñador visual. Por ejemplo, Category("Appearance") indica al examinador de propiedades que muestre la propiedad en la categoría Apariencia cuando el desarrollador de páginas utilice la vista por categorías en el examinador de propiedades. Puede especificar un argumento de cadena correspondiente a una categoría existente en el examinador de propiedades o crear una categoría propia. |
[Category("Appearance")] Se aplica a la propiedad Text del control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica un valor predeterminado para una propiedad. Este valor debe ser idéntico al valor predeterminado que se devuelve desde el descriptor de acceso de la propiedad (captador). En algunos diseñadores visuales como Visual Studio, el atributo DefaultValueAttribute permite a los desarrolladores de páginas restablecer el valor de una propiedad a su valor predeterminado mediante el comando Restablecer del menú contextual. |
[DefaultValue("")] Se aplica a la propiedad Text del control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica una breve descripción de la propiedad. En un diseñador visual como Visual Studio, el examinador de propiedades muestra la descripción de la propiedad seleccionada, generalmente en la parte inferior de la ventana. |
[Description("The welcome message text.")] Se aplica a la propiedad Text del control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
DesignerSerializationVisibilityAttribute Atributo en tiempo de diseño. Especifica si se tiene que serializar la propiedad o su contenido (como subpropiedades o elementos de colección) que se establecen en tiempo de diseño. El argumento del constructor del atributo es un valor de la enumeración DesignerSerializationVisibility. Cuando no se aplica este atributo, se infiere el valor predeterminado, Visible, y se serializa el valor de la propiedad. |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] Se aplica a la propiedad Author del control de ejemplo Book que aparece en Ejemplo de propiedades de controles de servidor. |
|
Atributo en tiempo de diseño. Asocia un editor UITypeEditor personalizado a una propiedad o a un tipo de propiedad. Si este atributo se aplica al tipo, no se tiene que aplicar a una propiedad de ese tipo. |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] Se aplica a la propiedad Contacts del control de ejemplo QuickContacts que aparece en Ejemplo de propiedad Collection de controles Web. |
|
Atributo en tiempo de diseño. Especifica si el nombre de la propiedad aparece en la lista IntelliSense de un editor de código fuente. Este atributo también se puede aplicar a métodos y eventos. El argumento del constructor del atributo es un valor de la enumeración EditorBrowsableState. Cuando no se aplica este atributo, se infiere el valor predeterminado, Always. |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] Aplique el atributo que se muestra en el ejemplo anterior para ocultar un miembro en IntelliSense. |
|
Atributo en tiempo de diseño y en tiempo de análisis. Especifica si una propiedad puede participar en el filtrado de dispositivos y exploradores. El filtrado permite a los desarrolladores de páginas especificar valores de propiedades diferentes para exploradores diferentes en una sola declaración para el control. Por ejemplo, un desarrollador de páginas puede utilizar el filtrado para establecer valores diferentes en la propiedad Text de un control Label, como se muestra en la sintaxis siguiente: "UP" e "IE" son filtros de exploradores. Cuando no se aplica este atributo, se infiere el valor predeterminado Filterable(true). |
[Filterable(false)] Aplique el atributo que se muestra en el ejemplo anterior para excluir una propiedad del filtrado de dispositivos y exploradores. |
|
Atributo en tiempo de diseño. Especifica si conviene traducir la propiedad. Cuando una propiedad se marca como Localizable(true), el valor de la propiedad se almacena en un archivo de recursos. Cuando no se aplica este atributo, se infiere el valor predeterminado, Localizable(false). |
[Localizable(true)] Se aplica a la propiedad Text del control de ejemplo WelcomeLabel que aparece en Tutorial: Desarrollar y utilizar un control de servidor personalizado. |
|
Atributo en tiempo de diseño. Especifica que en un examinador de propiedades, los cambios realizados en una subpropiedad se deben propagar a la propiedad primaria. |
[NotifyParentProperty(true)] Se aplica a las propiedades FirstName, LastName y MiddleName del tipo Author definido en Ejemplo de propiedades de controles de servidor. |
|
Atributo en tiempo de diseño. Especifica si la propiedad se debe conservar como atributo en la etiqueta del control o como contenido anidado en las etiquetas del control. El argumento del constructor del atributo es un valor de la enumeración PersistenceMode. |
[PersistenceMode(PersistenceMode.InnerProperty)] Se aplica a la propiedad Author del control de ejemplo Book que aparece en Ejemplo de propiedades de controles de servidor. |
|
Atributo en tiempo de diseño y en tiempo de análisis. Especifica el tipo de contenedor de nomenclatura para una propiedad que devuelve una interfaz ITemplate. |
[TemplateContainer(typeof(CustomTemplateContainer))] Aplique el atributo mostrado en el ejemplo anterior para especificar que la propiedad ITemplate está representada por la clase CustomTemplateContainer. |
|
Atributo en tiempo de diseño y en tiempo de análisis. Especifica si una propiedad de plantilla permite la creación de una sola instancia o de varias instancias. Si una propiedad de plantilla no se extiende con el atributo TemplateInstanceAttribute, se crean varias instancias de manera predeterminada. |
[TemplateInstance(TemplateInstance.Single)] Aplique el atributo mostrado en el ejemplo anterior para especificar que sólo se puede crear una instancia de una propiedad de plantilla. |
|
Atributo en tiempo de análisis. Especifica si los temas o máscaras de controles pueden afectar a un miembro de un control. De forma predeterminada, todas las propiedades expuestas por un control pueden tener temas aplicados si el propio tipo de control puede tener temas aplicados. |
[Themeable(false)] Aplique el atributo mostrado en el ejemplo anterior para evitar que los temas o máscaras de controles afecten a un miembro de un control. |
|
Atributo en tiempo de diseño, en tiempo de análisis y en tiempo de ejecución. Asocia un convertidor de tipos a una propiedad o un tipo de propiedad. Los convertidores de tipos realizan conversiones de una representación de cadena a un tipo determinado y viceversa. |
[TypeConverter(typeof(AuthorConverter))] Se aplica al tipo Author definido en Ejemplo de propiedades de controles de servidor. |
|
Atributo en tiempo de diseño y en tiempo de ejecución. Especifica que una propiedad de cadena representa un valor de dirección URL, lo que permitirá asociar un generador de direcciones URL a la propiedad. |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] Se aplica para establecer un filtro de archivos concreto para los archivos de ASP.NET y permitir el uso de rutas de acceso absolutas y relativas. |
Atributos aplicados a miembros de eventos
Los principales atributos que se aplican a los miembros de eventos son tres atributos en tiempo de diseño: BrowsableAttribute, CategoryAttribute y DescriptionAttribute. Estos atributos también se aplican a las propiedades y se describen en la tabla anterior. Para obtener un ejemplo de código, vea el evento Submit del control de ejemplo Register que aparece en Ejemplo de control Web compuesto.
Vea también
Tareas
Tutorial: Desarrollar y utilizar un control de servidor personalizado