Microsoft KB Archive/307860

= ASP.NET data binding overview =

Article ID: 307860

Article Last Modified on 5/18/2007

-

APPLIES TO


 * Microsoft ASP.NET 1.0
 * Microsoft Visual Basic .NET 2002 Standard Edition
 * Microsoft Visual C# .NET 2002 Standard Edition
 * Microsoft Visual J# .NET 2003 Standard Edition
 * Microsoft ASP.NET 1.1
 * Microsoft Visual Basic .NET 2003 Standard Edition
 * Microsoft Visual C# .NET 2003 Standard Edition
 * Microsoft Visual J# .NET 2003 Standard Edition

-



This article was previously published under Q307860



This article refers to the following Microsoft .NET Framework Class Library namespaces:
 * System.Data
 * System.Data.SqlClient



SUMMARY
This article provides an introduction to ASP.NET data binding.

For additional ASP.NET overviews, see the following Microsoft Knowledge Base article:

305140 ASP.NET roadmap



MORE INFORMATION
With ASP.NET data binding, you can bind any server control to simple properties, collections, expressions and/or methods. When you use data binding, you have more flexibility when you use data from a database or other means.

This article addresses the following data binding topics:
 * Data binding essentials
 * <%# %> Syntax
 * Page.DataBind versus Control.DataBind
 * Data-bound list controls
 * Repeater control
 * DataList control
 * DataGrid control
 * Accessing data
 * DataSet dlass
 * DataReader dlass
 * Binding in list control templates
 * DataBinder.Eval method
 * Explicit casting
 * ItemDataBound event

<%# %> Syntax
ASP.NET introduces a new declarative syntax, <%# %>. This syntax is the basis for using data binding in an .aspx page. All data binding expressions must be contained within these characters. The following list includes examples of simple data binding from multiple sources:   Simple property (syntax for a customer): <%# custID %>   Collection (syntax for an order): ' runat=&quot;server&quot;>   Expression (syntax for a contact): <%# ( customer.First Name + &quot; &quot; + customer.LastName ) %>   Method result (syntax for the outstanding balance): <%# GetBalance(custID) %> 

In the preceding examples, the inline <%# %> tags indicate where the information from a specific data source is to be placed in the .aspx page. The following data binding example uses a TextBox Web server control: &quot; runat=server /> For more information about data binding syntax, see the following .NET Framework Software Development Kit (SDK) documentation:

Data Binding Expression Syntax

http://msdn.microsoft.com/library/default.asp?url=/library/en-us /cpgenref/html/cpcondatabindingexpressionsyntax.asp

Page.DataBind versus Control.DataBind
After the particular data sources have been determined and set for the objects on the .aspx page, you must bind the data to these data sources. You can use the Page.DataBind or the Control.DataBind method to bind the data to the data sources.

Both methods work similarly. The main difference is that all data sources are bound to their server controls after the Page.DataBind method is called. No data is rendered to the control until you explicitly call either the DataBind method of the Web server control or until you invoke the page-level Page.DataBind method. Typically, Page.DataBind (or DataBind) is called from the Page_Load event.

For more information about the DataBind method, see the following .NET Framework SDK documentation: Control.DataBind Method

http://msdn.microsoft.com/library/default.asp?url=/library/en-us /cpref/html/frlrfSystemWebUIControlClassDataBindTopic.asp

Data-bound list controls
The list controls are special Web server controls that can bind to collections. You can use these controls to display rows of data in a customized template format. All list controls expose the DataSource and the DataMember properties, which are used to bind to collections.

These controls can bind their DataSource property to any collection that supports the IEnumerable, the ICollection, or the IListSource interface.

Repeater control
The Repeater control is a templated, data-bound list. The Repeater control is &quot;lookless;&quot; that is, it does not have any built-in layout or styles. Therefore, you must explicitly declare all HTML layout, formatting, and style tags in the control's templates.

The following code samples demonstrate how you can use one list control, the Repeater control, to display data:

NOTE: You must modify the parameters of the connection string as necessary for your environment.

Visual Basic .NET <%@ Page Language=&quot;vb&quot; %> <%@ Import Namespace=&quot;System.Data&quot; %> <%@ Import Namespace=&quot;System.Data.SqlClient&quot; %>

