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)

<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public Class ControlBuilder
Dim instance As ControlBuilder

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
Imports System
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Collections
Imports System.Drawing
Imports System.Security.Permissions

Namespace CustomControls

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyTableCell
        Inherits TableCell
        Implements INamingContainer
    End Class

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyCell
        Inherits Control
        Implements INamingContainer
        ' Class Name: MyCell. 
        ' Declares the class for the child controls to be included in the control collection. 

        Private _id As String 
        Private _value As String 
        Private _backColor As Color

        Public Property CellID() As String 
                Return _id
            End Get 
            Set(ByVal value As String)
                _id = value
            End Set 
        End Property 

        Public Property Text() As String 
                Return _value
            End Get 
            Set(ByVal value As String)
                _value = value
            End Set 
        End Property 

        Public Property BackColor() As Color
                Return _backColor
            End Get 
            Set(ByVal value As Color)
                _backColor = value
            End Set 
        End Property 
    End Class

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal)> _
    Public Class MyControlBuilderVB
        Inherits ControlBuilder

        Public Overrides Function GetChildControlType(ByVal tagName As String, ByVal attribs As IDictionary) As Type

            ' Allows TableRow without "runat=server" attribute to be added to the collection. 
            If (String.Compare(tagName, "mycell", True) = 0) Then 
                Return GetType(MyCell)
            End If 
            Return Nothing 
        End Function 

        ' Ignores literals between rows. 
        Public Overrides Sub AppendLiteralString(ByVal s As String)
            ' Ignores literals between rows. 
        End Sub 

    End Class

    <AspNetHostingPermission(SecurityAction.Demand, Level:=AspNetHostingPermissionLevel.Minimal), ControlBuilderAttribute(GetType(MyControlBuilderVB))> _
        Public Class MyVB_CustomControl
        Inherits Control
        Implements INamingContainer

        ' Class name: MyVB_CustomControl. 
        ' Processes the element declarations within a control  
        ' declaration. This builds the actual control. 

        ' Custom control to build programmatically. 
        Private _table As Table

        Private _cellObjects As New Hashtable()

        ' Variables that must contain the control attributes as defined in the Web page. 
        Private _rows As Integer 
        Private _columns As Integer 
        Private _title As String 

        ' Rows property to be used as the attribute name in the Web page.      
        Public Property Rows() As Integer 
                Return _rows
            End Get 
            Set(ByVal value As Integer)
                _rows = value
            End Set 
        End Property 

        ' Columns property to be used as the attribute name in the Web page. 

        Public Property Columns() As Integer 
                Return _columns
            End Get 
            Set(ByVal value As Integer)
                _columns = value
            End Set 
        End Property 

        ' Title property to be used as the attribute name in the Web page    
        Public Property Title() As String 
                Return _title
            End Get 
            Set(ByVal value As String)
                _title = value
            End Set 
        End Property 

        Protected Sub createNewRow(ByVal rowNumber As Integer)

            ' Creates a row and adds it to the table. 
            Dim row As TableRow

            row = New TableRow()

            ' Creates a cell that contains text. 
            Dim y As Integer 
            For y = 0 To Columns - 1
                appendCell(row, rowNumber, y)
            Next y
        End Sub 'createNewRow

        Protected Sub appendCell(ByVal row As TableRow, ByVal rowNumber As Integer, ByVal cellNumber As Integer)
            Dim cell As TableCell
            Dim textbox As TextBox

            cell = New TableCell()

            textbox = New TextBox()


            textbox.ID = "r" + rowNumber.ToString() + "c" + cellNumber.ToString()

            ' Checks for the MyCell child object. 
            If Not (_cellObjects(textbox.ID) Is Nothing) Then 
                Dim cellLookup As MyCell
                cellLookup = CType(_cellObjects(textbox.ID), MyCell)

                textbox.Text = cellLookup.Text
                textbox.BackColor = cellLookup.BackColor

                textbox.Text = "Row: " + rowNumber.ToString() + " Cell: " + cellNumber.ToString()
            End If

        End Sub 'appendCell

        ' Called at runtime when a child object is added to the collection. 
        Protected Overrides Sub AddParsedSubObject(ByVal obj As Object)

            Dim cell As MyCell = CType(obj, MyCell)
            If Not (cell Is Nothing) Then
                _cellObjects.Add(cell.CellID, cell)
            End If 
        End Sub 'AddParsedSubObject

        Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
            ' Sub 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
            End While 

            ' Checks that each row has the correct number of columns. 
            Dim i As Integer 
            For i = 0 To _table.Rows.Count - 1
                While _table.Rows(i).Cells.Count < Columns
                    appendCell(_table.Rows(i), i, _table.Rows(i).Cells.Count)
                End While 

                While _table.Rows(i).Cells.Count > Columns
                    _table.Rows(i).Cells.RemoveAt((_table.Rows(i).Cells.Count - 1))
                End While 
            Next i
        End Sub 'OnPreRender

        <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
        Protected Overrides Sub CreateChildControls()
            ' Sub name: CreateChildControls. 
            ' Adds the Table and the text controls to the control collection.  

            Dim [text] As LiteralControl

            ' Initializes the text control using the Title property.
            [text] = New LiteralControl("<h5>" + Title + "</h5>")

            _table = New Table()

        End Sub 
    End Class 

End Namespace

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="VB" %>
<%@ Register TagPrefix="AspNetSamples" Assembly="vb_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:MyVB_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>

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

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

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

.NET Framework

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