Walkthrough: Creating a Basic Web Forms Page with Code Separation in Visual Studio

When you create ASP.NET Web Forms pages and write code in them, you can select from two models for how to manage the visible elements (controls and text) and your programming code. In the single-file model, the visible elements and code are kept together in the same file. In the alternative model, called "code separation," the visible elements are in one file and the code is in another file, referred to as the "code-behind" file. This walkthrough introduces you to Web Forms pages that use code separation.


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.

The single-file model is introduced in Walkthrough: Creating a Basic Web Forms Page in Visual Studio. The walkthrough you are reading now shows you how to create a Web page with the same functionality as the page in the single-file walkthrough, but with a focus on using code separation.

The choice between using single-file pages and pages with code separation is primarily one of convenience and personal preference. Working with both models in Microsoft Visual Studio is similar; both models have approximately equal support in the editor. Both models have equivalent performance when the page runs. The page with code separation makes it more practical to let a Web designer work on the layout of a page while a programmer creates the code for the page, because the two pages can be edited separately.

Tasks illustrated in this walkthrough include:

  • Creating an ASP.NET Web Forms page with code separation.

  • Adding server controls.

  • Adding event handlers.

  • Running pages with the Visual Studio Development Server.


In order to complete this walkthrough, you will need:

  • Visual Studio or Visual Web Developer Express.


    If you are using Visual Studio, the walkthrough assumes that you selected the Web Development collection of settings when you started Visual Studio the first time. For more information, see How to: Select Web Development Environment Settings.

Creating a Web Site Project and Page

In this part of the walkthrough, you will create a Web site project and add a new page to it. You will also add HTML text and run the page in your Web browser.

If you have already created a Web Forms Web site project in Visual Studio (for example, by following the steps in Walkthrough: Creating a Basic Web Forms Page in Visual Studio), you can use that Web site and skip to "Creating a New Page" later in this walkthrough. Otherwise, create a new Web site project and page by following these steps.

To create a file system Web site project

  1. Open Visual Studio or Visual Web Developer Express.

  2. In the File menu, click New Web Site.

    The New Web Site dialog box is displayed.

  3. Under Installed Templates, click Visual Basic or Visual C# and then select ASP.NET Web Site.

  4. In the Web location box, select File System, and then enter the name of the folder where you want to keep the pages for your Web site.

    For example, type the folder name C:\WebSites.

  5. Click OK.

    Visual Studio creates a Web site project that includes prebuilt functionality for layout (a master page, the Default.aspx and About.aspx content pages, and a cascading style sheet), for Ajax (client script files), and for authentication (ASP.NET membership).

Creating a New Web Forms Page

When you create a new Web site project, Visual Studio adds a Web Forms page named Default.aspx. By default, Visual Studio creates a page with code separation.

To add a page with code separation to the Web site

  1. Close the Default.aspx page. To do this, right-click the tab with the file name in it and then click Close.

  2. In Solution Explorer, right-click the Web site (for example, C:\BasicWebSite) and then click Add New Item.

  3. Under Installed Templates, click Visual Basic or Visual C# and then select Web Form from the list.

  4. In the Name box, enter WebPageSeparated.

  5. Make sure that the Place code in separate file check box is selected.

  6. Make sure that the Select master page check box is cleared.

    For this walkthrough, you will create a page that does not use the master page that is included in the Web site project.

  7. Click Add.

    Visual Studio creates two files. The first file, WebPageSeparated.aspx, will contain the page's text and controls, and is opened in the editor. A second file, WebPageSeparated.aspx.vb or WebPageSeparated.aspx.cs (depending on what programming language you selected), is the code file. You can see both files in Solution Explorer by clicking the plus sign (+) next to the WebPageSeparated.aspx file; the code file has been created but is not open. You will open it later in the walkthrough when you write code.

Adding HTML to the Web Forms Page

In this part of the walkthrough, you will add some static HTML text to the WebPageSeparated.aspx page.

To add text to the page

  1. Click the Design tab at the bottom of the document window to switch to Design view.

    Design view displays the page you are working on in a WYSIWYG-like way. At this point, you do not have any text or controls on the page, so the page is blank.

  2. Place the insertion pointer in the div element that is already on the page.

  3. Type the words Welcome to Visual Studio Using Code Separation.

  4. Switch to Source view.

    You can see the HTML that you created by typing in Design view. At this stage, the page looks like an ordinary HTML page. The only difference is in the <%@ Page %> directive at the top of the page.

Adding and Programming Server Controls

In this part of the walkthrough, you will add server controls to the Web Forms page: a button, text box, and label control. You will also write code to handle the button's Click event. Server controls, which include buttons, labels, text boxes, and other familiar controls, provide typical form-processing capabilities for your ASP.NET Web Forms pages. However, you can program the controls with code that runs on the server, not the client.

