How to: Convert Web Forms Pages into ASP.NET User Controls

  • Article

If you have developed an ASP.NET Web page and would like to access its functionality throughout your application, you can make some minor alterations to the page to change it to a user control.

To convert a single-file ASP.NET Web page into a user control

  1. Rename the control so the file name extension is .ascx.

  2. Remove the html, body, and form elements from the page.

  3. Change the @ Page directive to an @ Control directive.

  4. Remove all attributes of the @ Control directive except Language, AutoEventWireup (if present), CodeFile, and Inherits.

  5. Include a className attribute in the @ Control directive. This allows the user control to be strongly typed when it is added to a page.

To convert a code-behind ASP.NET Web page into a user control

  1. Rename the .aspx file so the file name extension is .ascx.

  2. Rename the code-behind file to have the file name extension .ascx.vb or .ascx.cs, depending on what programming language the code-behind file is in.

  3. Open the code-behind file and change the class from which it inherits from Page to UserControl.

  4. In the .aspx file, do the following:

    1. Remove the html, body, and form elements from the page.

    2. Change the @ Page directive to an @ Control directive.

    3. Remove all attributes of the @ Control directive except Language, AutoEventWireup (if present), CodeFile, and Inherits.

    4. In the @ Control directive, change the CodeFile attribute to point to the renamed code-behind file.

  5. Include a className attribute in the @ Control directive. This allows the user control to be strongly typed when it is added to a page.

Example

The following example shows a single-file ASP.NET Web page in its original form and the resulting user control after converting the page.

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

 
<%@ Page Language="VB" %>
<html>
<script runat=server>
Sub EnterBtn_Click(sender as Object, e as EventArgs)
    Label1.Text = "Hi " & Name.Text & " welcome to ASP.NET!"
End Sub
</script>
<body>
<h3> <u>Web Forms Page</u> </h3>
<form>
    Enter Name: <asp:textbox id="Name" runat=server/>
    <asp:button Text="Enter" OnClick="EnterBtn_Click"
        runat=server/>
<br>
<br>
<asp:label id="Label1" runat=server/>
</form>
</body>
</html>

<%@ Page Language="C#" %>
<html>
<script runat=server>
void EnterBtn_Click(Object sender, EventArgs e)
{
    Label1.Text = "Hi " + Name.Text + " welcome to ASP.NET!";
}
</script>
<body>
<h3> <u>Web Forms Page</u> </h3>
<form>
Enter Name: <asp:textbox id="Name" runat=server/>
<asp:button Text="Enter" OnClick="EnterBtn_Click"
    runat=server/>
<br>
<br>
<asp:label id="Label1" runat=server/>
</form>
</body>
</html>

<%@ Control Language="VB" ClassName="SampleUserControl" %>
<h3> <u>User Control</u> </h3>
<script runat=server>
Sub EnterBtn_Click(sender as Object, e as EventArgs)
    Label1.Text = "Hi " & Name.Text & " welcome to ASP.NET!"
End Sub
</script>
Enter Name: <asp:textbox id="Name" runat=server/>
<asp:button Text="Enter" OnClick="EnterBtn_Click"
    runat=server/>
<br>
<br>
<asp:label id="Label1" runat=server/>

<%@ Control Language="C#" ClassName="SampleUserControl" %>
<h3> <u>User Control</u> </h3>
<script runat=server>
void EnterBtn_Click(Object Sender, EventArgs e)
{
    Label1.Text = "Hi " + Name.Text + " welcome to ASP.NET!";
}
</script>
Enter Name: <asp:textbox id="Name" runat=server/>
<asp:button Text="Enter" OnClick="EnterBtn_Click"
runat=server/>
<br>
<br>
<asp:label id="Label1" runat=server/>

See Also

Tasks

How to: Create ASP.NET User Controls

Concepts

ASP.NET User Controls Overview