ASP.NET Web Page Syntax Overview

Article
10/22/2014

ASP.NET Web pages are created in a manner similar to static HTML Web pages (pages that do not include server-based processing), but they include extra elements that ASP.NET recognizes and processes when the page runs. The characteristics that distinguish ASP.NET Web pages from static HTML (or other) pages are as follows:

A file name extension of .aspx instead of .htm, .html, or other file name extensions. The .aspx file name extension causes the page to be processed by ASP.NET.

Note

The mapping of file name extensions to ASP.NET is done in Internet Information Services (IIS). By default, .aspx pages are run by ASP.NET and .htm and .html pages are not.
An optional @ Page directive or other directive, as appropriate to the type of page that you are creating.
A form element that is configured correctly for ASP.NET. The form element is required only if the page contains controls whose values you want to use during page processing.
Web server controls.
Server code, if you add your own code to the page.

Note

If you want your pages to conform to XHTML standards, you must include additional elements, such as a DOCTYPE element. For details, see ASP.NET and XHTML.

The sections below provide more details on each of these elements.

You can rename any HTML page with the .aspx file name extension and it will run as an ASP.NET Web page. However, if a page does not involve server processing, you do not need to add the .aspx file name extension to it because doing so adds overhead to page processing.

Example ASP.NET Web Page

The following code example shows a page that includes the basic elements that constitute an ASP.NET Web page. The page contains static text as you might have in an HTML page, along with elements that are specific to ASP.NET. The elements that are specific to ASP.NET are highlighted.

Note

For clarity, this example page is not configured for XHTML compliance. For details, see ASP.NET and XHTML.

Security Note:
This example page contains 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 Button1_Click(ByVal sender As Object, _
        ByVal e As System.EventArgs)
        Label1.Text = "Welcome, " & TextBox1.Text
    End Sub
</script>
<head runat="server">
  <title>Basic ASP.NET Web Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <h1>Welcome to ASP.NET</h1>
    <p>Type your name and click the button.</p>
    <p>
      <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
      <asp:Button ID="Button1" runat="server" 
        Text="Click" OnClick="Button1_Click" />
    </p>
    <p>
      <asp:Label ID="Label1" runat="server"></asp:Label>
    </p>
  </form>
</body>
</html>

<%@ Page Language="C#" %>
<html>
<script runat="server">
void Button1_Click(object sender, System.EventArgs e) 
{
    Label1.Text = ("Welcome, " + TextBox1.Text);
}
</script>
<head runat="server">
  <title>Basic ASP.NET Web Page</title>
</head>
<body>
  <form id="form1" runat="server">
    <h1>Welcome to ASP.NET</h1>
    <p>Type your name and click the button.</p>
    <p>
      <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
      <asp:Button ID="Button1" runat="server" 
        Text="Click" OnClick="Button1_Click" />
    </p>
    <p>
      <asp:Label ID="Label1" runat="server"></asp:Label>
    </p>
  </form>
</body>
</html>

@ Directives

ASP.NET pages usually contain directives that allow you to specify page properties and configuration information for the page. The directives are used by ASP.NET as instructions for how to process the page, but they are not rendered as part of the markup that is sent to the browser.

The most commonly used directive is the @ Page directive, which allows you to specify many configuration options for the page, including the following:

The server programming language for code in the page.
Whether the page is a page with server code directly in the page, which is called a single-file page, or whether it is a page with code in a separate class file, which is called a code-behind page. In the previous example, the page is a single-file page; the code is directly in the page, and the @ Page directive does not include information about linked class files. For more information, see the "Server Code" section later in this topic, and see ASP.NET Web Page Code Model.
Debugging and tracing options.
Whether the page has an associated master page and should therefore be treated as a content page.

If you do not include an @ Page directive in the page, or if the directive does not include a specific setting, settings are inherited the from the configuration file for the Web application (the Web.config file) or from the site configuration file (the Machine.config file).

In addition to including an @ Page directive, you can include other directives that support additional page-specific options. Other common directives include the following:

@ Import This directive allows you to specify namespaces that you want to reference in your code.
@ OutputCache This directive allows you to specify that the page should be cached, along with parameters for when and how long to cache the page.
@ Implements This directive allows you to specify that the page implement a .NET interface.
@ Register This directive allows you to register additional controls for use on the page. The @ Register directive declares the control's tag prefix and the location of the control's assembly. You must use this directive if you want to add user controls or custom ASP.NET controls to a page.

