Jay Harris is Cpt. LoadTest

The previous installments of this series cover the core events of the ASP.NET Page class, of the ASP.NET Controls, and how the page and controls work together to co-exist in the same sandbox. We've gotten to the point where we know how these controls will interact with the page so that we can make our page more than just a sea of crazy peach gradient backgrounds, but that still isn't enough. Static content is so 1999, and that party broke up long ago. The next step in a quality, modern web site is creating dynamic content, and rendering it to the page. To do this, we need Data Binding.

About the Series

When a request occurs for an ASP.NET page, the response is processed through a series of events before being sent to the client browser. These events, known as the ASP.NET Page Life Cycle, are a complicated headache when used improperly, manifesting as odd exceptions, incorrect data, performance issues, and general confusion. It seems simple when reading yet-another-book-on-ASP.NET, but never when applied in the real world. What is covered in a few short pages in many ASP.NET books (and sometimes even just a few short paragraphs), is much more complicated outside of a "Hello, World!" application and inside of the complex demands of the enterprise applications that developers create and maintain in their day-to-day work life. As close to the core as the life cycle is to any ASP.NET web application, the complications and catches behind this system never seems to get wide coverage on study guides or other documentation. But, they should.

Part 1: Events of the ASP.NET Page Life Cycle
Part 2: ASP.NET Page & WebControl Event Execution Order
Part 3: Getting Started with ASP.NET Data Binding
Part 4: Wiring Events to your Page

Getting Started with ASP.NET Data Binding

When we load up data from the database, we could use a for-each loop to iterate through the data, manually create every new control, such as a table row, and manually write our data as the content for each new control, but that would be a lot of useless, repetitive, and senseless boilerplate code. Instead, we should use functionality that is built in to the ASP.NET framework, and allow the framework to do a lot of the work for us. This process of using the framework for binding dynamic data to the page, or to controls within the page, is called Data Binding.

As we've discussed before, there are several events that handle the processing and rendering of a page. Similarly, there are several events that handle the process of binding data to a page (and its child controls). Each of these events handle a very specific sub-set of the process. And as before, knowing the execution order of these events will make you more proficient at ASP.NET development.

For our examples, we will have a page for displaying Company data. The page will host a TextBox control containing the name of the company, and a repeater for departments within the company. Each repeater item will display the name of the department and a DropDownList containing the names of employees within the department.

public partial class CompanyInformation : Page
{
  private Repeater _deparmentsRepeater;
  private TextBox _companyNameTextbox;

  public _Default()
  {
    Init += Page_Init;
    Load += Page_Load;
  }

  void Page_Init(object sender, EventArgs e)
  {
    var container = new Panel();
    _companyNameTextbox = new TextBox();
    _companyNameTextbox.ID = "companyNameTextbox";
    _companyNameTextbox.DataBinding += TBox_DataBinding;
    container.Controls.Add(_companyNameTextbox);
    myForm.Controls.Add(container);

    _deparmentsRepeater = new Repeater();
    _deparmentsRepeater.ID = "departmentsRepeater";
    _deparmentsRepeater.ItemCreated += Rpt_ItemCreated;
    _deparmentsRepeater.ItemDataBound += Rpt_ItemDataBound;
    myForm.Controls.Add(_deparmentsRepeater);
  }
}

ASP.NET Data Binding Events

Page.DataBind() / Control.DataBind()

The first "Event" of ASP.NET's Data Binding Life Cycle is not an event at all; it is a method that gets everything started. The DataBind method initiates the process of binding all controls on the page, attaching your dynamic loaded classes or lists to the areas of your page where the data will be displayed. DataBind can be executed at the Page level, or on any bindable Control. Whenever it is executed, DataBind also cascades through all child controls of the execution point. If you have an ASP.NET Panel Control that contains several TextBox controls, executing DataBind on the panel will run the method on the Panel first, then all of the child text boxes. If you execute on the Page, it will fire first on the page, then on the panel, then on all of the text boxes. The cascading rules are the same as the event execution order discussed in Part 2 of this series.

Traditionally, DataBind is executed from within the Page Load event, though it can be executed from other places instead, as long as you keep the rest of the page life cycle in mind. For example, do not run DataBind on your page in PreInit; none of your controls have been instantiated, yet. Also, as my personal preference, I put all of my data retrieval logic in an override of the DataBind method, keeping all of my binding logic in a centralized location, though this can also occur elsewhere providing that it is prior to the execution of the base Page.DataBind() or Control.DataBind() method.

void Page_Load(object sender, EventArgs e)
{
  DataBind();
}
public override void DataBind()
{
  Trace.Write("Beginning to bind all controls");
  _myRepeater.DataSource = MyCompany.Departments();
  base.DataBind();
}

Here, the Page Load event kicks off our override of the DataBind method. This override retrieves a list of Departments for the company, and assigns the required properties from the company class instance to controls as needed, which includes all controls with a DataSource property. DataSource is usually a collection of objects to be used for binding collections to list-based controls from DropDownLists to Repeaters, though some other controls may have different needs and uses for DataSource. Above, we assign the Departments list to the repeater's DataSource property, so that later on in the binding process, the repeater can pass appropriate Department information on to each of its RepeaterItems and child controls. With the DataSource defined, the base DataBind method is executed to initiate binding to all controls on the page.

DataBinding Event

DataBinding is the first actual event that fires in the DataBinding series, and it will fire for every bindable control and child control from the point where the DataBind method was executed, top-down. When the event executes, binding has not yet been executed, but the data to be bound is available for manipulation. As such, binding has also not yet executed on any of the child controls of the event target. With the exception of list-based container controls like a DataGrid, GridView, or Repeater, during the DataBinding event would be where any dynamic child controls are created and their DataSources assigned.

