WebPartManager-Klasse

Das WebPartManager-Steuerelement fungiert als Hub oder Kontrollcenter einer Webparts-Anwendung. Auf jeder Seite, auf der Webparts-Steuerelemente verwendet werden, muss genau eine Instanz des WebPartManager-Steuerelements vorhanden sein. Wie die meisten Funktionen in Webparts-Anwendungen kann das WebPartManager-Steuerelement nur von authentifizierten Benutzern verwendet werden. Außerdem sind seine Funktionen fast gänzlich mit Serversteuerelementen in Webparts-Zonen wirksam, die von der WebZone-Klasse erben. Serversteuerelemente, die sich auf einer Seite außerhalb dieser Zonen befinden, können sehr wenige Webparts-Funktionen oder geringe Interaktion mit dem WebPartManager-Steuerelement aufweisen.

Als Hub für Webparts-Funktionen auf einer Seite führt das WebPartManager-Steuerelement die in der folgenden Tabelle beschriebenen Arten von Aufgaben aus.

Die WebPartManager-Klasse verfügt über einen großen Satz von Eigenschaften. Zur Nachverfolgung von anderen Steuerelementen verfügt WebPartManager über eine Reihe von Eigenschaften, die auf Auflistungen von Webparts-Steuerelementen oder speziellen Webparts-Objekten verweisen. Die Eigenschaften AvailableTransformers, Connections, Controls, DisplayModes, DynamicConnections, SupportedDisplayModes, WebParts und Zones werden vom WebPartManager-Steuerelement zum Nachverfolgen und für sonstige Aufgaben der Verwaltung verwendet.

Eine weitere Gruppe von Eigenschaften enthält anpassbare Warnungen für bestimmte Szenarios in einer Webparts-Anwendung. Dazu zählen die Eigenschaften CloseProviderWarning, DeleteWarning und ExportSensitiveDataWarning.

Die WebPartManager-Klasse überschreibt einige ihrer geerbten Basiseigenschaften, die von vielen Webserversteuerelementen verwendet werden. Dazu gehören die Eigenschaften EnableTheming, SkinID und Visible.

Schließlich gibt es eine Gruppe von Eigenschaften, die für den Zugriff auf den aktuellen Zustand der Anwendung nützlich sind. Die DisplayMode-Eigenschaft gibt den aktuellen Anzeigemodus an, in dem sich eine Seite befindet. Die EnableClientScript-Eigenschaft gibt an, ob ein Steuerelement clientseitige Skripts rendern kann. Dies ist in Situationen relevant, in denen Benutzer Browser mit anderen Funktionen oder deaktivierten Skripts verwenden. Die Internals-Eigenschaft ist nützlich zum Verweisen auf eine Hilfsklasse, die die Aufrufe einer Reihe wichtiger Webparts-Methoden enthält, die für die Erweiterbarkeit verwendet werden. Durch das Ausblenden der Aufrufe dieser Methoden in einer separaten Klasse (der WebPartManagerInternals-Klasse) wird die API der WebPartManager-Klasse vereinfacht. Die Personalization-Eigenschaft ermöglicht den Zugriff auf die Personalisierungsobjekte, die die Personalisierungseinstellungen von Benutzern speichern und diese Daten in dauerhaften Speichern beibehalten. Die SelectedWebPart-Eigenschaft gibt das WebPart-Steuerelement an, das auf einer Seite vom Benutzer oder von der Anwendung derzeit ausgewählt ist. Die IPersonalizable.IsDirty-Eigenschaft gibt an, ob benutzerdefinierte Personalisierungsdaten für ein WebPart-Steuerelement geändert wurden.

Das WebPartManager-Steuerelement enthält fünf integrierte Anzeigemodi oder Ansichten einer Webseite. Entwickler können dieses Feature erweitern und benutzerdefinierte Anzeigemodi erstellen, indem sie Typen wie die WebZone-Klasse oder die ToolZone-Klasse erweitern. Benutzer können eine Seite in die verschiedenen Anzeigemodi umschalten, sofern die Art von Steuerelementen, die einem bestimmten Anzeigemodus entspricht, auf einer Seite vorhanden ist.

