ASP.NET User Controls Overview

  • Article
  • five minutes to read

At times, you might need functionality in a control that is not provided by the built-in ASP.NET Spider web server controls. In those cases, you can create your own controls. You have 2 options. You tin can create:

  • User controls. User controls are containers into which you can put markup and Spider web server controls. Yous can so treat the user control as a unit of measurement and define properties and methods for it.

  • Custom controls. A custom control is a course that you write that derives from Control or WebControl.

User controls are substantially easier to create than custom controls, because you can reuse existing controls. They make it particularly easy to create controls with circuitous user interface elements.

This topic provides an overview of working with ASP.NET user controls.

User Control Structure

An ASP.Cyberspace Spider web user command is similar to a complete ASP.NET Spider web page (.aspx file), with both a user interface page and code. Y'all create the user control in much the same fashion yous create an ASP.Net page and and so add together the markup and child controls that you need. A user control can include code to manipulate its contents similar a page tin can, including performing tasks such every bit data binding.

A user controls differs from an ASP.Internet Web page in these means:

  • The file name extension for the user control is .ascx.

  • Instead of an @ Page directive, the user command contains an @ Control directive that defines configuration and other backdrop.

  • User controls cannot run as stand-alone files. Instead, you must add them to ASP.NET pages, every bit y'all would whatsoever control.

  • The user command does not have html, body, or form elements in it. These elements must be in the hosting page.

Y'all can utilise the same HTML elements (except the html, body, or form elements) and Web controls on a user control that you practice on an ASP.NET Web page. For instance, if you are creating a user control to apply as a toolbar, y'all can put a serial of Push button Web server controls onto the control and create consequence handlers for the buttons.

The following example shows a user control that implements a spinner control where users can click up and downwards buttons to rotate through a series of choices in a text box.

Security note Security 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.

 
              <%@ Control Language="VB" ClassName="UserControl1" %> <script runat="server">     Protected colors As Cord() = {"Red", "Green", "Blue", "Yellowish"}     Protected currentColorIndex As Integer = 0     Protected Sub Page_Load(ByVal sender As Object, _             ByVal e Every bit System.EventArgs)         If IsPostBack Then             currentColorIndex = CInt(ViewState("currentColorIndex"))         Else             currentColorIndex = 0             DisplayColor()         End If     Stop Sub          Protected Sub DisplayColor()         textColor.Text = colors(currentColorIndex)         ViewState("currentColorIndex") = currentColorIndex.ToString()     End Sub      Protected Sub buttonUp_Click(ByVal sender As Object, _             ByVal e As System.EventArgs)         If currentColorIndex = 0 And so             currentColorIndex = colors.Length - 1         Else             currentColorIndex -= 1         End If         DisplayColor()     End Sub          Protected Sub buttonDown_Click(ByVal sender As Object, _             ByVal e Equally System.EventArgs)         If currentColorIndex = colors.Length - one Then             currentColorIndex = 0         Else             currentColorIndex += 1         Finish If         DisplayColor()     Terminate Sub </script> <asp:TextBox ID="textColor" runat="server"      ReadOnly="Truthful" /> <asp:Push Font-Assuming="Truthful" ID="buttonUp" runat="server"       Text="^" OnClick="buttonUp_Click" /> <asp:Button Font-Bold="True" ID="buttonDown" runat="server"      Text="v" OnClick="buttonDown_Click" />                          
              <% @ Command Language="C#" ClassName="UserControl1" %> <script runat="server">     protected int currentColorIndex;     protected Cord[] colors = {"Crimson", "Blue", "Green", "Yellow"};     protected void Page_Load(object sender, EventArgs e)     {         if (IsPostBack)         {             currentColorIndex =                  Int16.Parse(ViewState["currentColorIndex"].ToString());         }         else         {             currentColorIndex = 0;             DisplayColor();         }     }          protected void DisplayColor()     {         textColor.Text = colors[currentColorIndex];         ViewState["currentColorIndex"] = currentColorIndex.ToString();     }          protected void buttonUp_Click(object sender, EventArgs e)     {         if(currentColorIndex == 0)         {             currentColorIndex = colors.Length - ane;         }         else         {             currentColorIndex -= 1;         }         DisplayColor();     }      protected void buttonDown_Click(object sender, EventArgs e)     {         if(currentColorIndex == (colors.Length - 1))         {             currentColorIndex = 0;         }             else         {             currentColorIndex += i;         }         DisplayColor();     } </script> <asp:TextBox ID="textColor" runat="server"      ReadOnly="Truthful" /> <asp:Button Font-Bold="True" ID="buttonUp" runat="server"      Text="^" OnClick="buttonUp_Click" /> <asp:Push button Font-Bold="Truthful" ID="buttonDown" runat="server"      Text="v" OnClick="buttonDown_Click" />

Notice that the user control looks much similar an ASP.Net page — it contains several controls (a TextBox command and two Push button controls) and lawmaking that handles the buttons' Click events and the folio's Load event. However, the control contains no markup except for the controls, and instead of an @ Folio directive information technology contains an @ Command directive.

Calculation a User Control to a Page

Yous add a user control to a page by registering it on the host page. When you lot register it, y'all specify the .ascx file that contains the user control, a tag prefix, and a tag name that you lot will use to declare the user command on the page. For details, see How to: Include a User Control in an ASP.Internet Web Page.

Defining Properties and Methods for a User Control

You can define properties and methods for a user control the same way you do for a page. By defining a belongings for a user control, yous get in possible to gear up its properties declaratively and in code.

Events in User Controls

When a user command contains Spider web server controls, you can write code in the user command to handle the events raised by the kid controls. For case, if your user control contains a Push control, you can create a handler in the user control for the button'south Click event.

By default, events raised by child controls in a user control are non bachelor to the host page. However, yous can ascertain events for your user control and enhance them and then that the host page is notified of the event. You practise this in the same way that you ascertain events for any class. For more data, see Raising an Event.

Referencing External Resource

When a user command runs, references to external resource such every bit images or anchors to other pages are resolved using the URL of the user control as the base URL. For example, if the user command contains an Image control whose ImageUrl property is set up to Images/Button1.gif, the URL of the image is added to the URL of the user control to resolve the complete path to the image. If the user command references a resources that is not in a subfolder of the user control itself, y'all must provide a path that resolves to the correct folder at run time. For more than information on specifying paths for ASP.Net server controls, see ASP.NET Web Site Paths.

Caching and User Controls

User controls tin can back up caching directives that are separate from the host folio. You tin therefore add user controls to pages and to enshroud portions of a page. For details, see Caching Portions of an ASP.Net Page.

See Likewise

Other Resources

ASP.Cyberspace User Controls