Tutorial: Desarrollar y utilizar un control de servidor personalizado

  • Artículo

Actualización: noviembre 2007

Este tutorial muestra cómo crear y compilar un control de servidor ASP.NET personalizado y utilizarlo en una página.

Durante este tutorial aprenderá a:

  • Crear un control de servidor ASP.NET.

  • Agregar metadatos al control y sus miembros para controlar la seguridad y el comportamiento en tiempo de diseño.

  • Utilizar el directorio App_Code en un sitio Web ASP.NET para probar el control sin necesidad de pasos de compilación manuales.

  • Especificar un prefijo de etiqueta en un archivo de configuración y en el ensamblado del control.

  • Compilar el control en un ensamblado y agregarlo al directorio Bin.

  • Incrustar un mapa de bits en el ensamblado del control como icono del cuadro de herramientas para un diseñador visual.

  • Utilizar el control compilado en una página.

Aunque las herramientas de diseño visual como Microsoft Visual Studio 2005 simplifican el desarrollo de controles, no son imprescindibles para la creación o generación de controles personalizados. Los controles pueden crearse con cualquier editor de texto y generarse desde la línea de comandos mediante los compiladores que forman parte de Kit de desarrollo de software de Windows (SDK). Independientemente del método empleado para crear el control, su aspecto y su comportamiento en tiempo de diseño en un diseñador visual serán los mismos. Los desarrolladores de páginas podrán agregar el control al cuadro de herramientas del diseñador visual, arrastrarlo a la superficie de diseño y tener acceso a sus propiedades y eventos en el explorador de propiedades. En algunos diseñadores visuales como Visual Studio 2005, los controles personalizados también admiten IntelliSense sin que sea necesario realizar ninguna operación adicional.

Crear el control de servidor

El control que va a crear, WelcomeLabel, es un control simple similar al control Label estándar. La clase WelcomeLabel se deriva de WebControl y define una propiedad Text que permite al desarrollador de páginas proporcionar una cadena de texto para dar la bienvenida a los usuarios de un sitio. WelcomeLabel agrega el nombre del usuario a la cadena de texto si dicho nombre está presente en el encabezado enviado por el explorador del usuario. Para obtener más información sobre cómo recuperar el nombre del usuario, vea User. Por ejemplo, si el desarrollador de páginas establece "Hola" como valor de la propiedad Text, WelcomeLabel representará "¡Hola, nombreDeUsuario!" u "¡Hola!" en función de si el nombre de usuario está presente en el encabezado.

Para crear el código del control de servidor personalizado

  1. Cree un archivo denominado WelcomeLabel.cs o WelcomeLabel.vb.

  2. Agregue el código siguiente al archivo de código fuente del control:

    ' 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("!");
        }
    }
}

Descripción del código

La descripción del código que sigue no es imprescindible para seguir los pasos de este tutorial y puede pasarse por alto inicialmente. No obstante, si carece de experiencia en la creación de controles, se recomienda que al menos la lea tras finalizar el tutorial.

Si el control representa un elemento de interfaz de usuario o cualquier otro elemento visible en el cliente, debe derivar el control de System.Web.UI.WebControls.WebControl (o una clase derivada). Si el control representa un elemento que no está visible en el explorador del cliente, como un elemento oculto o un elemento meta, derive el control de System.Web.UI.Control. La clase WebControl se deriva de Control y agrega propiedades relacionadas con el estilo como Font, ForeColor y BackColor. Por otra parte, los controles que se derivan de WebControl participan de las mismas características de temas de ASP.NET sin que sea necesario realizar ninguna operación adicional.

Si un control extiende la funcionalidad de otro control existente, como Button, Label o Image, puede derivarlo de ese control. Dado que WelcomeLabel extiende la funcionalidad del control Label, podría derivarse de Label. Sin embargo, este tutorial deriva WelcomeLabel de WebControl para mostrar cómo se debe definir una propiedad y los metadatos de las propiedades.

WelcomeLabel define una propiedad, Text, y utiliza el estado de vista para almacenar el valor de dicha propiedad. Al utilizar el estado de vista se conserva el valor de Text en las distintas devoluciones de datos. En cada devolución de datos, se vuelve a crear la página y los valores se restauran desde el estado de vista. Si el valor de Text no se almacenara en el estado de vista, el valor se establecería en su valor predeterminado, Empty, en cada devolución de datos. La propiedad ViewState heredada de WebControl es un diccionario en el que se guardan los valores de datos. Los valores se escriben y se recuperan utilizando una clave String. En este caso, se utiliza "Text" como clave. Los elementos del diccionario son de tipo Object y deberá convertirlos al tipo de la propiedad. Para obtener más información, vea Información general sobre la administración de estados de ASP.NET.

El control WelcomeLabel representa su propiedad Text reemplazando el método RenderContents heredado. El parámetro pasado al método RenderContents es un objeto del tipo HtmlTextWriter, que es una clase de utilidad que tiene métodos para representar etiquetas y otros formatos HTML (así como de las variantes de HTML).

Tenga en cuenta que WelcomeLabel realiza llamadas sucesivas al método Write del objeto HtmlTextWriter en lugar de realizar una concatenación de cadenas y, a continuación, invocar al método Write. Esto mejora el rendimiento debido a que el objeto HtmlTextWriter escribe directamente en la secuencia de salida. La concatenación de cadenas requiere tiempo y memoria para crear la cadena y, a continuación, escribe en la secuencia. Cuando implemente la representación en los controles, deberá seguir el modelo mostrado en este tutorial.

Nota:

En general, cuando el control se deriva de WebControl y representa un solo elemento, debe reemplazar el método RenderContents (no el método Render) para representar el contenido de las etiquetas del control. El método Render de WebControl invoca al método RenderContents después de representar la etiqueta de apertura del control y sus atributos de estilo. Si reemplaza el método Render para escribir el contenido, el control perderá la lógica de representación de estilos integrada en el método Render de WebControl. Para obtener más información sobre la representación de controles que se derivan de WebControl, vea Ejemplo de representación de controles Web.

Los atributos aplicados a WelcomeLabel contienen metadatos utilizados por Common Language Runtime y por las herramientas en tiempo de diseño.

En el nivel de clase, WelcomeLabel se marca con los atributos siguientes:

  • AspNetHostingPermissionAttribute es un atributo de seguridad de acceso a código. Hace que el compilador JIT compruebe que al código vinculado a WelcomeLabel se le ha concedido el permiso AspNetHostingPermission. Todas las clases de ASP.NET públicas se marcan con este atributo. Debe aplicar AspNetHostingPermissionAttribute a los controles como medida de seguridad frente a los llamadores de confianza parcial.

  • DefaultPropertyAttribute es un atributo en tiempo de diseño que especifica la propiedad predeterminada de un control. En los diseñadores visuales, el explorador de propiedades generalmente resalta la propiedad predeterminada cuando el desarrollador de páginas hace clic en el control en la superficie de diseño.

  • ToolboxDataAttribute especifica la cadena de formato del elemento. La cadena se convierte en el formato del control cuando se hace doble clic en el control en el cuadro de herramientas o cuando el control se arrastra del cuadro de herramientas a la superficie de diseño. En el caso de WelcomeLabel, la cadena crea este elemento:

    <aspSample:WelcomeLabel > </aspSample:WelcomeLabel>

El control WelcomeLabel también hereda dos atributos de la clase base WebControl: ParseChildrenAttribute y PersistChildrenAttribute. Se aplican como ParseChildren(true) y PersistChildren(false). Estos dos atributos funcionan juntos y con el atributo ToolboxDataAttribute a fin de que los elementos secundarios se interpreten como propiedades y las propiedades se conserven como atributos.

