Esta documentación está archivada y no tiene mantenimiento.

Cómo: Crear controles de usuario ASP.NET

Visual Studio 2005

La sintaxis declarativa de los controles de usuario es muy similar a la que se emplea para crear una página Web ASP.NET. Las principales diferencias radican en que los controles de usuario utilizan una directiva @ Control en lugar de una directiva @ Page y en que los controles de usuario no incluyen los elementos html, body y form junto al contenido.

Para obtener más información sobre las páginas Web ASP.NET y cómo crearlas, vea Introducción a páginas Web de ASP.NET. Para obtener más información sobre el uso de los controles de usuario en las páginas Web ASP.NET, vea Cómo: Incluir un control de usuario en una página Web ASP.NET.

Para crear un control de usuario

  1. Cree un archivo y asígnele un nombre con la extensión .ascx.

    Por ejemplo, asigne al control de usuario el nombre DisplayName.ascx.

    NoteNota

    No es posible colocar controles de usuario en la carpeta App_Code del sitio Web. Si dicha carpeta contiene algún control de usuario, se producirá un error de análisis cuando se ejecute la página que lo contiene.

  2. Cree una directiva @ Control en la parte superior de la página y especifique el lenguaje de programación que desea utilizar para el control (si desea utilizar uno).

  3. Agregue los controles que desea que muestre el control de usuario.

  4. Agregue el código para las tareas que realizará el control de usuario, como controlar eventos de control o leer datos de un origen de datos.

  5. Cree propiedades en el control si desea poder compartir información entre el control de usuario y la página que lo aloja. Las propiedades se crean del mismo modo que se crearían para cualquier clase, como miembros públicos o con los descriptores de acceso get y set.

Ejemplo

En el ejemplo siguiente se muestra un control de usuario completo. El control de usuario muestra un cuadro de texto de sólo lectura con un número dentro y dos flechas en las que los usuarios pueden hacer clic para aumentar o disminuir el valor del cuadro de texto. El control expone tres propiedades, MinValue, MaxValue y CurrentValue, que pueden utilizarse en la página que lo aloja.

Security noteNota de seguridad

En este ejemplo hay un cuadro de texto que acepta datos del usuario, lo que puede suponer una amenaza para la seguridad. De forma predeterminada, las páginas Web ASP.NET validan los datos escritos por el usuario para comprobar que no incluyen secuencias de comandos ni elementos HTML. Para obtener más información, vea Información general sobre los ataques mediante secuencias de comandos.

<% @ Control Language="C#" ClassName="Spinner" %>

<script runat="server">
private int m_minValue;
private int m_maxValue = 100;
private int m_currentNumber = 0;
public int MinValue
{
    get
    {
        return m_minValue;
    }
    set
    {
        if(value >= this.MaxValue)
        {    
            throw new Exception("MinValue must be less than MaxValue.");
        }
        else
        {
            m_minValue = value;
        }
    }
}

public int MaxValue
{
    get
    {
        return m_maxValue;
    }
    set
    {
        if(value <= this.MinValue)
        {
            throw new 
                Exception("MaxValue must be greater than MinValue.");
        }
        else
        {
            m_maxValue = value;
        }
    }
}

public int CurrentNumber
{
    get
    {
        return m_currentNumber;
    }
}

protected void Page_Load(Object sender, EventArgs e)
{
    if(IsPostBack)
    {
        m_currentNumber =
            Int16.Parse(ViewState["currentNumber"].ToString());
    }
    else
    {
        m_currentNumber = this.MinValue;
    }
    DisplayNumber();
}

protected void DisplayNumber()
{
    textNumber.Text = this.CurrentNumber.ToString();
    ViewState["currentNumber"] = this.CurrentNumber.ToString();
}

protected void buttonUp_Click(Object sender, EventArgs e)
{
    if(m_currentNumber == this.MaxValue)
    {
        m_currentNumber = this.MinValue;
    }
    else
    {
        m_currentNumber += 1;
    }
    DisplayNumber();
}

protected void buttonDown_Click(Object sender, EventArgs e)
{
    if(m_currentNumber == this.MinValue)
    {
        m_currentNumber = this.MaxValue;
    }
    else
    {
        m_currentNumber -= 1;
    }
    DisplayNumber();
}
</script>
<asp:TextBox ID="textNumber" runat="server" 
    ReadOnly="True" Width="32px" Enabled="False" />
<asp:Button Font-Bold="True" ID="buttonUp" runat="server"  
    Text="^" OnClick="buttonUp_Click" />
<asp:Button Font-Bold="True" ID="buttonDown" runat="server" 
    Text="v" OnClick="buttonDown_Click" />

El control de usuario de ejemplo incluye el código para definir tres propiedades: MinValue, MaxValue y CurrentValue. Las propiedades de los controles de usuario deben ser públicas. En este ejemplo, las tres propiedades se crean con descriptores de acceso get y set para permitir al control comprobar si los valores se encuentran dentro de un intervalo aceptable. Sin embargo, puede crear una propiedad con sólo declarar un miembro público.

Las propiedades MinValue y MaxValue pueden establecerse mediante declaración en la página contenedora mediante una sintaxis como la siguiente:

<uc:Spinner ID="Spinner1" runat="server" MinValue=0 MaxValue=10 />

Cuando el control de usuario se inicializa como parte de la página contenedora, ASP.NET analiza los valores declarados de las propiedades y los establece automáticamente en el control de usuario.

Como ocurre con las páginas, el control de usuario se reinicializa con cada devolución de datos. Por lo tanto, los valores de las propiedades deben almacenarse en una ubicación persistente entre las devoluciones de datos. Una ubicación típica para almacenar los valores de las propiedades es el estado de vista. Durante la ejecución del evento Load, debe comprobar si hay una devolución de datos y cargar de nuevo los valores de las propiedades desde el almacén. Para obtener más información sobre el estado de vista, vea Estado de vista en ASP.NET.

Programación eficaz

En el ejemplo se ha simplificado el control de excepciones. En los descriptores de acceso set para las propiedades MinValue y MaxValue, si las propiedades se establecen en un valor inaceptable, el código del control de usuario producirá una excepción simple en la cual la cadena se codifica de forma rígida. En las aplicaciones reales debe crear una clase de excepción especial y no utilizar cadenas codificadas de forma rígida para mostrar información de errores.

Vea también

Mostrar: