Control Builder Overview

A control builder is a class that governs how a server control is parsed when it is used declaratively on an ASP.NET page. Every ASP.NET control is associated with a default control builder (System.Web.UI.ControlBuilder). During page parsing, the default control builder checks whether a control is marked with the ParseChildren(true) attribute. If it is, nested elements within the control's opening and closing tags must correspond to properties of the control. Any other nested elements generate a parser error. See Using ParseChildrenAttribute for details. If a control is not marked as ParseChildren(true), the control builder creates the child controls and calls IParserAccessor.AddParsedSubObject on the control. The default implementation of AddParsedSubObject adds the child controls to the Controls collection of the control. Any literal text between nested control tags is parsed as a LiteralControl.

If you want to provide other (custom) parsing logic for your control, you can create your own control builder by deriving from ControlBuilder and overriding the methods of the base class. You must associate the custom control builder with your control by marking your control with a System.Web.UI.ControlBuilderAttribute, as shown in the following example.

// Define a custom control builder.
public class MyControlBuilder : ControlBuilder {...}

// Associate it with your control by applying a 
// ControlBuilder attribute.
[ControlBuilder(typeof(MyControlBuilder))]
public class MyControl : Control {...}
[Visual Basic]
' Define a custom control builder.
Public Class MyControlBuilder
   Inherits ControlBuilder
   ...
End Class

' Associate it with your control by applying a 
' ControlBuilder attribute.
<ControlBuilder(GetType(MyControlBuilder))> _ 
Public Class MyControl
   Inherits Control
   ...
End Class

The following table lists some of the methods of ControlBuilder that you are likely to override when you define a custom control builder. For a complete listing of the members of ControlBuilder, see ControlBuilder.

Method of ControlBuilder	What it does
AllowWhiteSpaceLiterals	Specifies whether intervening white spaces between nested child control tags are added to the Controls collection as LiteralControl instances. For a sample, see the Custom Control Builder Sample.
AppendSubBuilder	Adds a control builder for child controls.
GetChildControlType	Returns the Type of a child control based on its tag name. Use this method to filter the child controls that are added to the Controls collection. For a sample, see the ASP.NET QuickStart —> ASP.NET Web Forms —> Authoring Custom Controls.

For a sample of a control builder, see Custom Control Builder Sample.

Note   Another way to override parsing logic is to override the AddParsedSubObject method inherited from Control. An example is provided in the ASP.NET QuickStart —> ASP.NET Web Forms —> Authoring Custom Controls —> Overriding Control Parsing. Note that the parsing by a control builder happens at compile time, while the AddParsedSubObject method is executed at run time (and could have a performance overhead).

See Also

Custom Control Builder Sample | Control Parsing, ParseChildrenAttribute, and Control Builders | ControlBuilderAttribute