This documentation is archived and is not being maintained.

Walkthrough: Converting a Web Forms Page to a User Control

Visual Studio .NET 2003

If you have developed a Web Forms page and decide you would like to access its functionality throughout your application, you can make some minor alterations to the file to change it to a user control. Web user controls are very similar to Web Forms pages, and they are created using the same techniques. When you convert a Web Forms page to a Web user control, you create a reusable UI component that you can use on other Web Forms pages.

For this walkthrough, you will create a basic Web Forms page that presents a personalized welcome message to the user. To convert the page to a Web user control, you will make a few changes to the code:

  • Change the code-behind base class from Page to UserControl
  • Delete the <html>, <head>, <body>, and <form> tags from the .aspx file
  • Change the ASP.NET directive type from @ Page to @ Control
  • Change the Codebehind attribute to refer to the control's code-behind class file (ascx.vb or ascx cs)
  • Change the .aspx file extension to .ascx

To test the control, you will create a new Web Forms page, add the control to it, and open the page in a browser.

Creating the Web Forms Page

The first step is to create a Web application and a Web Forms page.

To create the project and form

  1. On the File menu, point to New, then click Project.
  2. In the New Project dialog box, do the following:
    1. In the Project Types pane, choose either Visual Basic Projects or Visual C# Projects.
    2. In the Templates pane, choose ASP.NET Web Application.
    3. In the Location box, enter the complete URL for your application, including http://, and the name of the server. The last part of the URL is the name of your project; for this walkthrough, name your project Conversion. The Web server must have IIS version 5 or later and the .NET Framework installed on it. If you have IIS on your computer, you can specify http://localhost for the server. (If you normally use a proxy server to access the Internet, you might need to configure Internet Explorer to bypass the proxy server in order to use localhost.)
      Tip   If you already have a solution open, choose Close Solution so that your new Web Forms project will be part of its own solution.

    When you click OK, a new Web Forms project is created at the root of the Web server you specified. In addition, a new Web Forms page called WebForm1.aspx is displayed in the Web Forms Designer in Design view.

You can now add a few controls and write some code to display a personalized welcome message.

To add controls and program them

  1. From the Web Forms tab of the Toolbox, drag a TextBox control onto the designer.
  2. Drag a Label control to the left of the text box. In the Properties window, change the Label control's Text property to Enter Name:.
  3. Drag a Button control underneath the text box, and change the Text property to Enter.
  4. Drag a second Label control underneath the button, and delete the default text so that the Text property is empty.
  5. Double-click the Button control to open the Code view with a Button_Click event handler added.
  6. Add the following code to the Button1_Click procedure:
    ' Visual Basic
    Label2.Text = "Hi " & TextBox1.Text & ", welcome to ASP.NET!"
    // C#
    Label2.Text = "Hi " + TextBox1.Text + ", welcome to ASP.NET!";

    Do not close this file, because you will return to it later in the walkthrough.

    Security Note   User input in a Web Forms page can include potentially malicious client script. By default, the Web Forms page validates that user input does not include script or HTML elements. For more information, see Scripting Exploits and Protecting Against Script Exploits in a Web Application.
  7. Press CTRL+F5 to run the Web Forms page and test it. When you are finished, close the browser that opened when you tested the page.

Now you have a basic Web Forms page that you can convert to a Web user control.

Converting the Page to a User Control

Since the <html>, <body>, and <form> elements are not included in user controls, you must remove these elements and include them in the parent Web Forms page instead. You must also change the ASP.NET directive type in the Web Forms page from @ Page to @ Control. These ASP.NET directives specify settings used by the page and user control compilers. For more information, see Directive Syntax.

To convert the Web Forms page to a user control

  1. Return to WebForm1.aspx in the designer, and switch to HTML view by clicking the HTML tab at the bottom of the designer window.
  2. Delete the <html> tags, <!doctype> tag, <head> tags and inner content, <body>, and <form> tags from the .aspx file. If you are using Visual Basic, the HTML looks like this:
    <%@ Page Language="vb" AutoEventWireup="false"
          Codebehind="WebForm1.aspx.vb" Inherits="Conversion.WebForm1">
    <asp:TextBox id="TextBox1" runat="server"></asp:TextBox>
    <asp:Label id="Label1" runat="server">Enter Name:</asp:Label>
    <asp:Button id="Button1" runat="server" Text="Enter"></asp:Button>
    <asp:Label id="Label2" runat="server"></asp:Label>

    If you are using C#, the HTML will look identical except for the first line, which will look like this:

    <%@ Page Language="cs" AutoEventWireup="false"
          Codebehind="WebForm1.aspx.cs" Inherits="Conversion.WebForm1">
    Note   The Code Editor adds underlines that normally indicate problems with the code. These marks will disappear after the conversion is completed.
  3. Change the ASP.NET directive type from @ Page to @ Control. In a Visual Basic project, it will look like this:
    <%@ Control Language="vb" AutoEventWireup="false"
          Codebehind="WebForm1.aspx.vb" Inherits="Conversion.WebForm1">

    In a C# project, it will look like this:

    <%@ Control Language="cs" AutoEventWireup="false"
          Codebehind="WebForm1.aspx.cs" Inherits="Conversion.WebForm1">
  4. Change the Codebehind attribute reference of the directive to reflect the fact that the .aspx extension will be changed to .ascx, which is the extension for user controls. You will also change the name of the control to welcome.ascx later in this walkthrough, so set the Codebehind attribute to welcome.ascx.vb or welcome.ascx.cs as appropriate.
  5. Similarly, change the Inherits attribute of the directive to refer to Conversion.welcome.
  6. Return to the WebForm1.aspx.vb or WebForm1.aspx.cs file.
  7. Change the base class from System.Web.UI.Page to System.Web.UI.UserControl, and change the Public Class declaration from WebForm1 to welcome.
    ' Visual Basic
    Public Class welcome
       Inherits System.Web.UI.UserControl
    // C#
    public class welcome : System.Web.UI.UserControl
  8. Save and close the code-behind file and the .aspx file.
  9. Right-click WebForm1.aspx in Solution Explorer and click Rename on the shortcut menu.
  10. Change the name of the file to welcome.ascx to reflect its new function. It is important to note that you must change the file name extension from .aspx to .ascx. When the confirmation dialog appears, click OK.

The file is now a Web user control, and it is ready to be consumed by Web Forms pages throughout your project.

Testing the User Control

You can test your user control by creating a new Web Forms page and adding the control to it.

To    test the user control

  1. On the Project menu, click Add Web Form. The Add New Item dialog appears with Web Form selected.
  2. Change the Name to WelcomeTest.aspx and click Open. The new Web Forms page opens in the designer.
  3. Drag welcome.ascx from Solution Explorer onto the design surface.
  4. Right-click WelcomeTest.aspx in Solution Explorer and click Set As Start Page on the shortcut menu.
  5. Press F5 to run the Web Forms page and test it.

See Also

Introduction to Web User Controls | Recommendations for Web User Controls vs. Web Custom Controls | Developing User Controls in a Code-Behind File | Overview of Web Application Security Threats