Cómo: Tratar un control de usuario como control de elementos Web

Actualización: noviembre 2007

El conjunto de controles de elementos Web de ASP.NET permite utilizar controles de servidor Web existentes como controles de elementos Web para poder volver a utilizar el código al máximo y aprovechar las ventajas de la personalización de los elementos Web. Los controles de usuario son un tipo de control de servidor que se puede utilizar como controles de elementos Web. En este tema se muestra cómo tratar un control de usuario existente como si fuera un control de elementos Web.

w9b5ett0.alert_note(es-es,VS.100).gifNota:

Para que funcione este procedimiento, necesita un sitio Web ASP.NET que pueda identificar a cada uno de los usuarios. Si ya tiene este tipo de sitio configurado, puede utilizarlo. En caso contrario, para obtener información sobre cómo crear un directorio virtual, vea Cómo: Crear y configurar directorios virtuales en IIS 5.0 y 6.0. También necesita un control de usuario que pueda funcionar con la personalización de los elementos Web. Si no tiene este tipo de control de usuario, se proporciona uno de ejemplo en la sección Code.

Al utilizar un control de usuario en una aplicación de elementos Web, asume las funciones completas de un control WebPart en tiempo de ejecución. Para obtener información detallada, vea Usar controles de servidor ASP.NET en aplicaciones de elementos Web. El control de usuario sigue teniendo sus funciones normales, con una excepción: el almacenamiento en la caché de resultados está deshabilitado en los controles de usuario que se utilicen en aplicaciones de elementos Web. El conjunto de controles de elementos Web exige que se agreguen todos los controles al árbol de control para todas las solicitudes de la página. Esto es necesario para que la característica de personalización funcione y los datos de personalización se puedan utilizar en acciones de ida y vuelta en los controles. Con todo, si el almacenamiento en la caché de resultados está habilitado en un control de usuario, no se agrega al árbol de control, lo que podría afectar a las características de los elementos Web. Ésta es la razón por la que el almacenamiento en la caché de resultados está deshabilitado por diseño en los controles de usuario de las aplicaciones de elementos Web.

Para crear una página de elementos Web para alojar el control de usuario

  1. Cree una nueva página ASP.NET. Agregue la siguiente declaración de página en la parte superior de la página.

    <@page language="VB" %>
    

    <@page language="C#" %>
    
  2. En la declaración de página que acaba de agregar, agregue la siguiente estructura de página básica con etiquetas HTML.

    <html>
    <head>
      <title>Web Parts Demo Page</title>
    </head>
    <body>
      <h1>Web Parts User Control Demonstration</h1>
      <form runat="server">
      <table cellspacing="0" cellpadding="0" border="0">
        <tr>
          <td valign="top">
          </td>
          <td valign="top">
          </td>
          <td valign="top">
          </td>
        </tr>
      </table>
      </form>
    </body>
    </html>
    
  3. Guarde la página en un directorio en el sitio que admite la personalización.

Para agregar controles de elementos Web a la página

  1. Inmediatamente debajo del elemento <form> de la página, agregue un control WebPartManager.

    <asp:webpartmanager id="WebPartManager1" runat="server" />
    
  2. Inmediatamente debajo del elemento <asp:webpartmanager>, y dentro del primer grupo de etiquetas <td> de la tabla (es decir, la primera columna de la tabla) agregue un control WebPartZone para que contenga el control de usuario que va a agregar en un paso posterior.

    <asp:webpartzone id="SideBarZone" runat="server" 
      headertext="Sidebar Zone">
      <zonetemplate>
      </zonetemplate>
    </asp:webpartzone>
    
  3. En el elemento <zonetemplate> de la zona que acaba de agregar, agregue un control de servidor existente y contenido estático que se tratará como otro control de elementos Web (puesto que está dentro de una zona de elementos Web) en tiempo de ejecución:

    <asp:label runat="server" id="linksPart" title="My Links">
      <a href="www.asp.net">ASP.NET site</a> 
      <br />
      <a href="www.gotdotnet.com">GotDotNet</a> 
      <br />
      <a href="www.contoso.com">Contoso.com</a> 
      <br />
    </asp:label>
    
  4. Dentro del segundo grupo de etiquetas <td> de la tabla (es decir, la segunda columna de la tabla) agregue otro control WebPartZone para que contenga el control de usuario que va a agregar en un paso posterior.

    <asp:webpartzone id="MainZone" runat="server" 
      headertext="Main Zone">
      <zonetemplate>
      </zonetemplate>
    </asp:webpartzone>
    
  5. Dentro del tercer elemento <td> de la tabla (la tercera columna) agregue un elemento <asp:editorzone>. Agregue un elemento <zonetemplate> y, a continuación, agregue un elemento <asp:appearanceeditorpart> y un elemento <asp:layouteditorpart>. El código en la zona del editor se debe ser similar al siguiente:

    <asp:editorzone id="EditorZone1" runat="server">
      <zonetemplate>
        <asp:appearanceeditorpart runat="server" 
          id="AppearanceEditorPart1" />
        <asp:layouteditorpart runat="server" 
          id="LayoutEditorPart1" />
      </zonetemplate>
    </asp:editorzone>
    
  6. Guarde la página.

Para crear un control de usuario

  1. Cree un nuevo archivo en el editor de texto. Este archivo contendrá un control de usuario que también se puede agregar a la página como control de elementos Web.

    w9b5ett0.alert_note(es-es,VS.100).gifNota:

    En realidad, el control de búsqueda de este tutorial no implementa funcionalidad de búsqueda; sólo se utiliza para mostrar las características de los elementos Web.

  2. En la parte superior del nuevo archivo, agregue una declaración de control como se muestra en el ejemplo siguiente.

    <%@ control language="VB" classname="SearchUserControl" %>
    

    <%@ control language="C#" classname="SearchUserControl" %>
    
  3. Debajo de la declaración de control, agregue un par de etiquetas <script> y, dentro de ellas, agregue el código para crear una propiedad personalizable. Observe que la propiedad ResultsPerPage tiene un atributo Personalizable. Esta propiedad permitiría a los usuarios del control personalizar el número de resultados de búsqueda que se deben devolver en cada página, si se ha proporcionado un control de edición con la interfaz de usuario para cambiar el valor en la vista de diseño. El código del control debe ser similar al ejemplo de código siguiente.

    <%@ control language="VB" classname="SearchUserControl" %>
    <script runat="server">
      Private results As Integer
      
      <Personalizable()> _
      Property ResultsPerPage() As Integer
        
        Get
          Return results
        End Get
        
        Set(ByVal value As Integer)
          results = value
        End Set
        
      End Property
    </script>
    

    <%@ control language="C#" classname="SearchUserControl" %>
    <script runat="server">
      private int results;
      
      [Personalizable]
      public int ResultsPerPage
      {
        get
          {return results;}
        
        set
          {results = value;}
      }    
    </script>
    
  4. Agregue un cuadro de texto y un botón debajo del elemento <script> para proporcionar la IU básica para un control de búsqueda, como se muestra en el siguiente ejemplo de código.

    <asp:textbox runat="server" id="inputBox"></asp:textbox>
    <br />
    <asp:button runat="server" id="searchButton" text="Search" />
    
  5. Denomine el archivo SearchUserControlVB.ascx o SearchUserControlCS.ascx (dependiendo del lenguaje que esté utilizando) y guárdelo en el mismo directorio que la página WebPartsDemo.aspx.

    w9b5ett0.alert_security(es-es,VS.100).gifNota de seguridad:

    Este control tiene un cuadro de texto que acepta datos del usuario, lo que puede resultar una amenaza para la seguridad. Los datos proporcionados por el usuario en una página Web pueden contener secuencias de comandos de cliente malintencionadas. De manera predeterminada, las páginas Web ASP.NET validan la entrada de datos del usuario para asegurarse de que no contiene ninguna secuencia de comandos o elemento HTML. Siempre que esta validación esté habilitada, no tendrá que comprobar explícitamente si algún usuario está insertando secuencias de comandos o elementos HTML. Para obtener más información, vea Información general sobre los ataques mediante secuencias de comandos.

Para hacer referencia al control de usuario dentro de la zona de elementos Web principal

  1. En la parte superior de la página Web, inmediatamente después de la declaración de la página, agregue la declaración siguiente para hacer referencia al control de usuario que acaba de crear. Si no utiliza el control de usuario de ejemplo que se proporciona en este tema, debe establecer el atributo src en la ruta de acceso y nombre de archivo del control de usuario que esté utilizando y, si lo desea, puede asignar otro valor al atributo tagname.

    [VB]

    <%@ register tagprefix="uc1" tagname="SearchUserControl" 
        src="searchusercontrolvb.ascx" %>
    

    [C#]

    <%@ register tagprefix="uc1" tagname="SearchUserControl" 
        src="searchusercontrolcs.ascx" %>
    
  2. En el elemento <zonetemplate> para la Principal zona, haga referencia al control de usuario que creó previamente.

    <uc1:SearchUserControl id="searchPart" runat="server"
      title="Search" />
    
  3. Guarde y cierre la página.

En el ejemplo de código siguiente se proporciona una lista de código completa de la página de elementos Web de muestra utilizada para alojar el control de usuario. También se proporciona el código para el control de usuario de ejemplo al que se hace referencia en la página como control de elementos Web. Tenga en cuenta que, para tratar al control de usuario como un verdadero control de elementos Web que se puede personalizar, el control debe exponer una propiedad pública mediante el atributo de código [Personalizable].

<!-- Web Parts page to host the user control -->
<%@ page language="C#" %>
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
  src="searchusercontrol.ascx" %>

<html>
<head>
  <title>Web Parts Demo Page</title>
</head>
<body>
  <h1>Web Parts User Control Demonstration</h1>
  <form runat="server" id="form1">
  <asp:webpartmanager id="WebPartManager1" runat="server" />
  <asp:webpartpagemenu
    id="pagemenu1"
    runat="server"
    Mode="Menu"
    MenuStyle-BorderWidth="1">
    <browsemodeverb text="Browse" />
    <designmodeverb text="Design" />
    <editmodeverb text="Edit" />
  </asp:webpartpagemenu>
  <table cellspacing="0" cellpadding="0" border="0">
    <tr>
      <td valign="top">
        <asp:webpartzone id="SideBarZone" runat="server" 
          headertext="Sidebar Zone">
          <zonetemplate>
            <asp:label runat="server" id="linksPart" title="My Links">
              <a href="www.asp.net">ASP.NET site</a> 
              <br />
              <a href="www.gotdotnet.com">GotDotNet</a> 
              <br />
              <a href="www.contoso.com">Contoso.com</a> 
              <br />
            </asp:label>
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:webpartzone id="MainZone" runat="server" 
          headertext="Main Zone">
          <zonetemplate>
            <uc1:SearchUserControl id="searchPart" runat="server"
              title="Search" />
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:editorzone id="EditorZone1" runat="server">
          <zonetemplate>
            <asp:appearanceeditorpart runat="server" 
              id="AppearanceEditorPart1" />
            <asp:layouteditorpart runat="server" 
              id="LayoutEditorPart1" />
          </zonetemplate>
        </asp:editorzone>
      </td>
    </tr>
  </table>
  </form>
</body>
</html>


<!-- Web Parts user control -->
<%@ control language="C#" classname="SearchUserControl" %>
<script runat="server">
  private int results;
  
  [Personalizable]
  public int ResultsPerPage
  {
    get
      {return results;}
    
    set
      {results = value;}
  }    
</script>
<asp:textbox runat="server" id="inputBox"></asp:textbox>
<br />
<asp:button runat="server" id="searchButton" text="Search" />

Si ejecuta el código de ejemplo y hace clic en el menú de página Modo de presentación, puede alternar entre los distintos modos de personalización en el menú: Examinar, Diseño y Edición. En el modo Diseño, puede disponer el diseño de la página haciendo clic en el encabezado de los dos controles de elementos Web y arrastrándolos a otras zonas. En el modo Edición, puede hacer clic en la imagen de edición del encabezado de cualquiera de los controles de elementos Web y establecer las distintas propiedades de IU del control.

Adiciones de comunidad

AGREGAR
Mostrar: