@ Register

  • Artículo

[Esta documentación se proporciona solo para fines preliminares y está sujeta a cambios en versiones posteriores. Se incluye temas en blanco como marcadores].

Crea una asociación entre un prefijo de etiqueta y un control personalizado, lo que proporciona a los desarrolladores una forma concisa de hacer referencia a controles personalizados en un archivo de aplicación ASP.NET (incluidos páginas Web, controles de usuario y páginas maestras).

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

Atributos

  • assembly
    Ensamblado en el que reside el espacio de nombres asociado al atributo tagprefix.

    Nota

    El nombre del ensamblado no puede incluir una extensión de archivo.Tenga en cuenta también que si falta el atributo assembly, el analizador de ASP.NET asume que hay código fuente en la carpeta App_Code de la aplicación.Si tiene código fuente para un control que desea registrar en una página sin tener que compilarlo, coloque el código fuente en la carpeta App_Code.ASP.NET compila dinámicamente los archivos de código fuente de la carpeta App_Code en tiempo de ejecución.

  • namespace
    Espacio de nombres del control personalizado que se registra.

  • src
    Ubicación (relativa o absoluta) del archivo declarativo de ASP.NET User Controls que se asocia al par tagprefix:tagname.

  • tagname
    Alias arbitrario que se asocia a una clase. Este atributo sólo se utiliza para los controles de usuario.

  • tagprefix
    Alias arbitrario que proporciona una referencia abreviada al espacio de nombres del marcado que se utiliza en el archivo que contiene la directiva.

Comentarios

Al incluir la directiva @ Register en una página o un control de usuario, se pueden diseñar controles de servidor o controles de usuario personalizados mediante Sintaxis de controles de servidor personalizados declarativa.

Nota

También se pueden registrar los controles personalizados en todas las páginas de una aplicación utilizando el Elemento controls para pages (Esquema de configuración de ASP.NET) en el archivo Web.config.

Utilice la directiva @ Register en las siguientes situaciones:

  • Para agregar mediante declaración un control de servidor personalizado a una página Web, un control de usuario, una página maestra o un archivo de máscara (vea ASP.NET Themes Overview).

  • Para agregar mediante declaración un control de usuario a una página Web, un control de usuario, una página maestra o un archivo de máscara.

Nota

ASP.NET utiliza el valor "mobile" de tagprefix para identificar los controles Web móviles del espacio de nombres System.Web.UI.MobileControls.Debe evitar utilizar este prefijo en los controles.

Cuando se utiliza la directiva @ Register para hacer referencia a un control, se puede colocar el código del control en las siguientes ubicaciones:

  • Como código fuente en la carpeta App_Code de la aplicación, donde se compilará dinámicamente en tiempo de ejecución. Ésta es una opción útil durante el desarrollo. Si elige esta opción, no utilice el atributo assembly en la directiva @ Register.

  • Como un ensamblado compilado en la carpeta Bin de la aplicación. Ésta es una opción común para las aplicaciones Web implementadas.

  • Como un ensamblado compilado y firmado en la caché global de ensamblados (GAC). Ésta es una opción común si desea compartir un control compilado entre varias aplicaciones. Puede hacer referencia a un control en la GAC asignando una cadena de identificación al atributo assembly. La cadena especifica los detalles necesarios sobre el control, incluido su nombre de tipo completo, su versión, su token de clave pública y su referencia cultural. En la cadena ficticia siguiente se muestra una referencia a un control personalizado en la GAC:

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

    Para obtener más información sobre cómo hacer referencia a ensamblados, consulte Elemento add aplicado a assemblies para compilation (Esquema de configuración de ASP.NET).

Para los controles de usuario declarativos, utilice los atributos tagname, tagprefix y src. Los dos primeros siempre se utilizan juntos, como un par separado por dos puntos (tagprefix:tagname), al declarar el control en la página. Puede asignar varios espacios de nombres al mismo tagname, como en el ejemplo siguiente:

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

El valor del atributo src puede ser una ruta de acceso relativa o absoluta al archivo de código fuente del control de usuario partiendo del directorio raíz de la aplicación. Para facilitar su utilización, se recomienda usar una ruta relativa. Por ejemplo, suponga que almacena todos los archivos de controles de usuario de la aplicación en un directorio \Usercontrol que es un subdirectorio del directorio raíz de la aplicación. Para incluir el control de usuario encontrado en un archivo Usercontrol1.ascx, agregue lo siguiente a la directiva @ Register:

Src="~\usercontrol\usercontrol1.ascx"

El carácter de tilde (~) representa el directorio raíz de la aplicación.

Nota

Si el control de usuario se encuentra en el mismo directorio que la página que lo contiene, el valor del atributo src debería ser el nombre y la extensión del archivo .ascx.

Al incluir controles de servidor personalizados que se han compilado en un archivo .dll para utilizarlos con la aplicación, utilice el atributo tagprefix con los atributos assembly y namespace. Si no incluye el atributo namespace o si le asigna una cadena vacía (""), se producirá un error en el analizador.

Advertencia

Al desarrollar un control de servidor personalizado, es preciso incluirlo en un espacio de nombres.En caso contrario, no será accesible desde una página ASP.NET.Para obtener más información sobre cómo desarrollar controles de servidor ASP.NET personalizados, vea Developing Custom ASP.NET Server Controls.

Ejemplo

En el ejemplo de código siguiente se utilizan directivas @ Register para declarar los alias tagprefix y tagname, y se asigna un atributo src, para hacer referencia a un control de usuario en una página Web. La primera parte del código es un control de usuario simple que se compone de un control ASP.NET Calendar. La segunda parte del código es una página que hospeda el control. Observe que el atributo tagprefix asigna un valor de prefijo arbitrario que se utiliza con la etiqueta. El atributo tagname usa el valor del nombre de clase asignado al control de usuario (aunque el valor de este atributo es arbitrario y se puede utilizar cualquier valor de cadena, por lo que no es necesario utilizar el nombre de clase del control al que se hace referencia). El atributo src señala al archivo de código fuente del control de usuario, tomando como referencia la carpeta raíz de la aplicación. Para hacer referencia al control de usuario dentro del cuerpo de la página se utiliza el prefijo, dos puntos y el nombre de la etiqueta, con este formato: <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>

Vea también

Referencia

Sintaxis de directivas de plantilla de texto

Conceptos

ASP.NET Web Page Syntax Overview

Otros recursos

ASP.NET User Controls