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

.NET Framework 4

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

Rename the control so the file name extension is .ascx.
Remove the html, body, and form elements from the page.
Change the @ Page directive to an @ Control directive.
Remove all attributes of the @ Control directive except Language, AutoEventWireup (if present), CodeFile, and Inherits.
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

Rename the .aspx file so the file name extension is .ascx.
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.
Open the code-behind file and change the class from which it inherits from Page to UserControl.
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.
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 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.

C++

JScript

Copy

<%@ 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>

C++

JScript

Copy

<%@ 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/>

Tasks

How to: Create ASP.NET User Controls

Concepts

ASP.NET User Controls Overview

Community ContentAdd

FAQ