Custom Server Control Syntax

  • Article

Defines user controls and user-authored server controls declaratively in a Web Forms page.

<tagprefix:tagname id="OptionalID" attributename="value" eventname="eventhandlermethod" runat="server" />
OR
<tagprefix:tagname id="OptionalID" runat="server" > </tagprefix:tagname>

Attributes

  • tagprefix
    An alias for the fully qualified namespace of the control. Aliases for user-authored controls are declared with the @ Register directive.
  • tagname
    The name of the class that encapsulates the control.
  • id
    A unique identifier that enables programmatic reference to the control.
  • attributename
    The name of the attribute.
  • value
    The value assigned to the attribute.
  • eventname
    The event name of the control.
  • eventhandlermethod
    The name of the event handler method defined in the code for the Web Forms page.

Remarks

The opening tags of these elements must include a runat="server" attribute/value pair. If you want to enable programmatic referencing on the control, specify a unique value with the id attribute. You can include multiple custom server controls in a single @ Register directive.

Any properties that you have authored on a custom server control can be exposed declaratively in the opening tag of the server control. Simply declare the property as an attribute and assign it a value. For example, if you create a custom text box control with a width property, declaring width="50" in the opening tag of the control sets the server control's display width to fifty pixels.

In some cases, attributes may be objects that have their own properties. In this case, include the property name in the declaration. For example, if you create a custom text box control that includes a font attribute, it can include a name property. You can then declare the property in the opening tag of the server control as font-name="Arial". For more information about developing custom server control with properties, see Properties in ASP.NET Server Controls.

You can also declare events with custom server controls and user controls in the same way you would with any ASP.NET server control. Simply specify the event binding in the opening tag of the server control with an attribute and value. For more information about writing event handlers, see Event Handling in Web Forms. For more information on authoring custom server controls that support events, see Events in ASP.NET Server Controls.

You can also use and develop custom server controls that support inline templates. For details on how to declare templates in a custom server control, see Server Control Inline Template Syntax. To learn how to author custom server controls that support inline templates, see Developing Templated Controls.

Example

The following example demonstrates how you can register and declare a custom server control in a Web Forms page. The control's tag prefix is Custom and the class it creates is found in the CustomWebFormsControls namespace. It is declared using the Custom:MyButton tag in the body of the page.

<%@ Register TagPrefix="Custom" Namespace="CustomWebFormsControls" Assembly="CustomControls" %>
<html>   
   <script language="C#" runat=server>
      private void Button_Click(Object sender, EventArgs e) {
         TextBox.BackColor = System.Drawing.Color.Green;
         TextBox.Text = "You clicked the button";
      }   
   </script>
   <body>      
      <form method="POST" action="MyButton.aspx" runat=server>
         Here is our custom button.<br>
         <Custom:MyButton id="Button"  OnClick="Button_Click"
              runat=server/> 
            <br>
            <br>
         <asp:TextBox id = "TextBox" Text = "Click the button"
                Width = "200"  BackColor "Cyan" runat=server/> 
         <br>      
      </form>         
    </body>         
</html>
[Visual Basic]
<%@ Register TagPrefix="Custom" Namespace="CustomWebFormsControls" Assembly="CustomControls" %>
<html>   
   <script language="VB" runat=server>
      Private Sub Button_Click(sender As Object, e As EventArgs)
         TextBox.BackColor = System.Drawing.Color.Green
         TextBox.Text = "You clicked the button"
      End Sub
   </script>
   <body>      
      <form method="POST" action="MyButton.aspx" runat=server>
         Here is our custom button.<br>
         <Custom:MyButton id="Button"  OnClick="Button_Click"
                    runat=server/> 
            <br>
            <br>
         <asp:TextBox id = "TextBox" Text="Click the button" 
                      Width="200"  BackColor="Cyan" runat=server/> 
         <br>      
      </form>         
    </body>         
</html>

See Also

Introduction to Web Forms Pages | ASP.NET Web Forms Syntax