Creating a User Control

  • Article

You can create a user control declaratively by using a text or HTML editor. User control declarative syntax is very similar to syntax used to create a Web Forms page. The primary differences are that the user controls use an @ Control directive in place of an @ Page directive, and that the user controls do not include the <html>, <body>, and <form> elements around the content.

For more information about Web Forms pages and how to create them, see Introduction to Web Forms Pages. For more information about declaring a user control in a Web Forms page, see Including a User Control in a Web Forms Page.

A user control can be as simple as a text file, or it can contain other ASP.NET server controls. If you want to share information between the user control and the hosting page, you can create properties for the user control.

The following procedure outlines a simple logon form that you can include on multiple pages of an application.

To create a user control

  1. Create a new file and give it a name with the extension .ascx.

    For example, name your user control Logonform.ascx.

  2. Create an @ Control directive at the top of the page and specify the programming language you want to use for the control (if any).

    The following example shows an @ Control directive for a page that uses Visual Basic .NET as its programming language.

    <%@ Control Language="VB" %>

    Note   When you create a Web application using Visual Studio .NET, all pages and user controls in the application must be in the same programming language.

  3. Create any user interface elements (controls) that you want the user control to display.

  4. Create properties in the control if you want to be able to share information between the user control and the hosting page.

    The following example shows a complete user control that displays a text box where users can enter a name and a label where the name is displayed. The user control also exposes a Name property so that the name can be set in the hosting page.

    <%@ Control Language="VB" %>
<script runat="server">
Public Property Name As String
   Get
       Return labelOutput.Text
   End Get
   Set
       textName.Text = Server.HtmlEncode(value)
       labelOutput.Text = Server.HtmlEncode(value)
   End Set
End Property

Public Sub buttonDisplayName_Click(sender As Object, e As EventArgs)
   labelOutput.Text = textName.Text
End Sub
</script>

<table>
    <tbody>
        <tr>
            <td>
                <b>Enter your name:</b></td>
        </tr>
        <tr>
            <td>
                <asp:TextBox id="textName" 
                    runat="server">
                </asp:TextBox>
            </td>
        </tr>
        <tr>
            <td>
                <asp:button id="buttonDisplayName" 
                   onclick="buttonDisplayName_Click" 
                   runat="server" text="Submit">
                </asp:button>
            </td>
        </tr>
        <tr>
            <td><b>Hello, 
                 <asp:Label id="labelOutput" 
                     runat="server">
                 </asp:Label>.</b>
            </td>
        </tr>
    </tbody>
</table>

[C#]<%@ Control Language="C#" %>
<script runat="server">
    public String Name {
        get
        {
            return labelOutput.Text;
        }
        set
        {
            textName.Text = Server.HtmlEncode(value);
            labelOutput.Text = Server.HtmlEncode(value);
        }
    }

    void buttonDisplayName_Click(object sender, EventArgs e) {
       labelOutput.Text = textName.Text;
    }
</script>

<table>
    <tbody>
        <tr>
            <td>
                <b>Enter your name:</b></td>
        </tr>
        <tr>
            <td>
                <asp:TextBox id="textName" 
                    runat="server">
                </asp:TextBox>
            </td>
        </tr>
        <tr>
            <td>
                <asp:button id="buttonDisplayName" 
                   onclick="buttonDisplayName_Click" 
                   runat="server" text="Submit">
                </asp:button>
            </td>
        </tr>
        <tr>
            <td><b>Hello, 
                 <asp:Label id="labelOutput" 
                     runat="server">
                 </asp:Label>.</b>
            </td>
        </tr>
    </tbody>
</table>

For information on how to add the user control to an ASP.NET Web page, see Including a User Control in a Web Forms Page.

See Also

Web Forms User Controls | Including a User Control in a Web Forms Page | Server Event Handling in Web Forms Pages