Home > Getting Started > ASP.NET Syntax > ASP.NET Page Syntax > Custom Server Control Syntax

ASP.NET Syntax   ASP.NET Page Syntax

---

Defines user controls and user-authored server controls declaratively in a Web Forms page.

<tagprefix:tagname
   id="accessID" 
   attributename = "value"
   attributename-propertyname = "value"
   eventname = "eventhandlermethod" 
   runat="server" />

or 

<tagprefix:tagname id="accessID" runat="server"> </tagprefix:tagname>

tagprefix	An alias for the fully qualified namespace of the control. Aliases for user-authored controls are declared with the @ Register directive.
tagname	The name of the class that encapsulates the control.
id	A unique identifier that enables programmatic reference to the control.
attributename	The name of the attribute.
propertyvalue	The value to assign to attributename.
propertyname	The name of the property being defined.
supropertyvalue	The value to assign to propertyname.
eventname	The event name of the control.
eventhandlermethod	The name of the event handler method defined in the code for the Web Forms page.

The opening tags of these elements must include a runat="server" attribute/value pair. If you want to enable programmatic referencing on the control, specify a unique value with the id attribute.

You must include an @ Register directive for each custom server control assembly and user control that you declare in a page. If you do not, a compilation error occurs.

<%@ Register tagPrefix="aspx" tagName="header" src="header.ascx" %>

Any properties that you have authored on a custom server control can be exposed declaratively in the opening tag of the server control. Simply declare the property as an attribute and assign it a value.

For example, if you create a custom text box control with a width property, declaring width = "50" in the opening tag of the control sets the server control’s display width to fifty pixels.

In some cases, attributes may be objects that have their own properties. In this case, include the property name in the declaration.

For example, if you create a custom text box control that includes a font attribute, it can include a name property. You can then declare the property in the opening tag of the server control as font-name = "Arial".

For more information about developing custom server control with properties, see Properties in ASP.NET Server Controls.

You can also declare events with custom server controls and user controls in the same way you would with any ASP.NET server control. Simply specify the event binding in the opening tag of the server control with an attribute and value.

For more information about writing event handlers, see Defining Web Forms Event-Handling Methods. For more information on authoring custom server controls that support events, see Web Forms Events and Handlers.

You can also use and develop custom server controls that support inline templates. For details on how to declare templates in a custom server control, see Server Control Inline Template Syntax. To learn how to author custom server controls that support inline templates, see Developing Templated Controls.

The below code snippet demonstrates how you can register and declare custom server controls in a Web Forms Master page.

<%@ Register tagPrefix="aspx" tagName="header" src="header.ascx" %>
<%@ Register tagPrefix="aspx" tagName="sidebar" src="sidebar.ascx" %>
<%@ Register tagPrefix="aspx" tagName="footer" src="footer.ascx" %>

The example below shows use of a header, sidebar and footer user controls in a real-world application built entirely with ASP.NET.

User Controls Example Run Sample

Introducing ASP.NET Web Forms