Los atributos siguientes aplicados a la propiedad Text de WelcomeLabel son atributos estándar en tiempo de diseño que se aplican generalmente a todas las propiedades públicas de los controles:

  • BindableAttribute, especificado como true o false, indica a los diseñadores visuales si tiene sentido enlazar la propiedad a datos. Por ejemplo, en Visual Studio 2005, si una propiedad se marca con Bindable(true), esta se mostrará en el cuadro de diálogo DataBindings. Si la propiedad no se marca con este atributo, el explorador de propiedades deduce que el valor es Bindable(false).

  • CategoryAttribute especifica en qué categoría se debe situar la propiedad en el explorador de propiedades del diseñador visual. Por ejemplo, Category("Appearance") indica al explorador de propiedades que muestre la propiedad en la categoría Apariencia cuando el desarrollador de páginas utilice la vista por categorías del explorador de propiedades. Puede especificar un argumento de cadena correspondiente a una categoría existente en el explorador de propiedades o crear una categoría propia.

  • DescriptionAttribute especifica una breve descripción de la propiedad. En Visual Studio 2005, el explorador de propiedades muestra la descripción de la propiedad seleccionada en la parte inferior de la ventana Propiedades.

  • DefaultValueAttribute especifica un valor predeterminado para la propiedad. Este valor debe ser idéntico al valor predeterminado que se devuelve desde el descriptor de acceso de la propiedad (captador). En Visual Studio 2005, DefaultValueAttribute permite al desarrollador de páginas restablecer el valor de una propiedad a su valor predeterminado si se abre el menú de acceso directo en la ventana Propiedades y se hace clic en el botón Restablecer.

  • LocalizableAttribute, especificado como true o false, indica a los diseñadores visuales si tiene sentido traducir la propiedad. Cuando una propiedad se marca con Localizable(true), el diseñador visual la incluye cuando se serializan los recursos traducibles. El diseñador conservará el valor de la propiedad en el archivo de recursos de referencia cultural neutra u otro origen de localización cuando el control se sondee para buscar propiedades localizables.

    Nota:

    En las versiones 1.0 y 1.1 de ASP.NET, LocalizableAttribute no se podía aplicar a los controles de servidor personalizados ya que el modelo de localización de ASP.NET era distinto en dichas versiones.

Los atributos en tiempo de diseño aplicados a un control y sus miembros no afectan al funcionamiento del control en tiempo de ejecución, pero mejoran la experiencia del desarrollador cuando el control se utiliza en un diseñador visual. Puede ver una lista completa de los atributos en tiempo de diseño, tiempo de análisis y tiempo de ejecución para los controles de servidor en Atributos de metadatos para controles de servidor personalizados.

Utilizar el directorio App_Code para probar los controles sin compilación

Puede utilizar la característica de compilación dinámica de ASP.NET para probar el control en una página sin compilarlo en un ensamblado. ASP.NET compila dinámicamente el código colocado en el directorio App_Code bajo la raíz de un sitio Web ASP.NET. De este modo, es posible obtener acceso a las clases de los archivos de código fuente de este directorio desde las páginas sin necesidad de compilarlas manualmente en ensamblados. Si coloca los archivos de código fuente para los controles en el directorio App_Code, los cambios que realice en el código de los controles se reflejarán de forma inmediata en las páginas que utilizan dichos controles.

Nota:

El directorio App_Code es una nueva característica que no estaba disponible en ASP.NET 1.0 y 1.1. El uso del directorio App_Code para las pruebas iniciales del control es opcional. Los pasos principales para generar un control de servidor son los mismos que en las versiones anteriores, como verá en la sección siguiente, "Compilar el control en un ensamblado".

Para crear el sitio Web ASP.NET y el directorio App_Code

  1. Cree un sitio Web denominado ServerControlsTest. Puede crear el sitio en IIS como un directorio virtual denominado ServerControlsTest. Para obtener más información sobre la creación y configuración de un directorio virtual de IIS, vea Cómo: Crear y configurar directorios virtuales en IIS 5.0 y 6.0.

  2. Cree un directorio App_Code directamente bajo el directorio raíz del sitio Web (también denominado raíz de la aplicación Web).

  3. Copie el archivo de código fuente del control (WelcomeLabel.cs o WelcomeLabel.vb) en el directorio App_Code.

