How to: Treat a User Control as a Web Parts Control

Article
12/04/2014

The ASP.NET Web Parts control set enables you to use existing Web server controls as Web Parts controls in order to achieve maximum code reuse and to gain the benefits of Web Parts personalization. User controls are one type of server control you can use as Web Parts controls. This topic demonstrates how to treat an existing user control as a Web Parts control.

Note

For this procedure to work, you need an ASP.NET Web site that can identify individual users. If you have such a site already configured, you can use that. Otherwise, for details on creating a virtual directory, see How to: Create and Configure Virtual Directories in IIS 5.0 and 6.0. You also need a user control that is enabled to work with Web Parts personalization. If you do not have such a user control, a sample one is provided in the Code section.

When you use a user control in a Web Parts application, it takes on the full capabilities of a WebPart control at run time. For details, see Using ASP.NET Server Controls in Web Parts Applications. The user control also retains its normal capabilities as a server control, with one exception: output caching is disabled on user controls that are being used in Web Parts applications. The Web Parts control set requires all controls to be added to the control tree for every page request. This is necessary so that the personalization feature can work, and personalization data can be round-tripped to the controls. However, when output caching is enabled on a user control, it is not added to the control tree, which would interfere with Web Parts features. This is why output caching is disabled by design on user controls in Web Parts applications.

To create a Web Parts page to host the user control

Create a new ASP.NET page. Add the following page declaration at the top of the page.
```
<@page language="VB" %>
```
```
<@page language="C#" %>
```

Beneath the page declaration you just added, add the following basic page structure with HTML tags.

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

Save the page to a directory under the site that is enabled for personalization.

To add Web Parts controls to the page

Just below the <form> element in your page, add a WebPartManager control.
```
<asp:webpartmanager id="WebPartManager1" runat="server" />
```
Just below the <asp:webpartmanager> element, and within the table's first set of <td> tags (the first table column) add a WebPartZone control to contain the user control that you will add in a later step.
```
<asp:webpartzone id="SideBarZone" runat="server" 
  headertext="Sidebar Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```

Within the <zonetemplate> element of the zone you just added, add an existing server control and some static content that will be treated as another Web Parts control (since it is within a Web Parts zone) at run time:

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

Within the table's second set of <td> tags (the second table column) add another WebPartZone control to contain the user control that you will add in a later step.
```
<asp:webpartzone id="MainZone" runat="server" 
  headertext="Main Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```

Within the table's third <td> element(the third column) add an <asp:editorzone> element. Add a <zonetemplate> element, then add an <asp:appearanceeditorpart> and an <asp:layouteditorpart> element. The code in the editor zone should look like the following:

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

Save the page.

To create a user control

Create a new file in your text editor. This file will contain a user control that can also be added to the page as a Web Parts control.

Note

The search control for this walkthrough does not implement actual search functionality; it is used only to demonstrate Web Parts features.

At the top of the new file, add a control declaration as shown in the following example.

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

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

Beneath the control declaration, add a pair of <script> tags, and within them add code to create a personalizable property. Note that the ResultsPerPage property has a Personalizable attribute. This property would enable users of the control to personalize how many search results to return per page, if you provided an edit control with the user interface (UI) to change the setting in Design view. The code for your control should look like the following code example.

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

Add a text box and a button below the <script> element to provide the basic UI for a search control, as shown in the following code example.
```
<asp:textbox runat="server" id="inputBox"></asp:textbox>
<br />
<asp:button runat="server" id="searchButton" text="Search" />
```

Name the file SearchUserControlVB.ascx or SearchUserControlCS.ascx (depending on which language you are using), and save it in the same directory as the WebPartsDemo.aspx page.

Security Note
This control has a textbox that accepts user input, which is a potential security threat. User input in a Web page can potentially contain malicious client script. By default, ASP.NET Web pages validate user input to ensure that the input does not contain HTML elements or script. As long as this validation is enabled, you do not need to explicitly check for script or HTML elements in user input. For more information, see Script Exploits Overview.

This control has a textbox that accepts user input, which is a potential security threat. User input in a Web page can potentially contain malicious client script. By default, ASP.NET Web pages validate user input to ensure that the input does not contain HTML elements or script. As long as this validation is enabled, you do not need to explicitly check for script or HTML elements in user input. For more information, see Script Exploits Overview.

To reference the user control within the main Web Parts zone

At the top of the Web page, just after the page declaration, add the following declaration to reference the user control you just created. If you are not using the user control sample provided in this topic, the src attribute needs to be set to the path and file name of the user control you are using, and you may also optionally assign a different value to the tagname attribute.

[VB]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolvb.ascx" %>
```
[C#]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolcs.ascx" %>
```
Inside the <zonetemplate> element for the Main zone, reference the user control you created previously.
```
<uc1:SearchUserControl id="searchPart" runat="server"
  title="Search" />
```
Save and close the page.

Example

The following code example provides a complete code listing of the sample Web Parts page used to host the user control. It also provides code for the sample user control that is referenced in the page as a Web Parts control. Note that in order for the user control to be treated as a true Web Parts control capable of personalization, it must expose a public property using the [Personalizable] code attribute.

<!-- 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 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="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>
<asp:textbox runat="server" id="inputBox"></asp:textbox>
<br />
<asp:button runat="server" 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 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" />

If you run the sample code and click the Display Mode page menu, you can alternate among the different personalization modes on the menu: Browse, Design, and Edit. In Design mode, you can arrange the layout of the page by clicking in the header of the two Web Parts controls and dragging them into other zones. In Edit mode, you can click the edit image in the header of either of the Web Parts controls, and then set various UI properties on that control.

Partager via

How to: Treat a User Control as a Web Parts Control

To create a Web Parts page to host the user control

To add Web Parts controls to the page

To create a user control

To reference the user control within the main Web Parts zone

Example

See Also

Tasks

Concepts

Ressources supplémentaires