Export (0) Print
Expand All

GenericWebPart Class

Note: This class is new in the .NET Framework version 2.0.

Wraps server controls that are not WebPart controls so that they can appear and behave as true WebPart controls at run time.

Namespace: System.Web.UI.WebControls.WebParts
Assembly: System.Web (in system.web.dll)

public class GenericWebPart : WebPart
public class GenericWebPart extends WebPart
public class GenericWebPart extends WebPart

The GenericWebPart control exists to provide a run-time wrapper for server controls that are not WebPart controls, so that such controls can be used in Web Parts pages and applications. When developers add server controls--such as user controls, ASP.NET server controls, or existing custom controls--to a WebPartZoneBase control, the GenericWebPart control automatically wraps the server controls at run time so they can exhibit the same functionality as true WebPart controls.

The following table compares and contrasts GenericWebPart controls and WebPart controls.

GenericWebPart control

WebPart control

Exists to equip server controls that are not WebPart controls with Web Parts functionality, so that any ASP.NET, custom, or user control can participate in Web Parts applications.

Exists to create custom ASP.NET controls that have native Web Parts functionality built in. This includes personalization, connections, import and export, and drag-and-drop capabilities.

Is never declared in the markup of a page. It exists only to wrap server controls at run time, and to give the wrapped control (or child control) the full functionality of a WebPart control.

Can be declared in the markup of a page at design time, like an ASP.NET server control, except that it is declared in a WebPartZoneBase zone.

Includes and integrates its child control into the Web Parts personalization process so that it can act as a true WebPart control. This occurs automatically, which makes it simple for developers to use server controls and user controls in Web Parts applications.

Is automatically included in the Web Parts personalization process.

Can be accessed programmatically at run time (by using the GetGenericWebPart method and passing to it the child server control), like a true WebPart control or a standard ASP.NET control.

Can be accessed programmatically at run time, like a standard ASP.NET control.

Users benefit from the GenericWebPart control because it provides a consistent user experience. Any server control can be made to function like a WebPart control, and will have the same consistent user interface (UI) elements such as verbs, icons, a title, and a header. Developers benefit from the GenericWebPart control because it enables them to reuse existing user controls and server controls within Web Parts applications.

NoteNote

When you create Web Parts pages, you do not have to do anything to enable an existing user control or custom control to be wrapped with the GenericWebPart control. Simply add your server or user control to a WebPartZoneBase zone, either programmatically or by declaring it in the page's markup, and the Web Parts control set automatically wraps your control with a GenericWebPart object at run time.

Because server controls that are placed in WebPartZoneBase zones are wrapped with a GenericWebPart control at run time, developers can use ordinary server and user controls exactly as if they were WebPart controls. Note that, if you declare custom controls that inherit from the base Control class within a WebPartZone, these controls cannot support the use of the intrinsic WebPart properties. Thus, you cannot declare the IWebPart properties on such controls, including properties such as the Title property and the Description property. In contrast, other types of server controls (such as WebPart controls, user controls, and custom controls that inherit from WebControl) can declare these properties, because they support the use of expando properties.

Expando properties are actually strings that can be added to a class dynamically as a property, by means of the IAttributeAccessor interface. Controls that implement this interface, including the WebControl class and its children, can use expando properties. Because the base Control class does not support expando properties, when a custom control that inherits from the Control class is placed in a WebPartZone and wrapped with a GenericWebPart control at run time, the Web Parts control set cannot dynamically add the intrinsic IWebPart properties to the custom control. You have two choices in this case. You can use the custom control without the IWebPart properties, or you can implement the IWebPart interface in the custom control, enabling it to use the properties.

As an example of how controls that inherit from WebControl can use the IWebPart properties, if you declare an ASP.NET Calendar control in the markup of a page (within a WebPartZoneBase zone) at design time, even though this control does not inherit from the WebPart class and does not natively contain WebPart members, you can still treat it exactly like a WebPart control. You can declare WebPart properties on the calendar control, such as Title, Description, and others. At run time, you can use the GetGenericWebPart method, which returns the GenericWebPart control that is dynamically wrapping the calendar control, and work with it programmatically exactly as you would with a WebPart control, with access to all the same properties, events, and methods.

The GenericWebPart control has a critical property that allows you to access its underlying server control: the ChildControl property. This property allows developers to programmatically access the server control. The ChildControl property is also used by the WebPartManager control to access personalization data from the child control, and to perform authorization, if the AuthorizationFilter property is set.

The GenericWebPart control has several other properties, all of which override properties inherited from the base WebPart class. As noted, you can use these properties with any child control, so that it can behave as a WebPart control. One important property is the ExportMode property; it determines whether all the exportable properties, or only those marked as non-sensitive, can be exported. The UI-oriented properties inherited from the WebPart class, such as CatalogIconImageUrl, Description, Height, Title, TitleUrl, and Width, can be set in the declarative markup for any server control that is placed in a WebPartZoneBase zone.

Important methods in the GenericWebPart class include the CreateControlCollection method, which creates the collection of controls (including child controls) associated with a GenericWebPart control, and the Render method, which delegates all rendering to the wrapped child controls. The constructors on the GenericWebPart class are protected and are intended either for internal use or for extensibility scenarios.

There are some additional helpful insights for working with GenericWebPart controls. If you want to set default values for the overridden properties in the GenericWebPart class, your user control or custom server control can implement the IWebPart and IWebActionable interfaces, and override their members. At run time, the GenericWebPart control will get its values for the implemented properties from the child control that implements the interfaces. If your control defines any of its properties as personalizable (by using the Personalizable metadata attribute), the GenericWebPart control automatically enables those properties for personalization at run time, just like the personalizable properties on a WebPart control.

If you want to provide Web Parts editing features for your control, you can implement the IWebEditable interface. At run time, when the CreateEditorParts method is called, the GenericWebPart control's code for the WebBrowsableObject property will call into the same property in the child control, and use the child control's implementation to create associated custom EditorPart controls.

Notes to Inheritors There are few occasions where it is necessary to inherit from the GenericWebPart class. One such case would be if a developer wants to implement some custom action in the constructor when a GenericWebPart control is created. For example, you might want to store the child control somewhere other than the control collection within the GenericWebPart class. If you inherit from the GenericWebPart class, you also need to inherit from the WebPartManager class and override its CreateWebPart method to enable it to create your custom control.

TopicLocation
How to: Export Web Parts Control SettingsBuilding ASP .NET Web Applications
How to: Treat a User Control as a Web Parts ControlBuilding ASP .NET Web Applications
How to: Treat a User Control as a Web Parts ControlBuilding ASP .NET Web Applications
How to: Export Web Parts Control SettingsBuilding ASP .NET Web Applications

The following code example demonstrates how the GenericWebPart control automatically wraps a server control that is not a WebPart control at run time.

The first part of the code example contains a Web Parts page with two WebPartZone controls. Within each zone is a standard ASP.NET server control. Because the controls are in a WebPartZone zone, they will be automatically wrapped with a GenericWebPart control when the page is compiled. So, you can declare WebPart class properties on these controls. After you load the page in a browser, if you click the Display All Property Values button, the details for each control are displayed in a label. To show how the GenericWebPart control works, the Calendar control in the first zone has some of the GenericWebPart properties set in the declarative markup of the .aspx page, whereas the BulletedList control does not. After you load the page, note the differences in the property values for the two controls, and that both have a parent GenericWebPart control.

<%@ Page Language="C#" 
  Codefile="genericwebpart.cs" 
  Inherits="genericwebpart_sample" %>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>GenericWebPart Example</title>
</head>
<body>
    <form id="form1" runat="server">
      <asp:WebPartManager ID="WebPartManager1" runat="server">
      </asp:WebPartManager>
      <asp:WebPartZone ID="WebPartZone1" runat="server">
        <ZoneTemplate>
          <asp:Calendar ID="Calendar1" runat="server"
            Title="My Calendar"
            Description="A calendar used as a GenericWebPart control."
            CatalogIconImageUrl="MyCatalogIcon.gif"
            TitleIconimageUrl ="MyTitleIcon.gif"
            TitleUrl="MyInfoUrl.htm" 
            Width="250"/>
        </ZoneTemplate>
      </asp:WebPartZone>
      <asp:WebPartZone ID="WebPartZone2" runat="server">
        <ZoneTemplate>
          <asp:BulletedList ID="BulletedList1" 
            Runat="server"
            DisplayMode="HyperLink">
            <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>        
        </ZoneTemplate>
      </asp:WebPartZone>
      <hr />
      <asp:Button ID="Button1" width="200"
        runat="server" 
        Text="Display All Property Values" OnClick="Button1_Click" /> 
      <br />
      <asp:Label ID="Label2" runat="server" Text="" />
      <br />   
      <asp:Label ID="Label3" runat="server" Text="" />
    </form>
</body>
</html>

The second part of the code example shows a partial class that accesses some properties of the GenericWebPart control programmatically. Notice that in the Page_Load method, the GetGenericWebPart method is used to retrieve the run-time instance of the GenericWebPart control that wraps a server control. This approach of getting a reference to the parent GenericWebPart control enables you to work programmatically with an ordinary server or user control as if it were a WebPart control at run time.

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

public partial class genericwebpart_sample : System.Web.UI.Page
{
  GenericWebPart calendarPart;
  GenericWebPart listPart;

  protected void Page_Load(Object sender, EventArgs e)
  {
    calendarPart = WebPartManager1.GetGenericWebPart(Calendar1);
    listPart = WebPartManager1.GetGenericWebPart(BulletedList1);

    if (!IsPostBack)
    {
      Label2.Text = String.Empty;
      Label3.Text = String.Empty;
    }
  }

  protected void Button1_Click(object sender, EventArgs e)
  {

    Label2.Text =
      @"<h3>Calendar GenericWebPart Properties</h3>" +
      "<em>Title: </em>" + calendarPart.Title +
      "<br />" +
      "<em>CatalogIconImageUrl:  </em>" + calendarPart.CatalogIconImageUrl +
      "<br />" +
      "<em>TitleUrl: </em>" + calendarPart.TitleUrl +
      "<br />" +
      "<em>Decription: </em>" + calendarPart.Description +
      "<br />" +
      "<em>TitleIconImageUrl: </em>" + calendarPart.TitleIconImageUrl +
      "<br />" +
      "<em>ChildControl ID: </em>" + calendarPart.ChildControl.ID +
      "<br />" +
      "<em>ChildControl Type: </em>" + calendarPart.ChildControl.GetType().Name +
      "<br />" +
      "<em>GenericWebPart ID: </em>" + calendarPart.ID +
      "<br />" +
      "<em>GenericWebPart Type: </em>" + calendarPart.GetType().Name +
      "<br />" +
      "<em>GenericWebPart Parent ID: </em>" + calendarPart.Parent.ID;

    Label3.Text =
      @"<h3>BulletedList GenericWebPart Properties</h3>" +
      "<em>Title: </em>" + listPart.Title +
      "<br />" +
      "<em>CatalogIconImageUrl:  </em>" + listPart.CatalogIconImageUrl +
      "<br />" +
      "<em>TitleUrl: </em>" + listPart.TitleUrl +
      "<br />" +
      "<em>Decription: </em>" + listPart.Description +
      "<br />" +
      "<em>TitleIconImageUrl: </em>" + listPart.TitleIconImageUrl +
      "<br />" +
      "<em>ChildControl ID: </em>" + listPart.ChildControl.ID +
      "<br />" +
      "<em>ChildControl Type: </em>" + listPart.ChildControl.GetType().Name +
      "<br />" +
      "<em>GenericWebPart ID: </em>" + listPart.ID +
      "<br />" +
      "<em>GenericWebPart Type: </em>" + listPart.GetType().Name +
      "<br />" +
      "<em>GenericWebPart Parent ID: </em>" + listPart.Parent.ID;
  }

}

System.Object
   System.Web.UI.Control
     System.Web.UI.WebControls.WebControl
       System.Web.UI.WebControls.Panel
         System.Web.UI.WebControls.WebParts.Part
           System.Web.UI.WebControls.WebParts.WebPart
            System.Web.UI.WebControls.WebParts.GenericWebPart

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows 2000 SP4, Windows Millennium Edition, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft