ControlBuilder Classe

Referência

Definição

Namespace:: System.Web.UI

Assembly:: System.Web.dll

Importante

Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Dá suporte ao analisador de página ao criar um controle e os controles filhos que ele contém.

public ref class ControlBuilder

public class ControlBuilder

type ControlBuilder = class

Public Class ControlBuilder

Herança: Object
ControlBuilder

Derivado: System.Web.UI.CodeStatementBuilder

System.Web.UI.DataSourceControlBuilder

System.Web.UI.HtmlControls.HtmlEmptyTagControlBuilder

System.Web.UI.HtmlControls.HtmlHeadBuilder

System.Web.UI.HtmlControls.HtmlSelectBuilder

Mais…

Exemplos

O exemplo de código a seguir cria um Table controle cujos atributos e conteúdo são definidos no momento em que a tabela é criada. Veja a seguir a linha de comando a ser usada para criar o executável.

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

O exemplo de código a seguir usa o controle personalizado anterior. Em particular, ele cria uma tabela cujos atributos e conteúdo são definidos em tempo de execução. Observe que os valores mostrados na diretiva @ Register refletem a linha de comando anterior.

<%@ 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>

Comentários

Por padrão, cada controle em uma página é associado a uma classe padrão ControlBuilder . Durante a análise, a estrutura de página ASP.NET cria uma árvore de ControlBuilder objetos correspondente à árvore de controles da página. Em ControlBuilder seguida, a árvore é usada para gerar código de página para criar a árvore de controle. Além dos controles filho, o ControlBuilder define o comportamento de como o conteúdo dentro das marcas de controle é analisado. Você pode substituir esse comportamento padrão definindo sua própria classe de construtor de controle personalizado. Isso é feito aplicando um ControlBuilderAttribute atributo à classe do construtor de controle da seguinte maneira:

[ControlBuilderAttribute(typeof(ControlBuilderType))]

Construtores

ControlBuilder()

Inicializa uma nova instância da classe ControlBuilder.

Campos

DesignerFilter

Representa a cadeia "__designer" de caracteres literal.

Propriedades

BindingContainerBuilder	Obtém o construtor de controle que corresponde ao contêiner de associação para o controle que esse construtor cria.
BindingContainerType	Obtém o tipo do contêiner de associação para o controle que esse construtor cria.
ComplexPropertyEntries	Obtém uma coleção de entradas de propriedade complexa.
ControlType	Obtém o Type para o controle a ser criado.
CurrentFilterResolutionService	Obtém um objeto IFilterResolutionService que é usado para gerenciar serviços relacionados ao filtro de dispositivo ao analisar e persistir controles no designer.
DeclareType	Obtém o tipo que será usado pela geração de código para declarar o controle.
FChildrenAsProperties	Obtém um valor que determina se o controle tem um ParseChildrenAttribute com ChildrenAsProperties definido como `true`.
FIsNonParserAccessor	Obtém um valor que determina se o controle implementa a interface IParserAccessor.
HasAspCode	Obtém um valor que indica se o controle contém algum bloco de código.
ID	Obtém ou define a propriedade do identificador para o controle a ser criado.
InDesigner	Retorna se o ControlBuilder está sendo executado no designer.
InPageTheme	Obtém um valor booliano que indica se este objeto ControlBuilder é usado para gerar os temas de página.
ItemType	Obtém o tipo definido no contêiner de associação.
Localize	Obtém um valor booliano que indica se o controle criado por este objeto ControlBuilder está localizado.
NamingContainerType	Obtém o tipo do contêiner de nomenclatura para o controle que esse construtor cria.
PageVirtualPath	Obtém o caminho virtual de uma página a ser criada por esta instância ControlBuilder.
Parser	Obtém o TemplateParser responsável por analisar o controle.
ServiceProvider	Obtém o objeto de serviço para esse objeto ControlBuilder.
SubBuilders	Obtém uma lista de objetos ControlBuilder filho para esse objeto ControlBuilder.
TagName	Obtém o nome da marca para o controle a ser criado.
TemplatePropertyEntries	Obtém uma coleção de entradas de propriedade de modelo.
ThemeResolutionService	Obtém um objeto IThemeResolutionService que é usado no tempo de design para gerenciar os temas e capas do controle.

Métodos

AllowWhitespaceLiterals()	Determina se literais de espaço em branco são permitidos no conteúdo entre marcas de abertura e fechamento do controle. Esse método é chamado pela estrutura de página ASP.NET.
AppendLiteralString(String)	Adiciona o conteúdo literal especificado a um controle. Esse método é chamado pela estrutura de página ASP.NET.
AppendSubBuilder(ControlBuilder)	Adiciona construtores ao objeto ControlBuilder para quaisquer controles filho que pertençam ao controle de contêiner.
BuildObject()	Cria uma instância de tempo de design do controle que é referenciado por esse objeto ControlBuilder.
CloseControl()	Chamado pelo analisador para informar o construtor que a análise das marcas de abertura e fechamento do controle está concluída.
CreateBuilderFromType(TemplateParser, ControlBuilder, Type, String, String, IDictionary, Int32, String)	Cria um objeto ControlBuilder do tipo de objeto e do nome da marca especificados, bem como outros parâmetros que definem o construtor.
Equals(Object)	Determina se o objeto especificado é igual ao objeto atual. (Herdado de Object)
GetChildControlType(String, IDictionary)	Obtém o Type do tipo de controle correspondente a uma marca filha. Esse método é chamado pela estrutura de página ASP.NET.
GetHashCode()	Serve como a função de hash padrão. (Herdado de Object)
GetObjectPersistData()	Cria o objeto ObjectPersistData para este objeto ControlBuilder.
GetResourceKey()	Recupera a chave de recurso para este objeto ControlBuilder.
GetType()	Obtém o Type da instância atual. (Herdado de Object)
HasBody()	Determina se um controle tem uma marca de abertura e de fechamento. Esse método é chamado pela estrutura de página ASP.NET.
HtmlDecodeLiterals()	Determina se a cadeia de caracteres literal de um controle HTML deve ser decodificada para HTML. Esse método é chamado pela estrutura de página ASP.NET.
Init(TemplateParser, ControlBuilder, Type, String, String, IDictionary)	Inicializa o ControlBuilder para uso após ele ser instanciado. Esse método é chamado pela estrutura de página ASP.NET.
MemberwiseClone()	Cria uma cópia superficial do Object atual. (Herdado de Object)
NeedsTagInnerText()	Determina se o construtor de controle precisa obter seu texto interno. Se sim, o método SetTagInnerText(String) deve ser chamado. Esse método é chamado pela estrutura de página ASP.NET.
OnAppendToParentBuilder(ControlBuilder)	Notifica o ControlBuilder que está sendo adicionado a um construtor de controle pai.
ProcessGeneratedCode(CodeCompileUnit, CodeTypeDeclaration, CodeTypeDeclaration, CodeMemberMethod, CodeMemberMethod)	Permite que os criadores de controle personalizado acessem o CodeDom (Modelo de Objeto do Documento de Código) gerado e insiram e modifiquem o código durante o processo de análise e criação de controles.
SetResourceKey(String)	Define a chave de recurso para este objeto ControlBuilder.
SetServiceProvider(IServiceProvider)	Define o objeto de serviço para esse objeto ControlBuilder.
SetTagInnerText(String)	Fornece o ControlBuilder com o texto interno da marca do controle.
ToString()	Retorna uma cadeia de caracteres que representa o objeto atual. (Herdado de Object)

Aplica-se a

Compartilhar via