How to: Create an ASP.NET User Control
User control declarative syntax is very similar to syntax used to create an ASP.NET Web page. The primary differences are that the user controls use andirective in place of an directive, and that the user controls do not include the html, body, and form elements around the content.
For more information about ASP.NET Web pages and how to create them, see. For more information about working with a user control in an ASP.NET Web page, see .
To create a user control
Create a new file and give it a name with the extension .ascx.
For example, name your user control
You cannot put user controls in the Web site's App_Code folder. If a user control is in the App_Code folder, a parse error occurs when the containing page runs.
Create andirective at the top of the page and specify the programming language you want to use for the control (if any).
Add controls that you want the user control to display.
Add code for the tasks that the user control will perform, such as handling control events or reading data from a data source.
Create properties in the control if you want to be able to share information between the user control and the hosting page. You create properties as you would for any class, either as public members or with get and set accessors.
The following example shows a complete user control. The user control displays a read-only text box with a number in it and two arrows that users can click to increment and decrement the value in the text box. The control exposes three properties,
CurrentValue, that can be used in the hosting page.
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.
<%@ Control Language="VB" ClassName="Spinner" %> <script runat="server"> Private m_minValue As Integer = 0 Private m_maxValue As Integer = 100 Private m_currentNumber As Integer = 0 Public Property MinValue() As Integer Get Return m_minValue End Get Set(ByVal value As Integer) If value >= Me.MaxValue Then Throw New Exception _ ("MinValue must be less than MaxValue.") Else m_minValue = value End If End Set End Property Public Property MaxValue() As Integer Get Return m_maxValue End Get Set(ByVal value As Integer) If value <= Me.MinValue Then Throw New Exception _ ("MaxValue must be greater than MinValue.") Else m_maxValue = value End If End Set End Property Public ReadOnly Property CurrentNumber() As Integer Get Return m_currentNumber End Get End Property Protected Sub Page_Load(ByVal sender As Object, _ ByVal e As System.EventArgs) If IsPostBack Then m_currentNumber = CInt(ViewState("currentNumber")) Else m_currentNumber = Me.MinValue End If DisplayNumber() End Sub Protected Sub DisplayNumber() textNumber.Text = Me.CurrentNumber.ToString() ViewState("currentNumber") = Me.CurrentNumber.ToString() End Sub Protected Sub buttonUp_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) If m_currentNumber = Me.MaxValue Then m_currentNumber = Me.MinValue Else m_currentNumber += 1 End If DisplayNumber() End Sub Protected Sub buttonDown_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) If m_currentNumber = Me.MinValue Then m_currentNumber = Me.MaxValue Else m_currentNumber -= 1 End If DisplayNumber() End Sub </script> <asp:TextBox ID="textNumber" runat="server" ReadOnly="True" Width="32px" Enabled="False" /> <asp:Button Font-Bold="True" ID="buttonUp" runat="server" Text="^" OnClick="buttonUp_Click" /> <asp:Button Font-Bold="True" ID="buttonDown" runat="server" Text="v" OnClick="buttonDown_Click" />
The example user control includes code to define three properties,
CurrentValue. Properties in user controls must be public. In this example, all three properties are created with get and set accessors to enable the control to check for values outside of an acceptable range. However, you can create a property by simply declaring a public member.
MaxValue properties can be set declaratively in the containing page using syntax such as the following:
<uc:Spinner ID="Spinner1" runat="server" MinValue=0 MaxValue=10 />
When the user control is initialized as part of the containing page, ASP.NET parses the declared property values and sets them in the user control automatically.
As with pages, the user control is re-initialized with each postback. Property values therefore must be stored in a persistent location between postbacks. A typical location to store property values is view state. During theevent, you must check for a postback and reload the property values from the store. For more information about view state, see .
For the example, exception handling has been simplified. In the set accessors for the
MaxValue properties, if the properties are set to an unacceptable value, the user control code throws a simple exception in which the string is hard-coded. In real applications, you should create a special exception class and not use hard-coded strings to display error information.