Developing User Controls in a Code-Behind File

Just as you can create Web Forms pages using code-behind files — separating the user interface (UI) syntax (in the .aspx file) from the logic that the page performs (the code-behind file) — you can do the same to create user controls. The techniques are the same, with some minor differences.

Note   If you are using a rapid application development (RAD) tool such as Visual Studio .NET to create your ASP.NET applications, the tool's default is to use code-behind techniques to build user controls and Web Forms pages. 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.

To develop user controls in a code-behind file

  1. Create a code-behind file that includes the namespaces that your user control will need to access. At a minimum you should include the System and the System.Web.UI namespaces, along with any other namespaces that your user control requires.
    Imports System
    Imports System.Web.UI
    Imports System.Web.UI.WebControls
    [C#]using System;
    using System.Web.UI;
    using System.Web.UI.WebControls;
  2. Declare a class that inherits from the UserControl class and write code to give it the functionality you want. Include any event-handling methods that you write for the user control. Also, declare public instances of the ASP.NET server controls that you plan to use in the user control.
    Public Class MyCodeBehind
    Inherits UserControl
        Public Name As TextBox
        Public Result As Label
        Public Sub SubmitBtn_Click(sender As Object, e As EventArgs)
            Result.Text = "Hi, " & Name.Text & ", welcome to ASP.NET!"
        End Sub
    End Class
    [C#]public class MyCodeBehind : UserControl {
        public TextBox   Name;
        public Label   Result;
        public void SubmitBtn_Click(Object sender, EventArgs e) {
            Result.Text = "Hi, " + Name.Text + ", welcome to ASP.NET!";   
  3. Name the code-behind file, making sure to include an extension that reflects the language in which you developed the file. If you do not do this, a compiler error will occur. In this example, the user control developed in Visual Basic is named UserControl.vb, and the one developed in C# is named UserControl.cs.
  4. Create an .ascx file, using the @ Control directive to indicate the name of the class the user control inherits and the path to the source file you created in step 1. Include the server controls and any text that you want the user control to display. When you declare the ID attribute on each server control, be sure it matches the name of the instance you created in the code-behind file. For example, the ID attribute in the <asp:textbox/> element below is Name, corresponding to the Name TextBox server control from step 2.
    <%@ control inherits = "MyCodeBehind" src = "UserControl.vb" %>
    <p>Name: <asp:textbox id="Name" runat="server"/> <br>
    <asp:button text="Click Me" OnClick="SubmitBtn_Click" runat="server"/><br>
    <asp:label id="Result" runat = "server" />
    [C#]<%@ control inherits = "MyCodeBehind" src = "UserControl.cs" %>
    <p>Name: <asp:textbox id="Name" runat="server"/> <br>
    <asp:button text="Click Me" OnClick="SubmitBtn_Click" runat="server"/><br>
    <asp:label id="Result" runat = "server" />
  5. Include the user control in the Web Forms pages where you want its functionality to appear. For more information, see Including a User Control in a Web Forms Page.

See Also

Introduction to Web Forms User Controls | Web Forms Code Model | Including a User Control in a Web Forms Page | @ Control | UserControl