Hinweis
Dieses Feature kann erweitert werden, sodass Benutzer in einen benutzerdefinierten Anzeigemodus umschalten können, ohne über eine entsprechende Zone auf der Seite zu verfügen. Das Standardverhalten ist jedoch, dass Anzeigemodi Zonen entsprechen.

Die Standardanzeigemodi werden durch öffentliche Felder in der WebPartManager-Klasse dargestellt. In der folgenden Tabelle sind die Felder und die Anzeigemodi, auf die sie verweisen, zusammengefasst. Wie oben bereits festgestellt wurde, wird in der DisplayMode-Eigenschaft stets auf den aktuellen Anzeigemodus verwiesen. Die SupportedDisplayModes-Eigenschaft enthält hingegen den Satz der Anzeigemodi, die auf einer bestimmten Seite auf der Grundlage der auf ihr vorhandenen Zonen möglich sind.

Das WebPartManager-Steuerelement enthält außerdem eine Reihe von Ereignisseen, die von zentraler Bedeutung im Lebenszyklus von Webparts-Seiten und Steuerelementen sind. Diese Ereignisse stellen eine präzise programmgesteuerte Kontrolle über das Verhalten von Webparts-Steuerelementen bereit. Die meisten Methoden betreffen direkt WebPart-Steuerelemente (oder andere Server- oder Benutzersteuerelemente, die in WebPartZoneBase-Zonen platziert sind, sodass sie als WebPart-Steuerelemente fungieren können). Einige Ereignisse betreffen hingegen den Zustand der Seite oder die Verbindungen auf der Seite. In der folgenden Tabelle sind die verfügbaren Ereignisse und ihre jeweilige Funktion zusammengefasst.

Hinweis
In der folgenden Tabelle ist mit dem Wort "Steuerelement" in allen Fällen ein WebPart-Steuerelement oder ein beliebiges Serversteuerelement gemeint, das sich in einer Zone befindet und zur Laufzeit mit einem GenericWebPart-Objekt umschlossen wird.

Das WebPartManager-Steuerelement verfügt über zahlreiche Methoden zum Verwalten von Webparts-Seiten. Eine Vielzahl von Methoden, die hier nicht aufgeführt sind, weisen die Form OnEreignisname auf. Diese Methoden lösen in der Regel das ihnen zugeordnete Ereignis aus und stellen dem Ereignis einen Handler des Typs WebPartEventHandler zur Verfügung. Die meisten dieser Methoden können von Entwicklern, die von der WebPartManager-Klasse erben, überschrieben werden. Außerdem können Seitenentwickler benutzerdefinierte Handler für die diesen Methoden zugeordneten Ereignisse bereitstellen. Im Falle eines WebPartAdded-Ereignisses kann ein Seitenentwickler beispielsweise dem <asp:webpartmanager>-Element im Markup einer Webseite ein OnWebPartAdded-Attribut hinzufügen und diesem anschließend einen benutzerdefinierten Methodennamen zuweisen, um eine benutzerdefinierte Behandlung des Ereignisses bereitzustellen. Das Attribut entspricht der OnWebPartAdded-Methode, und dieses grundlegende Muster der Ereignisbehandlung gilt für die meisten Webparts-Ereignisse und die ihnen zugeordneten Methoden.

Zusätzlich verfügt das WebPartManager-Steuerelement über spezielle Methoden zur Verwaltung von WebPart-Steuerelementen (und als WebPart-Steuerelemente verwendeten Server- oder Benutzersteuerelementen). Dazu gehören die Methoden AddWebPart, AuthorizeWebPart, CloseWebPart, CopyWebPart, CreateWebPart, DeleteWebPart, DisconnectWebPart, BeginWebPartEditing, EndWebPartEditing, ExportWebPart, GetGenericWebPart, ImportWebPart, IsAuthorized und MoveWebPart.

