Partager via

Procédure pas à pas : développement et utilisation d'un contrôle serveur personnalisé

  • Article

Mise à jour : novembre 2007

Cette procédure pas à pas montre comment créer et compiler un contrôle serveur ASP.NET personnalisé et comment l'utiliser dans une page.

Au cours de cette procédure pas à pas, vous apprendrez à :

  • Créer un contrôle serveur ASP.NET.

  • Ajouter des métadonnées au contrôle et à ses membres pour contrôler la sécurité et le comportement au moment du design.

  • Utiliser le répertoire App_Code dans un site Web ASP.NET pour tester votre contrôle sans étapes de compilation manuelles.

  • Spécifier un préfixe de balise dans un fichier de configuration et dans l'assembly du contrôle.

  • Compiler le contrôle en un assembly et l'ajouter au répertoire Bin.

  • Incorporer une bitmap dans l'assembly du contrôle, comme icône de concepteur visuel dans la boîte à outils.

  • Utiliser le contrôle compilé dans une page.

Un outil visuel de conception tel que Microsoft Visual Studio 2005, s'il simplifie le développement des contrôles, n'est pas indispensable pour créer ou générer des contrôles personnalisés. Vous pouvez créer vos contrôles à l'aide de n'importe quel éditeur de texte et les générer à partir de la ligne de commande à l'aide des compilateurs fournis avec le Kit de développement logiciel (SDK) Windows. Indépendamment de la façon dont vous créez votre contrôle, son apparence et son comportement au moment du design dans un concepteur visuel seront les mêmes. Un développeur de pages peut ajouter votre contrôle à la boîte à outils du concepteur visuel, le faire glisser sur l'aire de conception et accéder à ses propriétés et ses événements dans l'Explorateur de propriétés. Dans certains concepteurs visuels, tels que Visual Studio 2005, un contrôle personnalisé bénéficie également de la prise en charge d'IntelliSense sans intervention de votre part.

Création du contrôle serveur

Le contrôle que vous créerez, WelcomeLabel, est un contrôle simple, semblable au contrôle Label standard. La classe WelcomeLabel dérive de WebControl et définit une propriété Text qui permet à un développeur de pages de fournir une chaîne de texte afin d'accueillir un utilisateur sur un site. WelcomeLabel ajoute le nom de l'utilisateur à la chaîne de texte si ce nom figure dans l'en-tête envoyé par le navigateur de l'utilisateur. Pour plus d'informations sur la récupération du nom d'utilisateur, consultez User. Par exemple, si le développeur de pages définit "Hello" comme valeur de la propriété Text, WelcomeLabel rend "Hello, nomUtilisateur!" ou "Hello!" selon que le nom d'utilisateur apparaît ou non dans l'en-tête.

Pour créer le code du contrôle serveur personnalisé

  1. Créez un fichier nommé WelcomeLabel.cs ou WelcomeLabel.vb.

  2. Ajoutez le code suivant au fichier source du contrôle :

    ' WelcomeLabel.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet.VB.Controls
    < _
    AspNetHostingPermission(SecurityAction.Demand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission(SecurityAction.InheritanceDemand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    DefaultProperty("Text"), _
    ToolboxData( _
        "<{0}:WelcomeLabel runat=""server""> </{0}:WelcomeLabel>") _
    > _
    Public Class WelcomeLabel
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The welcome message text."), _
        Localizable(True) _
        > _
        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 Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            writer.WriteEncodedText(Text)
            If Context IsNot Nothing Then
                Dim s As String = Context.User.Identity.Name
                If (s IsNot Nothing) AndAlso (s <> String.Empty) Then
                    Dim split() As String = s.Split("\".ToCharArray)
                    Dim n As Integer = split.Length - 1
                    If (split(n) <> String.Empty) Then
                        writer.Write(", ")
                        writer.Write(split(n))
                    End If
                End If
            End If
            writer.Write("!")
        End Sub
    End Class
End Namespace

    // WelcomeLabel.cs
using System;
using System.ComponentModel;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace Samples.AspNet.CS.Controls
{
    [
    AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
    AspNetHostingPermission(SecurityAction.InheritanceDemand, 
        Level=AspNetHostingPermissionLevel.Minimal),
    DefaultProperty("Text"),
    ToolboxData("<{0}:WelcomeLabel runat=\"server\"> </{0}:WelcomeLabel>")
    ]
    public class WelcomeLabel : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The welcome message text."),
        Localizable(true)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            writer.WriteEncodedText(Text);
            if (Context != null)
            {
                string s = Context.User.Identity.Name;
                if (s != null && s != String.Empty)
                {
                    string[] split = s.Split('\\');
                    int n = split.Length - 1;
                    if (split[n] != String.Empty)
                    {
                        writer.Write(", ");
                        writer.Write(split[n]);
                    }
                }
            }
            writer.Write("!");
        }
    }
}

Explication du code

La description du code ci-après n'est pas indispensable pour exécuter les étapes de cette procédure pas à pas. Vous pouvez l'ignorer dans un premier temps. Toutefois, si vous abordez la création de contrôles pour la première fois, nous vous conseillons au moins de la lire une fois que vous aurez terminé la procédure pas à pas.

Si votre contrôle rend un élément d'interface utilisateur ou un autre élément visible sur le client, vous devez dériver votre contrôle de System.Web.UI.WebControls.WebControl (ou une classe dérivée). Si votre contrôle rend un élément non visible dans le navigateur client, tel qu'un élément masqué ou un élément meta, dérivez votre contrôle de System.Web.UI.Control. La classe WebControl dérive de Control et ajoute des propriétés relatives au style telles que Font, ForeColor et BackColor. De plus, un contrôle qui dérive de WebControl participe aux fonctionnalités de thèmes d'ASP.NET sans intervention supplémentaire de votre part.

Si votre contrôle étend les fonctionnalités d'un contrôle existant, tel que le contrôle Button, Label ou Image, vous pouvez dériver de ce contrôle. Puisque WelcomeLabel étend les fonctionnalités du contrôle Label, il pourrait dériver de Label. Mais cette procédure pas à pas dérive WelcomeLabel de WebControl pour montrer comment définir une propriété et des métadonnées de propriété.

WelcomeLabel définit une seule propriété, Text, et utilise l'état d'affichage pour en stocker la valeur. Utiliser l'état d'affichage rend la valeur de Text persistante d'une publication à l'autre. À chaque publication, la page est recréée et les valeurs sont restaurées depuis l'état d'affichage. Si la valeur de Text n'avait pas été stockée dans l'état d'affichage, elle serait la valeur par défaut, Empty, pour chaque publication. La propriété ViewState héritée de WebControl est un dictionnaire qui enregistre des valeurs de données. Les valeurs sont saisies et récupérées à l'aide d'une clé String. Dans ce cas précis, "Text" est utilisé comme clé. Les éléments du dictionnaire sont de type Object, pour lesquels vous devez alors effectuer un cast en type de propriété. Pour plus d'informations, consultez Vue d'ensemble de la gestion d'état ASP.NET.

Le contrôle WelcomeLabel rend sa propriété Text en substituant la méthode RenderContents héritée. Le paramètre passé dans la méthode RenderContents est un objet de type HtmlTextWriter, qui est une classe utilitaire possédant des méthodes pour rendre des balises et autre balisage HTML (ou une variante de HTML).

Remarquez que WelcomeLabel fait des appels répétés à la méthode Write de l'objet HtmlTextWriter au lieu d'exécuter la concaténation des chaînes, puis d'appeler la méthode Write. Cela améliore les performances parce que l'objet HtmlTextWriter écrit directement dans le flux de sortie. La concaténation de chaîne prend du temps et de la mémoire pour créer la chaîne avant d'écrire dans le flux de données. Lorsque vous implémentez le rendu dans vos contrôles, vous devez suivre le modèle illustré par cette procédure pas à pas.

Remarque :

En général, lorsque votre contrôle dérive de WebControl et rend un seul élément, vous devez substituer la méthode RenderContents (et non la méthode Render) pour rendre le contenu entre les balises du contrôle. La méthode Render de WebControl appelle RenderContents après avoir rendu la balise d'ouverture du contrôle et de ses attributs de style. Si vous substituez la méthode Render pour écrire du contenu, votre contrôle perdra la logique de rendu de style intégrée à la méthode Render de WebControl. Pour plus d'informations sur le rendu d'un contrôle qui dérive de WebControl, consultez Rendu de contrôle Web, exemple.

Les attributs appliqués à WelcomeLabel contiennent des métadonnées utilisées par le Common Language Runtime et par les outils au moment du design.

Au niveau de la classe, WelcomeLabel est marqué avec les attributs suivants :

  • AspNetHostingPermissionAttribute est un attribut de sécurité d'accès au code. Il force le compilateur JIT vérifie que le code qui lie à WelcomeLabel reçoit l'autorisation AspNetHostingPermission. Toutes les classes ASP.NET publiques sont marquées de cet attribut. Vous devez appliquer AspNetHostingPermissionAttribute à vos contrôles comme une vérification de sécurité vis-à-vis d'appelants d'un niveau de confiance partiel.

  • DefaultPropertyAttribute est un attribut au moment du design qui spécifie la propriété par défaut d'un contrôle. Dans les concepteurs visuels, l'Explorateur de propriétés met typiquement en surbrillance la propriété par défaut lorsqu'un développeur de pages clique sur le contrôle sur l'aire de conception.

  • ToolboxDataAttribute spécifie le format de la chaîne de l'élément. La chaîne devient le balisage du contrôle lorsque l'on double-clique sur le contrôle dans la boîte à outils ou qu'on le fait glisser de la boîte à outils sur l'aire de conception. Pour WelcomeLabel, la chaîne crée l'élément suivant :

    <aspSample:WelcomeLabel > </aspSample:WelcomeLabel>

Le contrôle WelcomeLabel hérite également deux attributs de la classe de base WebControl, ParseChildrenAttribute et PersistChildrenAttribute. Ils s'appliquent en tant que ParseChildren(true) et PersistChildren(false). Ces deux attributs fonctionnent ensemble, ainsi qu'avec l'attribut ToolboxDataAttribute, afin que les éléments enfants soient interprétés comme des propriétés et que les propriétés soient persistantes comme attributs.

Les attributs suivants appliqués à la propriété Text de WelcomeLabel sont des attributs standard au moment du design que vous appliquerez de façon générale à toutes les propriétés publiques de vos contrôles :

  • BindableAttribute, spécifié comme true ou false, spécifie aux concepteurs visuels s'il est pertinent de lier la propriété aux données. Par exemple, dans Visual Studio 2005, si une propriété est marquée avec Bindable(true), elle s'affiche 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).

  • CategoryAttribute spécifie comment classer la propriété dans l'Explorateur de propriétés du 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 de 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.

  • DescriptionAttribute spécifie une brève description de la propriété. Dans Visual Studio 2005, l'Explorateur de propriétés affiche la description de la propriété sélectionnée au bas de la fenêtre Propriétés.

  • DefaultValueAttribute spécifie une valeur par défaut pour la 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 Visual Studio 2005, DefaultValueAttribute permet à un développeur de pages de réinitialiser une propriété à sa valeur par défaut en ouvrant le menu contextuel de la fenêtre Propriétés et en cliquant sur le bouton Réinitialiser.

  • LocalizableAttribute, spécifié comme true ou false, spécifie aux concepteurs visuels s'il est pertinent de localiser la propriété. Lorsqu'une propriété est marquée Localizable(true), le concepteur visuel l'inclut lors de la sérialisation de ressources localisées. La valeur de la propriété sera persistante dans le fichier de ressources indépendant de la culture ou une autre source de localisation lorsque le contrôle sera sondé à la recherche de propriétés localisables.

    Remarque :

    Dans les versions 1.0 et 1.1 d'ASP.NET, vous ne pouviez pas appliquer de LocalizableAttribute aux contrôles serveur personnalisés parce que le modèle de localisation ASP.NET de ces versions était différent.

