Partager via

Comment : traiter un contrôle utilisateur comme un contrôle WebPart

  • Article

Mise à jour : novembre 2007

Le jeu de composants WebPart ASP.NET vous permet d'utiliser les contrôles serveur Web existants comme des contrôles WebPart pour optimiser la réutilisation du code et tirer parti de la personnalisation WebPart. Les contrôles utilisateur sont un type de contrôle serveur que vous pouvez utiliser en tant que contrôles WebPart. Cette rubrique montre comment traiter un contrôle utilisateur existant comme un contrôle WebPart.

Remarque :

Pour mettre en œuvre cette procédure, vous avez besoin d'un site Web ASP.NET capable d'identifier les utilisateurs individuels. Si vous possédez un site de ce type configuré, vous pouvez l'utiliser. Sinon, pour plus d'informations sur la création d'un répertoire virtuel, consultez Comment : créer et configurer des répertoires virtuels dans IIS 5.0 et 6.0. Vous avez également besoin d'un contrôle utilisateur compatible avec la personnalisation WebPart. Si vous ne disposez pas de contrôle utilisateur, un exemple est fourni dans la section Code.

Lorsque vous utilisez un contrôle utilisateur dans une application WebPart, il accepte les fonctions complètes d'un contrôle WebPart au moment de l'exécution. Pour plus d'informations, consultez Utilisation de contrôles serveur ASP.NET dans les applications WebPart. Le contrôle utilisateur conserve également ses fonctions normales comme un contrôle serveur, avec une exception : la mise en cache de sortie est désactivée sur les contrôles utilisateur qui sont utilisés dans les applications WebPart. Le jeu de composants WebPart requiert que tous les contrôles soient ajoutés à l'arborescence du contrôle pour chaque demande de page. Il s'agit d'un prérequis au fonctionnement de la fonctionnalité de personnalisation et aux allers-retours des données de personnalisation vers les contrôles. Toutefois, lorsque la mise en cache de sortie est activée sur un contrôle utilisateur, il n'est pas ajouté à l'arborescence du contrôle, ce qui pourrait interférer avec les fonctionnalités WebPart. C'est la raison pour laquelle la mise en cache de sortie est désactivée par conception sur les contrôles utilisateur dans les applications WebPart.

Pour créer une page WebPart afin d'héberger le contrôle utilisateur

  1. Créez une page ASP.NET. Ajoutez la déclaration de page suivante en haut de la page :

    <@page language="VB" %>

    <@page language="C#" %>

  2. Sous la déclaration de page que vous venez d'ajouter, ajoutez la structure de page de base suivante avec les balises HTML.

    <html>
<head>
  <title>Web Parts Demo Page</title>
</head>
<body>
  <h1>Web Parts User Control Demonstration</h1>
  <form >
  <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. Enregistrez la page dans un répertoire sous le site qui est activé pour la personnalisation.

Pour ajouter des contrôles WebPart à la page

  1. Ajoutez à votre page un contrôle WebPartManager immédiatement sous l'élément <form>.

    <asp:webpartmanager id="WebPartManager1"  />

  2. Ajoutez un contrôle WebPartZone pour contenir le contrôle utilisateur que vous ajouterez à une étape ultérieure immédiatement sous l'élément <asp:webpartmanager> et dans le premier jeu de balises <td> du tableau (première colonne du tableau) .

    <asp:webpartzone id="SideBarZone"  
  headertext="Sidebar Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>

  3. Dans l'élément <zonetemplate> de la zone que vous venez d'ajouter, ajoutez un contrôle serveur existant, et du contenu statique, qui sera traité comme un autre contrôle WebPart (puisqu'il se trouve dans une zone WebPart) au moment de l'exécution :

    <asp:label  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. Dans le deuxième jeu de balises <td> du tableau (deuxième colonne du tableau), ajoutez un autre contrôle WebPartZone pour contenir le contrôle utilisateur que vous ajouterez à une étape ultérieure.

    <asp:webpartzone id="MainZone"  
  headertext="Main Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>

  5. Dans le troisième élément <td> (troisième colonne) du tableau, ajoutez un élément <asp:editorzone>. Ajoutez un élément <zonetemplate>, puis un élément <asp:appearanceeditorpart> et un élément <asp:layouteditorpart>. Le code de la zone Éditeur doit se présenter comme suit :

    <asp:editorzone id="EditorZone1" >
  <zonetemplate>
    <asp:appearanceeditorpart  
      id="AppearanceEditorPart1" />
    <asp:layouteditorpart  
      id="LayoutEditorPart1" />
  </zonetemplate>
</asp:editorzone>

  6. Enregistrez la page.

Pour créer un contrôle utilisateur

  1. Créez un nouveau fichier dans votre éditeur de texte. Ce fichier contiendra un contrôle utilisateur qui peut également être ajouté à la page en tant que contrôle WebPart.

    Remarque :

    Le contrôle de recherche pour cette procédure pas à pas n'implémente pas des fonctionnalités de recherche réelles ; il est utilisé uniquement pour illustrer des fonctionnalités WebPart.

  2. En haut du nouveau fichier, ajoutez une déclaration de contrôle, comme le montre l'exemple suivant.

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

    <%@ control language="C#" classname="SearchUserControl" %>

  3. Sous la déclaration de contrôle, ajoutez une paire de balises <script> et entre les deux, ajoutez le code pour créer une propriété personnalisable. Notez que la propriété ResultsPerPage a un attribut Personalizable. Cette propriété permettrait aux utilisateurs du contrôle de personnaliser le nombre de résultats de la recherche à retourner par page, si vous avez fourni un contrôle d'édition avec l'interface utilisateur pour modifier le paramètre en mode Design. Le code de votre contrôle doit ressembler à l'exemple de code suivant.

    <%@ control language="VB" classname="SearchUserControl" %>
<script >
  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 >
  private int results;

  [Personalizable]
  public int ResultsPerPage
  {
    get
      {return results;}

    set
      {results = value;}
  }    
</script>

  4. Ajoutez une zone de texte et un bouton au-dessous de l'élément <script> pour fournir l'Interface utilisateur de base pour un contrôle de recherche, comme le montre l'exemple de code suivant.

    <asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />

  5. Nommez le fichier SearchUserControlVB.ascx ou SearchUserControlCS.ascx (selon le langage que vous utilisez) et enregistrez-le dans le même répertoire que la page WebPartsDemo.aspx.

    Note de sécurité :

    Ce contrôle a une zone de texte qui accepte l'entrée d'utilisateur, qui constitue une menace éventuelle pour la sécurité. Les entrées d'utilisateur dans une page Web peuvent inclure un script client nuisible. Par défaut, les pages Web ASP.NET valident les entrées d'utilisateur pour vérifier qu'elles ne contiennent pas d'éléments HTML ni de script. Tant que cette vérification est activée, vous n'avez pas besoin de vérifier explicitement la présence d'un script ou d'éléments HTML dans les entrées d'utilisateur. Pour plus d'informations, consultez Vue d'ensemble des attaques de script.

Pour référencer le contrôle utilisateur dans la zone WebPart principale

  1. En haut de la page Web, après la déclaration de page, ajoutez la déclaration suivante pour référencer le contrôle utilisateur que vous venez de créer. Si vous n'utilisez pas l'exemple de contrôle utilisateur fourni dans cette rubrique, l'attribut src doit être défini sur le chemin d'accès et le nom de fichier du contrôle utilisateur que vous utilisez, et vous pouvez éventuellement assigner une valeur différente à l'attribut tagname.

    [VB]

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

    [C#]

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

  2. Dans l'élément <zonetemplate> pour la zone principale, référencez le contrôle utilisateur que vous avez créé précédemment.

    <uc1:SearchUserControl id="searchPart" 
  title="Search" />

  3. Enregistrez et fermez la page.

Exemple

L'exemple de code suivant fournit une liste de code complète de la page WebPart d'exemple utilisée pour héberger le contrôle utilisateur. Il fournit également le code du contrôle utilisateur d'exemple qui est référencé dans la page en tant que contrôle WebPart. Notez que pour être traité en tant que contrôle WebPart réel qui prend en charge la personnalisation, le contrôle utilisateur doit posséder une propriété publique à l'aide de l'attribut de code [Personalizable].

<!-- Web Parts page to host the user control -->
<%@ page language="VB" %>
<%@ 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  id="form1">
  <asp:webpartmanager id="WebPartManager1"  />
  <asp:webpartpagemenu
    id="pagemenu1"
    
    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"  
          headertext="Sidebar Zone">
          <zonetemplate>
            <asp:label  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"  
          headertext="Main Zone">
          <zonetemplate>
            <uc1:SearchUserControl id="searchPart" 
              title="Search" />
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:editorzone id="EditorZone1" >
          <zonetemplate>
            <asp:appearanceeditorpart  
              id="AppearanceEditorPart1" />
            <asp:layouteditorpart  
              id="LayoutEditorPart1" />
          </zonetemplate>
        </asp:editorzone>
      </td>
    </tr>
  </table>
  </form>
</body>
</html>


<!-- Web Parts user control -->
<%@ control language="VB" classname="SearchUserControl" %>
<script >
  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>
<asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />

<!-- 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  id="form1">
  <asp:webpartmanager id="WebPartManager1"  />
  <asp:webpartpagemenu
    id="pagemenu1"
    
    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"  
          headertext="Sidebar Zone">
          <zonetemplate>
            <asp:label  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"  
          headertext="Main Zone">
          <zonetemplate>
            <uc1:SearchUserControl id="searchPart" 
              title="Search" />
          </zonetemplate>
        </asp:webpartzone>
      </td>
      <td valign="top">
        <asp:editorzone id="EditorZone1" >
          <zonetemplate>
            <asp:appearanceeditorpart  
              id="AppearanceEditorPart1" />
            <asp:layouteditorpart  
              id="LayoutEditorPart1" />
          </zonetemplate>
        </asp:editorzone>
      </td>
    </tr>
  </table>
  </form>
</body>
</html>


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

Si vous exécutez l'exemple de code et cliquez sur le menu de la page Mode d'affichage, vous pouvez alterner entre les différents modes de personnalisation du menu : Navigation, Designet Édition. En mode Design, vous pouvez modifier la disposition de la page en cliquant dans l'en-tête des deux contrôles WebPart et en les faisant glisser vers d'autres zones. En mode Édition, vous pouvez cliquer sur l'image de modification dans l'en-tête de l'un ou l'autre des contrôles WebPart, puis définir plusieurs propriétés d'interface utilisateur sur ce contrôle.

Voir aussi

Tâches

Procédure pas à pas : création d'une page WebPart

Concepts

Vue d'ensemble des WebParts ASP.NET

Utilisation de contrôles serveur ASP.NET dans les applications WebPart