Ein anderer Satz von Methoden ist speziell auf Verbindungen ausgerichtet. Dies umfasst beispielsweise die Methoden ActivateConnections, BeginWebPartConnecting, CanConnectWebParts, ConnectWebParts, CreateAvailableTransformers, DisconnectWebPart, DisconnectWebParts, EndWebPartConnecting, GetConsumerConnectionPoints und GetProviderConnectionPoints.

Schließlich erfüllen einige WebPartManager-Methoden Funktionen zur Personalisierung. Dazu gehören CreatePersonalization, LoadControlState, SaveCustomPersonalizationState, SetPersonalizationDirty, IPersonalizable.Load, IPersonalizable.Save und SaveControlState.

Informationen zu weiteren WebPartManager-Methoden, auf die durch die Internals-Eigenschaft zugegriffen werden kann, finden Sie in der Dokumentation zur WebPartManagerInternals-Klasse.

Das WebPartManager-Steuerelement ist so konzipiert, dass es erweitert werden kann. Da es von so zentraler Bedeutung für Webparts-Anwendungen ist, müssen Sie, wenn Sie einen bestimmten Typ oder ein bestimmtes Steuerelement im Webparts-Steuerelementsatz erweitern möchten, in vielen Fällen auch die WebPartManager-Klasse erweitern, da diese wahrscheinlich Eigenschaften oder Methoden enthält, die erforderlich sind, damit der benutzerdefinierte Typ im Kontext einer Webparts-Anwendung funktioniert. Wenn in der Webparts-Referenzdokumentation (siehe System.Web.UI.WebControls.WebParts) die Erweiterung eines Webparts-Typs behandelt wird, wird häufig auch dargestellt, wie darüber hinaus die WebPartManager-Klasse erweitert wird, bzw. die Erweiterung dieser Klasse wird in Codebeispielen veranschaulicht.

Im folgenden Codebeispiel werden die deklarative und die programmgesteuerte Verwendung des WebPartManager-Steuerelements veranschaulicht.

Das Codebeispiel besteht aus den folgenden vier Teilen:

• Ein Benutzersteuerelement, mit dessen Hilfe Sie die Anzeigemodi auf einer Webparts-Seite wechseln können.

• Einer Webseite, die zwei benutzerdefinierte WebPart-Steuerelemente, die verbunden werden können, und ein <asp:webpartmanager>-Element enthält.

• Einer Quellcodedatei, die zwei benutzerdefinierte WebPart-Steuerelemente und eine benutzerdefinierte Schnittstelle enthält.

• Einer Erläuterung zur Ausführung des Beispiels in einem Browser.

Das Benutzersteuerelement besitzt ein Dropdownlisten-Steuerelement mit den Anzeigemodi, die für eine Seite je nach auf ihr vorhandenen Webparts-Steuerelementen möglich sind. Auf der Webseite für dieses Codebeispiel wird dieses Benutzersteuerelement beispielsweise unmittelbar unter dem WebPartManager-Element im Markup der Seite deklariert, und im oberen Bereich der Webseite ist eine Register-Direktive zur Registrierung des Steuerelements. Ausführliche Informationen zu Anzeigemodi und eine Beschreibung des Quellcodes in diesem Steuerelement finden Sie unter Walkthrough: Changing Display Modes on a Web Parts Page.

