Partager via

@ Register

  • Article

Mise à jour : novembre 2007

Crée une association entre un préfixe de balise et un contrôle personnalisé et offre aux développeurs la possibilité de référencer de façon concise les contrôles personnalisés dans un fichier d'application ASP.NET (y compris les pages Web, les contrôles utilisateur et les pages maîtres).

<%@ Register tagprefix="tagprefix"
   namespace="namespace"
   assembly="assembly" %>
<%@ Register tagprefix="tagprefix"
   namespace="namespace" %>
<%@ Register tagprefix="tagprefix"
   tagname="tagname"
   src="pathname" %>

Attributs

  • assembly
    Assembly dans lequel l'espace de noms associé à l'attribut tagprefix réside.

    Remarque :

    Le nom de l'assembly ne peut pas inclure d'extension de fichier. Notez également que, si l'attribut assembly est manquant, l'analyseur ASP.NET suppose qu'il existe un code source dans le dossier App_Code de l'application. Si vous disposez d'un code source pour un contrôle que vous souhaitez enregistrer sur une page sans devoir le compiler, placez le code source dans le dossier App_Code. ASP.NET compile dynamiquement les fichiers sources dans le dossier App_Code au moment de l'exécution.

  • namespace
    Espace de noms du contrôle personnalisé qui est inscrit.

  • src
    Emplacement (relatif ou absolu) du fichier Contrôles utilisateur ASP.NET déclaratif à associer à la paire tagprefix:tagname.

  • tagname
    Alias arbitraire à associer à une classe. Cet attribut est utilisé uniquement pour les contrôles utilisateur.

  • tagprefix
    Alias arbitraire qui fournit une référence abrégée à l'espace de noms de la balise utilisée dans le fichier contenant la directive.

Notes

En incluant la directive @ Register dans une page ou un contrôle utilisateur, vous pouvez exposer des contrôles utilisateur ou des contrôles serveur personnalisés à l'aide de la Syntaxe de contrôle serveur personnalisé déclarative.

Remarque :

Vous pouvez également inscrire des contrôles personnalisés sur toutes les pages d'une application en utilisant l'élément controls, élément de pages (Schéma des paramètres ASP.NET) dans le fichier Web.config.

Utilisez la directive @ Register dans les situations suivantes :

  • Pour ajouter de façon déclarative un contrôle serveur personnalisé à une page Web, à un contrôle utilisateur, à une page maître ou à un fichier d'apparence (consultez Vue d'ensemble des thèmes et des apparences ASP.NET).

  • Pour ajouter de façon déclarative un contrôle utilisateur à une page Web, à un contrôle utilisateur, à une page maître ou à un fichier d'apparence.

Remarque :

La valeur tagprefix "mobile" est utilisée par ASP.NET pour identifier les contrôles Web mobiles dans l'espace de noms System.Web.UI.MobileControls. Vous devez éviter d'utiliser ce préfixe pour vos contrôles.

Lorsque vous utilisez la directive @ Register pour référencer un contrôle, vous pouvez placer le code pour le contrôle aux emplacements suivants :

  • Comme code source dans le dossier App_Code de l'application, où il sera compilé dynamiquement au moment de l'exécution. Il s'agit d'une option commode pendant le développement. Si vous choisissez cette option, vous n'utilisez pas l'attribut assembly dans la directive @ Register.

  • Comme assembly compilé dans le dossier Bin de l'application. Il s'agit d'une option courante pour les applications Web déployées.

  • Comme assembly compilé et signé dans le Global Assembly Cache (GAC). Il s'agit d'une option courante si vous souhaitez partager un contrôle compilé parmi plusieurs applications. Vous pouvez référencer un contrôle dans le GAC en assignant une chaîne d'identification à l'attribut assembly. La chaîne spécifie les détails requis sur le contrôle, y compris son nom de type qualifié complet, sa version, son jeton de clé publique et sa culture. La chaîne fictive suivante illustre une référence à un contrôle personnalisé dans le GAC :

    <%@ Register  tagprefix="custom"
     namespace="Mycompany.namespace"
     assembly="Mycompany.namespace.control, Version=1.2.3.4, 
        PublicKeyToken=12345678abcdefgh, Culture=neutral"  %>

    Pour plus d'informations sur la référence à des assemblys, consultez add, élément de assemblies pour compilation (Schéma des paramètres ASP.NET).

Pour les contrôles utilisateur déclaratifs, utilisez les attributs tagname, tagprefixet src. Les deux premiers sont toujours utilisés ensemble sous la forme d'une paire séparée par deux-points (tagprefix:tagname) lorsque vous déclarez le contrôle dans la page. Vous pouvez mapper plusieurs espaces de noms au même tagname, comme dans l'exemple suivant :

<% @Register tagprefix="tag1" namespace="MyNamespace1"/>
<% @Register tagprefix="tag1" namespace="MyNamespace2"/>

La valeur de l'attribut src peut être un chemin d'accès, soit relatif, soit absolu, au fichier source du contrôle utilisateur à partir du répertoire racine de votre application. Pour une utilisation simplifiée, il est recommandé d'utiliser le chemin d'accès relatif. Par exemple, supposons que vous stockez tous les fichiers de contrôle utilisateur de votre application dans un répertoire \Usercontrol qui constitue un sous-répertoire de votre racine d'application. Pour inclure le contrôle utilisateur trouvé dans un fichier Usercontrol1.ascx, incluez les informations suivantes dans la directive @ Register :

Src="~\usercontrol\usercontrol1.ascx"

Le tilde (~) représente le répertoire racine de l'application.

Remarque :

Si votre contrôle utilisateur est dans le même répertoire que la page qui le contient, la valeur de l'attribut src doit être le nom et l'extension du fichier .ascx.

Lorsque vous incluez les contrôles serveur personnalisés que vous avez compilés dans un fichier .DLL afin de les utiliser avec votre application, utilisez l'attribut tagprefix avec les attributs assembly et namespace. Si vous n'incluez pas l'attribut namespace ou si vous lui assignez une chaîne vide (""), une erreur d'analyse se produit.

Attention :

Lorsque vous développez un contrôle serveur personnalisé, vous devez l'inclure dans un espace de noms. Si vous ne le faites pas, il ne sera pas accessible à partir d'une page ASP.NET. Pour plus d'informations sur le développement de contrôles serveur ASP.NET personnalisés, consultez Développement de contrôles serveur ASP.NET personnalisés.

Exemple

L'exemple de code suivant utilise des directives @ Register pour déclarer des alias tagprefix et tagname et assigne un attribut src, pour référencer un contrôle utilisateur dans une page Web. La première partie du code est un contrôle utilisateur simple constitué d'un contrôle ASP.NET Calendar. La deuxième partie du code est une page qui héberge le contrôle. Notez que l'attribut tagprefix assigne une valeur de préfixe arbitraire à utiliser avec la balise. L'attribut tagname utilise la valeur du nom de classe assigné au contrôle utilisateur. Notez que la valeur de cet attribut est arbitraire et qu'il est possible d'utiliser n'importe quelle valeur de chaîne ; vous ne devez pas nécessairement utiliser le nom de classe du contrôle référencé). L'attribut src pointe vers le fichier source du contrôle utilisateur, relatif par rapport au dossier racine de l'application. Le contrôle utilisateur est référencé dans le corps de la page en utilisant le préfixe, les deux-points et le nom de la balise, sous la forme suivante : <uc1:CalendarUserControl runat="server" />.

<%@ Control ClassName="CalendarUserControl" %>
<asp:calendar id="Calendar1" runat="server" />


<%@ Page %>
<%@ register tagprefix="uc1" 
    tagname="CalendarUserControl" 
    src="~/CalendarUserControl.ascx" %>

<!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 runat="server">
    <title>Calendar Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <uc1:calendarusercontrol runat="server" />
  </form>
</body>
</html>

Voir aussi

Concepts

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

Référence

Syntaxe de directive

Autres ressources

Contrôles utilisateur ASP.NET