How to: Migrate an ASP.NET 1.1 Web Page Using the CodeBehind Attribute to ASP.NET 2.0

  • Article

This topic demonstrates how to create a Web page and user control that use the CodeBehind attribute of the @ Page directive, compile them, and then convert them to use the CodeFile attribute with a partial class in the code-behind files in the .NET Framework version 2.0.

The new Web page code-behind model in ASP.NET version 2.0 is based on partial classes. The markup for the page is stored in one file – the .aspx file – and the code is defined in a partial class – the code-behind file. Converting your existing Web pages to the new code-behind model allows even greater separation of markup and code because you do not have to include instance variables or explicit event binding in the partial class. For more information, see What's New in the ASP.NET Web Page Model.

Web pages using the CodeBehind and Inherits attributes of the @ Page directive will continue to work in the .NET Framework 2.0. However, you must compile code-behind files and put the resulting assembly in the Bin folder.

If you choose to migrate to the ASP.NET 2.0 code-behind model, you must make coordinated changes to your .aspx file and code-behind file. In your .aspx file, you will replace the CodeBehind attribute with the CodeFile attribute. In your code-behind files, you will use a partial class. The advantage of using the new code-behind model is that you do not have to explicitly compile the code-behind files because the ASP.NET compiler will do this automatically.

Additionally, when using the new code-behind model, references to other code-behind files must be added using @ Register directives.

To access the Web page created in the procedures below, you will need to create a virtual directory in Microsoft Internet Information Services (IIS). For details on to create a virtual directory for IIS, see How to: Create and Configure Virtual Directories in IIS.

To compile a Web page and user control using the CodeBehind attribute

  1. Create a Web page using the CodeBehind attribute of the @ Page directive, as shown in the following code example.

    <%@ Page Language="VB" AutoEventWireup="true" 
    CodeBehind="CodeBehindExample.aspx.vb" 
    Inherits="CodeBehindExample" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Code-Behind Using the CodeBehind Attribute</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:Label id="Label1" runat="server"></asp:Label>    
    </div>
    </form>
</body>
</html>

    <%@ Page Language="C#" AutoEventWireup="true" 
    CodeBehind="CodeBehindExample.aspx.cs" 
    Inherits="CodeBehindExample" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Code-Behind Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:Label id="Label1" runat="server"></asp:Label>    
    </div>
    </form>
</body>
</html>

    Public Class CodeBehindExample
    Inherits System.Web.UI.Page

    Protected Label1 As System.Web.UI.WebControls.Label

    Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Load

        Dim uc As CodeBehindExampleUserControl = _
        CType(LoadControl("~/CodeBehindExampleUserControl.ascx"), _
        CodeBehindExampleUserControl)
        Label1.Text = CType(uc.FindControl("Label2"), _
        System.Web.UI.WebControls.Label).Text

    End Sub

End Class

    public class CodeBehindExample : 
    System.Web.UI.Page
{
    protected System.Web.UI.WebControls.Label Label1;

    protected void Page_Load(object sender, 
        System.EventArgs e)
    {
        CodeBehindExampleUserControl uc =
          (CodeBehindExampleUserControl)LoadControl
          ("~/CodeBehindExampleUserControl.ascx");
        Label1.Text = ((System.Web.UI.WebControls.Label)
            uc.FindControl("Label2")).Text;

    }
}

    Note that for the Label control declared on the .aspx page, there is a corresponding declaration in the code-behind file. Also, the code-behind class is a normal class definition and not a partial class.

  2. Create a user control using the CodeBehind attribute of the @ Control directive, as shown in the following code example.

    <%@ Control Language="VB" AutoEventWireup="false" 
    CodeBehind="CodeBehindExampleUserControl.ascx.vb" 
    Inherits="CodeBehindExampleUserControl" %>
<asp:Label id="Label2" runat="server">
Label text in user control.
</asp:Label>

    <%@ Control Language="C#" AutoEventWireup="false" 
    CodeBehind="CodeBehindExampleUserControl.ascx.cs" 
    Inherits="CodeBehindExampleUserControl" %>
<asp:Label id="Label2" runat="server">
Label text in user control.
</asp:Label>

    Public Class CodeBehindExampleUserControl
    Inherits System.Web.UI.UserControl

    Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Load
        ' User control code.
    End Sub

