Gewusst wie: Behandeln eines Benutzersteuerelements als Webparts-Steuerelement

Artikel
10/22/2014

Aktualisiert: November 2007

Mit der ASP.NET-Webparts-Steuerelementreihe können Sie vorhandene Webserver-Steuerelemente als Webparts-Steuerelemente verwenden, um die maximale Wiederverwendung von Code zu erreichen und von der Webparts-Personalisierung zu profitieren. Benutzersteuerelemente sind ein Typ von Serversteuerelementen, der als Webparts-Steuerelement verwendet werden kann. In diesem Thema wird veranschaulicht, wie ein vorhandenes Benutzersteuerelement als Webparts-Steuerelement behandelt wird.

Hinweis:
Wenn Sie diese Prozedur verwenden möchten, benötigen Sie eine ASP.NET-Website, die einzelne Benutzer identifizieren kann. Wenn Sie bereits eine solche Site konfiguriert haben, können Sie diese verwenden. Andernfalls finden Sie ausführliche Informationen zum Erstellen eines virtuellen Verzeichnisses unter Gewusst wie: Erstellen und Konfigurieren von virtuellen Verzeichnissen in IIS 5.0 und 6.0. Außerdem benötigen Sie ein Benutzersteuerelement, das mit der Webparts-Personalisierung verwendet werden kann. Wenn Sie nicht über ein solches Benutzersteuerelement verfügen, finden Sie im Abschnitt Code ein Beispiel-Benutzersteuerelement.

Wenn Sie diese Prozedur verwenden möchten, benötigen Sie eine ASP.NET-Website, die einzelne Benutzer identifizieren kann. Wenn Sie bereits eine solche Site konfiguriert haben, können Sie diese verwenden. Andernfalls finden Sie ausführliche Informationen zum Erstellen eines virtuellen Verzeichnisses unter Gewusst wie: Erstellen und Konfigurieren von virtuellen Verzeichnissen in IIS 5.0 und 6.0. Außerdem benötigen Sie ein Benutzersteuerelement, das mit der Webparts-Personalisierung verwendet werden kann. Wenn Sie nicht über ein solches Benutzersteuerelement verfügen, finden Sie im Abschnitt Code ein Beispiel-Benutzersteuerelement.

Wenn Sie ein Benutzersteuerelement in einer Webparts-Anwendung verwenden, übernimmt dieses zur Laufzeit alle Fähigkeiten eines WebPart-Steuerelements. Weitere Informationen finden Sie unter Verwenden von ASP.NET-Serversteuerelementen in Webparts-Anwendungen. Außerdem behält das Benutzersteuerelement alle normalen Fähigkeiten eines Serversteuerelements mit einer Ausnahme bei: für Benutzersteuerelemente, die in Webparts-Anwendungen verwendet werden, ist die Ausgabecachefunktion deaktiviert. Für jede Anforderung einer Seite müssen in der Webparts-Steuerelementreihe alle Steuerelemente der Steuerelementstruktur hinzugefügt werden. Dies stellt die Voraussetzung für das Personalisierungsfeature dar sowie dafür, dass ein Roundtrip zwischen den Personalisierungsdaten und den Steuerelementen möglich ist. Wenn die Ausgabecachefunktion für ein Benutzersteuerelement jedoch aktiviert ist, wird es der Steuerelementstruktur nicht hinzugefügt, um Konflikte mit den Webparts-Features zu vermeiden. Aus diesem Grund ist die Ausgabecachefunktion in der Standardeinstellung für Benutzersteuerelemente in Webparts-Anwendungen deaktiviert.

So erstellen Sie eine Webparts-Seite, die das Benutzersteuerelement hostet

Erstellen Sie eine neue ASP.NET-Seite. Fügen Sie die folgende Seitendeklaration am oberen Rand der Seite hinzu:
```
<@page language="VB" %>
```
```
<@page language="C#" %>
```

Fügen Sie unterhalb der gerade hinzugefügten Seitendeklaration die folgende einfache Seitenstruktur mit HTML-Tags hinzu.

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

Speichern Sie die Seite in einem Verzeichnis unter der Site, die für die Personalisierung aktiviert ist.

