ASP.NET Quickstart Tutorial

In addition to the built-in server controls provided by ASP.NET, you can easily define your own controls using the same programming techniques that you have already learned for writing Web Forms pages. In fact, with just a few modifications, almost any Web Forms page can be reused in another page as a server control (note that a user control is of type System.Web.UI.UserControl, which inherits directly from System.Web.UI.TemplateParser). A Web Forms page used as a server control is named a user control for short. As a matter of convention, the .ascx extension is used to indicate such controls. This ensures that the user control's file cannot be executed as a standalone Web Forms page (you will see a little that there are a few, albeit important, differences between a user control and a Web Forms page). User controls are included in a Web Forms page using a Register directive:

<%@ Register TagPrefix="Acme" TagName="Message" Src="pagelet1.ascx" %>

The TagPrefix determines a unique namespace for the user control (so that multiple user controls with the same name can be differentiated from each other). The TagName is the unique name for the user control (you can choose any name). The Src attribute is the virtual path to the user control - for example "MyPagelet.ascx" or "/MyApp/Include/MyPagelet.ascx". After registering the user control, you may place the user control tag in the Web Forms page just as you would an ordinary server control (including the runat="server" attribute):

<Acme:Message runat="server"/>

The following example shows a user control imported into another Web Forms page. Note that the user control in this case is just a simple static file.

VB UserCtrl1.aspx

Exposing User Control Properties

When a Web Forms page is treated as a control, the public fields and methods of that Web Form are promoted to public properties (that is, tag attributes) and methods of the control as well. The following example shows an extension of the previous user control example that adds two public String fields. Notice that these fields can be set either declaratively or programmatically in the containing page.

VB UserCtrl2.aspx

In addition to promoting public fields to control properties, the property syntax may be used. Property syntax has the advantage of being able to execute code when properties are set or retrieved. The following example demonstrates an Address user control that wraps the text properties of TextBox controls within it. The benefit of doing this is that the control inherits the automatic state management of the TextBox control for free.

Notice that there are two Address user controls on the containing Web Forms page that set the Caption property to "Billing Address" and "Shipping Address", respectively. The real power of user controls is in this type of reusability.

VB UserCtrl3.aspx

Another useful user control is a Login control for collecting user names and passwords.

VB UserCtrl4.aspx

In this example, form validation controls are added to the Login user control.

VB UserCtrl5.aspx

Encapsulating Events in a User Control

User controls participate in the complete execution lifecycle of the request, much the way ordinary server controls do. This means that a user control can handle its own events, encapsulating some of the page logic from the containing Web Forms page. The following example demonstrates a product-listing user control that internally handles its own postbacks. Note that the user control itself has no wrapping <form runat="server"> control. Because only one form control may be present on a page (ASP.NET does not allow nested server forms), it is left to the containing Web Forms page to define this.

VB UserCtrl6.aspx

Creating User Controls Programmatically

Just as ordinary server controls can be created programmatically, so can be user controls. The page's LoadControl method is used to load the user control, passing the virtual path to the user control's source file:

		
Dim c1 As Control = LoadControl("userctrl7.ascx")
CType(c1, (UserCtrl7)).Category = "business"
Page.Controls.Add(c1)

The type of the user control is determined by a ClassName attribute on the Control directive. For example, a user control saved with the file name "userctrl7.ascx" is assigned the strong type "UserCtrl7" as follows:

<%@ Control ClassName="UserCtrl7" %>

Because the LoadControl method returns a type of System.Web.UI.Control, it must be cast to the appropriate strong type in order to set individual properties of the control. Finally, the user control is added to the base page's ControlCollection.

VB UserCtrl7.aspx

Important The strong type for a user control is available to the containing Web Forms page only if a Register directive is included for the user control (even if there are no user control tags actually declared).