ASP.NET Web Forms Page Code Model
An ASP.NET Web Forms page consists of two parts:
Visual elements, which include markup, server controls, and static text.
Programming logic for the page, which includes event handlers and other code.
Note
This topic applies only to ASP.NET Web Forms pages. It does not apply to pages that you create using ASP.NET MVC (Model View Controller) or ASP.NET Web Pages.
ASP.NET provides two models for managing the visual elements and code — the single-file page model and the code-behind page model. The two models function the same, and you can use the same controls and code for both models.
This topic explains how each model functions and provides suggestions for when to choose one model or the other.
The Single-File Page Model
In the single-file page model, a Web Forms page's markup and its programming code are in the same physical .aspx file. The programming code is in a script block that contains the attribute runat="server" to mark it as code that ASP.NET should execute.
The following code example shows a single-file page containing a Web Forms Button server control and a Label server control. The highlighted portion shows the Click event handler for the Button control inside a script block.
<%@ Page Language="VB" %>
<script runat="server">
Protected Sub Button1_Click(ByVal sender As Object, _
ByVal e As System.EventArgs)
Label1.Text = "Clicked at " & DateTime.Now.ToString()
End Sub
</script>
<html>
<head id="Head1" runat="server">
<title>Single-File Page Model</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label ID="Label1"
runat="server" Text="Label">
</asp:Label>
<asp:Button ID="Button1"
runat="server" OnClick="Button1_Click" Text="Button">
</asp:Button>
</div>
</form>
</body>
</html>
<%@ Page Language="C#" %>
<script runat="server">
void Button1_Click(Object sender, EventArgs e)
{
Label1.Text = "Clicked at " + DateTime.Now.ToString();
}
</script>
<html>
<head>
<title>Single-File Page Model</title>
</head>
<body>
<form runat="server">
<div>
<asp:Label id="Label1"
runat="server" Text="Label">
</asp:Label>
<br />
<asp:Button id="Button1"
runat="server"
onclick="Button1_Click"
Text="Button">
</asp:Button>
</div>
</form>
</body>
</html>
The scriptblock can contain as much code as the page requires. The code can consist of event handlers for controls on the page (as in the example), methods, properties, and any other code that you would normally use in a class file. At run time, a single-file page is treated as a class that derives from the Page class. The page does not contain an explicit class declaration. Instead, the compiler generates a new class that contains the controls as members. (Not all controls are exposed as page members; some are children of other controls.) The code in the page becomes part of the class; for example, event handlers that you create become members of the derived Page class.
Since all code in the page becomes members of the Page class, you cannot have a using statement in your code. Instead, add a @ Import directive that specifies the namespace to import. You might also need to add a reference to the DLL that contains the namespace.
For more information, see ASP.NET Page Class Overview.
The Code-Behind Page Model
The code-behind page model for Web Forms allows you to keep the markup in one file—the .aspx file—and the programming code in another file. The name of the code file varies according to what programming language you are using.
For example, if you are working with a page named SamplePage, the markup is in the file SamplePage.aspx and the code is in a file named SamplePage.aspx.vb (for Visual Basic) and SamplePage.aspx.cs (for C#).
Note
The code-behind model used in the .NET Framework version 1.1 is different than the one used in subsequent versions.
In the code-behind model, the example used in the preceding section for the single-file page would be in two parts. The markup would be in one file (in this example, SamplePage.aspx) and would be similar to the single-file page, as shown in the following code example.
<%@ Page Language="VB" CodeFile="SamplePage.aspx.vb"
Inherits="SamplePage" AutoEventWire="false" %>
<html>
<head runat="server" >
<title>Code-Behind Page Model</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label id="Label1"
runat="server" Text="Label" >
</asp:Label>
<br />
<asp:Button id="Button1"
runat="server"
onclick="Button1_Click"
Text="Button" >
</asp:Button>
</div>
</form>
</body>
</html>
<%@ Page Language="C#" CodeFile="SamplePage.aspx.cs"
Inherits="SamplePage" AutoEventWireup="true" %>
<html>
<head runat="server" >
<title>Code-Behind Page Model</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:Label id="Label1"
runat="server" Text="Label" >
</asp:Label>
<br />
<asp:Button id="Button1"
runat="server"
onclick="Button1_Click"
Text="Button" >
</asp:Button>
</div>
</form>
</body>
</html>
There are two differences in the .aspx page between the single-file and the code-behind models. In the code-behind model, there is no script block with the runat="server" attribute. (The page can contain script blocks without the runat="server" attribute if you want to write client script in the page.) The second difference is that the @ Page directive in the code-behind model contains attributes that reference an external file (SamplePage.aspx.vb or SamplePage.aspx.cs) and a class. These attributes link the .aspx page to its code.
In the example, the attribute that identifies the code-behind file is CodeFile. In a Web application project, the attribute is named CodBehind. For more information about the differences between Web site projects and Web application projects, see Web Application Projects versus Web Site Projects in Visual Studio.
The following code example shows a code-behind file that contains the same Click event handler as the example for the single-file page.
Partial Class SamplePage
Inherits System.Web.UI.Page
Protected Sub Button1_Click(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles Button1.Click
Label1.Text = "Clicked at " & DateTime.Now.ToString()
End Sub
End Class
using System;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
public partial class SamplePage : System.Web.UI.Page
{
protected void Button1_Click(object sender, EventArgs e)
{
Label1.Text = "Clicked at " + DateTime.Now.ToString();
}
}
The code-behind file contains the complete class declarations in the default namespace. However, the class is declared with the partial keyword, which indicates that the class is not contained entirely in one file. Instead, the compiler reads the .aspx page and the file it references in the @ Page directive, and assembles them into a single class.
The partial class file inherits from the page Page class. For more information, see ASP.NET Page Class Overview.
Choosing a Web Forms Page Model
The single-file and code-behind page models are functionally the same. At run time, the models execute the same way, and there is no performance difference between them. Choosing a page model therefore depends on other factors, such as how you want to organize the code in your application, whether it is important to separate page design from coding, and so on.
Note
Examples you read in the documentation are often presented as single-file pages. This is primarily as a convenience for the reader, because it avoids having to illustrate two files for each example. The fact that you find single-file examples in the documentation should not be interpreted to mean that single-file pages are favored over code-behind pages or that there is some other inherent benefit to single-file pages.
Advantages of Single-File Pages
As a rule, the single-file model is suitable for pages in which the code consists primarily of event handlers for the controls on the page.
Advantages of the single-file page model include the following:
In pages where there is not very much code, the convenience of keeping the code and markup in the same file can outweigh other advantages of the code-behind model. For example, it can be easier to study a single-file page because you can see the code and the markup in one place.
Pages written using the single-file model are slightly easier to deploy or to send to another programmer because there is only one file.
Because there is no dependency between files, a single-file page is easier to rename if you are using tools other than Visual Studio. (If you use Visual Studio to rename a file, Visual Studio automatically renames both files.)
Managing files in a source code control system is slightly easier, because the page is self-contained in a single file.
Advantages of Code-Behind Pages
Code-behind pages offer advantages that make them suitable for Web applications with significant code or in which multiple developers are creating a Web site.
Advantages of the code-behind model include the following:
Code-behind pages offer a clean separation of the markup (user interface) and code. It is practical to have a designer working on the markup while a programmer writes code.
Code is not exposed to page designers or others who are working only with the page markup.
Code can be reused for multiple pages.
See Also
Concepts
Introduction to Programming ASP.NET Web Forms Pages