Les attributs au moment du design appliqués à un contrôle et à ses membres n'affectent pas le fonctionnement du contrôle au moment de l'exécution, mais facilitent le développement lorsque le contrôle est utilisé dans un concepteur visuel. Vous pouvez voir une liste complète des attributs des contrôles serveur au moment du design, de l'analyse et de l'exécution dans Attributs de métadonnées pour des contrôles serveur personnalisés.

Utilisation du répertoire App_Code pour tester des contrôles sans compilation

Vous pouvez utiliser la fonctionnalité de compilation dynamique ASP.NET pour tester votre contrôle dans une page sans compiler le code dans un assembly. ASP.NET compile de manière dynamique le code placé dans le répertoire App_Code sous la racine d'un site Web ASP.NET. Les classes des fichiers sources du répertoire App_Code sont ainsi accessibles depuis les pages sans être compilées dans des assemblys. Si vous placez les fichiers sources de vos contrôles dans le répertoire App_Code, les modifications que vous apportez au code des contrôles sont immédiatement répercutées dans les pages qui utilisent ces contrôles.

Remarque :

Le répertoire App_Code est une nouvelle fonctionnalité dont ne disposaient pas les versions 1.0 et 1.1 d'ASP.NET. L'utilisation du répertoire App_Code pour un premier test des contrôles est facultative. Les étapes principales de la génération d'un contrôle serveur sont les mêmes que dans les versions précédentes, comme vous le verrez dans la section suivante, « Compiler le contrôle dans un assembly ».