<%@ control language="C#" classname="DisplayModeMenuCS"%>
<script runat="server">

 // Use a field to reference the current WebPartManager.
  WebPartManager _manager;

  void Page_Init(object sender, EventArgs e)
  {
    Page.InitComplete += new EventHandler(InitComplete);
  }  

  void InitComplete(object sender, System.EventArgs e)
  {
    _manager = WebPartManager.GetCurrentWebPartManager(Page);

    String browseModeName = WebPartManager.BrowseDisplayMode.Name;

    // Fill the dropdown with the names of supported display modes.
    foreach (WebPartDisplayMode mode in _manager.SupportedDisplayModes)
    {
      String modeName = mode.Name;
      // Make sure a mode is enabled before adding it.
      if (mode.IsEnabled(_manager))
      {
        ListItem item = new ListItem(modeName, modeName);
        DisplayModeDropdown.Items.Add(item);
      }
    }

    // If shared scope is allowed for this user, display the scope-switching
    // UI and select the appropriate radio button for the current user scope.
    if (_manager.Personalization.CanEnterSharedScope)
    {
      Panel2.Visible = true;
      if (_manager.Personalization.Scope == PersonalizationScope.User)
        RadioButton1.Checked = true;
      else
        RadioButton2.Checked = true;
    }

  }

  // Change the page to the selected display mode.
  void DisplayModeDropdown_SelectedIndexChanged(object sender, EventArgs e)
  {
    String selectedMode = DisplayModeDropdown.SelectedValue;

    WebPartDisplayMode mode = _manager.SupportedDisplayModes[selectedMode];
    if (mode != null)
      _manager.DisplayMode = mode;
  }

  // Set the selected item equal to the current display mode.
  void Page_PreRender(object sender, EventArgs e)
  {
    ListItemCollection items = DisplayModeDropdown.Items;
    int selectedIndex = 
      items.IndexOf(items.FindByText(_manager.DisplayMode.Name));
    DisplayModeDropdown.SelectedIndex = selectedIndex;
  }

  // Reset all of a user's personalization data for the page.
  protected void LinkButton1_Click(object sender, EventArgs e)
  {
    _manager.Personalization.ResetPersonalizationState();
  }

  // If not in User personalization scope, toggle into it.
  protected void RadioButton1_CheckedChanged(object sender, EventArgs e)
  {
    if (_manager.Personalization.Scope == PersonalizationScope.Shared)
      _manager.Personalization.ToggleScope();
  }

  // If not in Shared scope, and if user is allowed, toggle the scope.
  protected void RadioButton2_CheckedChanged(object sender, EventArgs e)
  {
    if (_manager.Personalization.CanEnterSharedScope && 
        _manager.Personalization.Scope == PersonalizationScope.User)
      _manager.Personalization.ToggleScope();
  }
</script>
<div>
  <asp:Panel ID="Panel1" runat="server" 
    Borderwidth="1" 
    Width="230" 
    BackColor="lightgray"
    Font-Names="Verdana, Arial, Sans Serif" >
    <asp:Label ID="Label1" runat="server" 
      Text="&nbsp;Display Mode" 
      Font-Bold="true"
      Font-Size="8"
      Width="120" 
      AssociatedControlID="DisplayModeDropdown"/>
    <asp:DropDownList ID="DisplayModeDropdown" runat="server"  
      AutoPostBack="true" 
      Width="120"
      OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
    <asp:LinkButton ID="LinkButton1" runat="server"
      Text="Reset User State" 
      ToolTip="Reset the current user's personalization data for the page."
      Font-Size="8" 
      OnClick="LinkButton1_Click" />
    <asp:Panel ID="Panel2" runat="server" 
      GroupingText="Personalization Scope"
      Font-Bold="true"
      Font-Size="8" 
      Visible="false" >
      <asp:RadioButton ID="RadioButton1" runat="server" 
        Text="User" 
        AutoPostBack="true"
        GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" />
      <asp:RadioButton ID="RadioButton2" runat="server" 
        Text="Shared" 
        AutoPostBack="true"
        GroupName="Scope" 
        OnCheckedChanged="RadioButton2_CheckedChanged" />
    </asp:Panel>
  </asp:Panel>
</div>

Das deklarative Markup für die Webseite enthält Register-Direktiven für das Benutzersteuerelement und die benutzerdefinierten Steuerelemente. Es sind ein <asp:webpartmanager>-Element, ein <asp:webpartzone>-Element, das als Container für die benutzerdefinierten Steuerelemente fungiert, sowie ein <asp:connectionszone>-Element vorhanden. Außerdem enthält die Seite Inlinecode, der Ereignisse für das WebPartManager-Steuerelement behandelt, die Verbindungen betreffen. Wenn Sie Steuerelemente verbinden bzw. die Verbindung von Steuerelementen trennen, können Sie feststellen, wie sich dieser Code auswirkt.

