Microsoft ASP.NET QuickStarts Tutorial

  Introduction to User Controls
  Exposing User Control Properties
  Encapsulating Events in a User Control
  Creating User Controls Programmatically
  Section Summary

Introduction to User Controls

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.Control). 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 Pagelet1.aspx

[Run Sample] | [View Source]

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 Pagelet2.aspx

[Run Sample] | [View Source]

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 Pagelet3.aspx

[Run Sample] | [View Source]

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

VB Pagelet4.aspx

[Run Sample] | [View Source]

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

VB Pagelet5.aspx

[Run Sample] | [View Source]

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 Pagelet6.aspx

[Run Sample] | [View Source]

Creating User Controls Programmatically

Just as ordinary server controls can be created programmatically, so user controls can be. 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("pagelet7.ascx")
CType(c1, (Pagelet7VB)).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 "pagelet7.ascx" is assigned the strong type "Pagelet7CS" as follows:

<%@ Control ClassName="Pagelet7CS" %>

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 Pagelet7.aspx

[Run Sample] | [View Source]

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).

Section Summary

User controls allow developers to easily define custom controls using the same programming techniques as for writing Web Forms pages.
As a matter of convention, an .ascx file name extension is used to indicate such controls. This ensures that a user control file cannot be executed as a standalone Web Forms page.
User controls are included into another Web Forms page using a Register directive, which specifies a TagPrefix, TagName, and Src location.
After the user control has been registered, a user control tag may be placed in a Web Forms page as an ordinary server control (including the runat="server" attribute).
The public fields, properties, and methods of a user control are promoted to public properties (tag attributes) and methods of the control in the containing Web Forms page.
User controls participate in the complete execution lifecycle of every request and can handle their own events, encapsulating some of the page logic from the containing Web Forms page.
User controls should not contain any form controls but should instead rely on their containing Web Forms page to include one if necessary.
User controls may be created programmatically using the LoadControl method of the System.Web.UI.Page class. The type of the user control is determined by the ASP.NET runtime, following the convention filename_extension.
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).