共用方式為

HOW TO：將使用者控制項視為 Web 組件控制項

  • 發行項

更新：2007 年 11 月

ASP.NET Web 組件控制項集合可讓您將現有 Web 伺服器控制項用做 Web 組件控制項，以達到最大程式碼重複使用率，並可以從 Web 組件個人化中獲益。使用者控制項是一種可以用做 Web 組件控制項的伺服器控制項型別。本主題示範如何將現有的使用者控制項視為 Web 組件控制項。

注意事項：

您需要可識別個別使用者的 ASP.NET 網站，才能讓這個程序運作。如果您已經設定了此類網站，便可以使用它。否則，如需建立虛擬目錄的詳細資訊，請參閱 HOW TO：在 IIS 5.0 和 6.0 中建立和設定虛擬目錄。您還需要一個使用者控制項，啟用它才可以使用 Web 組件個人化。如果沒有這樣的使用者控制項，程式碼一節中有提供範例。

當您在 Web 組件應用程式中利用使用者控制項時，它會在執行階段接受 WebPart 控制項的全部功能。如需詳細資訊，請參閱在 Web 組件應用程式中使用 ASP.NET 伺服器控制項。使用者控制項還會保留做為伺服器控制項的一般功能，除非：Web 組件應用程式中正在使用的使用者控制項上停用了輸出快取。Web 組件控制項集合需要針對每個網頁要求將所有的控制項都加入控制項樹狀結構。只有這樣，才能使用個人化功能，並對控制項來回存取個人化資料。然而，在使用者控制項上啟用輸出快取後，該控制項並沒有加入控制項樹狀結構，這會妨礙 Web 組件的功能。這就是在 Web 組件應用程式中的使用者控制項上，輸出快取設計為停用的原因。

若要建立裝載使用者控制項的 Web 組件頁面

  1. 建立新 ASP.NET Web 網頁。將下列網頁宣告加入網頁的頂端。

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

  2. 就在 <asp:webpartmanager> 項目之下，表格的第一組 <td> 標記 (第一個表格資料行) 中，加入 WebPartZone 控制項，以包含將在稍後步驟中加入的使用者控制項。

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

  3. 在剛加入之區域的 <zonetemplate> 項目內，加入現有伺服器控制項和某些靜態 (Static) 內容，這些內容將在執行階段視為另一個 Web 組件控制項 (因為其在 Web 組件區域內)：

    <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. 在表格的第二組 <td> 標記 (第二個表格資料行) 內，加入另一個 WebPartZone 控制項，以包含將在稍後步驟中加入的使用者控制項。

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

  5. 在表格的第三個 <td> 項目 (第三個表格資料行) 內，加入 <asp:editorzone> 項目。加入 <zonetemplate> 項目，然後加入 <asp:appearanceeditorpart> 和 <asp:layouteditorpart> 項目。編輯器區域中的程式碼應該看起來與下列項目相同：

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

  6. 儲存 Web 網頁。

建立使用者控制項

  1. 在文字編輯器中建立新檔案。這個檔案將包含也可做為 Web 組件控制項加入網頁的使用者控制項。

    注意事項：

    這個逐步解說的搜尋控制項不會實作實際的搜尋功能，它僅用於示範 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 >
  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. 在 <script> 項目之下加入文字方塊和按鈕，以提供搜尋控制項的基本 UI，如下列程式碼範例所示。

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

  5. 將檔案命名為 SearchUserControlVB.ascx 或 SearchUserControlCS.ascx (視您所使用的語言而定)，並將其儲存在與 WebPartsDemo.aspx 網頁相同的目錄中。

    安全性注意事項：

    此控制項具有接受使用者輸入的文字方塊，而這是一項可能的安全性威脅。在 Web 網頁中的使用者輸入可能會含有惡意的用戶端指令碼。ASP.NET Web 網頁預設會驗證使用者輸入，以確保輸入中未包含 HTML 項目或指令碼。一旦啟用了驗證，就不需要明確檢查使用者輸入中的指令碼或 HTML 項目。如需詳細資訊，請參閱指令碼攻擊概觀。

若要在主要 Web 組件區域內參考使用者控制項

  1. 在 Web 網頁頂端，就在網頁宣告之後，加入下列宣告以參考剛剛建立的使用者控制項。如果您不是在使用本主題中提供的使用者控制項範例，則 src 屬性需要設為所使用之使用者控制項的路徑和檔名，您也可以選擇性地將不同值指派給 tagname 屬性。

    [VB]

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

    [C#]

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

  2. 在 Main 區域的 <zonetemplate> 項目內，參考先前建立的使用者控制項。

    <uc1:SearchUserControl id="searchPart" 
  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  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" />

如果您執行範例程式碼並按一下 [顯示模式] 網頁功能表，則可以在此功能表上的不同個人化模式間進行切換：[瀏覽]、[設計] 和 [編輯]。在 [設計] 模式下，您可以藉由按一下兩個 Web 組件控制項的標頭，並將它們拖曳至其他區域，來排列網頁的配置。在 [編輯] 模式下，您可以按一下任意 Web 組件控制項標頭中的 [編輯影像]，然後對該控制項設定各種 UI 屬性。

請參閱

工作

逐步解說：建立 Web 組件頁面

概念

ASP.NET Web 組件概觀

在 Web 組件應用程式中使用 ASP.NET 伺服器控制項