Crear un prefijo de etiqueta

Un prefijo de etiqueta es el prefijo, como "asp" en <asp:Table />, que aparece antes del nombre de tipo del control cuando éste se crea mediante declaración en una página. Para habilitar el control a fin de que pueda utilizarse mediante declaración en una página, ASP.NET necesita que se asigne un prefijo de etiqueta al espacio de nombres del control. El desarrollador de páginas puede proporcionar una asignación de prefijo de etiqueta y espacio de nombres agregando una directiva @ Register en cada página que utiliza el control personalizado, como en el ejemplo siguiente:

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

[Visual Basic]

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

La directiva @ Register de ASP.NET 2.0 es la misma que en ASP.NET 1.0 y ASP.NET 1.1. Si está familiarizado con la directiva Register de versiones anteriores de ASP.NET, podrá observar que el atributo assembly que especifica el nombre de ensamblado del control no aparece en la directiva Register anterior. Cuando falta el atributo assembly, ASP.NET deduce que el ensamblado se ha compilado dinámicamente a partir de los archivos de código fuente del directorio App_Code.

Como alternativa al uso de la directiva @ Register en cada página .aspx, el desarrollador de páginas puede especificar la asignación de prefijo de etiqueta y espacio de nombres en el archivo Web.config. Esto resulta útil si el control personalizado se utiliza en varias páginas de la aplicación Web. En el procedimiento siguiente se describe cómo especificar la asignación del prefijo de etiqueta en el archivo Web.config.

Para agregar una asignación de prefijo de etiqueta al archivo Web.config

  1. Cree un archivo de texto denominado Web.config bajo el directorio raíz del sitio Web si dicho archivo no existe todavía.

  2. Si ha creado un archivo Web.config nuevo (vacío), copie el código siguiente en él y guarde el archivo.

    <?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 sección resaltada muestra una entrada de prefijo de etiqueta que asigna el prefijo "aspSample" al espacio de nombres Samples.AspNet.CS.Controls o Samples.AspNet.VB.Controls.

  3. Si ya existe el archivo Web.config, agregue el texto resaltado del paso anterior como elemento secundario del elemento controls del archivo de configuración. Si el archivo Web.config no contiene los elementos controls y pages, créelos tal como se muestra en el paso anterior.

    Nota:

    El prefijo de etiqueta debe ser un elemento secundario de la sección controls, que debe estar bajo la sección pages, que a su vez debe ser un elemento secundario de system.web.

Tras haber especificado la asignación del prefijo de etiqueta en el archivo de configuración, puede utilizar el control WelcomeLabel mediante declaración (como <aspSample:WelcomeLabel />) en cualquier página del sitio Web.

Nota:

La entrada de configuración para el prefijo de etiqueta es una característica nueva de ASP.NET 2.0. En ASP.NET 1.0 y 1.1 la asignación del prefijo de etiqueta se especificaba en la directiva @ Register de cada página que utilizaba el control personalizado.

Crear una página para utilizar el control

Para crear una página que utilice el control personalizado

  1. Cree un archivo de texto denominado WelcomeLabelTest.aspx en el sitio Web.

  2. Copie el formato siguiente en el archivo WelcomeLabelTest.aspx y guarde el archivo.

    <%@ 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. Visualice el archivo WelcomeLabelTest.aspx en el explorador escribiendo la dirección URL siguiente en la barra de direcciones:

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

  4. Realice algún cambio en el código fuente del control. Por ejemplo, escriba una cadena adicional agregando esta línea de código al final del método RenderContents:

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

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

  5. Actualice la página WelcomeLabelTest.aspx en el explorador.

    Verá que los cambios realizados en el control se reflejan en la página aunque no haya compilado el control.

