@ Register

[Cette documentation constitue un aperçu et pourra faire l'objet de modifications dans les versions ultérieures. Des rubriques vierges sont incluses en tant qu'espaces réservés.]

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.

  Notes

  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 ASP.NET User Controls 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.

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 ASP.NET Themes Overview).

• 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.

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.

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.

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

Référence

Syntaxe des directives de modèles de texte

Concepts

ASP.NET Web Page Syntax Overview

Autres ressources

ASP.NET User Controls