Edit

Share via

WebPartDescription Class

  • Reference

Definition

Namespace:
System.Web.UI.WebControls.WebParts
Assembly:
System.Web.dll

Provides information about a WebPart control that you can display in a catalog of Web Parts controls without having to create an instance of the control.

public ref class WebPartDescription
public class WebPartDescription
type WebPartDescription = class
Public Class WebPartDescription
Inheritance
Object
WebPartDescription

Examples

The following code example demonstrates programmatic use of the WebPartDescription class. Ordinarily, this type is used primarily by the Web Parts control set, but this code example is simply showing basic programmatic usage of the main description properties.

The code example has four parts:

  • A user control that enables users to change display modes on a Web page.

  • A custom WebPart control.

  • A Web page to host the other controls.

  • An explanation of how the code example works.

The first part of the code example is the user control. The source code for the user control comes from another topic. For more details about the user control, see the topic 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"/>
    <div>
    <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" />
    </div>
    <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>

<%@ control language="vb" classname="DisplayModeMenuVB"%>
<script runat="server">
  ' Use a field to reference the current WebPartManager.
  Dim _manager As WebPartManager

  Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs)
    AddHandler Page.InitComplete, AddressOf InitComplete
  End Sub

  Sub InitComplete(ByVal sender As Object, ByVal e As System.EventArgs)
    _manager = WebPartManager.GetCurrentWebPartManager(Page)
      
    Dim browseModeName As String = WebPartManager.BrowseDisplayMode.Name
      
    ' Fill the dropdown with the names of supported display modes.
    Dim mode As WebPartDisplayMode
    For Each mode In _manager.SupportedDisplayModes
      Dim modeName As String = mode.Name
      ' Make sure a mode is enabled before adding it.
      If mode.IsEnabled(_manager) Then
        Dim item As New ListItem(modeName, modeName)
        DisplayModeDropdown.Items.Add(item)
      End If
    Next mode
      
    ' 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 Then
      Panel2.Visible = True
      If _manager.Personalization.Scope = PersonalizationScope.User Then
        RadioButton1.Checked = True
      Else
        RadioButton2.Checked = True
      End If
    End If
   
  End Sub

  ' Change the page to the selected display mode.
  Sub DisplayModeDropdown_SelectedIndexChanged(ByVal sender As Object, _
    ByVal e As EventArgs)
    
    Dim selectedMode As String = DisplayModeDropdown.SelectedValue   
    Dim mode As WebPartDisplayMode = _
      _manager.SupportedDisplayModes(selectedMode)
    If Not (mode Is Nothing) Then
      _manager.DisplayMode = mode
    End If

  End Sub
   
  ' Set the selected item equal to the current display mode.
  Sub Page_PreRender(ByVal sender As Object, ByVal e As EventArgs)
    Dim items As ListItemCollection = DisplayModeDropdown.Items
    Dim selectedIndex As Integer = _
      items.IndexOf(items.FindByText(_manager.DisplayMode.Name))
    DisplayModeDropdown.SelectedIndex = selectedIndex

  End Sub

  ' Reset all of a user's personalization data for the page.
  Protected Sub LinkButton1_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
    
    _manager.Personalization.ResetPersonalizationState()
    
  End Sub

  ' If not in User personalization scope, toggle into it.
  Protected Sub RadioButton1_CheckedChanged(ByVal sender As Object, _
    ByVal e As EventArgs)
    
    If _manager.Personalization.Scope = PersonalizationScope.Shared Then
      _manager.Personalization.ToggleScope()
    End If

  End Sub
   
  ' If not in Shared scope, and if user is allowed, toggle the scope.
  Protected Sub RadioButton2_CheckedChanged(ByVal sender As Object, _
    ByVal e As EventArgs)
    
    If _manager.Personalization.CanEnterSharedScope AndAlso _
      _manager.Personalization.Scope = PersonalizationScope.User Then
      _manager.Personalization.ToggleScope()
    End If

  End Sub

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