Certain types of ASP.NET files use a directive other than @ Page. For example, ASP.NET master pages use an @ Master directive, and ASP.NET user controls use an @ Control directive. Each directive allows you to specify different options that are appropriate for the file.

For details, see ASP.NET Master Pages Overview and ASP.NET User Controls.

Form Elements

If your page includes controls that allow users to interact with the page and submit it, the page must include a form element. You use the standard HTML form element, but certain rules apply. The rules for using the form element are as follows:

The page can contain only one form element.
The form element must contain the runat attribute with the value set to server. This attribute allows you to refer to the form and the controls on the page programmatically in server code.
Server controls that can perform a postback must be inside the form element.
The opening tag must not contain an action attribute. ASP.NET sets these attributes dynamically when the page is processed, overriding any settings that you might make.

Web Server Controls

In most ASP.NET pages, you will add controls that allow the user to interact with the page, including buttons, text boxes, lists, and so on. These Web server controls are similar to HTML buttons and input elements. However, they are processed on the server, allowing you to use server code to set their properties. These controls also raise events that you can handle in server code.

Server controls use a special syntax that ASP.NET recognizes when the page runs. The following code example shows some typical Web server controls.

Security Note:
A TextBox 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.

<asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
<asp:Button ID="Button1" runat="server" 
    Text="Click" OnClick="Button1_Click" />

<asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
<asp:Button ID="Button1" runat="server" 
    Text="Click" OnClick="Button1_Click" />

The tag name for ASP.NET server controls starts with a prefix — in this case, asp:. The prefix might be different if the control is not part of the .NET Framework. ASP.NET server controls also include the runat="server" attribute and, optionally, an ID that you can use to reference the control in server code.

When the page runs, it identifies the server controls and runs the code that is associated with those controls. Many controls render some HTML or other markup into the page. For example, the asp:textbox control renders an input element with the type="text" attribute into a page. However, there is not necessarily a one-to-one mapping between a Web server control and an HTML element. For example, the asp:calendar control renders an HTML table. Some controls do not render anything to the browser; instead, they are processed on the server only, and they provide information to other controls.

HTML Elements as Server Controls

Instead of, or in addition to, using ASP.NET server controls, you can use ordinary HTML elements as server controls. You can add the runat="server" attribute and an ID attribute to any HTML element in the page. When the page runs, ASP.NET identifies the element as a server control and makes it available to server code. For example, you can add the required elements to an HTML body element, as shown in the following code example.

<body runat="server" id="body">

You can then reference the body element in server code — for example, to set the body background color at run time in response to user input or to information from a database.

For more information, see ASP.NET Web Server Controls Overview.

Server Code

Most ASP.NET pages include code that runs on the server when the page is processed. ASP.NET supports many languages including C#, Visual Basic, J#, Jscript, and others.

ASP.NET supports two models for writing server code for a Web page. In the single-file model, the code for the page is in a script element where the opening tag includes the runat="server" attribute. The example earlier in this topic shows the single-file model.

Alternatively, you can create the code for the page in a separate class file, which is referred to as the code-behind model. In this case, the ASP.NET Web page generally contains no server code. Instead, the @ Page directive includes information that links the .aspx page with its associated code-behind file. The following code example shows a typical @ Page directive for a page with a code-behind file.

<%@ Page Language="VB" CodeFile="Default.aspx.vb" Inherits="Default" %>

<%@ Page Language="C#" CodeFile="Default.aspx.cs" Inherits="Default" %>

The CodeFile attribute specifies the name of the separate class file, and the Inherits attribute specifies the name of the class within the code-behind file that corresponds to the page.

For more information, see ASP.NET Web Page Code Model.

Note

ASP.NET Web pages can also include client script that runs in the browser in response to client-side events. An ASP.NET page can include both client script and server code. For details, see Client Script in ASP.NET Web Pages.

ASP.NET Web Page Syntax Overview

Example ASP.NET Web Page

@ Directives

Form Elements

Web Server Controls

HTML Elements as Server Controls

Server Code

See Also

Concepts

Other Resources

Additional resources