<%@ Page Language="C#" %>
<%@ register TagPrefix="uc1" 
  TagName="DisplayModeMenuCS" 
  Src="DisplayModeMenuCS.ascx" %>
<%@ register tagprefix="aspSample" 
  Namespace="Samples.AspNet.CS.Controls" 
  Assembly="ConnectionSampleCS" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">

  private void UpdateLabelData(int wpCount, int connCount)
  {
    Label1.Text = "WebPart Control Count:  " + wpCount.ToString();
    Label2.Text = "Connections Count: " + connCount.ToString();
  }

  protected void WebPartManager1_WebPartsConnected(object sender, WebPartConnectionsEventArgs e)
  {
    UpdateLabelData(WebPartManager1.WebParts.Count,
      WebPartManager1.Connections.Count);
  }

  protected void WebPartManager1_WebPartsDisconnected(object sender, WebPartConnectionsEventArgs e)
  {
    UpdateLabelData(WebPartManager1.WebParts.Count,
      WebPartManager1.Connections.Count);
  }

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
    <title>ASP.NET Example</title>
</head>
<body>
    <form id="form1" runat="server">
      <!-- Reference the WebPartManager control. -->
      <asp:WebPartManager ID="WebPartManager1" runat="server"  
        OnWebPartsConnected="WebPartManager1_WebPartsConnected" 
        OnWebPartsDisconnected="WebPartManager1_WebPartsDisconnected" />
    <div>
      <uc1:DisplayModeMenuCS ID="displaymode1" runat="server" />
      <!-- Reference consumer and provider controls in a zone. -->
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <aspSample:ZipCodeWebPart ID="zip1" 
            runat="server" 
            Title="Zip Code Control"/>
          <aspSample:WeatherWebPart ID="weather1" 
            runat="server" 
            Title="Weather Control" />
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Label ID="Label1" runat="server" Text=""></asp:Label>
      <br />
      <asp:Label ID="Label2" runat="server" Text=""></asp:Label>
      <!-- Add a ConnectionsZone so users can connect controls. -->
      <asp:ConnectionsZone ID="ConnectionsZone1" runat="server" />
    </div>
    </form>
</body>
</html>

Der dritte Teil des Beispiels ist der Quellcode für die Steuerelemente. Es ist eine Schnittstelle mit dem Namen IZipCode vorhanden, und diese Schnittstelle wird in der ZipCodeWebPart-Klasse implementiert. Diese Klasse verfügt über eine spezielle Rückrufmethode mit dem Namen ProvideIZipCode, die als Anbieter fungiert. Der andere Typ, der WeatherWebPart heißt, wird ebenfalls mit einer speziellen Methode mit dem Namen GetIZipCode implementiert, die es dem Steuerelement ermöglicht, als Consumer des anderen Steuerelements zu fungieren.

Wenn Sie das Codebeispiel ausführen möchten, müssen Sie diesen Quellcode kompilieren. Sie können den Code explizit kompilieren und die sich ergebende Assembly im Ordner Bin der Website oder im globalen Assemblycache ablegen. Alternativ können Sie den Quellcode im Ordner App_Code der Site ablegen, wo er zur Laufzeit dynamisch kompiliert wird. Für dieses Codebeispiel wird angenommen, dass Sie den Quellcode in eine Assembly kompiliert haben und dass die Register-Direktive auf der Webseite auf den Assemblynamen verweist. Eine exemplarische Vorgehensweise, in der die Kompilierung veranschaulicht wird, finden Sie unter Walkthrough: Developing and Using a Custom Server Control.