The second part of the code example is a custom WebPart control. For the code example to run, you must compile this source code. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses the approach of dynamic compilation. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Web Server Control.

using System;
using System.Collections;
using System.ComponentModel;
using System.Drawing;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class TextDisplayWebPart : WebPart
  {
    private String _contentText = null;
    TextBox input;
    Label DisplayContent;
    Literal lineBreak;

    [Personalizable(), WebBrowsable]
    public String ContentText
    {
      get { return _contentText; }
      set { _contentText = value; }
    }

    protected override void CreateChildControls()
    {
      Controls.Clear();
      DisplayContent = new Label();
      DisplayContent.BackColor = Color.LightBlue;
      DisplayContent.Text = this.ContentText;
      this.Controls.Add(DisplayContent);

      lineBreak = new Literal();
      lineBreak.Text = @"<br />";
      Controls.Add(lineBreak);

      input = new TextBox();
      this.Controls.Add(input);
      Button update = new Button();
      update.Text = "Set Label Content";
      update.Click += new EventHandler(this.submit_Click);
      this.Controls.Add(update);
    }

    private void submit_Click(object sender, EventArgs e)
    {
      // Update the label string.
      if (!string.IsNullOrEmpty(input.Text))
      {
        _contentText = input.Text + @"<br />";
        input.Text = String.Empty;
        DisplayContent.Text = this.ContentText;
      }
    }
  }
}

Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class TextDisplayWebPart
    Inherits WebPart
    Private _contentText As String = Nothing
    Private _fontStyle As String = Nothing
    Private input As TextBox
    Private DisplayContent As Label
    Private lineBreak As Literal

    <Personalizable(), WebBrowsable()> _
    Public Property ContentText() As String
      Get
        Return _contentText
      End Get
      Set(ByVal value As String)
        _contentText = value
      End Set
    End Property

    Protected Overrides Sub CreateChildControls()
      Controls.Clear()
      DisplayContent = New Label()
      DisplayContent.BackColor = Color.LightBlue
      DisplayContent.Text = Me.ContentText
      Me.Controls.Add(DisplayContent)

      lineBreak = New Literal()
      lineBreak.Text = "<br />"
      Controls.Add(lineBreak)

      input = New TextBox()
      Me.Controls.Add(input)
      Dim update As New Button()
      update.Text = "Set Label Content"
      AddHandler update.Click, AddressOf Me.submit_Click
      Me.Controls.Add(update)

    End Sub

    Private Sub submit_Click(ByVal sender As Object, _
                             ByVal e As EventArgs)
      ' Update the label string.
      If input.Text <> String.Empty Then
        _contentText = input.Text + "<br />"
        input.Text = String.Empty
        DisplayContent.Text = Me.ContentText
      End If

    End Sub

  End Class

End Namespace

The third part of the code example is the Web page. Near the top are two Register directives: one that registers the user control, and the other to register the custom WebPart control whose source file is located in the App_Code folder of your site. The page contains an <asp:catalogzone> element, which in turn contains declarative references to two controls: the custom WebPart control named TextDisplayWebPart, and a BulletedList Web server control that will be treated as a WebPart control at run time because the WebPartManager control will wrap it with a GenericWebPart object. Note that in the code for the Button1_Click method, the available WebPartDescription objects for the WebPart controls in the catalog are retrieved using the GetAvailableWebPartDescriptions method, and then the description details are all written out to the page.

<%@ Page Language="C#" %>
<%@ Register TagPrefix="uc1"
    TagName="DisplayModeMenuCS"
    Src="~/DisplayModeMenuCS.ascx" %>
<%@ Register TagPrefix="aspSample" 
    Namespace="Samples.AspNet.CS.Controls"%>

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

