This documentation is archived and is not being maintained.

ControlBuilder Class

Supports the page parser in building a control and the child controls it contains.


Namespace:  System.Web.UI
Assembly:  System.Web (in System.Web.dll)

public class ControlBuilder

The ControlBuilder type exposes the following members.

Public methodControlBuilderInitializes a new instance of the ControlBuilder class.

Public propertyBindingContainerTypeGets the type of the binding container for the control that this builder creates.
Public propertyControlTypeGets the Type for the control to be created.
Public propertyCurrentFilterResolutionServiceGets an IFilterResolutionService object that is used to manage device-filter related services when parsing and persisting controls in the designer.
Public propertyDeclareTypeGets the type that will be used by code generation to declare the control.
Protected propertyFChildrenAsPropertiesDetermines whether the control has a ParseChildrenAttribute with ChildrenAsProperties set to true.
Protected propertyFIsNonParserAccessorDetermines whether the control implements the IParserAccessor interface.
Public propertyHasAspCodeGets a value indicating whether the control contains any code blocks.
Public propertyIDGets or sets the identifier property for the control to be built.
Protected propertyInDesignerReturns whether the ControlBuilder is running in the designer.
Protected propertyInPageThemeGets a Boolean value indicating whether this ControlBuilder object is used to generate page themes.
Public propertyLocalizeGets a Boolean value indicating whether the control that is created by this ControlBuilder object is localized.
Public propertyNamingContainerTypeInfrastructure. Gets the type of the naming container for the control that this builder creates.
Public propertyPageVirtualPathGets the virtual path of a page to be built by this ControlBuilder instance.
Protected propertyParserInfrastructure. Gets the TemplateParser responsible for parsing the control.
Public propertyServiceProviderGets the service object for this ControlBuilder object.
Public propertyTagNameGets the tag name for the control to be built.
Public propertyThemeResolutionServiceGets an IThemeResolutionService object that is used in design time to manage control themes and skins.

Public methodAllowWhitespaceLiteralsDetermines whether white space literals are permitted in the content between a control's opening and closing tags. This method is called by the ASP.NET page framework.
Public methodAppendLiteralStringAdds the specified literal content to a control. This method is called by the ASP.NET page framework.
Public methodAppendSubBuilderAdds builders to the ControlBuilder object for any child controls that belong to the container control.
Public methodBuildObjectBuilds a design-time instance of the control that is referred to by this ControlBuilder object.
Public methodCloseControlCalled by the parser to inform the builder that the parsing of the control's opening and closing tags is complete.
Public methodStatic memberCreateBuilderFromTypeCreates a ControlBuilder object from the specified tag name and object type, as well as other parameters defining the builder.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetChildControlTypeObtains the Type of the control type corresponding to a child tag. This method is called by the ASP.NET page framework.
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodGetObjectPersistDataCreates the ObjectPersistData object for this ControlBuilder object.
Public methodGetResourceKeyInfrastructure. Retrieves the resource key for this ControlBuilder object.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodHasBodyDetermines if a control has both an opening and closing tag. This method is called by the ASP.NET page framework.
Public methodHtmlDecodeLiteralsDetermines whether the literal string of an HTML control must be HTML decoded. This method is called by the ASP.NET page framework.
Public methodInitInitializes the ControlBuilder for use after it is instantiated. This method is called by the ASP.NET page framework.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodNeedsTagInnerTextDetermines if the control builder needs to get its inner text. If so, the SetTagInnerText method must be called. This method is called by the ASP.NET page framework.
Public methodOnAppendToParentBuilderNotifies the ControlBuilder that it is being added to a parent control builder.
Public methodProcessGeneratedCodeEnables custom control builders to access the generated Code Document Object Model (CodeDom) and insert and modify code during the process of parsing and building controls.
Public methodSetResourceKeyInfrastructure. Sets the resource key for this ControlBuilder object.
Public methodSetServiceProviderInfrastructure. Sets the service object for this ControlBuilder object.
Public methodSetTagInnerTextProvides the ControlBuilder with the inner text of the control tag.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)

Public fieldStatic memberDesignerFilterRepresents the "__designer" literal string.

By default, every control on a page is associated with a default ControlBuilder class. During parsing, the ASP.NET page framework builds a tree of ControlBuilder objects corresponding to the tree of controls for the page. The ControlBuilder tree is then used to generate page code to create the control tree. In addition to child controls, the ControlBuilder defines the behavior of how the content within control tags is parsed. You can override this default behavior by defining your own custom control builder class. This is done by applying a ControlBuilderAttribute attribute to your control builder class as follows:


The following code example creates a Table control whose attributes and content are defined at the time the table is built. The following is the command line to use to build the executable.

[Visual Basic]

vbc /r:System.dll /r:System.Web.dll /r:System.Drawing.dll /t:library /out:myWebAppPath/Bin/vb_mycontrolbuilder.dll myControlBuilder.vb