So fügen Sie der Seite Webparts-Steuerelemente hinzu

Fügen Sie direkt unterhalb des <form>-Elements in der Seite ein WebPartManager-Steuerelement hinzu.
```
<asp:webpartmanager id="WebPartManager1"  />
```
Fügen Sie direkt unterhalb des <asp:webpartmanager>-Elements und im ersten Satz von <td>-Tags der Tabelle (in der ersten Tabellenspalte) ein WebPartZone-Steuerelement hinzu, das das in einem späteren Schritt hinzuzufügende Benutzersteuerelement enthalten soll.
```
<asp:webpartzone id="SideBarZone"  
  headertext="Sidebar Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```
Fügen Sie dem <zonetemplate>-Element der gerade hinzugefügten Zone ein vorhandenes Serversteuerelement sowie einige statische Inhalte hinzu, die zur Laufzeit als weiteres Webparts-Steuerelement behandelt werden (da sie sich in einer Webparts-Zone befinden):
```
<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>
```
Fügen Sie im zweiten Set von <td>-Tags der Tabelle (in der zweiten Tabellenspalte) ein weiteres WebPartZone-Steuerelement hinzu, das das in einem späteren Schritt hinzuzufügende Benutzersteuerelement enthalten soll.
```
<asp:webpartzone id="MainZone"  
  headertext="Main Zone">
  <zonetemplate>
  </zonetemplate>
</asp:webpartzone>
```
Fügen Sie im dritten <td>-Element der Tabelle (in der dritte Spalte) ein <asp:editorzone>-Element hinzu. Fügen Sie ein <zonetemplate>-Element hinzu, und fügen Sie dann ein <asp:appearanceeditorpart>-Element und ein <asp:layouteditorpart>-Element hinzu. Der Code im Bearbeitungsbereich sollte der folgenden Darstellung entsprechen:
```
<asp:editorzone id="EditorZone1" >
  <zonetemplate>
    <asp:appearanceeditorpart  
      id="AppearanceEditorPart1" />
    <asp:layouteditorpart  
      id="LayoutEditorPart1" />
  </zonetemplate>
</asp:editorzone>
```
Speichern Sie die Seite.

So erstellen Sie ein Benutzersteuerelement

Erstellen Sie eine neue Datei im Text-Editor. Diese Datei enthält ein Benutzersteuerelement, das der Seite auch als Webparts-Steuerelement hinzugefügt werden kann.

Hinweis:
Das Search-Steuerelement für diese exemplarische Vorgehensweise implementiert nicht die eigentlichen Suchfunktionen; es wird lediglich zur Veranschaulichung von Webparts-Features verwendet.

Fügen Sie am oberen Rand der neuen Datei eine Steuerelementdeklaration hinzu, wie im folgenden Beispiel gezeigt:

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

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

Fügen Sie unterhalb der Steuerelementdeklaration ein <script>-Tagpaar hinzu, und fügen Sie innerhalb dieser Tags Code für das Erstellen einer personalisierbaren Eigenschaft hinzu. Beachten Sie, dass die ResultsPerPage-Eigenschaft über ein Personalizable-Attribut verfügt. Mit dieser Eigenschaft können Benutzer des Steuerelements festlegen, wie viele Suchergebnisse pro Seite angezeigt werden sollen, wenn Sie auf der Benutzeroberfläche ein Edit-Steuerelement zum Ändern der Einstellungen in der Entwurfsansicht bereitstellen. Der Code für das Steuerelement sollte der Darstellung im folgenden Codebeispiel entsprechen:
```
<%@ 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>
```
Fügen Sie unterhalb des <script>-Elements ein Textfeld und eine Schaltfläche hinzu, um für das Search-Steuerelement eine einfache Benutzeroberfläche bereitzustellen, wie im folgenden Codebeispiel dargestellt:
```
<asp:textbox  id="inputBox"></asp:textbox>
<br />
<asp:button  id="searchButton" text="Search" />
```

Geben Sie SearchUserControlVB.ascx oder SearchUserControlCS.ascx als Dateinamen ein (je nach der von Ihnen verwendeten Sprache), und speichern Sie die Datei im gleichen Verzeichnis wie die WebPartsDemo.aspx-Seite.

