ControlBuilder Class

Definition

Supporta il parser della pagina nella compilazione di un controllo e dei controlli figlio in esso contenuti.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
Inheritance
ControlBuilder
Derived

Examples

Nell'esempio di codice seguente viene creato un controllo Table i cui attributi e contenuto vengono definiti al momento della compilazione della tabella.The following code example creates a Table control whose attributes and content are defined at the time the table is built. Di seguito è riportata la riga di comando da usare per compilare il file eseguibile.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

Nell'esempio di codice seguente viene usato il controllo personalizzato precedente.The following code example uses the previous custom control. In particolare, compila una tabella i cui attributi e contenuto vengono definiti in fase di esecuzione.In particular, it builds a table whose attributes and content are defined at run time. Si noti che i valori mostrati nella direttiva @ Register riflettono la riga di comando precedente.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>

Remarks

Per impostazione predefinita, ogni controllo in una pagina è associato a una classe ControlBuilder predefinita.By default, every control on a page is associated with a default ControlBuilder class. Durante l'analisi, il Framework della pagina ASP.NET compila un albero di ControlBuilder oggetti corrispondenti all'albero dei controlli per la pagina.During parsing, the ASP.NET page framework builds a tree of ControlBuilder objects corresponding to the tree of controls for the page. L'albero ControlBuilder viene quindi utilizzato per generare il codice della pagina per creare la struttura ad albero del controllo.The ControlBuilder tree is then used to generate page code to create the control tree. Oltre ai controlli figlio, l'ControlBuilder definisce il comportamento di analisi del contenuto all'interno dei tag di controllo.In addition to child controls, the ControlBuilder defines the behavior of how the content within control tags is parsed. È possibile eseguire l'override di questo comportamento predefinito definendo la classe del generatore di controlli personalizzata.You can override this default behavior by defining your own custom control builder class. Questa operazione viene eseguita applicando un attributo ControlBuilderAttribute alla classe del generatore di controlli, come indicato di seguito:This is done by applying a ControlBuilderAttribute attribute to your control builder class as follows:

[ControlBuilderAttribute(typeof(ControlBuilderType))]

Constructors

ControlBuilder()

Inizializza una nuova istanza della classe ControlBuilder.Initializes a new instance of the ControlBuilder class.

Fields

DesignerFilter

Rappresenta la stringa letterale "__designer".Represents the "__designer" literal string.

Properties

BindingContainerBuilder

Ottiene il generatore di controlli che corrisponde al contenitore di associazione per il controllo creato da questo generatore.Gets the control builder that corresponds to the binding container for the control that this builder creates.

BindingContainerType

Ottiene il tipo di contenitore di associazione per il controllo creato da questo generatore.Gets the type of the binding container for the control that this builder creates.

ComplexPropertyEntries

Ottiene una raccolta di voci di proprietà complesse.Gets a collection of complex property entries.

ControlType

Ottiene l'oggetto Type per il controllo da creare.Gets the Type for the control to be created.

CurrentFilterResolutionService

Ottiene un oggetto IFilterResolutionService che consente di gestire i servizi correlati ai filtri di periferica durante l'analisi e il mantenimento dei controlli nella finestra di progettazione.Gets an IFilterResolutionService object that is used to manage device-filter related services when parsing and persisting controls in the designer.

DeclareType

Ottiene il tipo che verrà utilizzato dalla generazione del codice per dichiarare il controllo.Gets the type that will be used by code generation to declare the control.

FChildrenAsProperties

Ottiene un valore che determina se il controllo ha un ParseChildrenAttribute con ChildrenAsProperties impostato su true.Gets a value that determines whether the control has a ParseChildrenAttribute with ChildrenAsProperties set to true.

FIsNonParserAccessor

Ottiene un valore che determina se il controllo implementa l'interfaccia IParserAccessor.Gets a value that determines whether the control implements the IParserAccessor interface.

HasAspCode

Ottiene un valore che indica se il controllo contiene blocchi di codice.Gets a value indicating whether the control contains any code blocks.

ID

Ottiene o imposta la proprietà ID per il controllo da compilare.Gets or sets the identifier property for the control to be built.

InDesigner

Restituisce un valore che indica se l'oggetto ControlBuilder è in esecuzione nella finestra di progettazione.Returns whether the ControlBuilder is running in the designer.

InPageTheme

Ottiene un valore Boolean che indica se questo oggetto ControlBuilder viene utilizzato per generare temi di pagina.Gets a Boolean value indicating whether this ControlBuilder object is used to generate page themes.

ItemType

Ottiene il tipo impostato sul contenitore di associazione.Gets the type set on the binding container.

Localize

Ottiene un valore Boolean che indica se il controllo creato da questo oggetto ControlBuilder è localizzato.Gets a Boolean value indicating whether the control that is created by this ControlBuilder object is localized.

NamingContainerType

Ottiene il tipo di contenitore di denominazione per il controllo creato da questo generatore.Gets the type of the naming container for the control that this builder creates.

PageVirtualPath

Ottiene il percorso virtuale di una pagina da compilare a partire da questa istanza di ControlBuilder.Gets the virtual path of a page to be built by this ControlBuilder instance.