Además de la propiedad Text del control WelcomeLabel que ha definido de forma explícita, puede ver que la instancia del control de la página tiene las propiedades BackColor y ForeColor que no ha definido. El control WelcomeLabel obtiene estas y otras propiedades relacionadas con el estilo heredándolas de la clase base WebControl. Por otra parte, al control WelcomeLabel se le puede asignar una máscara y puede formar parte de un tema sin que sea necesario realizar ninguna operación adicional.

Compilar el control en un ensamblado

Aunque el directorio App_Code permite probar el control sin compilarlo, si desea distribuirlo a otros desarrolladores como código de objeto, debe compilarlo. Por otra parte, el control no se puede agregar al cuadro de herramientas del diseñador visual a menos que se compile en un ensamblado.

Para compilar el control en un ensamblado

  1. Establezca la variable PATH del entorno de Windows del equipo para que incluya la ruta de acceso a la instalación de .NET Framework siguiendo estos pasos:

    1. En Windows, haga clic con el botón secundario del mouse en Mi PC, seleccione Propiedades, haga clic en la ficha Avanzadas y, a continuación, en el botón Variables de entorno.

    2. En la lista Variables del sistema, haga doble clic en la variable Path.

    3. En el cuadro de texto Valor de variable, agregue un punto y coma (;) al final de los valores existentes en el cuadro de texto y, a continuación, escriba la ruta de acceso a su instalación de .NET Framework. Generalmente, .NET Framework está instalado en el directorio de instalación de Windows, en \Microsoft.NET\Framework\númeroDeVersión.

    4. Haga clic en Aceptar para cerrar todos los cuadros de diálogo.

  2. Ejecute el comando siguiente desde el directorio que ha creado para los archivos de código fuente en el primer procedimiento de este tutorial.

    Nota:

    Éste es diferente del directorio App_Code en el que ha copiado el archivo de código fuente del control para probarlo.

    		 
    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

    La opción del compilador /t:library indica al compilador que debe crear una biblioteca en lugar de un ensamblado ejecutable. La opción /out proporciona un nombre para el ensamblado y la opción /r muestra los ensamblados que están vinculados al ensamblado.

Para mantener el ejemplo independiente, este tutorial le pide que cree un ensamblado con un solo control. En general, las directrices de diseño de .NET Framework le recomiendan que no cree ensamblados que contengan sólo unas cuantas clases. Para facilitar la implementación, debe crear el menor número de ensamblados posible.

Incrustar un icono en el ensamblado del control

Generalmente, los diseñadores visuales como Visual Studio 2005 usan un icono predeterminado (como la imagen de un engranaje) para mostrar un control en el cuadro de herramientas. Como opción para el control, puede personalizar su aspecto en el cuadro de herramientas incrustando un mapa de bits de 16 por 16 píxeles en el ensamblado del control. Por convención, los diseñadores visuales utilizan el píxel situado más abajo en la parte izquierda del mapa de bits como color transparente.

Para incrustar un icono en el ensamblado del control

  1. Cree u obtenga un mapa de bits de 16 por 16 píxeles como icono del cuadro de herramientas para el control.

  2. Asigne el nombre WelcomeLabel.bmp al mapa de bits.

  3. Agregue el archivo de mapa de bits al directorio (CustomControlsCS o CustomControlsVB) en el que ha guardado los archivos de código fuente del control WelcomeLabel.

  4. Ejecute el comando siguiente desde el directorio que contiene los archivos de código fuente:

    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

    Este comando compila el control e incrusta el mapa de bits en el ensamblado como recurso. El nombre asignado al recurso de mapa de bits incrustado debe coincidir exactamente con el nombre completo del espacio de nombres del control con el que está asociado. Por ejemplo, si el nombre del control es Samples.AspNet.CS.Controls.WelcomeLabel, el nombre del mapa de bits incrustado debe ser Samples.AspNet.CS.Controls.WelcomeLabel.bmp. Esta convención de nomenclatura hace que el diseñador visual utilice automáticamente el mapa de bits como icono del cuadro de herramientas del control. Si no utiliza la convención de nomenclatura, debe aplicar ToolboxBitmapAttribute al control para especificar el nombre del recurso de mapa de bits incrustado.

