How to work with code-behind class files in an ASP.NET application by using Visual Basic .NET

This article demonstrates how to develop .aspx pages that use code-behind class files in Microsoft ASP.NET applications. The code samples in this article include the requirements for both code-behind class files that are precompiled and code-behind class files that are compiled on demand. For more information about code-behind class files and their deployment, see the "References" section.

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:

• Microsoft Windows 2000, Microsoft Windows XP, or Microsoft Windows Server 2003
• Microsoft .NET Framework 1.0 or Microsoft .NET Framework 1.1
• Microsoft Internet Information Services (IIS) version 5.0 or later

Create an ASP.NET Web application by using Microsoft Visual Basic .NET

This section demonstrates how to create a new ASP.NET Web application that is named CodeBehindSamples.

1. Start Microsoft Visual Studio .NET.
2. On the File menu, point to New, and then click Project.
3. Under Project Types, click Visual Basic Projects. Under Templates, click ASP.NET Web Application.
4. In the Location box, type the server name, and then type CodeBehindSamples for the project name. If you are using the local server, leave the location as http://localhost. For this example, your location is http://localhost/CodeBehindSamples.

Use code-behind class files

If you use code-behind class files with .aspx pages, you can separate the presentation code from the core application logic (or code-behind). The code-behind class file is compiled so that it can be created and used as an object. This allows access to its properties, its methods, its and event handlers. For this to work, the .aspx page must specify to inherit from the code-behind base class. To do this, use the Inherits attribute for the @ Page directive. The .aspx page inherits from the code-behind class, and the code-behind class inherits from the Page class.

By default, if you are using Visual Studio .NET, a Codebehind attribute is added to the @ Page directive. The .NET Framework does not actually use this attribute. Instead, Visual Studio .NET uses this attribute to maintain a reference to the associated code-behind file for the .aspx page.

To demonstrate how Visual Studio .NET uses the Codebehind attribute, remove the Codebehind attribute. Note that you can no longer right-click the .aspx page and then click View Code. This behavior occurs because Visual Studio .NET no longer contains a reference for the class file that it can use for the page. Remember that this is not how the .NET Framework uses code-behind class files, but how Visual Studio .NET manages these project files.

Use the Inherits attribute with precompiled classes

If you precompile your code-behind classes into an assembly, you can use the Inherits attribute to specify the class from which to inherit. In this scenario, you do not have to include the actual code-behind class file when you deploy the application. Instead, you must deploy the assembly and the .aspx page. You must put the assembly in the Bin folder for the application when you deploy the application.

This section demonstrates how to create a new Web Form that uses the precompiled approach and inherits from the code-behind class.

1. To add a new Web Form named InheritSample.aspx to your Visual Studio .NET project, follow these steps:
   1. In Solution Explorer, right-click the CodeBehindSamples project node, click Add, and then click Add Web Form.
   2. In the Name box, type InheritSample.aspx, and then click Open.
2. Switch to Design view, and then add a Web Form Label control to the .aspx page from Toolbox.
3. Right-click the .aspx page, and then click View Code. The code-behind file opens in the editor.
4. In the code-behind file, add the following code to the Page_Load event:

   Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
           Label1.Text = "(Precompiled): Page_Load fired!"
       End Sub
   						

   Note This code only demonstrates that the code-behind class is involved in the sample at run time in the later steps.
5. Switch from the code-behind class file to the .aspx page in the editor, and then switch to HTML view.
6. At the top of the page, review the code for the @ Page directive. The code should be similar to the following default code:

   <%@ Page Language="vb" AutoEventWireup="false" Codebehind="InheritSample.aspx.vb" Inherits="CodeBehindSamples.InheritSample"%>
   						

   In this example, notice that the .aspx page inherits from the code-behind class that is named InheritSample in the CodeBehindSamples namespace. By default, a Web application that is created in Visual Studio .NET uses a ProjectName.ClassName structure for the Inherits attribute value.
7. On the File menu, click Save All to save the Web Form and other associated project files.
8. In the Visual Studio .NET IDE, on the Build menu, click Build to build the project.
9. On the Project menu, click Show All Files.
10. In Solution Explorer, click to expand the Bin folder. The assembly that is generated when you compile the project from the previous section (which is CodeBehindSamples.dll in this example) appears in the Bin folder.
11. In Visual Studio .NET, right-click the InheritSample page in Solution Explorer, and then click View in Browser to run the code. The label is populated with the following value:

    (Precompiled): Page_Load fired!
    						

Use the Src attribute and compile on demand

