Comment : utiliser des contrôles serveur ASP.NET personnalisés dans Visual Studio

Article
10/22/2014

Mise à jour : novembre 2007

Vous pouvez rendre vos contrôles serveur personnalisés disponibles dans la boîte à outils Visual Studio en définissant les attributs de design appropriés que le concepteur visuel doit utiliser. Les procédures suivantes créent un contrôle simple nommé MailLink, l'incluent dans la boîte à outils et l'utilisent pour créer un lien de messagerie électronique dans une page Web en restituant un élément <a> de lien hypertexte avec une URL mailto:.

Pour créer un contrôle personnalisé qui contient des attributs de design

Dans Visual Studio, créez un projet de bibliothèque et définissez une classe personnalisée qui dérive de WebControl, comme illustré dans l'exemple suivant.

Remarque :
Le code source complet est présenté dans la section Exemple.

<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
Namespace Samples.AspNet
   < _
    ToolboxData("<{0}:MailLink ID='MailLinkID' Text='WebMaster' runat=""server""> </{0}:MailLink>")> _
    Public Class MailLink
        Inherits WebControl
     ' Custom code goes here.
End Class

End Namespace

[assembly:TagPrefix("Samples.AspNet", "Sample")]
namespace Samples.AspNet
{

    [
        ToolboxData("<{0}:MailLink ID='MailLinkID' Text='WebMaster' runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        // Custom code goes here.
    }

}

Ajoutez des attributs de design pour fournir des métadonnées personnalisées qui seront utilisées pour afficher le contrôle dans le concepteur visuel au moment du design. Les deux attributs de design suivants sont les seuls nécessaires pour rendre le contrôle MailLink disponible dans la boîte à outils Visual Studio.

L'attribut TagPrefix spécifie le préfixe devant le nom de contrôle MailLink. Ensemble, le préfixe et le nom de contrôle définissent le nom de balise pour le contrôle personnalisé (dans ce cas, <Sample:MailLink> </Sample:MailLink>).
```
<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
```
```
[assembly:TagPrefix("Samples.AspNet", "Sample")]
```
L'attribut ToolboxData spécifie la balise par défaut générée pour le contrôle MailLink lorsqu'il est déplacé de la boîte à outils vers une page au moment du design.
```
<ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Webmaster' runat='server'"> </{0}:MailLink>")> 
```
```
[ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Webmaster' runat=\"server\"> </{0}:MailLink>")]
```
Compilez le contrôle MailLink dans une bibliothèque et nommez-le MaiLink.Dll.

Pour ajouter le contrôle personnalisé à la boîte à outils

Dans le menu Affichage, cliquez sur Boîte à outils.
Dans la boîte à outils, cliquez avec le bouton droit et sélectionnez Choisir les éléments.
Dans la boîte de dialogue Choisir des éléments de boîte à outils, sélectionnez l'onglet Composants .NET Framework, puis cliquez sur le bouton Parcourir pour localiser la MailLink.Dll que vous venez de générer.
Activez la case à cocher pour le contrôle MailLink, puis cliquez sur OK.

Le contrôle MailLink personnalisé apparaît dans la boîte à outils.

Pour référencer le contrôle MailLink dans une page

Créez un projet Web. Créez ensuite une page nommée MailLink.aspx. Cette page contiendra l'une des directives suivantes, selon le langage que vous avez sélectionné pour le projet.
```
<%@ page language="VB" %>
```
```
<%@ page language="C#" %>
```

Ajoutez la structure de page simple suivante pour héberger le contrôle MailLink.

<html xmlns="http://www.w3.org/1999/xhtml" >
<head >
    <title>Using the MailLink control</title>
</head>
<body>
<h1>Using the MailLink Custom Server Control</h1>
    <form id="form1" >
    <div>

   </div>

    </form>
</body>
</html>

Basculez en mode Design et faites glisser le contrôle MailLink sur votre page.

Visual Studio ajoute deux éléments à la page : une directive Register pour le contrôle MailLink et le nom de balise du contrôle MailLink à utiliser dans la page.
Exécutez la page dans un navigateur et cliquez sur le lien Mail Webmaster.

Un message électronique s'ouvre, à destination de l'adresse spécifiée par la propriété Email du contrôle.

Exemple

Le contrôle MailLink substitue la propriété TagKey pour rendre un élément <a> au lieu de l'élément <span> par défaut rendu par la classe WebControl.

Imports System
Imports System.ComponentModel
Imports System.Security
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

<Assembly: TagPrefix("Samples.AspNet", "Sample")> 
Namespace Samples.AspNet