To add controls to the page

  1. Click the Design tab to switch to Design view.

  2. Place the insertion pointer after the text that you added previously.

  3. Press ENTER a few times to make some room.

  4. From the Standard tab in the Toolbox, drag three controls onto the page: a TextBox control, a Button control, and a Label control.

  5. Put the insertion pointer in front of the text box and type Enter your name:.

    This static HTML text is the caption for the TextBox control. You can mix static HTML and server controls on the same page.

Setting Server Control Properties

Visual Studio offers you various ways to set the properties of server controls on the page. In this part of the walkthrough, you will work with properties in both Design view and Source view.

To set control properties

  1. Select the Button control and in the Properties window set its Text property to Display Name.

  2. Switch to Source view.

    Source view displays the HTML markup for the page, including the elements that Visual Studio has created for the server controls. Server controls are declared using HTML-like syntax, except that the tags use the prefix asp: and include the attribute runat="server".

    Server control properties are declared as attributes. For example, when you set the button's Text property in Step 1, you were actually setting the Text attribute in the control's markup.

    Note that all the controls are inside a form element that also has the attribute runat="server". The runat="server" attribute and the asp: prefix for control tags mark the controls so that they are processed by ASP.NET when the page runs.

Programming the Button Control

For this walkthrough, you will write code that reads the name that the user enters in the text box and then displays it in the Label control.

To add a default button event handler

  1. Switch to Design view

  2. Double-click the Button control.

    Visual Studio opens the WebPageSeparated.aspx.vb or WebPageSeparated.aspx.cs file in a separate window in the editor. The file contains a skeleton Click event handler for the button.

  3. Complete the Click event handler by adding the following highlighted code.

    Protected Sub Button1_Click(ByVal sender As Object, _
        ByVal e As System.EventArgs) Handles Button1.Click
            Label1.Text = Textbox1.Text & ", welcome to Visual Studio!"
    End Sub
    protected void Button1_Click(object sender, System.EventArgs e)
        Label1.Text = TextBox1.Text + ", welcome to Visual Studio!";

    Notice that as you type, IntelliSense helps you with context-sensitive choices. This is identical to the behavior when you are coding in a single-file page.

Examining the Page and Code File

You now have two files that make up the complete Web Forms page named WebPageSeparated: WebPageSeparated.aspx and WebPageSeparated.aspx.vb or WebPageSeparated.aspx.cs. In this section of the walkthrough, you will examine how these files are structured and how they relate to each other.

To examine the page and code file

  1. Click the WebPageSeparated.aspx tab at the top of the editor window to switch to the page file.

  2. Switch to Source view.

    At the top of the page is an @ Page directive that binds this page to the code file. The directive looks like the following code.

    <%@ Page Language="VB" AutoEventWireup="false" CodeFile="WebPageSeparated.aspx.vb" Inherits="WebPageSeparated" %>
    <%@ Page Language="C#" AutoEventWireup="true" CodeFile="WebPageSeparated.aspx.cs" Inherits="WebPageSeparated" %>

    (The line does not wrap in the editor, and the language attribute and file name extensions will match the programming language you selected.)

    When the page runs, ASP.NET dynamically creates an instance of a class representing the Web Forms page. The Inherits attribute identifies the class defined in the code-behind file from which the .aspx page is derived. By default, Visual Studio uses the page name as the basis for the class name in the code-behind file.

    The CodeFile attribute identifies the code file for this page. In simple terms, the code-behind file contains the event-handling code for your page.

  3. Click the WebPageSeparated.aspx.vb or WebPageSeparated.aspx.cs tab to switch to the code file.

    The code file contains code that is similar to a class definition. However, it is not a complete class definition; instead, it is a partial class that contains only a portion of the complete class that will make up the page. Specifically, the partial class defined in the code file contains the event handlers and other custom code that you write. At run time, ASP.NET generates another partial class containing your user code. This complete class is then used as the base class that is used to render the page. For more information, see ASP.NET Page Class Overview.

Running the Page

You can now test the page.

To run the page

  1. Press CTRL+F5 to run the page in the browser.

    The page runs using the Visual Studio Development Server.

  2. Enter a name in the text box and click the button.

    The name you entered is displayed in the Label control.

  3. In the browser, view the source of the page you are running.

  4. Close the browser.

    The page works exactly the same as it would if it were a single-file page. (If you followed the steps in Walkthrough: Creating a Basic Web Forms Page in Visual Studio to create a single-file page, you can compare the two pages to see that they are the same when running.)

Next Steps

This walkthrough has illustrated how to create and edit a Web Forms page that uses code separation. From the perspective of creating and running the page, there is not a significant difference between a single-file page and a page with code separation.

You might want to explore other features. For example, you might want to:

See Also


Walkthrough: Creating a Basic Web Forms Page in Visual Studio


Types of Web Site Projects in Visual Studio

Other Resources

ASP.NET Web Forms Pages

Web Application Projects versus Web Site Projects in Visual Studio