<script runat="server">

  // <snippet2>
  protected void Button1_Click(object sender, EventArgs e)
  {
    Label1.Text = String.Empty;
    
    WebPartDescriptionCollection descriptions = 
      DeclarativeCatalogPart1.GetAvailableWebPartDescriptions();

    foreach (WebPartDescription desc in descriptions)
    {
      Label1.Text += "ID: " + desc.ID + "<br />" +
        "Title: " + desc.Title + "<br />" +
        "Description: " + desc.Description + "<br />" +
        "ImageUrl: " + desc.CatalogIconImageUrl + "<br />" +
        "<hr />";
    }
  }
  // </snippet2>

  protected void Page_PreRender(object sender, EventArgs e)
  {
    if (mgr1.DisplayMode == WebPartManager.CatalogDisplayMode)
    {
      Button1.Visible = true;
      Label1.Visible = true;
    }
    else
    {
      Button1.Visible = false;
      Label1.Visible = false;
    }
  }
</script>

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
  <title>Untitled Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <asp:WebPartManager ID="mgr1" runat="server">
    </asp:WebPartManager>
    <uc1:DisplayModeMenuCS ID="menu1" runat="server" />
    <asp:WebPartZone ID="WebPartZone1" runat="server">
      <ZoneTemplate>
        <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
      </ZoneTemplate>
    </asp:WebPartZone>
    <asp:CatalogZone ID="CatalogZone1" runat="server">
      <ZoneTemplate>
        <asp:DeclarativeCatalogPart ID="DeclarativeCatalogPart1" runat="server">
          <WebPartsTemplate>
            <aspSample:TextDisplayWebPart ID="txtDisplayWebPart1" runat="server"
              Title="Text Display"
              Description="Displays entered text in a label control."
              CatalogIconImageUrl="MyWebPartIcon.gif" 
              />
            <asp:BulletedList 
              ID="BulletedList1"
              Runat="server"
              DisplayMode="HyperLink" 
              Title="Favorite Links"
              CatalogIconImageUrl="MyLinksIcon.gif"
              Description="My Favorite Links">
              <asp:ListItem Value="http://msdn.microsoft.com">
                MSDN
              </asp:ListItem>
              <asp:ListItem Value="http://www.asp.net">
                ASP.NET
              </asp:ListItem>
              <asp:ListItem Value="http://www.msn.com">
                MSN
              </asp:ListItem>
            </asp:BulletedList>
          </WebPartsTemplate>
        </asp:DeclarativeCatalogPart>
      </ZoneTemplate>
    </asp:CatalogZone> 
    <hr />
    <asp:Button ID="Button1" runat="server" 
      Text="List WebPartDescription Info" OnClick="Button1_Click" /> 
    <br />
    <asp:Label ID="Label1" runat="server" Text="" />
    <div>
    </div>
  </form>
</body>
</html>

<%@ Page Language="vb" %>
<%@ Register TagPrefix="uc1"
    TagName="DisplayModeMenuVB"
    Src="~/DisplayModeMenuVB.ascx" %>
<%@ Register TagPrefix="aspSample" 
    Namespace="Samples.AspNet.VB.Controls"%>

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

<script runat="server">

  ' <snippet2>
  Protected Sub Button1_Click(ByVal sender As Object, _
    ByVal e As System.EventArgs)
    
    Label1.Text = String.Empty
        
    Dim descriptions As WebPartDescriptionCollection = _
     DeclarativeCatalogPart1.GetAvailableWebPartDescriptions()
            
    Dim desc As WebPartDescription
        
    For Each desc In descriptions
      Label1.Text += "ID: " & desc.ID & "<br />" & _
        "Title: " & desc.Title & "<br />" & _
        "Description: " & desc.Description & "<br />" & _
        "ImageUrl: " & desc.CatalogIconImageUrl & "<br />" & _
        "<hr />"
    Next
    
  End Sub
  ' </snippet2>

  Protected Sub Page_PreRender(ByVal sender As Object, _
    ByVal e As System.EventArgs)
        
    If mgr1.DisplayMode Is WebPartManager.CatalogDisplayMode Then
      Button1.Visible = True
      Label1.Visible = True
    Else
      Button1.Visible = False
      Label1.Visible = False
    End If
        
  End Sub


</script>

<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" runat="server">
  <title>Untitled Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <asp:WebPartManager ID="mgr1" runat="server">
    </asp:WebPartManager>
    <uc1:DisplayModeMenuVB ID="menu1" runat="server" />
    <asp:WebPartZone ID="WebPartZone1" runat="server">
      <ZoneTemplate>
        <asp:Calendar ID="Calendar1" runat="server"></asp:Calendar>
      </ZoneTemplate>
    </asp:WebPartZone>
    <asp:CatalogZone ID="CatalogZone1" runat="server">
      <ZoneTemplate>
        <asp:DeclarativeCatalogPart ID="DeclarativeCatalogPart1" runat="server">
          <WebPartsTemplate>
            <aspSample:TextDisplayWebPart ID="txtDisplayWebPart1" runat="server"
              Title="Text Display"
              Description="Displays entered text in a label control."
              CatalogIconImageUrl="MyWebPartIcon.gif" 
              />
            <asp:BulletedList 
              ID="BulletedList1"
              Runat="server"
              DisplayMode="HyperLink" 
              Title="Favorite Links"
              CatalogIconImageUrl="MyLinksIcon.gif"
              Description="My Favorite Links">
              <asp:ListItem Value="http://msdn.microsoft.com">
                MSDN
              </asp:ListItem>
              <asp:ListItem Value="http://www.asp.net">
                ASP.NET
              </asp:ListItem>
              <asp:ListItem Value="http://www.msn.com">
                MSN
              </asp:ListItem>
            </asp:BulletedList>
          </WebPartsTemplate>
        </asp:DeclarativeCatalogPart>
      </ZoneTemplate>
    </asp:CatalogZone> 
    <hr />
    <asp:Button ID="Button1" runat="server" 
      Text="List WebPartDescription Info" OnClick="Button1_Click" /> 
    <br />
    <asp:Label ID="Label1" runat="server" Text="" />
    <div>
    </div>
  </form>
</body>
</html>

After you load the page in a browser, use the Display Mode drop-down list control and select Catalog to change the page to catalog display mode. In the catalog, you should see the two controls that are available to be added to the page. Click the List WebPartDescription Information button, and the code writes out the values of all available WebPartDescription objects to the page. This demonstrates that you can retrieve description details for WebPart controls in a catalog without having to create instances of the controls themselves.

Remarks

When WebPart controls are displayed in a catalog of controls that users can add to a page, some basic information about each control is required. For example, it is useful to have a title for the control, and a description, so that as users view a catalog they have enough information to decide whether to add a control to the page. However, a catalog of WebPart controls can potentially contain many controls, and it could affect the performance of an application if an instance of every WebPart control must be created to extract the information to display in the catalog.

The WebPartDescription class exists so that it is not necessary to create an instance of a WebPart control to retrieve the information about the control that is displayed in a catalog of controls. In the Web Parts control set, a WebPartDescription object is also used in conjunction with the various CatalogPart controls when a page is in catalog display mode.

The WebPartDescription class has two overloads of its constructor, one that takes a WebPart control as a parameter when an instance is available (the WebPartDescription constructor), and one that takes several strings with information about the control as parameters (the WebPartDescription constructor).

The WebPartDescription class also has several properties designed to contain the description information for WebPart controls. The following table summarizes the WebPartDescription properties, and what property each one corresponds to in a WebPart control.

Description property Related part control property
ID ID
Title Title
Description Description
CatalogIconImageUrl CatalogIconImageUrl

Constructors

WebPartDescription(String, String, String, String)

Initializes a new instance of the class by using several strings that contain description information for a WebPart control.
WebPartDescription(WebPart)

Initializes a new instance of the class when a WebPart control instance is available.

Properties

CatalogIconImageUrl

Gets a URL containing the path to an image used as an icon for a WebPart control.
Description

Gets the text of a description for a WebPart control.
ID

Gets the ID of a corresponding WebPart control.
Title

Gets the title text of a corresponding WebPart control.

Methods

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetType()

Gets the Type of the current instance.

(Inherited from Object)
MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
ToString()

Returns a string that represents the current object.

(Inherited from Object)

Applies to

See also