Creating Web Server Controls in ASP.NET
Creating Web Server Control
Inherits from WebControl class.
Contains (or inherits) code necessary to render control.
May be compiled into DLL.
Can add ViewState support by expanding property implementations to set values via ViewState. By using ViewState to act as a backing store for the property values you ensure properties set in server code are not switched back to markup values on postback.
Inheriting from existing Web Server control
Base functionality inherited from existing web server control.
For example create LabeledTextBox that adds a label to a text box.
- Create ASP.NET Server control project, class library project referencing System.Web or (if only using within site) a class file.
- Define class inheriting from TextBox.
- Provide properties allowing label text and position to be controlled
- Final step is to render control, do this by overriding the Render method of the TextBox.
Inheriting from WebControl class
Preferable when no existing control provides enough default behaviour. Typically override Render method:
| Method | Description |
|---|---|
| Render | Controls all output of controls HTML to client. By default calls RenderBeginTag, RenderContents and then RenderEndTag. When overriding you control whether these methods are called. |
| RenderContents | Sets HTML rendered between begin and end tags. |
| RenderBeginTag and RenderEndTag | Render HTML at the beginning and end of a control. |
| RenderChildren | If custom control contains controls in its ControlCollection call this method to ensure each is rendered as part of HTML output. |
RenderEndTag not often needed as will render closing tag based on RenderBeginTag output.
Adding Toolbox Support
Web control must be held within DLL - usually created as ASP.NET Server Control project.
Add project based reference to web server control or right click in Toolbox and select Choose items and then navigate to control DLL.
Will be added to own section at top of Toolbox.
Defining Custom Icon
Specify by applying ToolboxBitmap attribute to control class.
Provide path or reference to embedded 16x16 bitmap to attribute constructor.
To embed bitmap, add image to project then in it properties window set the Build Action to Embedded Resource.
Default Properties
Can specify default property to have focus in Properties window by applying DefaultProperty attribute to class.
This attribute takes name of default property in its constructor.
Control Property Attributes
Attributes applied to control properties that control how used
| Method | Description |
|---|---|
| Bindable | Indicates if property is bound to data. If true property will be displayed in DataBinding section of property grid. |
| Category | Indicates which category, e.g. "Appearance", property should be displayed in. |
| Description | Brief description of property usage |
| DefaultValue | Default value for property |
| Localizable | Setting to true indicates property should be serialized as localized resource |
Controlling Markup Generated By Control
Can control markup generated when control dropped onto page via the ToolboxData attribute. Common scenario is to set default property values.
[ToolboxData(@"<{0}:LabeledTextBox runat="server" PromptWidth="100" >")]The {0} placeholder contains namespace prefix defined by webpage designer.
Can set namespace prefix assigned to control by webpage designer by adding attribute declaration to AssemblyInfo class:
[assembly: TagPrefix("MyUserControls", "muc")]which will assign the "muc" prefix to controls in the MyUserControls project.
Custom Designers for Custom Web Server Controls
May want to alter control rendering when in design mode. Other controls may not be visible during design because they require specific properties to be populated.
To control design rendering add reference to System.Design.dll.
Create class deriving from ControlDesigner.
Override GetDesignTimeHtml method to render appropriate output.
Apply Designer attribute to control, providing it with name of your derived designer class, e.g.
[Designer("MyUserControls.LebeledTextBoxDesigner")];Creating Composite Control
Custom web control containing other web server controls.
Does not provide .ascx file or designer.
Inherits from CompositeControl, add constituent controls to it.
Handles events raised by children.
Each child handles own ViewState and postback data - no extra coding required!
Start by creating class derived from CompositeControl.
Override CreateChildControls method to contain code to instantiate children and set their properties.
If need to assign styles to composite control then need to create instance of Panel class to provide container for attributes. Then add child controls into Panel instance.
Creating Templated Web Server Control
Provides separation of control data from presentation.
Templated control must provide naming container and a class with methods & properties that are accessible to host page.
- Create ClassLibrary (DLL) project for templated control
- Add reference to System.Web.dll
- Add container class to project. Expose properties for data to be accessed via Container object in template
- In container class derive from System.Web.UI.Control class and implement INamingContainer interface
- Add class to project for templated control
- Add ParseChildren(true) attribute to class. This directs page parser that nested content within control is parsed as a control and not used to set properties of templated control
- Create properties on templated control with data type of ITemplate. These properties used by page developer to define layout of control. Properties must have TemplateContainer attribute set to data type of container. Must have PersistenceMode attribute set to InnerProperty thus allowing page designers to add inner HTML source to the controlled.
- Override DataBind to call EnsureChildControls method on base Control class.
- Override CreateChildControls to provide code to instantiate template via the ITemplate interface.
Primary difference to templated user control is in how the custom web server control is created.
Registering Web Server Controls in Web.Config
Can register controls globally for entire site via the Web.Config file - removes requirement for @ Register directive on every page.
<pages>
<controls>
<add assembly="MyUserControls" namespace="MyUserControls" tagPrefix="muc" />
</controls>
</pages>