<script runat=&quot;server&quot;> Sub Page_Load(sender As Object, e As EventArgs)

Dim cnn As SqlConnection = New SqlConnection(&quot;server=(local);&quot; & _                                               &quot;database=pubs;Integrated Security=SSPI&quot;) Dim cmd As SqlDataAdapter = New SqlDataAdapter(&quot;select * from authors&quot;, cnn) Dim ds As DataSet = New DataSet cmd.Fill(ds) Repeater1.DataSource = ds  Repeater1.DataBind

End Sub <form id=&quot;Form1&quot; method=&quot;post&quot; runat=&quot;server&quot;> <asp:Repeater id=&quot;Repeater1&quot; runat=&quot;server&quot;> <ItemTemplate> <%# DataBinder.Eval(Container.DataItem,&quot;au_id&quot;) %> </ItemTemplate> </asp:Repeater> Visual C# .NET <%@ Page language=&quot;c#&quot; %> <%@ Import Namespace=&quot;System.Data&quot; %> <%@ Import Namespace=&quot;System.Data.SqlClient&quot; %>

<script runat=&quot;server&quot;> void Page_Load(Object sender, EventArgs e) { SqlConnection cnn = new SqlConnection(&quot;server=(local);database=pubs;Integrated Security=SSPI&quot;); SqlDataAdapter da = new SqlDataAdapter(&quot;select * from authors&quot;, cnn); DataSet ds = new DataSet; da.Fill(ds, &quot;authors&quot;); Repeater1.DataSource = ds.Tables[&quot;authors&quot;]; Repeater1.DataBind; }  <form id=&quot;WebForm2&quot; method=&quot;post&quot; runat=&quot;server&quot;> <asp:Repeater id=&quot;Repeater1&quot; runat=&quot;server&quot;> <ItemTemplate> <%# DataBinder.Eval(Container.DataItem,&quot;au_id&quot;) %> </ItemTemplate> </asp:Repeater> Visual J# .NET <%@ Page language=&quot;VJ#&quot; %> <%@ Import Namespace=&quot;System.Data&quot; %> <%@ Import Namespace=&quot;System.Data.SqlClient&quot; %>

<script runat=&quot;server&quot;> void Page_Load(Object sender, EventArgs e) { SqlConnection cnn = new SqlConnection(&quot;server=(local);database=pubs;Integrated        Security=SSPI&quot;); SqlDataAdapter da = new SqlDataAdapter(&quot;select * from authors&quot;, cnn); DataSet ds = new DataSet; da.Fill(ds, &quot;authors&quot;); DataTableCollection dtc = ds.get_Tables; int index = dtc.IndexOf(&quot;authors&quot;); Repeater1.set_DataSource(dtc.get_Item(index)); Repeater1.DataBind; }  <form id=&quot;WebForm2&quot; method=&quot;post&quot; runat=&quot;server&quot;> <asp:Repeater id=&quot;Repeater1&quot; runat=&quot;server&quot;> <ItemTemplate> <%# DataBinder.Eval(Container.DataItem,&quot;au_id&quot;) %> </ItemTemplate> </asp:Repeater> For more information about the Repeater control, see the following .NET Framework SDK documentation:

Repeater Web Server Control

http://msdn.microsoft.com/library/en-us/cpgenref/html/cpconrepeaterwebservercontrol.asp

DataList control
The DataList class is a feature-rich, templated, data-bound list. You can modify the templates to customize this control. Unlike the Repeater control, DataList supports directional rendering and can optionally render in an HTML table at run time.

For more information about the DataList control, see the following .NET Framework SDK documentation:

DataList Web Server Control

http://msdn.microsoft.com/library/en-us/cpgenref/html/cpcondatalistwebservercontrol.asp

DataGrid control
The DataGrid control is a fully featured, multicolumn, data-bound grid. To customize the layout of individual columns in the DataGrid, you can set the column type to &quot;templated&quot; and modify the column's templates. The DataGrid control can render without templates, which makes this control ideal for reporting scenarios. DataGrid also supports selection, editing, deletion, paging, and sorting by column and button columns.

For more information about the DataGrid control, see the following .NET Framework SDK documentation:

DataGrid Web Server Control

http://msdn.microsoft.com/library/en-us/cpgenref/html/cpcondatagridwebservercontrol.asp

