WebPartManager Class

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

Serves as the central class of the Web Parts control set, managing all the Web Parts controls, functionality, and events that occur on a Web page.

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

public ref class WebPartManager : public Control, INamingContainer, IPersonalizable
/** @attribute BindableAttribute(false) */ 
public class WebPartManager extends Control implements INamingContainer, IPersonalizable
public class WebPartManager extends Control implements INamingContainer, IPersonalizable

The WebPartManager control acts as the hub or control center of a Web Parts application. There must be one--and only one--WebPartManager control instance on every page that uses Web Parts controls. As with most aspects of Web Parts applications, the WebPartManager control works only with authenticated users. Further, its functionality works almost entirely with server controls that reside within Web Parts zones that inherit from the WebZone class. Server controls that reside on a page outside of these zones can have very little Web Parts functionality or interaction with the WebPartManager control.

As the hub for Web Parts functionality on a page, the WebPartManager control carries out the kinds of tasks described in the following table.

Task category

What the control does

Tracking Web Parts controls

Keeps track of the many different kinds of controls on a page that provide Web Parts features, including WebPart controls, connections, zones, and others.

Adding and removing Web Parts controls

Provides the methods for adding, deleting, and closing WebPart controls on a page.

Administering connections

Creates connections between controls, and monitors the connections as well as the processes of adding and removing them.

Personalizing controls and pages

Enables users to move controls to different locations on a page, and launches the views in which users can edit the appearance, properties, and behavior of controls. Maintains user-specific personalization settings on each page.

Toggling between different page views

Switches a page among different specialized views of the page, so that users can carry out certain tasks such as changing page layout or editing controls.

Raising Web Parts life-cycle events

Defines, raises, and enables developers to handle life-cycle events of Web Parts controls, such as when controls are being added, moved, connected, or deleted.

Enabling import and export of controls

Exports XML streams that contain the state of the properties of WebPart controls, and allows users to import the files for convenience in personalizing complex controls in other pages or sites.

The WebPartManager class has a large set of properties. Consistent with the WebPartManager role of tracking other controls, it has a number of properties that reference collections of either Web Parts controls, or other special Web Parts objects. The AvailableTransformers, Connections, Controls, DisplayModes, DynamicConnections, SupportedDisplayModes, WebParts, and Zones properties are all collections used by the WebPartManager control for its tracking and other management tasks.

Another group of properties contains customizable warnings that apply in certain scenarios that occur in a Web Parts application. These include the CloseProviderWarning, the DeleteWarning, and the ExportSensitiveDataWarning properties.

The WebPartManager class overrides some of its base inherited properties, which are used by many Web server controls. These include the EnableTheming, SkinID, and Visible properties.

Finally, there is a group of properties useful for accessing the current state of the application. The DisplayMode property indicates the current display mode that a page is in. The EnableClientScript property indicates whether a control is allowed to render client-side script, which is relevant in situations where users might have browsers with different capabilities or have scripting turned off. The Internals property is useful for referencing a utility class that contains the calls to a number of important Web Parts methods that are used for extensibility cases. By hiding the calls to these methods in a separate class (the WebPartManagerInternals class), the WebPartManager class's own API is simplified. The Personalization property provides access to the personalization objects that store users' personalization settings and persist that data to permanent storage. The SelectedWebPart property indicates which WebPart control on a page is currently selected by the user or the application. The System.Web.UI.WebControls.WebParts.IPersonalizable.IsDirty property indicates whether custom personalization data on a WebPart control has changed.

The WebPartManager control contains five built-in display modes, or views of a Web page. Developers can extend this feature, creating custom display modes by extending types such as the WebZone class or the ToolZone class. Users can switch a page into the various display modes, provided that the proper kind of controls that correspond to a given display mode are present on a page.


It is possible to extend this feature so that users can switch into a custom display mode without having a corresponding zone on the page. However, the default behavior is that display modes correspond to zones.

The standard display modes are represented by public fields in the WebPartManager class. The following table summarizes the fields and the display modes they refer to. The current display mode of a page, as noted above, is always referenced in the DisplayMode property, and the set of display modes that is possible on a particular page, given the kind of zones that are present on the page, is contained in the SupportedDisplayModes property.


Display mode details


The normal user view of a Web page; the default and most common display mode.


The view in which users can rearrange or delete controls to change the page layout.


The view in which an editing user interface (UI) becomes visible; users can edit the appearance, properties, and behavior of the controls that are visible in the normal browse mode.


The view in which a catalog UI becomes visible; users can add controls to a page from catalogs of available controls.


The view in which a connection UI becomes visible; users can connect, manage, or disconnect connections between controls.

The WebPartManager control also contains a number of events that are critical in the life cycle of Web Parts pages and controls. These events provide precise programmatic control over the behavior of Web Parts controls. Most methods pertain directly to WebPart controls (or other server or user controls that are placed in WebPartZoneBase zones so that they can behave as WebPart controls). However, a few events pertain to the state of the page or connections on the page. The following table lists the available events and summarizes their purposes.


In all cases in the following table, the word "control" refers to a WebPart control or any server control that resides in a zone and is wrapped with a GenericWebPart object at run time.




Occurs just before a control is added to a page to verify that it is authorized.


Occurs after all the connections on a page have been activated.


Occurs just before the process of activating all the connections on a page.


Occurs after the current display mode of a page has changed.


Occurs just before the process of changing a page's display mode.


Occurs after the selection of a control has been canceled.


Occurs just before the process of canceling the selection of a control.


Occurs after a control has been added to a zone.


Occurs just before the process of adding a control to a zone.


Occurs after a control has been closed (removed from a page).


Occurs just before the process of closing a control.


