ControlBuilder 类

定义

支持页分析器生成控件及其包含的子控件。Supports the page parser in building a control and the child controls it contains.

public ref class ControlBuilder
public class ControlBuilder
type ControlBuilder = class
Public Class ControlBuilder
继承
ControlBuilder
派生

示例

下面的代码示例创建一个 Table 控件,该控件的属性和内容在生成表时定义。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.

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
{
    [AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal)]
    public class MyTableCell : TableCell, INamingContainer { };

    [AspNetHostingPermission(SecurityAction.Demand,
        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
        {
            get
            { return _id; }
            set
            { _id = value; }
        }

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

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

    [AspNetHostingPermission(SecurityAction.Demand,
    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.
        }
    }
    [AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal)]
    [ControlBuilderAttribute(typeof(MyControlBuilder))]
    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
        {
            get
            { return _rows; }
            set
            { _rows = value; }
        }

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

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

        protected void createNewRow(int rowNumber)
        {

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

            row = new TableRow();
            _table.Rows.Add(row);

            // 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();
            cell.Controls.Add(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;
            }
            else
                textbox.Text = "Row: " + rowNumber.ToString() + " Cell: " +
                cellNumber.ToString();

            row.Cells.Add(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)
            {
                createNewRow(_table.Rows.Count);
            }

            // 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>");
            Controls.Add(text);

            _table = new Table();
            _table.BorderWidth = 2;
            Controls.Add(_table);
        }
    }
}
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
            Get
                Return _id
            End Get
            Set(ByVal value As String)
                _id = value
            End Set
        End Property

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


        Public Property BackColor() As Color
            Get
                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
            Get
                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
            Get
                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
            Get
                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()
            _table.Rows.Add(row)

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


        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()

            cell.Controls.Add(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

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

            row.Cells.Add(cell)
        End Sub

        ' 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


        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
                createNewRow(_table.Rows.Count)
            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


        <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>")
            Controls.Add([text])


            _table = New Table()

            Controls.Add(_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. 请注意, @ Register指令中显示的值反映了前面的命令行。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" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>ControlBuilder Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
       <AspNetSamples:MyCS_CustomControl id="Custom1" 
                                         title="Auto-Generated Table"
                                         columns="3"
                                         rows="3"  
                                         runat="server">
         <mycell cellid="r0c0" BackColor="red" text="red cell"></mycell>
         <mycell cellid="r2c2" BackColor="green" text="green cell"></mycell>
       </AspNetSamples:MyCS_CustomControl>
    </div>
    </form>
</body>
</html>
<%@ Page Language="VB" %>
<%@ Register TagPrefix="AspNetSamples" Assembly="vb_mycontrolbuilder" Namespace="CustomControls" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>ControlBuilder Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
       <AspNetSamples:MyVB_CustomControl id="Custom1" 
                                         title="Auto-Generated Table"
                                         columns="3"
                                         rows="3"  
                                         runat="server">
         <mycell cellid="r0c0" BackColor="red" text="red cell"></mycell>
         <mycell cellid="r2c2" BackColor="green" text="green cell"></mycell>
       </AspNetSamples:MyVB_CustomControl>
    </div>
    </form>
</body>
</html>

注解

默认情况下,页面上的每个控件都与默认 ControlBuilder 类相关联。By default, every control on a page is associated with a default ControlBuilder class. 在分析过程中,ASP.NET 页框架将生成与页面控件树对应的 ControlBuilder 对象的树。During parsing, the ASP.NET page framework builds a tree of ControlBuilder objects corresponding to the tree of controls for the page. 然后,使用 ControlBuilder 树生成用于创建控件树的页代码。The ControlBuilder tree is then used to generate page code to create the control tree. 除子控件外,ControlBuilder 还定义了如何分析控件标记内的内容。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. 为此,可将 ControlBuilderAttribute 特性应用于控件生成器类,如下所示:This is done by applying a ControlBuilderAttribute attribute to your control builder class as follows:

[ControlBuilderAttribute(typeof(ControlBuilderType))]

构造函数

ControlBuilder()

初始化 ControlBuilder 类的新实例。Initializes a new instance of the ControlBuilder class.

字段

DesignerFilter

表示 "__designer" 字符串。Represents the "__designer" literal string.

属性

BindingContainerBuilder

获取与此生成器创建的控件的绑定容器对应的控件生成器。Gets the control builder that corresponds to the binding container for the control that this builder creates.

BindingContainerType

获取此生成器所创建控件的绑定容器的类型。Gets the type of the binding container for the control that this builder creates.

ComplexPropertyEntries

获取复杂属性项的集合。Gets a collection of complex property entries.

ControlType

获取要创建的控件的 TypeGets the Type for the control to be created.

CurrentFilterResolutionService

获取一个 IFilterResolutionService 对象,在设计器中分析和保持控件时使用该对象管理与设备筛选器相关的服务。Gets an IFilterResolutionService object that is used to manage device-filter related services when parsing and persisting controls in the designer.

DeclareType

获取代码生成将用于声明控件的类型。Gets the type that will be used by code generation to declare the control.

FChildrenAsProperties

获取确定控件是否有设置到 ParseChildrenAttributeChildrenAsPropertiestrue 的值。Gets a value that determines whether the control has a ParseChildrenAttribute with ChildrenAsProperties set to true.

FIsNonParserAccessor

获取确定控件是否实现了 IParserAccessor 界面的值。Gets a value that determines whether the control implements the IParserAccessor interface.

HasAspCode

获取一个值,该值指示控件是否包含任何代码块。Gets a value indicating whether the control contains any code blocks.

ID

获取或设置要生成的控件的标识符属性。Gets or sets the identifier property for the control to be built.

InDesigner

返回 ControlBuilder 是否正在设计器中运行。Returns whether the ControlBuilder is running in the designer.

InPageTheme

获取一个布尔值,该值指示此 ControlBuilder 对象是否用于生成页主题。Gets a Boolean value indicating whether this ControlBuilder object is used to generate page themes.

ItemType

获取在绑定容器上设置的类型。Gets the type set on the binding container.

Localize

获取一个布尔值,该值指示由此 ControlBuilder 对象所创建的控件是否已本地化。Gets a Boolean value indicating whether the control that is created by this ControlBuilder object is localized.

NamingContainerType

获取此生成器所创建控件的命名容器的类型。Gets the type of the naming container for the control that this builder creates.

PageVirtualPath

通过 ControlBuilder 实例获取要建立的页的虚拟路径。Gets the virtual path of a page to be built by this ControlBuilder instance.

Parser

获取负责分析控件的 TemplateParserGets the TemplateParser responsible for parsing the control.

ServiceProvider

获取此 ControlBuilder 对象的服务对象。Gets the service object for this ControlBuilder object.

SubBuilders

获取此 ControlBuilder 对象的 ControlBuilder 子对象的列表。Gets a list of child ControlBuilder objects for this ControlBuilder object.

TagName

获取要生成的控件的标记名称。Gets the tag name for the control to be built.

TemplatePropertyEntries

获取模板属性项的集合。Gets a collection of template property entries.

ThemeResolutionService

获取一个 IThemeResolutionService 对象,该对象用于在设计时管理控件的主题和外观。Gets an IThemeResolutionService object that is used in design time to manage control themes and skins.

方法

AllowWhitespaceLiterals()

确定在控件的开始和结束标记之间的内容中是否允许存在空白。Determines whether white space literals are permitted in the content between a control's opening and closing tags. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

AppendLiteralString(String)

将指定的文本内容添加到控件。Adds the specified literal content to a control. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

AppendSubBuilder(ControlBuilder)

将生成器添加到属于容器控件的任何子控件的 ControlBuilder 对象。Adds builders to the ControlBuilder object for any child controls that belong to the container control.

BuildObject()

生成此 ControlBuilder 对象所引用的控件的设计时实例。Builds a design-time instance of the control that is referred to by this ControlBuilder object.

CloseControl()

由分析器调用以通知生成器对控件的开始和结束标记的分析已完成。Called by the parser to inform the builder that the parsing of the control's opening and closing tags is complete.

CreateBuilderFromType(TemplateParser, ControlBuilder, Type, String, String, IDictionary, Int32, String)

根据指定的标记名称和对象类型,以及定义生成器的其他参数创建一个 ControlBuilder 对象。Creates a ControlBuilder object from the specified tag name and object type, as well as other parameters defining the builder.

Equals(Object)

确定指定对象是否等于当前对象。Determines whether the specified object is equal to the current object.

(继承自 Object)
GetChildControlType(String, IDictionary)

获取与子标记对应的控件类型的 TypeObtains the Type of the control type corresponding to a child tag. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

GetHashCode()

用作默认哈希函数。Serves as the default hash function.

(继承自 Object)
GetObjectPersistData()

创建此 ObjectPersistData 对象的 ControlBuilder 对象。Creates the ObjectPersistData object for this ControlBuilder object.

GetResourceKey()

检索此 ControlBuilder 对象的资源键。Retrieves the resource key for this ControlBuilder object.

GetType()

获取当前实例的 TypeGets the Type of the current instance.

(继承自 Object)
HasBody()

确定控件是否同时具有开始标记和结束标记。Determines if a control has both an opening and closing tag. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

HtmlDecodeLiterals()

确定 HTML 控件的字符串是否必须是 HTML 解码的。Determines whether the literal string of an HTML control must be HTML decoded. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

Init(TemplateParser, ControlBuilder, Type, String, String, IDictionary)

实例化 ControlBuilder 后再进行初始化以便使用。Initializes the ControlBuilder for use after it is instantiated. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

MemberwiseClone()

创建当前 Object 的浅表副本。Creates a shallow copy of the current Object.

(继承自 Object)
NeedsTagInnerText()

确定控件生成器是否需要获取它的内部文本。Determines if the control builder needs to get its inner text. 如果需要,则必须调用 SetTagInnerText(String) 方法。If so, the SetTagInnerText(String) method must be called. 此方法由 ASP.NET 页面框架调用。This method is called by the ASP.NET page framework.

OnAppendToParentBuilder(ControlBuilder)

通知 ControlBuilder 正在将它添加到父控件生成器。Notifies the ControlBuilder that it is being added to a parent control builder.

ProcessGeneratedCode(CodeCompileUnit, CodeTypeDeclaration, CodeTypeDeclaration, CodeMemberMethod, CodeMemberMethod)

启用自定义控件生成器以访问生成的代码文档对象模型 (CodeDom),并在分析和生成控件的过程中插入和修改代码。Enables 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.

SetResourceKey(String)

设置此 ControlBuilder 对象的资源键。Sets the resource key for this ControlBuilder object.

SetServiceProvider(IServiceProvider)

设置此 ControlBuilder 对象的服务对象。Sets the service object for this ControlBuilder object.

SetTagInnerText(String)

ControlBuilder 提供控件标记的内部文本。Provides the ControlBuilder with the inner text of the control tag.

ToString()

返回表示当前对象的字符串。Returns a string that represents the current object.

(继承自 Object)

适用于

另请参阅