Accessing data
This section describes how to access data from a database and bind the data to list controls. You can use the DataSet or the DataReader class to obtain data from a database.

DataSet class
A DataSet contains a complete representation of data, including the table structure, the relationships between tables, and the ordering of the data. DataSet classes are flexible enough to store any kind of information from a database to an Extensible Markup Language (XML) file. DataSet classes are stateless; that is, you can pass these classes from client to server without tying up server connection resources. The following code demonstrates how to use a DataSet to bind data to a control:

NOTE: You must modify the parameters of the connection string as necessary for your environment.

Visual Basic .NET Dim cnn As SqlConnection = New SqlConnection(&quot;server=(local);&quot; & _                                            &quot;database=pubs;Integrated Security=SSPI&quot;) Dim cmd As SqlDataAdapter = New SqlDataAdapter(&quot;select * from authors&quot;, cnn) Dim ds As DataSet = New DataSet cmd.Fill(ds) MyRepeater.DataSource = ds MyRepeater.DataBind Visual C# .NET SqlConnection cnn = new SqlConnection(&quot;server=(local);                                      database=pubs;Integrated Security=SSPI&quot;); SqlDataAdapter da = new SqlDataAdapter(&quot;select * from authors&quot;, cnn); DataSet ds = new DataSet; da.Fill(ds); MyRepeater.DataSource = ds; MyRepeater.DataBind; Visual J# .NET SqlConnection cnn = new SqlConnection(&quot;server=(local);                                      database=pubs;Integrated Security=SSPI&quot;); SqlDataAdapter da = new SqlDataAdapter(&quot;select * from authors&quot;, cnn); DataSet ds = new DataSet; da.Fill(ds); MyRepeater.set_DataSource(ds); MyRepeater.DataBind; For more information about the DataSet class, see the following .NET Framework SDK documentation:

DataSet Class

http://msdn2.microsoft.com/en-us/library/system.data.dataset(vs.71).aspx

DataReader class
Conversely, if you only need to display (and not change) the data that is to be rendered, a DataReader class may be a better solution. For example, it is better to use a DataReader for a DropDownList control because the DataReader is a forward-only data cursor. The following code demonstrates how to use a SqlDataReader class to bind data to a control:

Visual Basic .NET Dim cnn As SqlConnection = New SqlConnection(&quot;server=(local);&quot; & _                                            &quot;database=pubs;Integrated Security=SSPI&quot;) Dim cmd As SqlCommand = New SqlCommand(&quot;select * from authors&quot;, cnn)

cnn.Open MyRepeater.DataSource = cmd.ExecuteReader(CommandBehavior.CloseConnection) MyRepeater.DataBind Visual C# .NET SqlConnection cnn = new SqlConnection(&quot;server=(local);                                      database=pubs;Integrated Security=SSPI&quot;); SqlCommand cmd = new SqlCommand(&quot;select * from authors&quot;, cnn);

cnn.Open; MyRepeater.DataSource = cmd.ExecuteReader(CommandBehavior.CloseConnection); MyRepeater.DataBind; Visual J# .NET SqlConnection cnn = new SqlConnection(&quot;server=(local);                                      database=pubs;Integrated Security=SSPI&quot;);

SqlCommand cmd = new SqlCommand(&quot;select * from authors&quot;, cnn);

cnn.Open; MyRepeater.set_DataSource(cmd.ExecuteReader(CommandBehavior.CloseConnection)); MyRepeater.DataBind; For more information about the SqlDataReader class and data access with ASP.NET, see the following topics in the .NET Framework SDK documentation:

SqlDataReader Class

http://msdn.microsoft.com/library/default.asp?url=/library/en-us /cpref/html/frlrfSystemDataSqlClientSqlDataReaderClassTopic.asp

Developing High-Performance ASP.NET Applications

http://msdn2.microsoft.com/en-us/library/5dws599a(vs.71).aspx

Binding in list control templates
You can use templates in the list controls to bind and to customize individual records of a data source. This section includes three methods to do this.

DataBinder.Eval method
When the data source works with data that is returned from a database, the data source may contain numerous pieces of information. You can use the generic DataBinder.Eval method to return data. In the following code sample, the &quot;au_id&quot; field is returned from the data source of the container object: <%# DataBinder.Eval(Container.DataItem,&quot;au_id&quot;) %> For more information about the DataBinder.Eval method, see the following .NET Framework SDK documentation:

DataBinder.Eval Method

http://msdn.microsoft.com/library/default.asp?url=/library/en-us /cpref/html/frlrfSystemWebUIDataBinderClassEvalTopic.asp

Explicit casting
If you need more control, use explicit casting. An explicit conversion uses a type conversion keyword. These keywords act as functions, but the compiler generates the code inline. Therefore, execution is slightly faster than with a function call. The following code samples use explicit casting:

Visual Basic .NET ' DataTable as the DataSource <%# CType(Container.DataItem, System.Data.DataRowView)(&quot;au_id&quot;) %>

' DataReader as the DataSource <%# CType(Container.DataItem, System.Data.Common.DbDataRecord)(&quot;au_id&quot;) %>

' DataReader as the DataSource <%# CType(Container.DataItem, System.Data.Common.DbDataRecord)(0) %> Visual C# .NET // DataTable as the DataSource <%# ((System.Data.DataRowView)Container.DataItem)[&quot;au_id&quot;] %>

// DataReader as the DataSource <%# ((System.Data.Common.DbDataRecord)Container.DataItem)[&quot;au_id&quot;] %>

// DataReader as the DataSource <%# ((System.Data.Common.DbDataRecord)Container.DataItem)[0] %> Visual J# .NET // DataTable as the DataSource <%# ((System.Data.DataRowView)Container.DataItem)[&quot;au_id&quot;] %>

// DataReader as the DataSource <%# ((System.Data.Common.DbDataRecord)Container.DataItem)[&quot;au_id&quot;] %>

// DataReader as the DataSource <%# ((System.Data.Common.DbDataRecord)Container.DataItem)[0] %> Note that the preceding samples use either a DataTable, which is a subset of a DataSet, or DataReader as a data source.

ItemDataBound event
You can also use the ItemDataBound event of the control to bind the data. This event occurs when an item is data bound to the control. The following HTML code sample defines a Repeater control with an ItemTemplate: <asp:repeater id=rptr runat=server> <asp:label id=lblAuthorID runat=server /> </asp:repeater> The following methods are required in your page:

Visual Basic .NET public Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) 'TODO: Retrieve data from a database, 'and bind the data to a list control.

End Sub

public Sub rptr_OnItemDataBound(ByVal sender As Object, _ ByVal e As System.Web.UI.WebControls.RepeaterItemEventArgs) Handles rptr.ItemDataBound Dim rec As DataRowView rec = e.Item.DataItem

'Make sure that you have the data. If Not IsDBNull(rec) Then Dim l1 As Label l1 = e.Item.FindControl(&quot;lblAuthorID&quot;) l1.Text = rec(&quot;au_id&quot;).ToString End If End Sub Visual C# .NET public void Page_Init(object sender, System.EventArgs e) { rptr.ItemDataBound += new RepeaterItemEventHandler(rptr_OnItemDataBound); } public void Page_Load(object sender, System.EventArgs e) { // TODO: Retrieve data from a database, // and bind the data to a list control. } public void rptr_OnItemDataBound(object sender, RepeaterItemEventArgs e) { System.Data.Common.DbDataRecord rec = (System.Data.Common.DbDataRecord) e.Item.DataItem; if(rec!=null) //Make sure that you have the data. {     Label l1 = (Label)e.Item.FindControl(&quot;lblAuthorID&quot;); l1.Text = rec[&quot;au_id&quot;].ToString; } } Visual J# .NET public void Page_Init(Object sender, System.EventArgs e) { rptr.add_ItemDataBound(new RepeaterItemEventHandler(rptr_OnItemDataBound)); } private void Page_Load(Object sender, System.EventArgs e) { // TODO: Retrieve data from a database, // and bind the data to a list control. } public void rptr_OnItemDataBound(Object sender, RepeaterItemEventArgs e) { System.Data.Common.DbDataRecord rec = (System.Data.Common.DbDataRecord) e.get_Item.get_DataItem; if (rec != null) //Make sure that you have the data. {                       Label l1 = (Label)e.get_Item.FindControl(&quot;lblAuthorID&quot;); l1.set_Text(((rec.get_Item(&quot;au_id&quot;)).ToString)); } }

<div class="references_section">