Sintaxis de controles de servidor personalizados

Artículo
05/27/2012

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

La sintaxis de controles de servidor personalizados se utiliza para declarar controles de usuario y controles de servidor personalizados como elementos de marcado en los archivos de aplicación ASP.NET, incluidos páginas Web, controles de usuario y páginas maestras. Esta sintaxis es prácticamente idéntica a la sintaxis utilizada para declarar todos los controles de servidor ASP.NET, con la diferencia de que para los controles personalizados y de usuario normalmente se declara un prefijo de etiqueta único y un nombre de etiqueta que se corresponde con el control.

<tagprefix:tagname id="OptionalID"
   attributename="value"
   eventname="eventhandlermethod"
   runat="server" />
OR
<tagprefix:tagname id="OptionalID"
   runat="server" />

Atributos

tagprefix
Alias del espacio de nombres completo de los elementos de marcado utilizados en la página. El valor del alias es arbitrario, pero ofrece una manera rápida de asociar el marcado de un control personalizado o control de usuario al espacio de nombres de los demás elementos de marcado declarados en un archivo ASP.NET.
tagname
En el caso de los controles personalizados, tagname hace referencia al nombre de un tipo para el que ASP.NET creará una instancia en tiempo de ejecución. En el caso de los controles de usuario, tagname se asigna al archivo de código fuente asociado que define el control de usuario y, a su vez, ese archivo define el tipo para el que ASP.NET crea una instancia.
id
Identificador único que permite utilizar una referencia de programa para el control.
attributename
Nombre de un atributo, que se corresponde con una propiedad del control.
value
Valor que se asigna al atributo (propiedad).
eventname
Nombre de un evento en el control.
eventhandlermethod
Nombre de un controlador de eventos definido para controlar el evento especificado para el control.

Comentarios

Utilice la sintaxis de controles de servidor personalizados para declarar controles de usuario y controles de servidor personalizados en el cuerpo de una página Web ASP.NET. Para que esta sintaxis funcione, el control debe estar registrado en la página o en un archivo de configuración (para registrar un control en todas las páginas de una aplicación se agrega a <controls> del archivo Web.config). Para registrar un control en una página individual, utilice la directiva @ Register.

La etiqueta de apertura de un elemento para un control personalizado o de usuario debe incluir un par de atributo y valor runat="server". Para habilitar la referencia al control mediante programación, opcionalmente se puede especificar un valor único para el atributo id.

Las propiedades creadas en un control de servidor personalizado o de usuario se pueden exponer de forma declarativa en la etiqueta de apertura del control de servidor. Simplemente se declara la propiedad como un atributo y se le asigna un valor. Por ejemplo, si se crea un control personalizado para un cuadro de texto con una propiedad width y se declara width="50" en la etiqueta de apertura del control, se establece el ancho de presentación del control de servidor en cincuenta píxeles.

En algunos casos, los atributos pueden ser objetos que contengan sus propias propiedades. En este caso, se incluye el nombre de la propiedad en la declaración. Por ejemplo, si se crea un control personalizado para un cuadro de texto con un atributo font, puede incluir la propiedad name. A continuación, se puede declarar la propiedad en la etiqueta de apertura del control de servidor como font-name="Arial". Para obtener más información sobre cómo desarrollar los controles de servidor personalizados con propiedades, vea Server Control Simple Properties and SubProperties.

Puede declarar eventos con controles de usuario y controles de servidor personalizados como se declaran con los controles de servidor ASP.NET. Especifique el enlace de eventos en la etiqueta de apertura del control de servidor con un atributo y un valor. Para obtener más información sobre cómo crear controles de servidor personalizados que admitan eventos, vea Server Event Handling in ASP.NET Web Pages.

Puede utilizar y programar controles de servidor personalizados que sean compatibles con plantillas en línea. Para obtener detalles sobre cómo declarar plantillas en un control de servidor personalizado, vea Sintaxis de plantillas en línea para controles de servidor. Para obtener información sobre cómo crear controles de servidor personalizados que sean compatibles con plantillas en línea, vea How to: Create Templated ASP.NET User Controls.

Ejemplo

En el ejemplo de código siguiente se muestra cómo registrar y declarar un control de servidor personalizado en una página Web ASP.NET. En la primera sección de código se crea una clase pública derivada de la clase Button. La segunda parte del código es una página Web que hospeda el botón personalizado. Observe que la página Web utiliza la directiva @ Register para registrar el espacio de nombres del control y establecer el atributo tagprefix. Después, en la página se hace referencia al control mediante el valor tagprefix y el nombre de la clase del control, separados por dos puntos (:).

Para ejecutar el ejemplo de código debe compilar este control personalizado. Se puede compilar de manera explícita y colocar el ensamblado resultante en la carpeta Bin del sitio Web o en la caché global de ensamblados. El código fuente también se puede colocar en la carpeta App_Code del sitio Web, donde se compilará dinámicamente en tiempo de ejecución. En este ejemplo de código se utiliza la compilación dinámica, razón por la cual no es necesario que la directiva @ Register de la página declare un atributo Assembly, ya que el código fuente se compila dinámicamente en tiempo de ejecución. Para ver un tutorial en el que muestra cómo realizar una compilación, vea Walkthrough: Developing and Using a Custom Server Control.

Nota sobre la 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 ASP.NET Web Pages validan los datos escritos por el usuario para comprobar que no incluyen script ni elementos HTML.Para obtener más información, vea Script Exploits Overview.

// A custom Button control to reference in the page.
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Security.Permissions
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
  Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class CustomButton : Button
  {
    public CustomButton()
    {
      this.Text = "Click Here";
    }
  }
}

<!-- A page that references the custom control. -->
<%@Page language="C#" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"  
    namespace="Samples.AspNet.CS.Controls" %>
    
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>   
 <script runat="server">
     private void custButton_Click(Object sender, EventArgs e)
     {
       TextBox.BackColor = System.Drawing.Color.Green;
       TextBox.Text = "You clicked the button";
     }       
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

' A custom Button control to reference in the page.
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.Configuration
Imports System.Data.Sql
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class CustomButton
    Inherits Button

    Public Sub New()
      Me.Text = "Click Here"
    End Sub

  End Class

End Namespace
<!-- A page that references the custom control. -->
<%@ Page Language="VB" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"
    namespace="Samples.AspNet.VB.Controls" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>   
 <script runat="server">
   Sub custButton_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
     TextBox.BackColor = Drawing.Color.Green
     TextBox.Text = "You clicked the button."
   End Sub
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton" 
         onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

Vea también

Conceptos

ASP.NET Web Page Syntax Overview