NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Writing a Custom Web Forms Control

The Web Forms framework provides the set of classes and interfaces used to build custom controls. The classes are contained in these namespaces:

System.Web Namespace

System.Web.UI Namespace

System.Web.UI.HtmlControls Namespace

System.Web.UI.WebControls Namespace

You build controls by creating new classes that inherit appropriate base classes within these namespaces, and overriding the base class methods. The base class implementation handles all the work in your control.

The System.Web.UI.Control Class

The root of the server control class hierarchy is the System.Web.UI.Control base class, from which all server controls inherit. This class provides the methods and properties for managing page execution life cycle including view state management, postback data handling, postback event handling, and output rendering. To create your own server control, you only need to derive from this class and override the methods you want to implement or customize.

The Page Execution Life Cycle

Understanding the page execution life cycle will help you understand the role of the classes and interfaces you must implement as you develop custom controls.

The Page class (which inherits from the Control class) instantiates and populates a tree of server control instances representing the appropriate declarative .aspx file on each incoming Web request. Once the tree is created, the Page class begins the following execution sequence that enables both ASP+ page code and server controls to participate in the request processing and rendering of the page.

Init

Controls can use Init to initialize any settings that will be needed during the lifetime of the incoming Web request (for example, loading external template files, setting up event wirings, and so on). View state information is not available for use at this stage.

LoadViewState

A control’s view state information is automatically populated within the Control.State collection. The State methods allow you to programmatically restore internal state settings between page views.

PostBack Data Processing

Controls use the PostBack Data Processing stage to process any incoming form data and update their object modelsand internal state appropriately. (Note that change notification events are not raised during this stage; this occurs later in the life cycle execution.) This enables you to automatically (and accurately) reflect the state of the control on the client. (For example, if a user typed their name into a text box on the client, the text box control on the server should also reflect the text value of their name at the end of this stage of page execution).

Load

Controls use Load to perform any actions common to each request (for example, setting up a database query or updating a timer on a page). At this point in the life cycle, all the server controls in the tree have been created, initialized, and populated with the appropriate view state values, and all form controls have been populated with the appropriate client-side data values.

PostBack Change Notification

Controls fire appropriate change notification events during the PostBack Change Notification phase in response to form and control value changes that occurred on the client between the previous and current postbacks to a page.

For example, a text box server control whose initial value was “Bob” when a page was first rendered, would raise an OnChange event to all registered listeners if the value of the text box came back as “Fred” on the next postback.

PostBack Event Processing

Controls use the PostBack Event Processing phase to correctly handle client actions that cause a page postback and to raise appropriate events on the server.

For example, a button server control could handle a postback from the client in response to a user clicking it, and then raise an appropriate OnClick event on the server.

PreRender

Controls use PreRender to perform any last minute update operations that must take place immediately before page/control state is saved and output rendered.

SaveViewState

A control’s State information is automatically transferred from the Control.State collection into a string object immediately after the SaveViewState stage of execution. To prepare for this, your control can override the SaveViewState event to modify the State collection.

Render

Controls use the Render class to generate HTML output to the browser client. This is accomplished through a hierarchical, top-down, tree walk of all server controls.

Dispose

Controls can use Dispose to perform any final cleanup work (for example, closing files or database connections). It is very important that expensive resources (such as database connections) are explicitly closed. Otherwise, they remain open until the next garbage collection (GC) occurs. On a heavily loaded server (which might process hundreds of requests between GCs), this can quickly cause resource exhaustion (for example, hundreds of open connections to a database server).