How to: Create Event Handlers in ASP.NET Web Forms Pages

In an ASP.NET Web Forms page, you can create server event handlers for server controls and for the page in a variety of ways. Some of the ways depend on which programming language you are working in. You can create handlers by using the facilities in Visual Studio, or you can create them declaratively or in 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.

You can also add events for client script, which execute when the control is running in the browser as an element in the page. That's a different process than what is described in this topic. For details, see How to: Add Client Script Events to ASP.NET Web Server Controls.

If a server control supports more than one event, it is usually configured so that one event is the default. For example, for the Button control, the default event is the Click event.

Creating Event Handlers in Visual Studio

To create an event handler for the default event

  • In Design view, double-click the page or double-click the control for which you want to create a default event handler.

    Visual Studio creates a handler for the default event and opens the code editor with the insertion point in the event handler.

To create an event handler in the Properties window

  1. In Design view, select the control for which you want to create an event handler.

    Note

    You cannot select the page in Design view, so you cannot create a page-level event using this procedure. Use the previous procedure instead.

  2. In Properties, click the events symbol Events Button.

    The Properties window displays a list of events for the selected control.

  3. In the box next to an event name, do one of the following:

    • Double-click to create a new event handler for that event. The designer will name the handler using the convention controlID_event.

    • Type the name of the handler to create.

    • In the drop-down list, select the name of an existing handler.

      The drop-down list displays a list of methods that have the correct signature for the event.

    When you are finished, Visual Web Developer switches to the code editor and puts the insertion point in the handler.

To create an event handler in the code editor

  1. Switch to the code editor by using one of the following techniques:

    • For a single-file Web Forms page, switch to Source view.

    • For a code-behind page, in Solution Explorer, right-click the name of the page, and then click View Code.

      Note

      In code-behind pages that use C#, this technique will not work because the control name will not appear in the drop-down list in the last step. Use one of the other procedures instead.

  2. At the top of the code editor window, select the control from the drop-down list located on the left side, and then select the event from the drop-down list located on the right side.

    Note

    Events for which methods already exist are displayed in bold text.

Creating Event Handlers Declaratively

When you use Visual Studio to create a handler, Visual Studio creates the skeleton handler and configures the control to call the handler. You can do the same yourself.

To create a handler for page events

  • In the code editor, create a method with the name Page_event.

    For example, to create a handler for the page's Load event, create a method named Page_Load.

    Note

    Page event handlers are not required to take parameters the way that other controls event handlers are.

    ASP.NET Web Forms pages automatically bind page events to methods that have the name Page_event. This automatic binding is configured by the AutoEventWireup attribute in the @ Page directive, which is set to true by default. If you set AutoEventWireup to false, the page does not automatically search for methods that use the Page_event naming convention.

    The following code example shows a handler for the page's Load event.

    Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        If Page.IsPostBack Then
            Response.Write("<br>Page has been posted back.")
        End If 
    End Sub
    
    protected void Page_Load(object sender, EventArgs e)
    {
        if (IsPostBack)
        {
            Response.Write("<br>Page has been posted back.");
        }
    }
    

To add a handler declaratively for a server control

  1. In the code editor, create an event-handling method with the appropriate signature.

    The method can be named anything you like.

  2. In the markup of the control, use the attributes that are named On<event name> to hook up the event handler. Use the event handler method name as the value.

    The following code example shows the markup for a TextBox control for which the TextChanged event is bound to the event handler method named NameChange:

    Security noteSecurity Note

    This example contains a text box that accepts user input, which is a potential security threat. By default, ASP.NET Web Forms pages validate that user input does not include script or HTML elements. For more information, see Script Exploits Overview.

    Protected Sub NameChange(ByVal sender As Object, ByVal e As System.EventArgs) Handles textbox1.TextChanged
        'Sub for the OnTextChanged event 
    End Sub
    
    <asp:TextBox ID="textbox1" Runat="server" 
    Text="" 
    OnTextChanged="NameChange" />
    
  3. Add the event method to your code. For example, the following code example shows the code for the event handler method named NameChange:

    protected void NameChange(object sender, EventArgs e)
    {
        //Method for the OnTextChanged event.
    }
    

To add an event handler implicitly in Visual Basic

  1. In the code editor, create an event-handling method with the appropriate signature.

    The method can be named anything you like.

  2. Use the Handles keyword, specifying the control and event to which the method should bind.

    The following code example shows an event handler for the Click event of a button named SampleButton. The method in the example is named Clicked.

    Protected Sub SampleButton_Click(ByVal sender As Object, ByVal e As System.EventArgs) _
            Handles SampleButton.Click
        ' Code goes here. 
    End Sub
    

    Note

    If you use the Handles keyword, do not include an event attribute in the control markup. If you do, the handler will be called twice.

  3. If the method handles multiple events, add the names of the additional events to the Handles clause, separated by a comma.

    The following code example shows a method that handles the Click event for several buttons. In the handler, the code tests the sender argument to determine which button was clicked.

    Protected Sub AnyClicked(ByVal sender As Object, ByVal e As System.EventArgs) _
            Handles Button1.Click, Button2.Click, Button3.Click
        Dim b As Button = CType(sender, Button)
        Response.Write("You clicked the button labeled " & b.ID)
    End Sub
    

See Also

Tasks

How to: Dynamically Bind Event Handlers at Run Time in ASP.NET Web Forms Pages

Reference

System.Web.UI.Page

Concepts

ASP.NET Web Server Controls Overview

Other Resources

Handling and Raising Events

Server Event Handling in ASP.NET Web Forms Pages

Handling and Raising Events