If your code-behind class files will be compiled on demand instead of precompiled, you must use the Src attribute to specify the relative path of the code-behind class file. Make sure that you include the actual class file when you use this method to deploy the application.

Note If you develop your applications in Visual Studio .NET, see the "References" section in this article for more information about potential issues with using the Src attribute. Visual Studio .NET is designed to take advantage of precompiling your application code into an assembly instead of using the compile on demand approach that is described in this section.

1. To add a new Web Form that is named SrcSample.aspx to your project in Visual Studio .NET, follow these steps:
   1. In Solution Explorer, right-click the project node, click Add, and then click Add Web Form.
   2. In the Name box, type SrcSample.aspx, and then click Open.
2. Switch to Design view, and then add a Web Form Label control to the .aspx page from Toolbox.
3. Right-click the .aspx page, and then click View Code. The code-behind file opens in the editor.
4. In the code-behind file, add the following code to the Page_Load event:

   Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
           Label1.Text = "(Src): Page_Load fired!"
       End Sub
   					

5. Switch from the code-behind class file to the .aspx page in the editor, and then switch to HTML view.
6. At the top of the page, review the code for the @ Page directive. The code should be similar to the following default code:

   <%@ Page language="vb" Codebehind="SrcSample.aspx.vb" 
   AutoEventWireup="false" Inherits="CodeBehindSamples.SrcSample"%>
   					

7. To simplify this example, delete the Global.asax file from your project. This is only done in this example to prevent additional errors that are related to the code-behind page of the Global.asax file.
8. On the File menu, click Save All to save the Web Form and other associated project files.
   
   Note Because you want the code-behind class file for this sample to compile on demand, do not build the solution now.
9. To run the page, start Microsoft Internet Explorer and then manually enter the URL to the page. Do not select the View in Browser or the Browse with options from the Visual Studio .NET IDE. Otherwise, if you are using Visual Studio .NET 2003, the code-behind page will be precompiled into an assembly that is located in the Bin directory by default. After you view the page, you should receive the following error message:
   Could not load type 'CodeBehindSamples.SrcSample'.
   This error occurs because the code-behind class file is not yet compiled, and you have not yet included the Src attribute to reference the code-behind class file.
10. Add the Src attribute to the @ Page directive as follows:

    <%@ Page language="vb" Codebehind="SrcSample.aspx.vb" 
    AutoEventWireup="false" Inherits="SrcSample" 
    Src="SrcSample.aspx.vb"%>
    						

    Notice that the Src attribute is listed with the relative path of the code-behind class file (SrcSample.aspx.vb), and that the Inherits attribute value is set to reference the SrcSample class.
11. On the File menu, click Save All to save the Web Form and other associated project files. Remember, do not build the solution because you want the code-behind class file for this sample to be compiled on demand.
12. To run the page, start Internet Explorer and then manually enter the URL to the page. Do not select the View in Browser or the Browse with options from the Visual Studio .NET IDE. Otherwise, if you are using Visual Studio .NET 2003, the code-behind page will be precompiled into an assembly that is located in the Bin directory by default. At this point, the page should be loaded in the browser, and the label is populated with the following value:

    (Src): Page_Load fired!
    							

    The code-behind class file has now been compiled on demand and functions correctly.

Troubleshooting

• If you do not precompile the code-behind class file and do not add the Src attribute to the @ Page directive, or if the virtual path for the attribute is not correct, you receive the following error message:
  Could not load type 'CodeBehindSamples.SrcSample'.
  Note This error message may also be the result of incorrect casing of the Inherits attribute value. Make sure that the value of the Inherits attribute is spelled and capitalized the same way as the code-behind class name.
• If you receive the following error message, please review your @ Page directive attribute values to make sure that they are set correctly:
  The base type 'CodeBehindSamples.SrcSample' does not exist in the source file 'SrcSample.aspx.vb'.
  You can refer to step 10 of "The Src Attribute and Compile On Demand" section of this article for an example of how this should be specified.
• When you deploy .aspx pages, if their associated code-behind class files are precompiled, you are only required to deploy the assembly to the Bin folder of the application. You do not have to deploy the actual code-behind class files with the application.
• When you deploy .aspx pages, if their associated code-behind class files are not precompiled, you must deploy the code-behind class files with the application. In addition, you must add the Src attribute to the @ Page directive, because the class file must be available when it is compiled on demand.
• If you want to or if you must contain your Web Form pages in a single file, you can develop your .aspx pages to contain your code rather than the code-behind class file. For more information about how to develop single-file Web Forms in Visual Studio .NET, visit the following Microsoft Developer Network (MSDN) Web site:
  http://msdn.microsoft.com/en-us/library/aa290385(VS.71).aspx