Occurs after an instance of a dynamic control (one that was created programmatically or added from a catalog) has been permanently deleted.


Occurs just before the process of deleting a dynamic control.


Occurs after a control has moved within its zone or to another zone.


Occurs just before the process of moving a control.


Occurs after two controls selected for participation in a connection have established the connection.


Occurs just before the process of connecting two controls.


Occurs after two connected controls have been disconnected.


Occurs just before the process of disconnecting two controls.

The WebPartManager control has numerous methods for managing Web Parts pages. A large set of the methods, not listed here, are methods whose names take the form of OnEventName. These methods typically raise their associated event, and provide the event with a handler of type WebPartEventHandler. Most of these methods can be overridden by developers who inherit from the WebPartManager class. Also, page developers can provide custom handlers for the events associated with these methods. For example, in the case of the WebPartAdded event, a page developer could add an OnWebPartAdded attribute to the <asp:webpartmanager> element in the markup of a Web page, and then assign a custom method name to the attribute to provide custom handling for the event. The attribute corresponds to the OnWebPartAdded method, and this basic pattern of event handling works for most Web Parts events and their associated methods.

In addition, the WebPartManager control has methods particular to the task of managing WebPart controls (and server or user controls used as WebPart controls). These methods include AddWebPart, AuthorizeWebPart, CloseWebPart, CopyWebPart, CreateWebPart, DeleteWebPart, DisconnectWebPart, BeginWebPartEditing, EndWebPartEditing, ExportWebPart, GetGenericWebPart, ImportWebPart, IsAuthorized, and MoveWebPart.

Another set of methods is specialized for connections. This includes methods such as ActivateConnections, BeginWebPartConnecting, CanConnectWebParts, ConnectWebParts, CreateAvailableTransformers, DisconnectWebPart, DisconnectWebParts, EndWebPartConnecting, GetConsumerConnectionPoints, and GetProviderConnectionPoints.

Finally, some WebPartManager methods focus on personalization functionality. These include CreatePersonalization, LoadControlState, SaveCustomPersonalizationState, SetPersonalizationDirty, System.Web.UI.WebControls.WebParts.IPersonalizable.Load, System.Web.UI.WebControls.WebParts.IPersonalizable.Save, and SaveControlState.

For more information on other WebPartManager methods that are accessible through the Internals property, see the documentation for the WebPartManagerInternals class.

Notes to Inheritors The WebPartManager control is designed to be extended. Because it is so central to Web Parts applications, when you want to extend some specific type or control in the Web Parts control set, in many cases you must also extend the WebPartManager class, because it is likely to have some property or method that is required to make your custom type work in the context of a Web Parts application. The Web Parts reference documentation (see System.Web.UI.WebControls.WebParts), when discussing how to extend a Web Parts type, frequently mentions what needs to be done to extend the WebPartManager class as well, or shows how to extend it in a code example.

How to: Declare a Static Connection between Two Web Parts ControlsBuilding ASP .NET Web Applications
How to: Disable Web Parts PersonalizationBuilding ASP .NET Web Applications
How to: Declare a Static Connection between Two Web Parts ControlsBuilding ASP .NET Web Applications
How to: Disable Web Parts PersonalizationBuilding ASP .NET Web Applications

The following code example demonstrates both declarative and programmatic use of the WebPartManager control.

The code example has four parts:

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

  • A Web page that contains two custom WebPart controls that can be connected, and an <asp:webpartmanager> element.

  • A source code file that contains two custom WebPart controls, and a custom interface.

  • An explanation of how the example works in a browser.

The user control has a drop-down list control that shows the possible display modes on a page, given the Web Parts controls that are present on the page. In the Web page for this code example, this user control is declared just below the WebPartManager element in the page's markup, and there is a Register directive near the top of the Web page to register the control. For details about display modes and a description of the source code in this control, see Walkthrough: Changing Display Modes on a Web Parts Page.

No code example is currently available or this language may not be supported.

The declarative markup for the Web page contains Register directives for both the user control and the custom controls. There is an <asp:webpartmanager> element, an <asp:webpartzone> element to contain the custom controls, and an <asp:connectionszone> element. The page also contains some inline code that handles connection-related events for the WebPartManager control; you can see the effect of this code as you connect and disconnect controls.

No code example is currently available or this language may not be supported.

The third part of the example is the source code for the controls. Note that there is an interface named IZipCode, and this interface is implemented in the ZipCodeWebPart class. This class has a special callback method named ProvideIZipCode that serves as a provider. The other type, named WeatherWebPart, is also implemented with a special method named GetIZipCode, which enables the control to act as a consumer of the other 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 assumes that you have compiled the source into an assembly, and the Register directive in the Web page references the assembly name. For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Server Control.

No code example is currently available or this language may not be supported.

After you have loaded the Web page in a browser, click the Display Mode drop-down list control and select Connect to switch the page to connect mode. Connect mode uses the <asp:connectionszone> element to enable you to create connections between controls. In connect mode, click the downward arrow in the title bar of the ZIP Code control to activate its verbs menu, and then click Connect. After the connection UI appears, click the Create a connection to a Consumer link. A cell appears that has a drop-down list control. Select Weather Control in the drop-down list, and then click Connect to complete the connection of the two controls. Click Close, and then use the Display Mode drop-down list to return the page to normal browse mode. You can enter a ZIP Code, and the consumer control will be updated with the value you enter. Because the ZipCode property was marked with the Personalizable attribute in the source code, this property value will persist across browser sessions, thus saving the value entered by a user. A more sophisticated consumer control could take the ZIP code information, look up weather information based on the code, and display it to a user.

  • AspNetHostingPermission  for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.
  • AspNetHostingPermission  for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.


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