Syntaxe de contrôle serveur personnalisé

Article
09/04/2008

Mise à jour : novembre 2007

La syntaxe de contrôle serveur personnalisé permet de déclarer des contrôles utilisateur et des contrôles serveur personnalisés comme éléments de balisage dans les fichiers d'application ASP.NET, notamment les pages Web, les contrôles utilisateur et les pages maîtres. Cette syntaxe est pratiquement identique à la syntaxe utilisée pour déclarer tous les contrôles serveur ASP.NET, à la seule différence que vous déclarez généralement, pour les contrôles utilisateur et personnalisés, un préfixe de balise unique et un nom de balise qui correspond à votre contrôle.

<tagprefix:tagname id="OptionalID"
   attributename="value"
   eventname="eventhandlermethod"
   runat="server" />
OR
<tagprefix:tagname id="OptionalID"
   runat="server" />

Attributs

tagprefix
Alias de l'espace de noms qualifié complet des éléments de balisage utilisés sur la page. La valeur de l'alias est arbitraire, mais il offre la possibilité d'utiliser un nom abrégé pour associer la balise d'un contrôle personnalisé ou d'un contrôle utilisateur à l'espace de noms des autres éléments de balisage déclarés dans un fichier ASP.NET.
tagname
Pour un contrôle personnalisé, l'attribut tagname fait référence au nom d'un type pour lequel ASP.NET créera une instance d'exécution. Dans le cas d'un contrôle utilisateur, l'attribut tagname est mappé au fichier source associé qui définit le contrôle utilisateur. Ce fichier définit, quant à lui, le type pour lequel ASP.NET crée une instance.
id
Identificateur unique qui active la référence programmatique sur le contrôle.
attributename
Nom d'un attribut qui correspond à une propriété du contrôle.
value
Valeur assignée à l'attribut (propriété).
eventname
Nom d'un événement du contrôle.
eventhandlermethod
Nom d'un gestionnaire d'événements défini pour gérer l'événement spécifié pour le contrôle.

Notes

Utilisez la syntaxe de contrôle serveur personnalisé pour déclarer des contrôles utilisateur et des contrôles serveur personnalisés dans le corps d'une page Web ASP.NET. Pour que cette syntaxe fonctionne, le contrôle doit être inscrit dans la page ou dans un fichier de configuration (vous pouvez inscrire un contrôle dans toutes les pages d'une application en l'ajoutant à l'élément <controls> du fichier Web.config). Vous pouvez inscrire un contrôle dans une page individuelle à l'aide de la directive @ Register.

La balise d'ouverture d'un élément d'un contrôle utilisateur ou personnalisé doit inclure une paire attribut/valeur runat="server". Pour activer la référence du contrôle par programme, vous pouvez éventuellement spécifier une valeur unique pour l'attribut id.

Toute propriété créée sur un contrôle utilisateur ou un contrôle serveur personnalisé peut être exposée de façon déclarative dans la balise d'ouverture du contrôle serveur. Il vous suffit de déclarer la propriété en tant qu'attribut et de lui assigner une valeur. Par exemple, si vous créez un contrôle zone de texte personnalisé avec une propriété width, la déclaration de width="50" dans la balise d'ouverture définit une valeur de cinquante pixels comme largeur d'affichage du contrôle serveur.

Dans certains cas, les attributs peuvent être des objets possédant leurs propres propriétés. Incluez alors le nom de la propriété dans la déclaration. Si, par exemple, vous créez un contrôle zone de texte personnalisé qui inclut un attribut font, ce dernier peut comprendre une propriété name. Vous pouvez ensuite déclarer la propriété dans la balise d'ouverture du contrôle serveur sous la forme font-name="Arial". Pour plus d'informations sur le développement de contrôles serveur personnalisés avec des propriétés, consultez Propriétés et sous-propriétés simples des contrôles serveur.

Vous pouvez déclarer des événements avec des contrôles serveur personnalisés et des contrôles utilisateur de la même façon que vous le feriez avec des contrôles serveur ASP.NET. Spécifiez la liaison de l'événement dans la balise d'ouverture du contrôle serveur avec un attribut et une valeur. Pour plus d'informations sur la création de contrôles serveur personnalisés qui prennent en charge des événements, consultez Gestion des événements serveur dans les pages Web ASP.NET.

Vous pouvez utiliser et développer des contrôles serveur personnalisés prenant en charge des modèles inline. Pour plus d'informations sur la déclaration de modèles dans un contrôle serveur personnalisé, consultez Syntaxe de modèle inline de contrôle serveur. Pour savoir comment créer des contrôles serveur personnalisés qui prennent en charge des modèles inline, consultez Comment : créer des contrôles utilisateur ASP.NET avec modèles.

Exemple

L'exemple de code suivant montre comment inscrire et déclarer un contrôle serveur personnalisé dans une page Web ASP.NET. La première section du code crée une classe publique dérivée de la classe Button. La seconde partie du code est une page Web qui héberge le bouton personnalisé. Notez que la page Web utilise la directive @ Register pour inscrire l'espace de noms du contrôle et définir l'attribut tagprefix. Le contrôle est ensuite référencé dans la page à l'aide de la valeur de tagprefix et du nom de classe du contrôle, séparés par deux-points (:).

Pour que l'exemple de code s'exécute, vous devez compiler ce contrôle personnalisé. Vous pouvez le compiler explicitement et mettre l'assembly résultant dans le dossier Bin de votre site Web ou dans le Global Assembly Cache. Vous pouvez également mettre le code source dans le dossier App_Code de votre site où il sera compilé dynamiquement au moment de l'exécution. Cet exemple de code utilise la compilation dynamique, ce qui explique pourquoi la directive @ Register de la page n'a pas besoin de déclarer un attribut Assembly (la source est, en effet, compilée dynamiquement au moment de l'exécution). Pour obtenir une procédure pas à pas qui illustre le processus de compilation, consultez Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé.

Note de sécurité :
Cet exemple a une zone de texte qui accepte l'entrée d'utilisateur, ce qui constitue une menace éventuelle pour la sécurité. Par défaut, les pages Web ASP.NET vérifient que les entrées d'utilisateur n'incluent pas de script ou d'éléments HTML. Pour plus d'informations, consultez Vue d'ensemble des attaques de script.

// A custom Button control to reference in the page.
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Security.Permissions
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
  Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class CustomButton : Button
  {
    public CustomButton()
    {
      this.Text = "Click Here";
    }
  }
}

<!-- A page that references the custom control. -->
<%@Page language="C#" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"      namespace="Samples.AspNet.CS.Controls" %>
    
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>   
 <script runat="server">
     private void custButton_Click(Object sender, EventArgs e)
     {
       TextBox.BackColor = System.Drawing.Color.Green;
       TextBox.Text = "You clicked the button";
     }       
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton"          onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

' A custom Button control to reference in the page.
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.Configuration
Imports System.Data.Sql
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class CustomButton
    Inherits Button

    Public Sub New()
      Me.Text = "Click Here"
    End Sub

  End Class

End Namespace
<!-- A page that references the custom control. -->
<%@ Page Language="VB" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"    namespace="Samples.AspNet.VB.Controls" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>   
 <script runat="server">
   Sub custButton_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
     TextBox.BackColor = Drawing.Color.Green
     TextBox.Text = "You clicked the button."
   End Sub
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton"          onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

Voir aussi

Concepts

Vue d'ensemble de la syntaxe des pages Web ASP.NET

Partager via