ControlBuilder 類別

參考

定義

命名空間:: System.Web.UI

組件:: System.Web.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

支援網頁剖析器建置控制項及其包含的子控制項。

public ref class ControlBuilder

public class ControlBuilder

type ControlBuilder = class

Public Class ControlBuilder

繼承: Object
ControlBuilder

衍生: System.Web.UI.CodeStatementBuilder

System.Web.UI.DataSourceControlBuilder

System.Web.UI.HtmlControls.HtmlEmptyTagControlBuilder

System.Web.UI.HtmlControls.HtmlHeadBuilder

System.Web.UI.HtmlControls.HtmlSelectBuilder

更多…

範例

下列程式代碼範例會 Table 建立控件，其屬性和內容會在建立數據表時定義。以下是用來建置可執行檔的命令行。

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

下列程式代碼範例會使用先前的自定義控制項。特別是，它會建置數據表，其屬性和內容會在運行時間定義。請注意， @ Register 指示詞中顯示的值會反映上一個命令行。

<%@ 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 類別相關聯。在剖析期間，ASP.NET 頁面架構會建置對應至頁面控件樹狀 ControlBuilder 結構的物件樹狀結構。然後，樹 ControlBuilder 狀結構會用來產生頁面程序代碼，以建立控件樹狀結構。除了子控件之外，還會 ControlBuilder 定義如何剖析控件標籤內容的行為。您可以藉由定義自己的自訂控件產生器類別來覆寫此預設行為。這可藉由將 ControlBuilderAttribute 屬性套用至控件產生器類別來完成，如下所示：

[ControlBuilderAttribute(typeof(ControlBuilderType))]

建構函式

ControlBuilder()

初始化 ControlBuilder 類別的新執行個體。

欄位

DesignerFilter

表示 "__designer" 常值字串。

屬性

BindingContainerBuilder	取得控制項產生器，對應於這個產生器所建立之控制項的繫結容器。
BindingContainerType	取得這個產生器所建立之控制項的繫結容器型別。
ComplexPropertyEntries	取得複雜屬性項目的集合。
ControlType	取得所要建立的控制項的 Type。
CurrentFilterResolutionService	取得 IFilterResolutionService 物件，用於設計工具中剖析和保存控制項時，管理裝置篩選條件相關的服務。
DeclareType	取得產生程式碼時用來宣告控制項的型別。
FChildrenAsProperties	取得值，判斷控制項是否有 ParseChildrenAttribute 設為 `true` 的 ChildrenAsProperties。
FIsNonParserAccessor	取得值，判斷控制項是否實作 IParserAccessor 介面。
HasAspCode	取得值，指出控制項是否包含任何程式碼區塊。
ID	取得或設定要建置的控制項的識別項屬性。
InDesigner	傳回值，指出 ControlBuilder 是否在設計工具中執行。
InPageTheme	取得布林值，指出這個 ControlBuilder 物件是否用來產生頁面主題。
ItemType	取得在繫結容器上設定的類型。
Localize	取得布林值，指出這個 ControlBuilder 物件所建立的控制項是否當地語系化。
NamingContainerType	取得這個產生器所建立之控制項的命名容器型別。
PageVirtualPath	取得欲以此 ControlBuilder 執行個體組建之頁面的虛擬路徑。
Parser	取得負責剖析控制項的 TemplateParser。
ServiceProvider	取得這個 ControlBuilder 物件的服務物件。
SubBuilders	取得這個 ControlBuilder 物件之子 ControlBuilder 物件的清單。
TagName	取得要建置的控制項的標記名稱。
TemplatePropertyEntries	取得樣板屬性項目的集合。
ThemeResolutionService	取得 IThemeResolutionService 物件，這個物件在設計階段用來管理控制項主題和面板。

方法

AllowWhitespaceLiterals()	判斷控制項的開頭和結尾標記之間的內容是否允許空白字元常值。此方法由 ASP.NET 網頁架構呼叫。
AppendLiteralString(String)	將指定的常值內容加入控制項。此方法由 ASP.NET 網頁架構呼叫。
AppendSubBuilder(ControlBuilder)	針對屬於容器控制項的任何子控制項，將產生器加入 ControlBuilder 物件中。
BuildObject()	建置這個 ControlBuilder 物件所參考之控制項的設計階段執行個體。
CloseControl()	由剖析器呼叫，通知產生器，控制項開頭和結尾標記的剖析已經完成。
CreateBuilderFromType(TemplateParser, ControlBuilder, Type, String, String, IDictionary, Int32, String)	根據指定的標記名稱和物件型別，以及其他定義產生器的參數，建立 ControlBuilder 物件。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetChildControlType(String, IDictionary)	取得對應到子標記之控制項類型的 Type。此方法由 ASP.NET 網頁架構呼叫。
GetHashCode()	做為預設雜湊函式。 (繼承來源 Object)
GetObjectPersistData()	建立這個 ObjectPersistData 物件的 ControlBuilder 物件。
GetResourceKey()	擷取這個 ControlBuilder 物件的資源索引鍵。
GetType()	取得目前執行個體的 Type。 (繼承來源 Object)
HasBody()	判斷控制項是否有開頭和結尾標記。此方法由 ASP.NET 網頁架構呼叫。
HtmlDecodeLiterals()	判斷 HTML 控制項的常值字串是否必須為解碼的 HTML。此方法由 ASP.NET 網頁架構呼叫。
Init(TemplateParser, ControlBuilder, Type, String, String, IDictionary)	初始化 ControlBuilder，以便當它執行個體化之後，可供使用。此方法由 ASP.NET 網頁架構呼叫。
MemberwiseClone()	建立目前 Object 的淺層複製。 (繼承來源 Object)
NeedsTagInnerText()	判斷控制項產生器是否需要取得它的內部文字。如果是，必須呼叫 SetTagInnerText(String) 方法。此方法由 ASP.NET 網頁架構呼叫。
OnAppendToParentBuilder(ControlBuilder)	告知 ControlBuilder 已經加入到父控制項產生器中。
ProcessGeneratedCode(CodeCompileUnit, CodeTypeDeclaration, CodeTypeDeclaration, CodeMemberMethod, CodeMemberMethod)	讓自訂控制項產生器存取產生的程式碼文件物件模型 (CodeDom)，並在剖析及建置控制項的過程中插入及修改程式碼。
SetResourceKey(String)	設定這個 ControlBuilder 物件的資源索引鍵。
SetServiceProvider(IServiceProvider)	設定這個 ControlBuilder 物件的服務物件。
SetTagInnerText(String)	提供控制項標記內部文字給 ControlBuilder。
ToString()	傳回代表目前物件的字串。 (繼承來源 Object)

適用於

ControlBuilder 類別

定義

範例

備註

建構函式

欄位

屬性

方法

適用於

另請參閱

意見反應

其他資源