Share via

Custom Server Control Syntax

  • Article

Custom server control syntax is used to declare user controls and custom server controls as markup elements in ASP.NET application files, including Web pages, user controls, and master pages. This syntax is nearly identical to the syntax used to declare all ASP.NET server controls, except that for custom and user controls you typically declare a unique tag prefix and a tag name that corresponds to your control.

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

Attributes

  • tagprefix
    An alias for the fully qualified namespace of the markup elements used on the page. The value of the alias is arbitrary, but it provides a shorthand way of associating the markup for a custom control or user control with the namespace of the other markup elements declared in an ASP.NET file.
  • tagname
    For a custom control, the tagname refers to the name of a type for which ASP.NET will create a run-time instance. For a user control, the tagname maps to the associated source file that defines the user control, and that file in turn defines the type for which ASP.NET creates an instance.
  • id
    A unique identifier that enables programmatic reference to the control.
  • attributename
    The name of an attribute, which corresponds to a property on the control.
  • value
    The value assigned to the attribute (property).
  • eventname
    The name of an event in the control.
  • eventhandlermethod
    The name of an event handler defined to handle the specified event for the control.

Remarks

Use custom server control syntax to declare user controls and custom server controls within the body of an ASP.NET Web page. For this syntax to work, the control must be registered on the page or in a configuration file (you can register a control on all pages of an application by adding it to the <controls> of the Web.config file). You can register a control on an individual page by using the @ Register directive.

The opening tag of an element for a user or custom control must include a runat="server" attribute/value pair. To enable programmatic referencing of the control, you can optionally specify a unique value for the id attribute.

Any properties that you have authored on a user or 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 might 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 controls with properties, see Server Control Simple Properties and Subproperties.

You can declare events with custom server controls and user controls in the same way you would with any ASP.NET server control. Specify the event binding in the opening tag of the server control with an attribute and value. For more information on authoring custom server controls that support events, see Server Event Handling in ASP.NET Web Pages.

You can 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 How to: Create Templated ASP.NET User Controls.

Example

The following code example demonstrates how you can register and declare a custom server control in an ASP.NET Web page. The first section of code creates a public class derived from the Button class. The second part of the code is a Web page that hosts the custom button. Notice that the Web page uses the @ Register directive to register the namespace for the control and to set the tagprefix attribute. The control is then referenced in the page by using the tagprefix value and the control's class name, separated by a colon (:).

For the code example to run, you must compile this custom control. You can compile it explicitly and put the resulting assembly in your Web site's Bin folder or the global assembly cache. Alternatively, you can put the source code in your site's App_Code folder, where it will be dynamically compiled at run time. This code example uses dynamic compilation, which is why the @ Register directive in the page does not need to declare an Assembly attribute (because the source is dynamically compiled at run time). For a walkthrough that demonstrates how to compile, see Walkthrough: Developing and Using a Custom Server Control.

Security noteSecurity Note

This example has a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

 
// A custom Button control to reference in the page.
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Security.Permissions
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

namespace Samples.AspNet.CS.Controls
{
  [AspNetHostingPermission(SecurityAction.Demand,
  Level = AspNetHostingPermissionLevel.Minimal)]
  [AspNetHostingPermission(SecurityAction.InheritanceDemand,
    Level = AspNetHostingPermissionLevel.Minimal)]
  public class CustomButton : Button
  {
    public CustomButton()
    {
      this.Text = "Click Here";
    }
  }
}

<!-- A page that references the custom control. -->
<%@Page language="C#" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"      namespace="Samples.AspNet.CS.Controls" %>
    
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html>   
 <script runat="server">
     private void custButton_Click(Object sender, EventArgs e)
     {
       TextBox.BackColor = System.Drawing.Color.Green;
       TextBox.Text = "You clicked the button";
     }       
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton"          onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

' A custom Button control to reference in the page.
Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Drawing
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.Configuration
Imports System.Data.Sql
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts

Namespace Samples.AspNet.VB.Controls

  <AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  <AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class CustomButton
    Inherits Button

    Public Sub New()
      Me.Text = "Click Here"
    End Sub

  End Class

End Namespace
<!-- A page that references the custom control. -->
<%@ Page Language="VB" %>
<!-- This directive does not require the assembly attribute 
     because the source file is in the App_Code directory, 
     so it gets dynamically compiled with the page. -->
<%@ Register TagPrefix="custom"    namespace="Samples.AspNet.VB.Controls" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html>   
 <script runat="server">
   Sub custButton_Click(ByVal sender As Object, _
    ByVal e As EventArgs)
     TextBox.BackColor = Drawing.Color.Green
     TextBox.Text = "You clicked the button."
   End Sub
 </script>
 <body>      
    <form id="Form1" runat=server>
       Here is the custom button.<br>
       <custom:CustomButton runat="server" id="custButton"          onclick="custButton_Click" /> 
       <br>
       <br>
       <asp:TextBox id = "TextBox" Text="Click the button"
        Width = "200" BackColor="Cyan" runat="server" /> 
       <br>      
    </form>         
  </body>          
</html>

See Also

Concepts

ASP.NET Web Page Syntax Overview