This documentation is archived and is not being maintained.

ControlBuilderAttribute Class

Specifies a ControlBuilder class for building a custom control within the ASP.NET parser. This class cannot be inherited.

For a list of all members of this type, see ControlBuilderAttribute Members.

System.Object
   System.Attribute
      System.Web.UI.ControlBuilderAttribute

[Visual Basic]
<AttributeUsage(AttributeTargets.Class)>
NotInheritable Public Class ControlBuilderAttribute
   Inherits Attribute
[C#]
[AttributeUsage(AttributeTargets.Class)]
public sealed class ControlBuilderAttribute : Attribute
[C++]
[AttributeUsage(AttributeTargets::Class)]
public __gc __sealed class ControlBuilderAttribute : public
   Attribute
[JScript]
public
   AttributeUsage(AttributeTargets.Class)
class ControlBuilderAttribute extends Attribute

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Remarks

This attribute specifies the builder Type to be used to create a custom control as follows:

[ControlBuilderAttribute(typeof(ControlBuilderType))]

Example

[Visual Basic, C#, C++] The following creates a customized selection list that is used to display a message based upon the SelectedIndex and the Message values defined at run time. The following command line is used to build the executable.

vbc /r:System.dll /r:System.Web.dll /r:System.Drawing.dll /t:library /out:myWebAppPath/bin/vb_MyControlBuilderAtt.dll ControlBuilderAtt.vb

csc /t:library /out:myWebAppPath/bin/cs_MyControlBuilderAtt.dll ControlBuilderAtt.cs

[Visual Basic] 

'File name: controlBuilderAttribute.vb.

Imports System
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Collections



Namespace CustomControls

Public Class MyVB_Item: Inherits Control
      
      Private _message As String
      
      Public Property Message() As String
         Get
            Return _message
         End Get
         Set
            _message = value
         End Set
      End Property
   End Class 'MyVB_Item
   
   Public Class VB_CustomParseControlBuilder: Inherits ControlBuilder

      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")>  _
      Public Overrides Function GetChildControlType(TagName As String, attributes As IDictionary) As Type
          If (TagName = "customitem")  Then
            Return GetType(CustomControls.MyVB_Item)
         End If
         Return Nothing
      End Function 'GetChildControlType
   End Class 'CustomParseControlBuilder
   
   <ControlBuilderAttribute(GetType(VB_CustomParseControlBuilder))>  Public Class MyVB_CustomParse: Inherits Control
      
      Private _items As New ArrayList
      Private _selectedIndex As Integer = 0
      
      
      Public Property SelectedIndex() As Integer
         Get
            Return _selectedIndex
         End Get
         Set
            _selectedIndex = value
         End Set
      End Property
      
      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
      Protected Overrides Sub AddParsedSubObject(obj As Object)
         If TypeOf obj Is MyVB_Item Then
            _items.Add(obj)
         End If
      End Sub 'AddParsedSubObject
      
      <System.Security.Permissions.PermissionSetAttribute(System.Security.Permissions.SecurityAction.Demand, Name:="FullTrust")> _
      Protected Overrides Sub Render(output As HtmlTextWriter)        
        output.Write(("<span style='background-color:aqua; color:red; font:8pt tahoma, verdana;'><b>" + CType(_items(SelectedIndex), MyVB_Item).Message + "</b></span>"))
      End Sub 'Render
   End Class 'MyVB_CustomParse 
   
End Namespace 'CustomControls


[C#] 

/* File name: controlBuilderAttribute.cs. */

using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections;


namespace CustomControls

{
  public class MyCS_Item : Control 
  /* Class name: MyCS_Item. 
   * Defines the child control class.
   */
    {

      private String _message;

      public String Message 
      {
        get 
        {
          return _message;
        }
        set 
        {
           _message = value;
        }
     }
    }


    public class CustomParseControlBuilder : ControlBuilder 
    /* Class name: CustomParserControlBuilder.
     * Defines the functions and data to be used in building custom controls. 
     * This class is referenced using the ControlBuilderAttribute class. See class below.
     */
    {
      [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")] 
      public override Type GetChildControlType(String tagName, IDictionary attributes) 
      {
        if (String.Compare(tagName, "customitem", true) == 0) 
        {
           return typeof(MyCS_Item);
        }
        return null;
      }
    }


    [ 
       ControlBuilderAttribute(typeof(CustomParseControlBuilder)) 
    ]
    public class MyCS_CustomParse : Control 
    /* Class name: MyCS_CustomParse.
     * Performs custom parsing of a MyCS_CustomParse control type 
     * child control. 
     * If the child control is of the allowed type, it is added to an 
     * array list. This list is accessed, using the container control attribute 
     * SelectedIndex, to obtain the related child control Message attribute to be displayed.
     */
    {

       private ArrayList _items         = new ArrayList();
       private int       _selectedIndex = 0;

       public int SelectedIndex 
       { 
           get 
           {
              return _selectedIndex;
           }
           set 
           {
              _selectedIndex = value;
           }
       }

       [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")] 
       protected override void AddParsedSubObject(Object obj) 
       /* Function name: AddParsedSubObject.
        * Updates the array list with the allowed child objects.
        * This function is called during the parsing of the child controls and 
        * after the GetChildControlType function defined in the associated control 
        * builder class.
        */
       {
          if (obj is MyCS_Item) 
         {
              _items.Add(obj);
           }
       }

       [System.Security.Permissions.PermissionSet(System.Security.Permissions.SecurityAction.Demand, Name="FullTrust")] 
       protected override void Render(HtmlTextWriter output) 
       /* Function name: Render.
        * Establishes the rules to render the built control. In this case, a message is
        * rendered that is a function of the parent control SelectedIndex attribute and 
        * the related child Message attribute.
        */
       {
          if (SelectedIndex < _items.Count) 
         {
              output.Write("<span style='background-color:aqua; color:red; font:8pt tahoma, verdana;'><b>" +
              ((MyCS_Item) _items[SelectedIndex]).Message + "</b></span>" );
         }
       }
    }    
}


[C++] 
/* File name: controlBuilderAttribute.cpp. */
#using <mscorlib.dll>
#using <System.dll>
#using <System.Web.dll>
using namespace System;
using namespace System::Web;
using namespace System::Web::UI;
using namespace System::Web::UI::WebControls;
using namespace System::Collections;

public __gc class MyCS_Item : public Control
{
   /* Class name: MyCS_Item.
   * Defines the child control class.
   */
private:
   String*  _message;

public:
   __property String * get_Message() 
   {
      return _message;
   }

   __property void set_Message(String * value) 
   {
      _message = value;
   }
};

public __gc class CustomParseControlBuilder : public ControlBuilder
{
   /* Class name: CustomParserControlBuilder.
   * Defines the functions and data to be used in building custom controls.
   * This class is referenced using the ControlBuilderAttribute class. See class below.
   */
public:
   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")] 
   Type * GetChildControlType(String * tagName, IDictionary* attributes) 
   {
      if (String::Compare(tagName, S"customitem", true) == 0)
         return __typeof(MyCS_Item);
      return 0;
   }
};

[ControlBuilderAttribute(__typeof(CustomParseControlBuilder))]
public __gc class MyCS_CustomParse : public Control
{
   /* Class name: MyCS_CustomParse.
   * Performs custom parsing of a MyCS_CustomParse control type
   * child control.
   * If the child control is of the allowed type, it is added to an
   * array list. This list is accessed, using the container control attribute
   * SelectedIndex, to obtain the related child control Message attribute to be displayed.
   */
private:
   ArrayList* _items;
   int _selectedIndex;

public:
   MyCS_CustomParse()
   {
      _items = new ArrayList();
      _selectedIndex = 0;
   }

   __property int get_SelectedIndex() 
   {
      return _selectedIndex;
   }

   __property void set_SelectedIndex(int value) 
   {
      _selectedIndex = value;
   }

protected:
   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")] 
   void AddParsedSubObject(Object * obj)
   {
      /* Function name: AddParsedSubObject.
      * Updates the array list with the allowed child objects.
      * This function is called during the parsing of the child controls and
      * after the GetChildControlType function defined in the associated control
      * builder class.
      */
      if (dynamic_cast<MyCS_Item*>(obj))
         _items->Add(obj);
   }

protected:
   [System::Security::Permissions::PermissionSet(System::Security::Permissions::SecurityAction::Demand, Name="FullTrust")] 
   void Render(HtmlTextWriter * output)
   {
      /* Function name: Render.
      * Establishes the rules to render the built control. In this case, a message is
      * rendered that is a function of the parent control SelectedIndex attribute and
      * the related child Message attribute.
      */
      if (SelectedIndex < _items->Count)
         output->Write(S"<span style='background-color:aqua; color:red; font:8pt tahoma, verdana;'><b> {0} </b></span>", (dynamic_cast<MyCS_Item*>(_items->Item[SelectedIndex])->Message));
   }
};

[Visual Basic, C#, C++] The following example uses the custom control defined above. In particular, it assigns the SelectedIndex and Message values at runtime to determine the message to be rendered. Notice, the values shown in the Register directive reflect the previous command line.

[Visual Basic] 
<%@ Register TagPrefix="custom" Assembly="myControlBuilderAtt" Namespace="CustomControls" %>
<h4>Using ControlBuilderAttribute Class<h4>
<form runat="server">
 <custom:MyVB_CustomParse SelectedIndex="3" runat=server>
 <customitem Message="VB version. Item One selected"/>
 <customitem Message="VB version. Item Two selected"/>
 <customitem Message="VB version. Item Three selected"/>
 <customitem Message="VB version. Item Four selected"/>
 </custom:MyVB_CustomParse>
</form>
[C#] 
<%@ Register TagPrefix="custom" Assembly="myControlBuilderAtt" Namespace="CustomControls" %>
<h4>Using ControlBuilderAttribute Class<h4>
<form runat="server">
 <custom:MyCS_CustomParse SelectedIndex="2" runat=server>
 <customitem Message="C# version. Item One selected"/>
 <customitem Message="C# version. Item Two selected"/>
 <customitem Message="C# version. Item Three selected"/>
 <customitem Message="C# version. Item Four selected"/>
 </custom:MyCS_CustomParse>
</form>

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Web.UI

Platforms: Windows 2000, Windows XP Professional, Windows Server 2003 family

Assembly: System.Web (in System.Web.dll)

See Also

ControlBuilderAttribute Members | System.Web.UI Namespace | Attribute | Developing a Composite Control

Show: