Attributs de métadonnées pour des contrôles serveur personnalisés
Mise à jour : novembre 2007
Les attributs de métadonnées sont appliqués aux contrôles serveur et à leurs membres pour fournir des informations utilisées par les outils de conception, l'analyseur de page ASP.NET, ASP.NET au moment de l'exécution et le Common Language Runtime. Les attributs au moment du design facilitent le développement au moment du design lorsqu'un développeur de pages utilise le contrôle dans un concepteur visuel. Les attributs réservés exclusivement au moment du design n'ont aucun effet sur les fonctionnalités d'un contrôle pendant une demande de page. Les attributs d'un contrôle au moment de l'analyse servent à l'analyseur de page ASP.NET lorsqu'il lit la syntaxe déclarative du contrôle dans une page. Les attributs d'un contrôle au moment de l'analyse et au moment de l'exécution sont essentiels au fonctionnement d'un contrôle dans une page.
Cette rubrique décrit les attributs de métadonnées que vous appliquerez couramment aux contrôles, ainsi qu'à leurs propriétés publiques et leurs événements.
Attributs appliqués à un contrôle
Attribut |
Exemple |
|---|---|
AspNetHostingPermissionAttribute Attribut de sécurité d'accès du code au moment de la compilation JIT. Requis pour garantir que le code qui lie au contrôle dispose des autorisations de sécurité appropriées. La classe Control est marquée avec deux attributs de sécurité d'accès du code au moment de la compilation JIT : AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal) et AspNetHostingPermission(SecurityAction.InheritanceDemand, Level=AspNetHostingPermissionLevel.Minimal). Vous devez appliquer le premier attribut à votre contrôle, mais vous n'êtes pas obligé d'appliquer le second puisqu'une demande d'héritage est transitive et reste effective sur les classes dérivées. Pour plus d'informations, consultez SecurityAction. |
[AspNetHostingPermission(SecurityAction.Demand, Level=AspNetHostingPermissionLevel.Minimal)] S'applique à l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé. |
|
Attribut au moment de l'analyse. Associe un générateur de contrôles personnalisé au contrôle. Vous ne devez appliquer cet attribut que si vous souhaitez utiliser un générateur de contrôles personnalisé pour modifier la logique par défaut utilisée par l'analyseur de page pour analyser la syntaxe déclarative du contrôle. Si vous souhaitez simplement spécifier si le contenu situé entre les balises d'un contrôle correspond à des propriétés ou à des contrôles enfants, utilisez ParseChildrenAttribute (décrit plus loin dans cette table) plutôt qu'un générateur de contrôles personnalisé. |
[ControlBuilder(typeof(MyControlBuilder))] |
|
Attribut au moment du design et au moment de l'exécution. Spécifie la propriété utilisée comme valeur par défaut d'un contrôle. Appliquer cet attribut permet d'utiliser un contrôle comme paramètre dans une requête au moment de l'exécution, et définit la valeur par défaut à laquelle un objet ControlParameter se lie au moment de l'exécution. |
[ControlValueProperty("Text")] |
|
Attribut au moment du design. Spécifie l'événement par défaut du contrôle dans un concepteur visuel. Dans de nombreux concepteurs visuels, lorsque le développeur de pages double-clique sur le contrôle dans l'aire de conception, l'éditeur de code s'ouvre avec le curseur placé dans le gestionnaire d'événements de l'événement par défaut. |
[DefaultEvent("Submit")] S'applique à l'exemple de contrôle Register dans Contrôle Web composite, exemple. |
|
Attribut au moment du design. La propriété spécifiée dans cet attribut apparaît en surbrillance dans l'explorateur de propriétés d'un concepteur visuel lorsque le développeur de pages sélectionne le contrôle sur l'aire de conception. |
[DefaultProperty("Text")] S'applique à l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé. |
|
Attribut au moment du design. Spécifie la classe de concepteur associée à un contrôle. Une classe de Concepteur de contrôles est responsable de l'apparence et du comportement du contrôle associé sur l'aire de conception d'un concepteur visuel. |
[Designer(typeof(SimpleCompositeControlDesigner))] S'applique aux exemples de contrôles dans Procédure pas à pas : création d'un Concepteur de contrôles de base pour un contrôle serveur Web |
|
Attribut au moment de l'analyse. Spécifie si le contenu situé entre les balises d'un contrôle correspond à des propriétés ou à des contrôles enfants. La classe Control est marquée ParseChildren(false), ce qui signifie que l'analyseur de page interprète le contenu des balises du contrôle comme des contrôles enfants. La classe WebControl est marquée ParseChildren(true), ce qui signifie que l'analyseur de page interprète le contenu des balises du contrôle comme des propriétés. Vous n'avez besoin d'appliquer cet attribut que si vous souhaitez modifier la logique spécifiée dans l'attribut ParseChildrenAttribute de la classe WebControl. |
[ParseChildren(true, "Contacts")] S'applique à l'exemple de contrôle QuickContacts dans Propriété de collection de contrôles Web, exemple. |
|
Attribut au moment du design. Spécifie si un concepteur visuel doit rendre persistants des contrôles enfants ou des propriétés entre les balises d'un contrôle lorsque ce contrôle est utilisé de façon déclarative dans une page. La classe Control est marquée PersistChildren(true), ce qui signifie que le concepteur rend des contrôles enfants persistants entre les balises du contrôle. La classe WebControl est marquée PersistChildren(false), ce qui signifie que le concepteur rend des propriétés persistantes entre les balises du contrôle. |
[PersistChildren(false)] Appliqué à la classe WebControl et approprié à la plupart des contrôles qui dérivent de cette classe. Toutefois, les contrôles conteneur, tels que Panel, qui rendent des contrôles enfants persistants entre leurs balises sont marqués PersistChildren(true) et ParseChildren(false). |
|
Attribut au moment de l'analyse. Spécifie si un contrôle peut être affecté par des thèmes ou apparences de contrôle. Si vous marquez un type de contrôle pour empêcher l'application de thèmes à celui-ci, tous les membres du contrôle ne sont pas non plus affectés par les thèmes. |
[Themeable(false)] Appliquez l'attribut indiqué dans l'exemple précédent pour empêcher un contrôle et tous ses membres d'être affectés par les thèmes ou apparences de contrôle. |
|
Attribut au moment du design. Spécifie le format de balisage créé pour la balise par le concepteur visuel lorsque le contrôle est créé à partir de la boîte à outils. |
[ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>"] S'applique à l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé. |
|
Attribut au moment du design. Spécifie si un concepteur visuel doit afficher un contrôle ou un composant dans la boîte à outils. Par défaut, la boîte à outils affiche toujours des contrôles. Vous n'avez à appliquer ceci qu'à un contrôle (comme le propriétaire d'une propriété de modèle) que vous ne souhaitez pas afficher dans la boîte à outils. |
[ToolboxItem(false)] S'applique au contrôle TemplateOwner dans Contrôle serveur basé sur des modèles, exemple. |
|
Attribut au moment du design. Spécifie le nom de la propriété vérifiée par un contrôle de validation. En général, c'est la propriété dont la valeur est fournie par les utilisateurs au moment de l'exécution, par exemple la propriété Text d'un contrôle TextBox. Dans un concepteur visuel, la boîte de dialogue qui permet aux développeurs de pages de sélectionner la cible d'un contrôle de validation répertorie les propriétés spécifiées avec des ValidationPropertyAttribute provenant de contrôles de la page. |
[ValidationProperty("Text")] |
Attributs appliqués à des propriétés publiques
Attribut |
Exemple |
|---|---|
|
Attribut au moment du design. Spécifie s'il est pertinent de lier des données à une propriété. Dans un concepteur visuel, l'explorateur de propriétés peut afficher dans une boîte de dialogue les propriétés d'un contrôle qui peuvent être liées. (Par exemple, dans Visual Studio, les propriétés pouvant être liées s'affichent dans la boîte de dialogue DataBindings). Si une propriété n'est pas marquée de cet attribut, l'explorateur de propriétés en déduit que la valeur est Bindable(false). |
[Bindable(true)] S'applique à la propriété Text de l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé. |
|
Attribut au moment du design. Spécifie si une propriété doit s'afficher dans l'explorateur de propriétés d'un concepteur visuel. Appliquez Browsable(false) à une propriété que vous ne souhaitez pas afficher dans l'explorateur de propriétés. La valeur par défaut, Browsable(true), est déduite par l'explorateur de propriétés lorsqu'une propriété n'est pas marquée avec cet attribut. |
[Browsable(false)] S'applique à la propriété Template de l'exemple de contrôle VacationHome dans Contrôle serveur basé sur des modèles, exemple. |
|
Attribut au moment du design. Spécifie comment classer la propriété dans l'explorateur de propriétés d'un concepteur visuel. Par exemple, Category("Appearance") indique à l'explorateur de propriétés d'afficher la propriété dans la catégorie Appearance lorsque le développeur de pages utilise l'affichage des catégories dans l'explorateur de propriétés. Vous pouvez spécifier un argument string correspondant à une catégorie existante dans l'explorateur de propriétés ou créer votre propre catégorie. |
[Category("Appearance")] S'applique à la propriété Text de l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé |
|
Attribut au moment du design. Spécifie une valeur par défaut pour une propriété. Cette valeur doit être la même que la valeur par défaut que vous retournez depuis l'accesseur de propriété (accesseur Get). Dans certains concepteurs visuels tels que Visual Studio, l'attribut DefaultValueAttribute permet à un développeur de pages de réinitialiser une propriété à sa valeur par défaut à l'aide de la commande Réinitialiser dans le menu contextuel. |
[DefaultValue("")] S'applique à la propriété Text de l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé |
|
Attribut au moment du design. Spécifie une brève description de la propriété. Dans un concepteur visuel tel que Visual Studio, l'explorateur de propriétés affiche la description de la propriété sélectionnée, en général au bas de la fenêtre. |
[Description("The welcome message text.")] S'applique à la propriété Text de l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé |
DesignerSerializationVisibilityAttribute Attribut au moment du design. Spécifie s'il faut sérialiser une propriété ou son contenu (tel que des sous-propriétés ou des éléments de collection), défini au moment du design. L'argument du constructeur de l'attribut est une valeur de l'énumération DesignerSerializationVisibility. La valeur par défaut, Visible, est sous-entendue lorsque cet attribut n'est pas appliqué, et la valeur de la propriété est sérialisée. |
[DesignerSerializationVisibility (DesignerSerializationVisibility.Content)] S'applique à la propriété Author de l'exemple de contrôle Book dans Propriétés de contrôle serveur, exemple. |
|
Attribut au moment du design. Associe un éditeur UITypeEditor personnalisé à une propriété ou un type de propriété. Si cet attribut est appliqué au type, il n'est pas nécessaire qu'il s'applique à une propriété de ce type. |
[Editor(typeof(ContactCollectionEditor), typeof(UITypeEditor))] S'applique à la propriété Contacts de l'exemple de contrôle QuickContacts dans Propriété de collection de contrôles Web, exemple. |
|
Attribut au moment du design. Spécifie si le nom de la propriété apparaît dans la liste IntelliSense d'un éditeur de code source. Cet attribut peut également s'appliquer aux méthodes et aux événements. L'argument du constructeur de l'attribut est une valeur de l'énumération EditorBrowsableState. La valeur par défaut, Always, est sous-entendue lorsque cet attribut n'est pas appliqué. |
[EditorBrowsableAttribute (EditorBrowsableState.Never)] Appliquez l'attribut de l'exemple précédent pour masquer un membre dans IntelliSense. |
|
Attribut au moment du design et au moment de l'analyse. Spécifie si une propriété peut participer au filtrage de périphérique et de navigateur. Le filtrage permet à un développeur de pages de spécifier des valeurs de propriété différentes pour des navigateurs différents dans une déclaration de contrôle seule. Par exemple, un développeur de pages peut utiliser le filtrage pour définir différentes valeurs pour la propriété Text d'un contrôle Label, comme dans la syntaxe suivante : "UP" et "IE" sont des filtres de navigateurs. La valeur par défaut, Filterable(true), est sous-entendue lorsque cet attribut n'est pas appliqué. |
[Filterable(false)] Appliquez l'attribut de l'exemple précédent pour exclure une propriété du filtrage de périphérique et de navigateur. |
|
Attribut au moment du design. Spécifie s'il est pertinent de localiser la propriété. Lorsqu'une propriété est marquée Localizable(true), sa valeur est stockée dans un fichier de ressources. La valeur par défaut, Localizable(false), est sous-entendue lorsque cet attribut n'est pas appliqué. |
[Localizable(true)] S'applique à la propriété Text de l'exemple de contrôle WelcomeLabel dans Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé. |
|
Attribut au moment du design. Spécifie que, dans un explorateur de propriétés, les modifications faites à une sous-propriété doivent être propagées à la propriété parente. |
[NotifyParentProperty(true)] Appliqué aux propriétés FirstName, LastName et MiddleName du type Author défini dans Propriétés de contrôle serveur, exemple. |
|
Attribut au moment du design. Spécifie s'il faut rendre une propriété persistante comme attribut de la balise du contrôle ou comme contenu imbriqué entre les balises du contrôle. L'argument du constructeur de l'attribut est une valeur de l'énumération PersistenceMode. |
[PersistenceMode(PersistenceMode.InnerProperty)] S'applique à la propriété Author de l'exemple de contrôle Book dans Propriétés de contrôle serveur, exemple. |
|
Attribut au moment du design et au moment de l'analyse. Spécifie le type de conteneur d'attribution de noms (naming container) d'une propriété qui retourne une interface ITemplate. |
[TemplateContainer(typeof(CustomTemplateContainer))] Appliquez l'attribut indiqué dans l'exemple précédent pour spécifier que la propriété ITemplate est représentée par la classe CustomTemplateContainer. |
|
Attribut au moment du design et au moment de l'analyse. Spécifie si une propriété de modèle autorise la création d'une seule ou de plusieurs instances. Si une propriété de modèle n'est pas étendue avec l'attribut TemplateInstanceAttribute, la valeur par défaut est la création de plusieurs instances. |
[TemplateInstance(TemplateInstance.Single)] Appliquez l'attribut illustré dans l'exemple précédent pour spécifier qu'une seule instance d'une propriété de modèle peut être créée. |
|
Attribut au moment de l'analyse. Spécifie si un membre d'un contrôle peut être affecté par les thèmes ou apparences de contrôle. Par défaut, des thèmes peuvent être appliqués à toutes les propriétés exposées par un contrôle si le type de contrôle lui-même autorise l'application de thèmes. |
[Themeable(false)] Appliquez l'attribut illustré dans l'exemple précédent pour empêcher un membre de contrôle d'être affecté par les thèmes ou apparences de contrôle. |
|
Attribut au moment du design, de l'analyse et de l'exécution. Associe un convertisseur de type à une propriété ou un type de propriété. Les convertisseurs de type exécutent la conversion d'une représentation sous forme de chaîne en un type donné et vice-versa. |
[TypeConverter(typeof(AuthorConverter))] Appliqué au type Author défini dans Propriétés de contrôle serveur, exemple. |
|
Attribut au moment du design et au moment de l'exécution. Spécifie qu'une propriété de type chaîne représente une valeur d'URL, ce qui vous permet d'associer un générateur d'URL à la propriété. |
[UrlProperty("*.aspx",AllowedTypes=UrlTypes.Absolute|UrlTypes.RootRelative|UrlTypes.AppRelative)] Appliquer pour définir un filtre de fichiers spécifique pour les fichiers ASP.NET et autoriser les chemins d'accès absolus et relatifs. |
Attributs appliqués à des membres d'événements
Les principaux attributs appliqués à des membres d'événements sont trois attributs au moment du design : BrowsableAttribute, CategoryAttribute et DescriptionAttribute. Ces attributs sont également appliqués aux propriétés et décrits dans la table précédente. Pour obtenir un exemple de code, consultez l'événement Submit de l'exemple de contrôle Register dans Contrôle Web composite, exemple.
Voir aussi
Tâches
Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé