通过

如何：将用户控件作为 Web 部件控件使用

  • 项目

更新：2007 年 11 月

通过 ASP.NET Web 部件控件集，可以将现有的 Web 服务器控件用作 Web 部件控件，以尽可能地重复使用代码，并实现 Web 部件个性化设置。用户控件是一种可以用作 Web 部件控件的服务器控件。本主题演示如何将现有的用户控件作为 Web 部件控件使用。

w9b5ett0.alert_note(zh-cn,VS.90).gif说明：

若要正常使用此过程，您需要一个可以识别单个用户的 ASP.NET 网站。如果配置了这样的站点，则可以使用它。否则，若要查看有关创建虚拟目录的详细信息，请参见 如何：在 IIS 5.0 和 6.0 中创建和配置虚拟目录。您还需要一个已启用、可以用于 Web 部件个性化设置的用户控件。如果您没有这样的用户控件，则可以使用代码一节中提供的示例。

使用 Web 部件应用程序中的用户控件时，可以在运行时利用 WebPart 控件的所有功能。有关详细信息，请参见 在 Web 部件应用程序中使用 ASP.NET 服务器控件。用户控件还保留了作为服务器控件的正常功能，但有一个例外：在 Web 部件应用程序中使用的用户控件上禁用输出缓存。对于每个页请求，Web 部件控件集都要求将所有控件添加到控件树。要使个性化设置功能能够正常工作，且个性化设置数据可以往返回到控件，这是必需的。但是，如果在用户控件上启用了输出缓存，控件将不会添加到控件树，这就会与 Web 部件功能发生冲突。这就是通过设计在 Web 部件应用程序中的用户控件上禁用输出缓存的原因。

创建 Web 部件页以承载用户控件

  1. 创建一个新的 ASP.NET 页。在页顶部添加下面的页声明。

    <@page language="VB" %>

    <@page language="C#" %>

  2. 在刚才添加的页声明下面，添加以下具有 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. 将该页保存到启用了个性化设置的站点下的目录中。

向页添加 Web 部件控件

  1. 在页的 <form> 元素紧下面，添加一个 WebPartManager 控件。

    <asp:webpartmanager id="WebPartManager1" runat="server" />

  2. 在 <asp:webpartmanager> 元素的紧下面、表的第一组 <td> 标记（第一个表列）中间，添加一个 WebPartZone 控件，以包含您将在后面的步骤中添加的用户控件。

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

  3. 在您刚才添加的区域的 <zonetemplate> 元素中，添加一个现有的服务器控件以及一些静态内容，在运行时会将它们视为另一个 Web 部件控件（因为它在 Web 部件区域中）：

    <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. 在表的第二组 <td> 标记（第二个表列）中，添加另一个 WebPartZone 控件，以包含您将在后面的步骤中添加的用户控件。

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

  5. 在表的第三个 <td> 元素（第三列）中，添加一个 <asp:editorzone> 元素。添加一个 <zonetemplate> 元素，然后添加一个 <asp:appearanceeditorpart> 和一个 <asp:layouteditorpart> 元素。编辑器区域中的代码应类似于下面这样：

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

  6. 保存页。

创建用户控件

  1. 在文本编辑器中创建一个新文件。此文件将包含也可以作为 Web 部件控件添加到页面的用户控件。

    w9b5ett0.alert_note(zh-cn,VS.90).gif说明：

    本演练的搜索控件并不实现实际的搜索功能；它只用于演示 Web 部件功能。

  2. 在新文件的顶部，如下例中所示添加控件声明。

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

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

  3. 在控件声明的下面，添加一对 <script> 标记，并在这对标记之间添加用于创建可个性化设置的属性的代码。请注意，ResultsPerPage 属性 (Property) 包含一个 Personalizable 属性 (Attribute)。如果提供了具有用户界面 (UI) 的编辑控件在“设计”视图中更改设置，则此属性将使控件的用户能够个性化设置每一页要返回的搜索结果数量。控件的代码应当类似于下面的代码示例。

    <%@ 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. 在 <script> 元素的下面添加一个文本框和一个按钮，以便为搜索控件提供基本的用户界面，如下面的代码示例所示。

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

  5. 将文件命名为 SearchUserControlVB.ascx 或 SearchUserControlCS.ascx（具体取决于您使用的语言），并将其保存到 WebPartsDemo.aspx 页所在的目录中。

    w9b5ett0.alert_security(zh-cn,VS.90).gif安全说明：

    该控件具有一个文本框，用于接受用户输入，这是一个潜在的安全威胁。网页中的用户输入可能会包含具有恶意的客户端脚本。默认情况下，ASP.NET 网页验证用户输入，以确保输入中不包含 HTML 元素或脚本。只要启用了此验证，就不需要显式检查用户输入中的脚本或 HTML 元素。有关更多信息，请参见脚本侵入概述。

在主 Web 部件区域中引用用户控件

  1. 在网页的顶部，将下面的声明添加到页声明的后面，以引用刚刚创建的用户控件。如果您使用的不是本主题中提供的用户控件示例，则需要将 src 属性设置为您所使用的用户控件的路径和文件名，您还可以选择为 tagname 属性赋一个不同的值。

    [VB]

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

    [C#]

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

  2. 在主区域的 <zonetemplate> 元素中，引用您在前面创建的用户控件。

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

  3. 保存和关闭该页。

示例

下面的代码示例提供了用于承载用户控件的示例 Web 部件页的完整代码清单。该示例还提供了在页中作为 Web 部件控件引用的示例用户控件的代码。请注意，为了使用户控件可以用作真正的能够个性化的 Web 部件控件，必须使用 [Personalizable] 代码属性 (Attribute) 来公开一个公共属性 (Property)。

<!-- 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" />

如果运行该代码示例并单击“显示模式”页菜单，您可以在菜单上切换不同的个性化设置模式：“浏览”、“设计”和“编辑”。在**“设计”模式中，您可以通过单击两个 Web 部件控件的标头并将它们拖至其他区域来排列页面布局。在“编辑”**模式中，您可以单击任何一个 Web 部件控件的标头中的编辑图像，然后在该控件上设置各种用户界面属性。

请参见

任务

演练：创建 Web 部件页

概念

ASP.NET Web 部件概述

在 Web 部件应用程序中使用 ASP.NET 服务器控件