Using ASP.NET Server Controls in Web Parts Applications
In a Web Parts application, the primary user interface (UI) consists of ASP.NET server controls that reside within zones--regions on a Web page that have a common UI and are created by a type of composite control derived from the WebPartZoneBase class. The capabilities of these server controls that form the primary UI of a Web Parts application are defined in the base WebPart class, but you are not limited to using controls that derive from this class. You can also use any standard ASP.NET server control, user control, or custom server control. This topic discusses some issues about using server controls in Web Parts applications when the controls do not inherit from the WebPart class.
Creating Run-Time Web Parts Controls
For the various kinds of server controls that do not inherit from the WebPart class, the Web Parts control set provides a mechanism that enables them to participate in Web Parts applications and to have the same capabilities as a control derived from the WebPart class. This does not require any special action by developers; all that is necessary is to add a server control to a WebPartZoneBase zone. When a Web page is compiled, any server control that resides in a zone and does not inherit from the WebPart class is automatically wrapped with an instance of the GenericWebPart class, and becomes a child control of that instance. Because the GenericWebPart class inherits from the WebPart class, the server control is now enabled with the full functionality of a WebPart control. In essence, by adding server controls that do not inherit from the WebPart class to a WebPartZoneBase zone, developers enable the controls to become run-time WebPart controls.
.gif "Note") Note |
|---|
Just as you can use server controls in Web Parts applications, you can also use WebPart controls outside of Web Parts applications. If you add a control that inherits from the WebPart class to a page outside of a zone, it functions as a normal server control and simply loses its Web Parts capabilities. |
Adding ASP.NET Server Controls to Zones
When you add ASP.NET server controls, user controls, or custom controls to a WebPartZoneBase zone, no special techniques or declarations on the page are required. You can add them to a zone in the same ways that you would normally add controls to a Web page: declaratively (in the page persistence format), or programmatically. In addition, you can use the Web Parts catalog feature, which enables you to add server controls to a catalog from which users can select and add controls to the page at run time. For more information, see the DeclarativeCatalogPart and ImportCatalogPart controls.
If you add a server control to a zone programmatically, the recommended approach is to add it by using the AddWebPart method of the WebPartManager control.
When you add server controls that are not WebPart controls declaratively to a zone, if you use a visual design tool such as Microsoft Visual Studio 2005, you will not see WebPart properties and members in the properties pane or in IntelliSense. For more information, see the following section that discusses when to use WebPart controls versus using other server controls.
Deciding When to Use Different Server Control Options
Because you can use any kind of server control in a Web Parts application, you might wonder if there is ever any reason to create a control that derives from the WebPart class.
The key factors you must consider are the advantages of adapting preexisting server controls versus creating new ones by deriving from the WebPart class. The following guidelines might help in your decision.
Using Server Controls
In many cases, the preferred option to create Web Parts controls is to use an ASP.NET server control, a user control, or a custom control, particularly if the controls already exist. You do not lose any run-time Web Parts functionality when you use these kinds of server controls, and you gain many advantages such as the ability to reuse existing code, and the ability to leverage your knowledge of control development and apply it to Web Parts applications.
You can also make the various server controls behave identically to true WebPart controls by implementing several interfaces that the WebPart class implements. These include:
The IWebActionable interface. If you implement this interface, you will be able to add custom verbs (common actions that users can carry out on a control in the UI, such as minimize, close, or edit) to the verbs menu of your control.
The IWebEditable interface. If you implement this interface, you can associate custom EditorPart controls with your server control, enabling users to edit specified custom properties and behavior on the control at run time.
The IWebPart interface. If you implement this interface, your control will have a number of the properties of a true WebPart control that is inherited from the Part class, which give it the same look and feel as a WebPart control, even at design time.
Deriving from WebPart
The main benefit of creating a control by deriving from the WebPart class is that you gain full control over its Web Parts-specific behavior.
An example of this occurs when a control developer wants to change the run-time behavior of a control, and then redistribute it to users. A developer could override one of the WebPart class's virtual properties--such as AllowClose--and make it a read-only property that always returns false. This prevents the control from ever being closed, and users of the control are limited to that behavior.
A second example where you can benefit by inheriting from the WebPart class relates to design-time behavior. On a WebPart control, all the exposed WebPart members are visible to page developers at design time through IntelliSense (if they use a visual design tool such as Microsoft Visual Studio 2005), so that they can work with the properties in declarative mode and in the Properties pane. In contrast, if you declare server controls in a zone at design time, and they are not WebPart controls, you cannot see any members that are specific to the WebPart class (although you can still declare them) in IntelliSense or in the Properties pane. That is because at design time, an ordinary server control has not yet been wrapped with a GenericWebPart object, so it does not have the WebPart features it will have at run time. Although you can enable server controls to look and act like WebPart controls by implementing the interfaces listed above, often it is more straightforward to simply create a WebPart control. Control developers and vendors who create packages of controls can benefit from deriving from the WebPart class so that they can provide richer design-time features for their controls.
Conclusions
In conclusion, if you do not need to override the controls' standard properties, you might find it easier to use the pre-existing server controls and make them parts of the WebPart control.
If you decide to create a custom WebPart control, the following are the properties that you can potentially override:
AllowClose
User Controls as WebPart Controls
User controls are a powerful option for ASP.NET developers, because they enable developers to quickly build a complex UI for a control using the same declarative syntax that is used in Web pages. They also provide a convenient way to partition and reuse code across multiple pages. As ASP.NET server controls, user controls are also an excellent option to use in Web Parts applications. User controls can be added directly to a WebPartZoneBase zone, and they will function as run-time WebPart controls, as described above. They can also be used with the Web Parts catalog feature, either as controls that can be imported, or to package a set of other server controls that users can select and add to a page (for more information, see the WebPartsListUserControlPath property).
| Important |
|---|
You should be aware that ASP.NET output caching is disabled on user controls being used as run-time WebPart controls. The Web Parts control set requires that a control be in the control tree for each request to a page. This is necessary for certain Web Parts features such as personalization (for more information, see Web Parts Personalization Overview) to work. On requests where a user control is cached (for more information, see the @ OutputCache directive), it is not added to the control tree. For this reason, output caching is incompatible with Web Parts features, and does not work with user controls that are functioning as WebPart controls in a Web Parts application. |
See Also
Reference
WebPart
GenericWebPart
WebPartZoneBase