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

取得值,判斷控制項是否有 ParseChildrenAttribute 設為 trueChildrenAsPropertiesGets 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)

提供控制項標記內部文字給 ControlBuilderProvides the ControlBuilder with the inner text of the control tag.

ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)

適用於

另請參閱