// Use with: _companyNameTextbox.DataBinding += TBox_DataBinding;
void TBox_DataBinding(object sender, EventArgs e)
{
  ((TextBox) sender).Text = MyCompany.Name;
}

Above, we bind our TextBox control to the name of our company. TextBox does not have a DataSource property, so the company name is manually assigned directly to the TextBox's Text property.

RowCreated / ItemCreated Event

Note: RowCreated is used for GridView Control, only. ItemCreated is used for DataGrid, ListView, Repeater, and all other list-based container controls.
The RowCreated and ItemCreated events are very similar in nature to the DataBinding event, and are used for list-based container controls like a DataGrid, GridView, or Repeater. This event will execute once for each item in the DataSource collection, and correspond to one Row or Item in the control. On execution, the individual Row or Item in your control has been created, any child controls specified in your markup have been initialized and loaded, and the individual data item is available for manipulation. However, Data Binding has not yet been executed on the row or any of its child controls. This event cannot be dependent upon any control data since the binding has yet to occur. An example scenario that would use this event would be if your data item contained another list, such as our Department class instance that contains a list of Employees, and the Employees will display in a dropdown. During Created, the dropdown's DataSource can be assigned to the list contained within the Employees property. After the Created event finished for the Row or Item, ASP.NET will automatically execute the DataBind method on the Employees dropdown, binding the list data to populate the control. This automatic execution of DataBind applies to all child controls of the Row or Item, including controls defined in the Code-In-Front markup or those that were manually created in the code-behind.

Be aware that any code in the Created events cannot be dependent upon Control data. Even if you specify the DataSource property of a child dropdown, the DropDownList.Items list property is still empty. Executing code dependant upon control data, such as setting the selected item, will fail.

// Use with: _myRepeater.ItemCreated += Rpt_ItemCreated;
void Rpt_ItemCreated(object sender, RepeaterItemEventArgs e)
{
  //Preparing another Repeater Item for binding
  var dataItem = (Department) e.Item.DataItem;

  var departmentLabel = new Label();
  departmentLabel.Text = dataItem.Name;
  e.Item.Controls.Add(departmentLabel);

  var dropdownOfEmployees = new DropDownList();
  dropdownOfEmployees.DataSource = dataItem.Employees;
  dropdownOfEmployees.DataTextField = "Name";
  e.Item.Controls.Add(dropdownOfEmployees);

  e.Item.Controls.Add(new LiteralControl("
"));
}

The ItemCreated event creates a label for the name of the department, assigning the name, and a DropDownList of Employees, assigning only the list's DataSource. ItemCreated is repeated for every item in the repeater's DataSource collection, or in other words, every department associated with our company. Because DataBinding has not yet executed for any child control, none of the Employee ListItems exist in our DropDownList, but because it has not yet executed, we also do not need to manually create the ListItems or manually re-execute DropDownList.DataBind().

RowDataBound / ItemDataBound

Note: RowDataBound is used for GridView Control, only. ItemDataBound is used for DataGrid, ListView, Repeater, and all other list-based container controls.
The final event in the Data Binding Life Cycle is the Bound events, RowDataBound and ItemDataBound. This event fires when the data binding process has completed for all child controls within the Row or Item. All controls within the row have their data, and code that is dependant upon control data, such as setting a selected item, can now be executed. It is strongly advised that this event contains no modifications to the item data that would require a DataBind method to be executed; this sort of data manipulation should occur instead in the Created events, prior to Data Binding the child control tree. If DataBind were to be executed again on this control, the Data Binding process for this control and all children is restarted and re-executed, causing controls to be Data Bound two or more times and potentially leading to an unknown state and adverse outcomes in your application.

The DataBound events indicate that binding has been completed for this item and all child controls; for us, this means our DropDownList of employees has been fully bound, and that a ListItem exists for each Employee. We can use this post-binding event to perform any data-dependent logic. In this case, we now set the SelectedIndex of our DropDownList; the method would fail if it was executed during ItemCreated. As with ItemCreated, this event will execute for each item in our repeater's DataSource collection.

// Use with: _myRepeater.ItemDataBound += Rpt_ItemDataBound;
void Rpt_ItemDataBound(object sender, RepeaterItemEventArgs e)
{
  var dropdownOfEmployees = (DropDownList) e.Item.Controls[1];
  dropdownOfEmployees.SelectedIndex = 2;
}

Proper Data Binding

This is the essence of Data Binding within ASP.NET Web Forms: one method and three events. When done properly, the DataBind method should only be called once on a control tree. Execute DataBind directly on the page, or execute it once on individual controls such as each of your top-level Repeaters, but whatever path you follow, make sure that the method is not executed twice on any single control. Use the binding events to make this happen. Failure to do so can cause unfortunate side effects and extensive pain.

• DataSources should be assigned prior to execution of a control's DataBind method.
• Controls without a DataSource property can be manually bound using the controls DataBinding event, after executing DataBind.
• For collection-based container controls, define child controls and assign their DataSource using the RowCreated/ItemCreated events.
• For collection-based container controls, perform data-dependent logic on child controls in the RowDataBound/ItemDataBound event.

The ASP.NET Page Life Cycle may seem like a monotonous mess, but it is a useful tool if you understand the events, their order, and their relationship to each other. If you missed them, go back and review Part 1 for the core Page Life Cycle events and to Part 2 for the Event Execution Order between a page and its controls. Once you have these down, there still are some oddities to look out for (and some tricks to help you out). As the series continues, we discuss some of these tips, tricks, and traps to help you unleash the full power of your ASP.NET applications.