End Class

    public class CodeBehindExampleUserControl : 
    System.Web.UI.UserControl
{
    protected void Page_Load(object sender, 
        System.EventArgs e)
    {
        // User control code.
    }
}

    Note that, similar to the code-behind file for the Web page, the code-behind file for the user control uses a class and not a partial class.

  3. Compile the Web page and user control, and place the code library into the Bin folder of your application. Using the CodeBehind attribute requires you to compile all code-behind classes into a single code library and place the resulting .dll file in the Bin folder. For the Web page and user control example, the compile statement that compiles both code-behind files is:

    vbc /target:library /nologo /out:bin\CodeBehindExample.dll /r:System.dll,System.Web.dll CodeBehindExample.aspx.vb CodeBehindExampleUserControl.ascx.vb

    csc /target:library /nologo /out:bin\CodeBehindExample.dll CodeBehindExample.aspx.cs CodeBehindExampleUserControl.ascx.cs

  4. Request the Web page CodeBehindExample.aspx in a browser to verify that it works in the .NET Framework 2.0.

To convert a Web page and user control using the CodeBehind attribute to the ASP.NET 2.0 code-behind model

  1. Make changes to the Web page's .aspx file to match the following code example.

    <%@ Reference Control="~/CodeBehindExampleUserControl.ascx" %>
<%@ Page Language="VB" AutoEventWireup="false" 
    CodeFile="CodeBehindExample.aspx.vb" 
    Inherits="CodeBehindExample" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Code-Behind Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:Label id="Label1" runat="server"></asp:Label>        
    </div>
    </form>
</body>
</html>

    <%@ Reference Control="~/CodeBehindExampleUserControl.ascx" %>
<%@ Page Language="C#" AutoEventWireup="true"  
    CodeFile="CodeBehindExample.aspx.cs" 
    Inherits="CodeBehindExample" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>Code-Behind Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <asp:Label id="Label1" runat="server"></asp:Label>
    </div>
    </form>
</body>
</html>

    A CodeFile attribute is now used instead of a CodeBehind attribute in the @ Page directive of the .aspx file. An @ Reference directive is used to reference the user control in the code-behind page.

  2. Make changes to your Web pages code-behind file to match the following code example.

    Partial Class CodeBehindExample
    Inherits System.Web.UI.Page


    Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Load

        Dim uc As CodeBehindExampleUserControl = _
        CType(LoadControl("~/CodeBehindExampleUserControl.ascx"), _
        CodeBehindExampleUserControl)
        Label1.Text = CType(uc.FindControl("Label2"), _
        System.Web.UI.WebControls.Label).Text

    End Sub
End Class

    public partial class CodeBehindExample : 
    System.Web.UI.Page 
{
    protected void Page_Load(object sender, 
        System.EventArgs e)
    {
        CodeBehindExampleUserControl uc =
            (CodeBehindExampleUserControl)LoadControl
            ("~/CodeBehindExampleUserControl.ascx");
        Label1.Text = ((System.Web.UI.WebControls.Label)
            uc.FindControl("Label2")).Text;

    }
}

    In the code-behind file, a partial class is used to define additional coding for the .aspx page. There is now no need to declare the Label control used on the .aspx page, as was the case with the previous code-behind page based on the CodeBehind attribute.

  3. Make changes to your user control's .aspx file to match the following code example.

    <%@ Control Language="VB" AutoEventWireup="false" 
    CodeFile="CodeBehindExampleUserControl.ascx.vb" 
    Inherits="CodeBehindExampleUserControl" %>
<asp:Label id="Label2" runat="server">
Label text in user control.
</asp:Label>

    <%@ Control Language="C#" AutoEventWireup="true" 
    CodeFile="CodeBehindExampleUserControl.ascx.cs" 
    Inherits="CodeBehindExampleUserControl" %>
<asp:Label id="Label2" runat="server">
Label text in user control.
</asp:Label>

    Similar to the Web page, the user control now uses a CodeFile attribute instead of the CodeBehind attribute.

  4. Make changes to your user control's code-behind file to match the following code example.

    Partial Class CodeBehindExampleUserControl
    Inherits System.Web.UI.UserControl

    Protected Sub Page_Load(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Load
        ' User control code.
    End Sub
End Class

    public partial class CodeBehindExampleUserControl : 
    System.Web.UI.UserControl
{
    protected void Page_Load(object sender, 
        System.EventArgs e)
    {
        // User control code.
    }
}

    Similar to the Web page's code-behind file, the user control's code-behind file now uses a partial class.

  5. Delete the CodeBehindExample.dll file from the Bin folder that was created in the previous procedure.

    ASP.NET 2.0 will compile your page on first request along with its code-behind files.

  6. Request the Web page CodeBehindExample.aspx and verify that it works as before.

See Also

Concepts

ASP.NET Side-by-Side Overview
What's New in ASP.NET

Other Resources

Migrating to ASP.NET