Sicherheitshinweis:
Dieses Steuerelement verfügt über ein Textfeld, das Benutzereingaben akzeptiert. Dies stellt ein potenzielles Sicherheitsrisiko dar. Benutzereingaben auf einer Webseite können möglicherweise schädliche Clientskripts enthalten. Standardmäßig werden die Benutzereingaben von ASP.NET-Webseiten validiert, um sicherzugehen, dass die Eingabe keine Skript- oder HTML-Elemente enthält. Solange die Überprüfung aktiviert ist, müssen Sie Benutzereingaben nicht explizit auf Skripts oder HTML-Elemente überprüfen. Weitere Informationen finden Sie unter Übersicht über Skriptangriffe.

Dieses Steuerelement verfügt über ein Textfeld, das Benutzereingaben akzeptiert. Dies stellt ein potenzielles Sicherheitsrisiko dar. Benutzereingaben auf einer Webseite können möglicherweise schädliche Clientskripts enthalten. Standardmäßig werden die Benutzereingaben von ASP.NET-Webseiten validiert, um sicherzugehen, dass die Eingabe keine Skript- oder HTML-Elemente enthält. Solange die Überprüfung aktiviert ist, müssen Sie Benutzereingaben nicht explizit auf Skripts oder HTML-Elemente überprüfen. Weitere Informationen finden Sie unter Übersicht über Skriptangriffe.

So verweisen Sie auf das Benutzersteuerelement in der zentralen Webparts-Zone

Fügen Sie am oberen Rand der Webseite direkt unterhalb der Seitendeklaration die folgende Deklaration hinzu, um auf das gerade erstellte Benutzersteuerelement zu verweisen. Wenn Sie nicht das in diesem Thema bereitgestellte Beispiel-Benutzersteuerelement verwenden, muss das src-Attribut auf den Pfad und den Dateinamen des von Ihnen verwendeten Benutzersteuerelements festgelegt werden; außerdem muss dem tagname-Attribut möglicherweise noch ein anderer Wert zugewiesen werden.

[VB]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolvb.ascx" %>
```
[C#]
```
<%@ register tagprefix="uc1" tagname="SearchUserControl" 
    src="searchusercontrolcs.ascx" %>
```
Verweisen Sie im <zonetemplate>-Element für die zentrale Zone auf das zuvor erstellte Benutzersteuerelement.
```
<uc1:SearchUserControl id="searchPart" 
  title="Search" />
```
Speichern und schließen Sie die Seite.

Beispiel

Im folgenden Codebeispiel wird der vollständige Code der Webparts-Beispielseite aufgeführt, die das Benutzersteuerelement hostet. Außerdem wird der Code für das Beispiel-Benutzersteuerelement bereitgestellt, auf das auf der Seite als Webparts-Steuerelement verwiesen wird. Beachten Sie, dass für die Verwendung des Benutzersteuerelements als echtes Webparts-Steuerelement für Personalisierungen unter Verwendung des [Personalizable]-Codeattributs eine öffentliche Eigenschaft verfügbar gemacht werden muss.

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

Wenn Sie den Beispielcode ausführen und im Entwurfsmodus auf das Seitenmenü klicken, können Sie zwischen den verschiedenen Personalisierungsmodi im Menü wechseln: Durchsuchen, Entwerfen und Bearbeiten. Im Modus Entwerfen können Sie das Layout der Seite durch Klicken in den Header der beiden Webparts-Steuerelemente in Verbindung mit dem Ziehen in andere Zonen anpassen. Im Modus Bearbeiten können Sie auf die entsprechende Grafik im Header eines der beiden Webparts-Steuerelemente klicken und verschiedene Benutzeroberflächeneigenschaften für dieses Steuerelement festlegen.

Siehe auch

Aufgaben

Exemplarische Vorgehensweise: Erstellen einer Webparts-Seite

Konzepte

Übersicht über ASP.NET-Webparts

Verwenden von ASP.NET-Serversteuerelementen in Webparts-Anwendungen