Parser

Ottiene l'oggetto TemplateParser responsabile dell'analisi del controllo.Gets the TemplateParser responsible for parsing the control.

ServiceProvider

Ottiene l'oggetto servizio per questo oggetto ControlBuilder.Gets the service object for this ControlBuilder object.

SubBuilders

Ottiene un elenco di oggetti figlio ControlBuilder per questo oggetto ControlBuilder.Gets a list of child ControlBuilder objects for this ControlBuilder object.

TagName

Ottiene il nome del tag per il controllo da compilare.Gets the tag name for the control to be built.

TemplatePropertyEntries

Ottiene una raccolta di voci di proprietà di modello.Gets a collection of template property entries.

ThemeResolutionService

Ottiene un oggetto IThemeResolutionService utilizzato in fase di progettazione per gestire i temi e le interfacce del controllo.Gets an IThemeResolutionService object that is used in design time to manage control themes and skins.

Methods

AllowWhitespaceLiterals()

Determina se sono consentiti valori letterali con spazi nel contenuto tra i tag di apertura e di chiusura di un controllo.Determines whether white space literals are permitted in the content between a control's opening and closing tags. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

AppendLiteralString(String)

Aggiunge il contenuto literal specificato a un controllo.Adds the specified literal content to a control. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

AppendSubBuilder(ControlBuilder)

Aggiunge generatori all'oggetto ControlBuilder per qualsiasi controllo figlio che appartiene al controllo contenitore.Adds builders to the ControlBuilder object for any child controls that belong to the container control.

BuildObject()

Compila un'istanza in fase di progettazione del controllo a cui questo oggetto ControlBuilder fa riferimento.Builds a design-time instance of the control that is referred to by this ControlBuilder object.

CloseControl()

Metodo chiamato dal parser per comunicare al generatore che l'analisi dei tag di apertura e di chiusura del controllo è terminata.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)

Crea un oggetto ControlBuilder dal nome di tag e dal tipo di oggetto specificati, oltre ad altri parametri che definiscono il generatore.Creates a ControlBuilder object from the specified tag name and object type, as well as other parameters defining the builder.

Equals(Object)

Determina se l'oggetto specificato è uguale all'oggetto corrente.Determines whether the specified object is equal to the current object.

(Inherited from Object)
GetChildControlType(String, IDictionary)

Ottiene l'oggetto Type del tipo di controllo corrispondente a un tag figlio.Obtains the Type of the control type corresponding to a child tag. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

GetHashCode()

Funge da funzione hash predefinita.Serves as the default hash function.

(Inherited from Object)
GetObjectPersistData()

Crea l'oggetto ObjectPersistData per questo oggetto ControlBuilder.Creates the ObjectPersistData object for this ControlBuilder object.

GetResourceKey()

Recupera la chiave di risorsa per questo oggetto ControlBuilder.Retrieves the resource key for this ControlBuilder object.

GetType()

Ottiene l'oggetto Type dell'istanza corrente.Gets the Type of the current instance.

(Inherited from Object)
HasBody()

Determina se un controllo dispone di entrambi i tag di apertura e chiusura.Determines if a control has both an opening and closing tag. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

HtmlDecodeLiterals()

Determina se la stringa letterale di un controllo HTML deve essere decodificata in linguaggio HTML.Determines whether the literal string of an HTML control must be HTML decoded. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

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

Inizializza l'oggetto ControlBuilder da utilizzare dopo la creazione della relativa istanza.Initializes the ControlBuilder for use after it is instantiated. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

MemberwiseClone()

Crea una copia superficiale dell'oggetto Object corrente.Creates a shallow copy of the current Object.

(Inherited from Object)
NeedsTagInnerText()

Determina se il generatore di controllo deve ottenere il testo interno.Determines if the control builder needs to get its inner text. In questo caso, è necessario chiamare il metodo SetTagInnerText(String).If so, the SetTagInnerText(String) method must be called. Questo metodo viene chiamato dal framework per le pagine ASP.NET.This method is called by the ASP.NET page framework.

OnAppendToParentBuilder(ControlBuilder)

Notifica all'oggetto ControlBuilder che viene aggiunto a un generatore di controllo padre.Notifies the ControlBuilder that it is being added to a parent control builder.

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

Consente a compilatori di controllo personalizzati di accedere al CodeDom (Code Document Object Model) generato e inserire e modificare il codice durante il processo di analisi e compilazione dei controlli.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)

Imposta la chiave di risorsa per questo oggetto ControlBuilder.Sets the resource key for this ControlBuilder object.

SetServiceProvider(IServiceProvider)

Imposta l'oggetto servizio per questo oggetto ControlBuilder.Sets the service object for this ControlBuilder object.

SetTagInnerText(String)

Fornisce all'oggetto ControlBuilder il testo interno del tag di controllo.Provides the ControlBuilder with the inner text of the control tag.

ToString()

Restituisce una stringa che rappresenta l'oggetto corrente.Returns a string that represents the current object.

(Inherited from Object)

Applies to

See also