Pour créer le site Web ASP.NET et le répertoire App_Code

  1. Créez un site Web nommé ServerControlsTest. Vous pouvez créer le site dans IIS en tant que répertoire virtuel nommé ServerControlsTest. Pour plus d'informations sur la création et la configuration d'un répertoire virtuel IIS, consultez Comment : créer et configurer des répertoires virtuels dans IIS 5.0 et 6.0.

  2. Créez directement un répertoire App_Code sous le répertoire racine de votre site Web (également appelé racine d'application Web).

  3. Copiez le fichier source du contrôle (WelcomeLabel.cs ou WelcomeLabel.vb) dans le répertoire App_Code.

Création d'un préfixe de balise

Un préfixe de balise est le préfixe, tel que "asp" dans <asp:Table />, qui apparaît avant le nom du type d'un contrôle lorsque le contrôle est créé de façon déclarative dans une page. Pour que votre contrôle puisse être utilisé de façon déclarative dans une page, ASP.NET a besoin d'un préfixe de balise, mappé à l'espace de noms de votre contrôle. Un développeur de pages peut fournir un mappage de préfixe de balise/espace de noms en ajoutant une directive @ Register à chaque page qui utilise le contrôle personnalisé, comme dans l'exemple suivant :

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.CS.Controls"%>

[Visual Basic]

<%@ Register TagPrefix="aspSample" 
        Namespace="Samples.AspNet.VB.Controls"%>
Remarque :

La directive @ Register dans ASP.NET 2.0 est la même que dans ASP.NET 1.0 et ASP.NET 1.1. Si vous connaissiez déjà la directive Register dans les versions précédentes d'ASP.NET, vous pouvez remarquer que l'attribut assembly qui spécifie le nom de l'assembly du contrôle est absent dans la directive Register précédente. Lorsque l'attribut assembly manque, ASP.NET en déduit que l'assembly est compilé dynamiquement à partir de fichiers sources dans le répertoire App_Code.

Plutôt que d'utiliser la directive @ Register dans chaque page .aspx, le développeur de pages peut spécifier le mappage de préfixe de balise/espace de noms dans le fichier Web.config. Cela est utile si le contrôle personnalisé doit être utilisé sur plusieurs pages d'une application Web. La procédure suivante décrit comment spécifier le mappage de préfixe de balise dans le fichier Web.config.

Pour ajouter un mappage de préfixe de balise dans le fichier Web.config

  1. Créez un fichier texte nommé Web.config sous le répertoire racine de votre site Web, si un tel fichier n'existe pas déjà.

  2. Si vous avez créé un nouveau (vide) fichier Web.config, copiez-y le code suivant et enregistrez le fichier.

    <?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.CS.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

    <?xml version="1.0"?>
<configuration>
  <system.web>    
   <pages>
     <controls>
       <add tagPrefix="aspSample"            namespace="Samples.AspNet.VB.Controls">       </add>
     </controls>
   </pages>
  </system.web>
</configuration>

    La section en surbrillance montre une entrée de préfixe de balise qui mappe le préfixe de balise "aspSample" à l'espace de noms Samples.AspNet.CS.Controls ou Samples.AspNet.VB.Controls.

  3. Si un fichier Web.config existe déjà, ajoutez le texte mis en surbrillance à l'étape précédente en tant qu'enfant de l'élément controls du fichier de configuration. Si les éléments controls et pages n'existent pas dans le fichier Web.config, créez-les comme à l'étape précédente.

    Remarque :

    L'entrée de préfixe de balise doit être un enfant de la section controls, qui doit se trouver sous la section pages, laquelle doit à son tour être un enfant de system.web.

Après avoir spécifié le mappage de préfixe de balise dans le fichier de configuration, vous pouvez utiliser le contrôle WelcomeLabel de façon déclarative (sous la forme <aspSample:WelcomeLabel />) sur n'importe quelle page du site Web.

Remarque :

L'entrée de configuration pour le préfixe de balise est une nouvelle fonctionnalité d'ASP.NET 2.0. Dans ASP.NET 1.0 et 1.1, le mappage de préfixe de balise était spécifié dans la directive @ Register de chacune des pages qui utilisaient le contrôle personnalisé.

Création d'une page pour utiliser le contrôle

Pour créer une page qui utilise le contrôle personnalisé

  1. Créez un fichier texte nommé WelcomeLabelTest.aspx dans votre site Web.

  2. Copiez le balisage suivant dans le fichier WelcomeLabelTest.aspx et enregistrez le fichier.

    <%@ Page Language="VB"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

    <%@ Page Language="C#"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head id="Head1" >
    <title>WelcomeLabel Test</title>
  </head>
  <body>
    <form id="form1" >
      <div>
        <aspSample:WelcomeLabel Text="Hello" ID="WelcomeLabel1" 
           BackColor="Wheat" ForeColor="SaddleBrown" />
      </div>
    </form>
  </body>
</html>

  3. Affichez WelcomeLabelTest.aspx dans votre navigateur en saisissant l'URL suivante dans la barre d'adresses :

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

  4. Apportez quelques modifications au code source du contrôle. Par exemple, écrivez une chaîne supplémentaire en ajoutant cette ligne de code à la fin de la méthode RenderContents :

    writer.Write("Testing how the App_Code directory works.");

    writer.Write("Testing how the App_Code directory works.")

  5. Actualisez la page WelcomeLabelTest.aspx dans votre navigateur.

    Vous constaterez que les modifications apportées au contrôle se sont répercutées dans la page, bien que vous n'ayez pas compilé le contrôle.

En plus de la propriété Text du contrôle WelcomeLabel que vous avez explicitement définie, vous pouvez constater dans l'instance du contrôle dans la page que celui-ci possède des propriétés BackColor et ForeColor que vous n'avez pas définies. Le contrôle WelcomeLabel les obtient, ainsi que d'autres propriétés relatives au style, par héritage de la classe de base WebControl. WelcomeLabel peut en outre se voir assigner une apparence et faire partie d'un thème sans aucune intervention de votre part.

Compilation du contrôle dans un assembly

Bien que le répertoire App_Code vous permette de tester votre contrôle sans le compiler, si vous souhaitez le distribuer comme code objet à d'autres développeurs, vous devrez le compiler. De plus, un contrôle ne peut pas être ajouté à la boîte à outils d'un concepteur visuel s'il n'est pas compilé dans un assembly.

Pour compiler le contrôle dans un assembly

  1. Paramétrez la variable d'environnement Windows PATH de votre ordinateur de façon à ce qu'elle intègre le chemin d'accès de votre installation .NET Framework en suivant ces étapes :

    1. Dans Windows, cliquez avec le bouton droit sur Poste de travail, sélectionnez Propriétés, cliquez sur l'onglet Avancé, puis sur le bouton Variables d'environnement.

    2. Dans la liste Variables système, double-cliquez sur la variable Path.

    3. Dans la zone de texte Valeur de la variable, ajoutez un point-virgule (;) à la fin des valeurs existantes dans la zone de texte, puis saisissez le chemin d'accès de votre installation .NET Framework. Le .NET Framework est en général installé dans le répertoire d'installation de Windows à l'emplacement \Microsoft.NET\Framework\numéroVersion.

    4. Cliquez sur OK pour fermer toutes les boîtes de dialogue.

  2. Exécutez la commande suivante à partir du répertoire que vous avez créé pour les fichiers sources dans la première procédure de ce pas à pas.

    Remarque :

    Il est différent du répertoire App_Code dans lequel vous avez copié le fichier source du contrôle à des fins de test.

    		 
    csc /t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll /r:System.Web.dll *.cs

    vbc /t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll /r:System.Web.dll *.vb

    L'option /t:library du compilateur indique à ce dernier de créer une bibliothèque plutôt qu'un assembly exécutable. L'option /out fournit un nom à l'assembly et l'option /r liste les assemblys liés à votre assembly.

Pour que l'exemple reste indépendant, cette procédure pas à pas vous demande de créer un assembly avec un seul contrôle. En général, les indications de conception du .NET Framework vous recommandent de ne pas créer d'assemblys ne contenant que quelques classes. Pour faciliter le déploiement, vous devez créer aussi peu d'assemblys que possible.

Incorporation d'une icône dans l'assembly du contrôle

Un concepteur visuel tel que Visual Studio 2005 utilise en général une icône par défaut (par exemple une image d'engrenage) pour afficher un contrôle dans la boîte à outils. Vous pouvez, si vous le souhaitez, personnaliser l'apparence de votre contrôle dans la boîte à outils en incorporant une bitmap 16 x 16 pixels dans l'assembly du contrôle. Par convention, les concepteurs visuels utilisent le pixel situé tout en bas à gauche de la bitmap comme couleur transparente.

Pour incorporer une icône dans l'assembly du contrôle

  1. Créez ou récupérez une bitmap 16 x 16 pixels comme icône de votre contrôle dans la boîte à outils.

  2. Nommez la bitmap WelcomeLabel.bmp.

  3. Ajoutez le fichier bitmap au répertoire (CustomControlsCS ou CustomControlsVB) dans lequel se trouvent les fichiers sources du contrôle WelcomeLabel.

  4. Exécutez la commande suivante à partir du répertoire qui contient les fichiers sources :

    csc /res:WelcomeLabel.bmp,Samples.AspNet.CS.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll 
/r:System.Web.dll *.cs

    vbc /res:WelcomeLabel.bmp,Samples.AspNet.VB.Controls.WelcomeLabel.bmp 
/t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll 
/r:System.Web.dll *.vb

    Cette commande compile le contrôle et incorpore la bitmap à l'assembly en tant que ressource. Vous devez donner à la ressource bitmap incorporée exactement le même nom que le nom qualifié dans l'espace de noms du contrôle auquel elle est associée. Par exemple, si le nom du contrôle est Samples.AspNet.CS.Controls.WelcomeLabel, le nom de la bitmap incorporée doit être Samples.AspNet.CS.Controls.WelcomeLabel.bmp. Cette convention d'affectation de noms force un concepteur visuel à utiliser automatiquement la bitmap comme icône de votre contrôle dans la boîte à outils. Si vous n'utilisez pas la convention d'affectation de noms, vous devez appliquer le ToolboxBitmapAttribute au contrôle pour spécifier le nom de la ressource bitmap incorporée.

Utilisation de TagPrefixAttribute pour fournir un mappage de préfixe de balise/espace de noms

Nous avons vu plus tôt dans cette procédure pas à pas, lors de l'utilisation du répertoire App_Code, comment un développeur de pages peut spécifier un préfixe de balise dans la page ou dans le fichier Web.config. Vous pouvez suggérer facultativement un préfixe de balise qu'un concepteur visuel devra utiliser par défaut pour votre contrôle en incluant l'attribut System.Web.UI.TagPrefixAttribute de niveau assembly. L'attribut TagPrefixAttribute est utile parce qu'il fournit un préfixe de balise à utiliser par un concepteur visuel si celui-ci ne trouve pas de mappage de préfixe de balise dans le fichier Web.config ou dans une directive Register de la page. Le préfixe de balise est enregistré avec la page la première fois que l'on double-clique sur le contrôle dans la boîte à outils ou qu'on le fait glisser de la boîte à outils sur la page.

Si vous décidez d'utiliser l'attribut TagPrefixAttribute, vous pouvez le spécifier dans un fichier distinct compilé avec vos contrôles. Par convention, le fichier est nommé AssemblyInfo.extensionLangage, comme AssemblyInfo.cs ou AssembyInfo.vb. La procédure suivante décrit comment spécifier les métadonnées TagPrefixAttribute.

Remarque :

Si vous ne spécifiez pas TagPrefixAttribute dans l'assembly du contrôle et si le développeur de pages ne spécifie pas le mappage de préfixe de balise/espace de noms dans la page ou dans le fichier Web.config, le concepteur visuel peut créer un préfixe de balise par défaut. Par exemple, Visual Studio 2005 créera sa propre balise (telle que cc1) pour votre contrôle lorsque l'on fera glisser celui-ci depuis la boîte à outils.

Pour ajouter un mappage d'espace de noms/préfixe de balise à l'aide de TagPrefixAttribute

  1. Créez un fichier a nommé AssemblyInfo.cs ou AssemblyInfo.vb dans le répertoire de votre code source et ajoutez le code suivant au fichier.

    using System;
using System.Web.UI;
[assembly: TagPrefix("Samples.AspNet.CS.Controls", "aspSample")]

    Imports System
Imports System.Web.UI
<Assembly: TagPrefix("Samples.AspNet.VB.Controls", "aspSample")>

    L'attribut de préfixe de balise crée un mappage entre l'espace de noms Samples.AspNet.CS.Controls ou Samples.AspNet.VB.Controls et le préfixe aspSample.

  2. Recompilez tous les fichiers sources à l'aide de la commande de compilation que vous avez utilisée précédemment (avec ou sans la ressource incorporée).

Utilisation du contrôle personnalisé compilé dans une page ASP.NET

Pour tester la version compilée de votre contrôle personnalisé, vous devez rendre l'assembly de votre contrôle accessible aux pages du site Web.

Pour rendre l'assembly de votre contrôle accessible au site Web

  1. Créez un répertoire Bin sous la racine du site Web.

  2. Copiez l'assembly du contrôle (Samples.AspNet.CS.Controls.dll ou Samples.AspNet.VB.Controls.dll) dans le répertoire Bin.

  3. Supprimez le fichier source du contrôle du répertoire App_Code.

    Si vous ne supprimez pas les fichiers sources, le type de votre contrôle existera à la fois dans l'assembly compilé et dans l'assembly généré dynamiquement créé par ASP.NET. Cela créera une référence ambiguë lors du chargement du contrôle, et toutes les pages dans lesquelles le contrôle est utilisé généreront une erreur du compilateur.

L'assembly que vous avez créé dans cette procédure pas à pas est appelé assembly privé parce qu'il doit être placé dans le répertoire Bin d'un site Web ASP.NET pour permettre aux pages du site Web d'utiliser votre contrôle. L'assembly ne peut pas être accessible à d'autres applications, à moins qu'une copie ne soit également installée avec ces applications. Si vous créez des contrôles pour des applications d'hébergement Web partagées, vous les intégrerez en général à un assembly privé. Cependant, si vous créez des contrôles devant être utilisés dans un environnement d'hébergement dédié, ou une suite de contrôles qu'un FAI rend disponible à tous ses abonnés, vous risquez de devoir intégrer ces contrôles à un assembly partagé (avec nom fort), installé dans le Global Assembly Cache. Pour plus d'informations, consultez Utilisation d'assemblys et du Global Assembly Cache.

Vous devez ensuite modifier le mappage de préfixe de balise que vous avez créé dans Web.config pour spécifier le nom de l'assembly de votre contrôle.

Pour modifier le mappage de préfixe de balise dans Web.config

  • Modifiez le fichier Web.config pour ajouter un attribut assembly à un élément add tagPrefix:

    <controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.CS.Controls" 
    assembly="Samples.AspNet.CS.Controls">
  </add>
</controls>

    <controls>
  <add tagPrefix="aspSample"   
    namespace="Samples.AspNet.VB.Controls" 
    assembly="Samples.AspNet.VB.Controls">
  </add>
</controls>

L'attribut assembly spécifie le nom de l'assembly dans lequel se trouve le contrôle. Un élément addtagPrefix mappe un préfixe de balise à une combinaison d'espace de noms et d'assembly. Lorsque l'assembly est généré dynamiquement par ASP.NET à partir des fichiers sources du répertoire App_Code, l'attribut d'assembly n'est pas nécessaire. Lorsque l'attribut d'assembly n'est pas utilisé, ASP.NET charge le type du contrôle à partir des assemblys générés dynamiquement depuis le répertoire App_Code.

Pour afficher la page qui utilise le contrôle personnalisé

  • Affichez la page WelcomeLabelTest.aspx dans votre navigateur en saisissant l'URL suivante dans la barre d'adresses :

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

Si vous utilisez votre contrôle dans un concepteur visuel tel que Visual Studio 2005, vous serez en mesure de l'ajouter à la boîte à outils, de le faire glisser de la boîte à outils vers l'aire de conception et d'accéder aux propriétés et aux événements de l'Explorateur de propriétés. De plus, dans Visual Studio 2005, votre contrôle bénéficie de la prise en charge complète d'IntelliSense dans l'affichage en mode Source du concepteur de pages et dans l'éditeur de code. Cela inclut l'achèvement de l'instruction dans un bloc de script, ainsi que la prise en charge de l'Explorateur de propriétés lorsqu'un développeur de pages clique sur la balise du contrôle.

Remarque :

Dans de nombreux concepteurs visuels, vous pouvez ajouter des contrôles personnalisés à la boîte à outils du concepteur. Pour plus d'informations, consultez la documentation de votre concepteur.

Étapes suivantes

Cette procédure pas à pas vous a montré comment développer un contrôle serveur ASP.NET personnalisé simple et comment l'utiliser dans une page. Vous avez vu comment définir une propriété et comment compiler votre contrôle dans un assembly. Pour plus d'informations, notamment sur le rendu, la définition de propriétés, l'entretien de l'état et l'implémentation de contrôles composites, consultez Développement de contrôles serveur ASP.NET personnalisés.

Dans la procédure pas à pas, vous avez vu que vous pouviez fournir une icône personnalisée de votre contrôle dans la boîte à outils. Vous avez également appris comment ajouter des métadonnées au moment du design pour personnaliser la prise en charge de l'Explorateur de propriétés pour votre contrôle. Les contrôles complexes, tels que le contrôle GridView, facilitent encore leur conception à l'aide de classes de concepteurs visuels, qui fournissent une interface utilisateur différente au moment du design et au moment de l'exécution. Le modèle objet concepteur d'ASP.NET 2.0 pour les contrôles serveur est nettement différent du modèle fourni dans ASP.NET 1.0 et 1.1. Pour apprendre comment implémenter des classes de concepteur personnalisées pour vos contrôles dans ASP.NET 2.0, consultez Vue d'ensemble des Concepteurs de contrôles ASP.NET.

Dans ASP.NET 2.0, un contrôle serveur peut définir des comportements différents pour les navigateurs ou les périphériques clients en utilisant des classes d'adaptateurs. Pour plus d'informations, consultez Développement d'adaptateurs pour les contrôles serveur ASP.NET

Des navigateurs différents, et différentes versions du même navigateur, prennent en charge des fonctionnalités différentes. Les contrôles serveur ASP.NET déterminent automatiquement le navigateur qui a demandé la page .aspx et appliquent au balisage HTML généré le format correspondant à ce navigateur. Toutefois, certaines fonctionnalités des contrôles ne sont pas prises en charge par les anciens navigateurs. Il est donc recommandé de visualiser la sortie de vos pages sur le plus grand nombre de navigateurs possible pour vous assurer qu'elles s'affichent comme vous le souhaitez dans tous les navigateurs. Pour plus d'informations, consultez Fonctionnalités des contrôles serveur Web ASP.NET et du navigateur.

Voir aussi

Autres ressources

Développement de contrôles serveur ASP.NET personnalisés