namespace Samples.AspNet.CS.Controls
{
  using System;
  using System.Web;
  using System.Web.Security;
  using System.Security.Permissions;
  using System.Web.UI;
  using System.Web.UI.WebControls;
  using System.Web.UI.WebControls.WebParts;

  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public interface IZipCode
  {
    string ZipCode { get; set;}
  }

  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class ZipCodeWebPart : WebPart, IZipCode
  {
    string zipCodeText = String.Empty;
    TextBox input;
    Button send;

    public ZipCodeWebPart()
    {
    }

    // Make the implemented property personalizable to save 
    // the Zip Code between browser sessions.
    [Personalizable()]
    public virtual string ZipCode
    {
      get { return zipCodeText; }
      set { zipCodeText = value; }
    }

    // This is the callback method that returns the provider.
    [ConnectionProvider("Zip Code")]
    public IZipCode ProvideIZipCode()
    {
      return this;
    }

    protected override void CreateChildControls()
    {
      Controls.Clear();
      input = new TextBox();
      this.Controls.Add(input);
      send = new Button();
      send.Text = "Enter 5-digit Zip Code";
      send.Click += new EventHandler(this.submit_Click);
      this.Controls.Add(send);
    }

    private void submit_Click(object sender, EventArgs e)
    {
      if (input.Text != String.Empty)
      {
        zipCodeText = Page.Server.HtmlEncode(input.Text);
        input.Text = String.Empty;
      }
    }

  }

  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class WeatherWebPart : WebPart
  {
    private IZipCode _provider;
    string _zipSearch;
    Label DisplayContent;

    // This method is identified by the ConnectionConsumer 
    // attribute, and is the mechanism for connecting with 
    // the provider. 
    [ConnectionConsumer("Zip Code")]
    public void GetIZipCode(IZipCode Provider)
    {
      _provider = Provider;
    }

    protected override void OnPreRender(EventArgs e)
    {
      EnsureChildControls();

      if (this._provider != null)
      {
        _zipSearch = _provider.ZipCode.Trim();
        DisplayContent.Text = "My Zip Code is:  " + _zipSearch;
      }
    }

    protected override void CreateChildControls()
    {
      Controls.Clear();
      DisplayContent = new Label();
      this.Controls.Add(DisplayContent);
    }

  }
}

Wählen Sie nach dem Laden der Webseite in einem Browser im Display Mode-Dropdownlisten-Steuerelement die Option Verbinden aus, um die Seite in den Verbindungsmodus umzuschalten. Im Verbindungsmodus ermöglicht das <asp:connectionszone>-Element das Erstellen von Verbindungen zwischen Steuerelementen. Klicken Sie im Verbindungsmodus auf der Titelleiste des Steuerelements ZIP Code auf den Pfeil nach unten, um dessen Verbenmenü zu aktivieren, und klicken Sie dann auf Verbinden. Daraufhin wird die Verbindungsbenutzeroberfläche angezeigt. Klicken Sie auf den Link Verbindung mit einem Consumer erstellen. Es wird eine Zelle mit einem Dropdownlisten-Steuerelement angezeigt. Wählen Sie in der Dropdownliste Weather Control aus, und klicken Sie dann auf Verbinden, um die Verbindung der beiden Steuerelemente zu erstellen. Klicken Sie auf Schließen, und schalten Sie die Seite über die Dropdownliste Display Mode in den normalen Durchsuchen-Modus zurück. Sie können eine Postleitzahl eingeben, und das Consumersteuerelement wird mit dem eingegebenen Wert aktualisiert. Da die ZipCode-Eigenschaft im Quellcode mit dem Personalizable-Attribut gekennzeichnet ist, wird dieser Wert über Browsersitzungen beibehalten, was dem Benutzer die erneute Eingabe erspart. Ein noch komplexeres Consumersteuerelement könnte beispielsweise auf der Grundlage der PLZ-Informationen Wetterdaten abrufen und anzeigen.

.NET Framework

Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core-Rolle wird nicht unterstützt), Windows Server 2008 R2 (Server Core-Rolle wird mit SP1 oder höher unterstützt; Itanium wird nicht unterstützt)

Referenz

Weitere Ressourcen