Utilizar TagPrefixAttribute para proporcionar una asignación de prefijo de etiqueta y espacio de nombres

Anteriormente en este tutorial, al utilizar el directorio App_Code, se ha visto que el desarrollador de páginas puede especificar un prefijo de etiqueta en la página o en el archivo Web.config. Opcionalmente también puede sugerir el prefijo de etiqueta predeterminado que el diseñador visual deba utilizar para el control, incluyendo el atributo System.Web.UI.TagPrefixAttribute del nivel de ensamblado. El atributo TagPrefixAttribute es útil porque proporciona un prefijo de etiqueta para que el diseñador visual pueda utilizarlo si no encuentra una asignación de prefijo de etiqueta en el archivo Web.config o en una directiva Register de la página. El prefijo de etiqueta se registra con la página la primera vez que se hace doble clic en el control en el cuadro de herramientas o cuando el control se arrastra del cuadro de herramientas a la página.

Si decide usar el atributo TagPrefixAttribute, puede especificarlo en un archivo independiente que se compila con los controles. Por convención, el archivo se denomina AssemblyInfo.extensiónDeIdioma, como AssemblyInfo.cs o AssemblyInfo.vb. En el procedimiento siguiente se describe cómo especificar los metadatos de TagPrefixAttribute.

Nota:

Si no especifica el atributo TagPrefixAttribute en el ensamblado del control y el desarrollador de páginas no especifica la asignación de prefijo de etiqueta y espacio de nombres en la página o en el archivo Web.config, el diseñador visual podría crear un prefijo de etiqueta predeterminado. Por ejemplo, Visual Studio 2005 creará su propia etiqueta (como cc1) para el control cuando éste se arrastre desde el cuadro de herramientas.

Para agregar una asignación de espacio de nombres y prefijo de etiqueta mediante TagPrefixAttribute

  1. Cree un archivo denominado AssemblyInfo.cs o AssemblyInfo.vb en el directorio del código fuente y agregue el código siguiente al archivo.

    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")>

    El atributo de prefijo de etiqueta crea una asignación entre el espacio de nombres Samples.AspNet.CS.Controls o Samples.AspNet.VB.Controls y el prefijo aspSample.

  2. Vuelva a compilar todos los archivos de código fuente utilizando el comando de compilación que empleó anteriormente (con o sin el recurso incrustado).

Utilizar el control personalizado compilado en una página ASP.NET

Para probar la versión compilada del control personalizado es necesario que las páginas del sitio Web puedan tener acceso al ensamblado del control.

Para hacer que el sitio Web tenga acceso al ensamblado del control

  1. Cree un directorio Bin bajo la raíz del sitio Web.

  2. Copie el ensamblado del control (Samples.AspNet.CS.Controls.dll o Samples.AspNet.VB.Controls.dll) en el directorio Bin.

  3. Elimine el archivo de código fuente del control del directorio App_Code.

    Si no elimina los archivos de código fuente, el tipo del control existirá tanto en el ensamblado compilado como en el ensamblado generado dinámicamente creado por ASP.NET. Esto creará una referencia ambigua al cargar el control y las páginas en las que se utilice dicho control producirán un error de compilador.

El ensamblado que ha creado en este tutorial se denomina ensamblado privado porque debe estar colocado en un directorio Bin del sitio Web ASP.NET para permitir que las páginas del sitio utilicen el control. No es posible tener acceso al ensamblado desde otras aplicaciones a menos que también se instale una copia con dichas aplicaciones. Si crea controles para aplicaciones de hospedaje Web compartidas, normalmente los empaquetará en un ensamblado privado. No obstante, si crea controles para su uso en un entorno de hospedaje dedicado o crea un conjunto de controles que un ISP pone a disposición de todos sus clientes, podría necesitar empaquetar los controles en un ensamblado compartido (con nombre seguro) que esté instalado en la Caché de ensamblados global. Para obtener más información, vea Trabajar con ensamblados y la memoria Caché de ensamblados global.

A continuación, debe modificar la asignación del prefijo de etiqueta que ha creado en Web.config para especificar el nombre de ensamblado del control.

Para modificar la asignación del prefijo de etiqueta de Web.config

  • Edite el archivo Web.config para agregar un atributo assembly al elemento addtagPrefix:

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

El atributo assembly especifica el nombre del ensamblado en el que está el control. El elemento addtagPrefix asigna un prefijo de etiqueta a una combinación de espacio de nombres y ensamblado. Cuando ASP.NET genera dinámicamente el ensamblado a partir de los archivos de código fuente del directorio App_Code, el atributo assembly no es necesario. Cuando no se utiliza el atributo assembly, ASP.NET carga el tipo del control de los ensamblados generados dinámicamente desde el directorio App_Code.

Para ver la página que utiliza el control personalizado

  • Visualice la página WelcomeLabelTest.aspx en el explorador escribiendo la dirección URL siguiente en la barra de direcciones:

    https://localhost/ServerControlsTest/WelcomeLabelTest.aspx

Si utiliza el control en un diseñador visual como Visual Studio 2005, podrá agregar el control al cuadro de herramientas, arrastrarlo del cuadro de herramientas a la superficie de diseño y tener acceso a sus propiedades y eventos en el explorador de propiedades. Además, en Visual Studio 2005, el control es totalmente compatible con IntelliSense en la vista de código fuente del diseñador de páginas y en el editor de código. Esto incluye la finalización de instrucciones en un bloque script así como la compatibilidad con el explorador de propiedades cuando el desarrollador de páginas hace clic en la etiqueta del control.

Nota:

En muchos diseñadores visuales, es posible agregar controles personalizados al cuadro de herramientas del diseñador. Para obtener información detallada, consulte la documentación del diseñador.

Pasos siguientes

En este tutorial se ha mostrado cómo desarrollar un sencillo control de servidor ASP.NET personalizado y cómo utilizarlo en una página. Ha visto cómo definir una propiedad y cómo compilar el control en un ensamblado. Para obtener más información, incluida información sobre la representación, la definición de propiedades, el mantenimiento del estado y la implementación de controles compuestos, vea Desarrollar controles de servidor ASP.NET personalizados.

En el tutorial, ha visto que puede proporcionar un icono personalizado del cuadro de herramientas para el control. También ha aprendido a agregar metadatos en tiempo de diseño a fin de personalizar la compatibilidad con el explorador de propiedades para el control. Los controles complejos como el control GridView mejoran aún más su experiencia en tiempo de diseño si se utilizan clases de diseñador visual que proporcionan una interfaz de usuario diferente en tiempo de diseño y en tiempo de ejecución. El modelo de objetos del diseñador de ASP.NET 2.0 para los controles de servidor es bastante diferente del modelo proporcionado en ASP.NET 1.0 y 1.1. Para obtener información sobre la implementación de las clases de diseñador personalizadas para los controles en ASP.NET 2.0, vea Información general sobre los diseñadores de controles ASP.NET.

En ASP.NET 2.0, un control de servidor puede definir comportamientos diferentes para los exploradores o los dispositivos de cliente si se utilizan clases de adaptador. Para obtener más información, vea Desarrollar adaptadores para controles de servidor ASP.NET

La compatibilidad con las distintas características varía según el explorador que se utilice y según la versión del mismo. Los controles de servidor ASP.NET determinarán de forma automática el explorador que ha solicitado la página .aspx y asignarán el formato HTML que se genera correctamente para él. No obstante, algunas características del control podrían no representarse en los exploradores más antiguos, por lo que es conveniente examinar el resultado de las páginas en el mayor número posible de exploradores para asegurarse de que éstas se presentan en todos los exploradores en la forma ideada. Para obtener más información, vea Controles de servidor Web ASP.NET y funciones del explorador.

Vea también

Otros recursos

Desarrollar controles de servidor ASP.NET personalizados