csc /t:library /out:myWebAppPath/Bin/cs_mycontrolbuilder.dll myControlBuilder.cs

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections;
using System.Drawing;
using System.Security.Permissions;

namespace CustomControls
		Level = AspNetHostingPermissionLevel.Minimal)]
	public class MyTableCell : TableCell, INamingContainer { };

		Level = AspNetHostingPermissionLevel.Minimal)]
	public class MyCell
	 * Class name: MyCell.
	 * Declares the class for the child controls to include in the control collection.
		string _id;
		string _value;
		Color _backColor;

		public string CellID
			{ return _id; }
			{ _id = value; }

		public string Text
			{ return _value; }
			{ _value = value; }

		public Color BackColor
			{ return _backColor; }
			{ _backColor = value; }

	Level = AspNetHostingPermissionLevel.Minimal)]
	public class MyControlBuilder : ControlBuilder

		public override Type GetChildControlType(string tagName, IDictionary attribs)
			// Allows TableRow without "runat=server" attribute to be added to the collection.
			if (String.Compare(tagName, "mycell", true) == 0)
				return typeof(MyCell);
			return null;

		public override void AppendLiteralString(string s)
			// Ignores literals between rows.

		Level = AspNetHostingPermissionLevel.Minimal)]
	public class MyCS_CustomControl : Control, INamingContainer
	 * Class name: MyCS_CustomControl.
	 * Processes the element declarations within a control declaration. 
	 * This builds the actual control.
		// Declares the custom control that must be built programmatically.
		Table _table;

		private String _title;
		private int _rows;
		private int _columns;

		Hashtable _cellObjects = new Hashtable();

		// Rows property to be used as the attribute name in the Web page.  
		public int Rows
			{ return _rows; }
			{ _rows = value; }

		// Columns property to be used as the attribute name in the Web page.
		public int Columns
			{ return _columns; }
			{ _columns = value; }

		// Title property to be used as the attribute name in the Web page.
		public string Title
			{ return _title; }
			{ _title = value; }

		protected void createNewRow(int rowNumber)

			// Creates a row and adds it to the table.
			TableRow row;

			row = new TableRow();

			// Creates a cell that contains text.

			for (int y = 0; y < Columns; y++)
				appendCell(row, rowNumber, y);


		protected void appendCell(TableRow row, int rowNumber, int cellNumber)
			TableCell cell;
			TextBox textbox;

			cell = new TableCell();
			textbox = new TextBox();
			textbox.ID = "r" + rowNumber.ToString() + "c" + cellNumber.ToString();

			// Checks for the MyCell child object.
			if (_cellObjects[textbox.ID] != null)
				MyCell cellLookup;
				cellLookup = (MyCell)_cellObjects[textbox.ID];

				textbox.Text = cellLookup.Text;
				textbox.BackColor = cellLookup.BackColor;
				textbox.Text = "Row: " + rowNumber.ToString() + " Cell: " +



		// Called at runtime when a child object is added to the collection.  
		protected override void AddParsedSubObject(object obj)
			MyCell cell = obj as MyCell;
			if (cell != null)
				_cellObjects.Add(cell.CellID, cell);


		protected override void OnPreRender(EventArgs e)
		 * Function name: OnPreRender.
		 * Carries out changes affecting the control state and renders the resulting UI.

			// Increases the number of rows if needed.
			while (_table.Rows.Count < Rows)

			// Checks that each row has the correct number of columns.
			for (int i = 0; i < _table.Rows.Count; i++)
				while (_table.Rows[i].Cells.Count < Columns)
					appendCell(_table.Rows[i], i, _table.Rows[i].Cells.Count);

				while (_table.Rows[i].Cells.Count > Columns)
					_table.Rows[i].Cells.RemoveAt(_table.Rows[i].Cells.Count - 1);

		protected override void CreateChildControls()
		 * Function name: CreateChildControls.
		 * Adds the Table and the text control to the control collection.
			LiteralControl text;

			// Initializes the text control using the Title property.
			text = new LiteralControl("<h5>" + Title + "</h5>");

			_table = new Table();
			_table.BorderWidth = 2;

The following code example uses the previous custom control. In particular, it builds a table whose attributes and content are defined at run time. Notice that the values shown in the @ Register directive reflect the previous command line.

<%@ Page Language="C#" %>
<%@ Register TagPrefix="AspNetSamples" Assembly="cs_mycontrolbuilder" Namespace="CustomControls" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">

<script runat="server">

<html xmlns="" >
<head runat="server">
    <title>ControlBuilder Example</title>
    <form id="form1" runat="server">
       <AspNetSamples:MyCS_CustomControl id="Custom1" 
                                         title="Auto-Generated Table"
         <mycell cellid="r0c0" BackColor="red" text="red cell"></mycell>
         <mycell cellid="r2c2" BackColor="green" text="green cell"></mycell>

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0, 1.1, 1.0

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.