    <AspNetHostingPermission( _
    SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission( _
    SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal), _
    ParseChildren(True, "Text"), _
    DefaultProperty("Email"), _
    ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Web Master' runat=""server""> </{0}:MailLink>")> _
    Public Class MailLink
        Inherits WebControl

        <Browsable(True), Category("Appearance"), _
        DefaultValue("webmaster@contoso.com"), _
        Description("The e-mail address.")> _
        Public Overridable Property Email() As String
            Get
                Dim s As String = CStr(ViewState("Email"))
                If s Is Nothing Then s = "webmaster@contoso.com"
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Email") = value
            End Set
        End Property


        <Browsable(True), Category("Appearance"), _
        DefaultValue("Web Master"), _
        Description("The name to display."), _
        Localizable(True), _
        PersistenceMode(PersistenceMode.InnerDefaultProperty)> _
        Public Overridable Property [Text]() As String
            Get
                Dim s As String = CStr(ViewState("Text"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Text") = value
            End Set
        End Property


        Protected Overrides ReadOnly Property TagKey() _
        As HtmlTextWriterTag
            Get
                Return HtmlTextWriterTag.A
            End Get
        End Property


        Protected Overrides Sub AddAttributesToRender(ByVal writer _
        As HtmlTextWriter)
            MyBase.AddAttributesToRender(writer)
            writer.AddAttribute( _
            HtmlTextWriterAttribute.Href, "mailto:" + Email)

        End Sub 'AddAttributesToRender


        Protected Overrides Sub RenderContents(ByVal writer _
        As HtmlTextWriter)
            If [Text] = String.Empty Then
                [Text] = Email
            End If
            writer.WriteEncodedText([Text])

        End Sub 'RenderContents
    End Class 'MailLink
End Namespace

using System;
using System.ComponentModel;
using System.Security;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

[assembly:TagPrefix("Samples.AspNet", "Sample")]
namespace Samples.AspNet
{


    [
        AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
        AspNetHostingPermission(SecurityAction.InheritanceDemand,
        Level = AspNetHostingPermissionLevel.Minimal),
        ParseChildren(true, "Text"),
        DefaultProperty("Email"),
        ToolboxData("<{0}:MailLink ID='MailLinkID' Text='Mail Web Master' runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        [
            Browsable(true),
            Category("Appearance"),
            DefaultValue("webmaster@contoso.com"),
            Description("The e-mail address.")
        ]
        public virtual string Email
        {
            get
            {
                string s = (string)ViewState["Email"];
                return (s == null) ? "webmaster@contoso.com" : s;
            }
            set
            {
                ViewState["Email"] = value;
            }
        }

        [
            Browsable(true),
            Category("Appearance"),
            DefaultValue("Web Master"),
            Description("The name to display."),
            Localizable(true),
            PersistenceMode(PersistenceMode.InnerDefaultProperty)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override HtmlTextWriterTag TagKey
        {
            get
            {
                return HtmlTextWriterTag.A;
            }
        }

        protected override void AddAttributesToRender(
            HtmlTextWriter writer)
        {
            base.AddAttributesToRender(writer);
            writer.AddAttribute(HtmlTextWriterAttribute.Href,
                "mailto:" + Email);
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            if (Text == String.Empty)
            {
                Text = Email;
            }
            writer.WriteEncodedText(Text);
        }
    }
}

Le contrôle MailLink illustre également la persistance du texte interne. MailLink permet à un développeur de pages de spécifier la propriété Text dans les balises du contrôle, comme illustré dans l'exemple suivant :

<Sample:MailLink id="MaillinkID" Email="Webmaster@contoso.com" 
    >
 Mail Support Team
</Sample:MailLink>

La persistance interne s'oppose à la persistance par défaut sur la balise d'ouverture du contrôle, comme dans l'exemple suivant :

<Sample:MailLink Text="Mail Webmaster"  > </Sample:MailLink>

Le code précédent est la balise par défaut générée pour le contrôle lorsqu'il est déplacé de la boîte à outils vers une page.

Compilation du code

Dans Visual Studio, créez un projet de bibliothèque et définissez une classe personnalisée qui dérive de WebControl, comme illustré dans la procédure ci-dessus. Le code source complet est présenté dans la section de code précédente.

Sécurité

Les contrôles serveur personnalisés étendent les fonctionnalités d'ASP.NET et doivent respecter des consignes de sécurité précises. En particulier, vous devez prendre en compte les éléments suivants :

Sécurité au moment de l'exécution et au moment du design.
Contrôles personnalisés dans les assemblys avec nom fort.
Sécurité du système d'exploitation et listes de contrôle d'accès sur le serveur qui héberge le contrôle serveur personnalisé.
Sécurité d'accès du code pour restreindre les ressources auxquelles le contrôle peut accéder.
Assemblys managés dans le Global Assembly Cache.