This documentation is archived and is not being maintained.

DataBoundControl Class

Serves as the base class for all ASP.NET version 2.0 data-bound controls that display their data in list or tabular form.

Namespace:  System.Web.UI.WebControls
Assembly:  System.Web (in System.Web.dll)

'Declaration
<AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level := AspNetHostingPermissionLevel.Minimal)> _
Public MustInherit Class DataBoundControl _
	Inherits BaseDataBoundControl
'Usage
Dim instance As DataBoundControl
<asp:DataBoundControl />

The DataBoundControl class is the base class used for ASP.NET controls that retrieve tabular or list-style data from an ASP.NET data source control and bind user-interface (UI) elements of the control to that data for display. Composite data-bound controls such as GridView, DetailsView, and FormView; list-style data-bound controls such as BulletedList and CheckBoxList; and other controls such as AdRotator derive from DataBoundControl.

Page developers do not use the DataBoundControl class directly; instead, they use controls that derive from this class.

Control developers extend this class to create data-bound controls that work with classes that implement the IDataSource interface and classes that derive from the DataSourceControl and DataSourceView classes. When deriving a class from the DataBoundControl class, override the PerformDataBinding method to bind the UI elements of your control to data retrieved by the GetData method. In most cases, the PerformDataBinding method is the only method you will override in your derived class.

For ASP.NET 2.0 data-bound controls, the PerformSelect method is the equivalent of the DataBind method, and is called to bind data at run time. The PerformSelect method calls the GetData and PerformDataBinding methods.

The following code example demonstrates how to derive a class from the DataBoundControl class to create a custom data-bound control. The TextBoxSet control creates a TextBox control for each data item retrieved from its associated data source control, and binds to the value of the data item at run time. The current implementation of the Render method renders the TextBox controls as an unordered list.

Imports System
Imports System.Collections
Imports System.ComponentModel
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet.Controls.VB

<AspNetHostingPermission(SecurityAction.Demand, _
    Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission(SecurityAction.InheritanceDemand, _
    Level:=AspNetHostingPermissionLevel.Minimal)> _
  Public Class TextBoxSet
    Inherits DataBoundControl

    Private alBoxSet As IList

    Public ReadOnly Property BoxSet() As IList
        Get 
            If alBoxSet Is Nothing Then
                alBoxSet = New ArrayList()
            End If 
            Return alBoxSet
        End Get 
    End Property 

    Public Property DataTextField() As String 
        Get 
            Dim o As Object = ViewState("DataTextField")
            If o Is Nothing Then 
                Return String.Empty
            Else 
                Return CStr(o)
            End If 
        End Get 
        Set(ByVal value As String)
            ViewState("DataTextField") = value
            If (Initialized) Then
                OnDataPropertyChanged()
            End If 
        End Set 
    End Property 

    Protected Overrides Sub PerformSelect()

        ' Call OnDataBinding here if bound to a data source using the  
        ' DataSource property (instead of a DataSourceID) because the  
        ' data-binding statement is evaluated before the call to GetData. 
        If Not IsBoundUsingDataSourceID Then
            OnDataBinding(EventArgs.Empty)
        End If 

        ' The GetData method retrieves the DataSourceView object from the  
        ' IDataSource associated with the data-bound control.            
        GetData().Select(CreateDataSourceSelectArguments(), _
            AddressOf OnDataSourceViewSelectCallback)

        ' The PerformDataBinding method has completed.
        RequiresDataBinding = False
        MarkAsDataBound()

        ' Raise the DataBound event.
            OnDataBound(EventArgs.Empty)

    End Sub 'PerformSelect

    Private Sub OnDataSourceViewSelectCallback(ByVal retrievedData As IEnumerable)

        ' Call OnDataBinding only if it has not already 
        ' been called in the PerformSelect method. 
        If IsBoundUsingDataSourceID Then
            OnDataBinding(EventArgs.Empty)
        End If 
        ' The PerformDataBinding method binds the data in the retrievedData  
        ' collection to elements of the data-bound control.
        PerformDataBinding(retrievedData)

    End Sub 'OnDataSourceViewSelectCallback

    Protected Overrides Sub PerformDataBinding(ByVal retrievedData As IEnumerable)
        MyBase.PerformDataBinding(retrievedData)

        ' If the data is retrieved from an IDataSource as an IEnumerable  
        ' collection, attempt to bind its values to a set of TextBox controls. 
        If Not (retrievedData Is Nothing) Then 

            Dim dataItem As Object
            For Each dataItem In retrievedData

                Dim box As New TextBox()

                ' The dataItem is not just a string, but potentially 
                ' a System.Data.DataRowView or some other container.  
                ' If DataTextField is set, use it to determine which  
                ' field to render. Otherwise, use the first field.                     
                If DataTextField.Length > 0 Then
                    box.Text = DataBinder.GetPropertyValue( _
                    dataItem, DataTextField, Nothing)
                Else 
                    Dim props As PropertyDescriptorCollection = _
                        TypeDescriptor.GetProperties(dataItem)

                    ' Set the "default" value of the TextBox.
                    box.Text = String.Empty

                    ' Set the true data-bound value of the TextBox, 
                    ' if possible. 
                    If props.Count >= 1 Then 
                        If props(0).GetValue(dataItem) IsNot Nothing Then
                            box.Text = props(0).GetValue(dataItem).ToString()
                        End If 
                    End If 
                End If

                BoxSet.Add(box)
            Next dataItem
        End If 

    End Sub 'PerformDataBinding

    Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)

        ' Render nothing if the control is empty.             
        If BoxSet.Count <= 0 Then 
            Return 
        End If 

        ' Make sure the control is declared in a form tag with runat=server. 
        If Not (Page Is Nothing) Then
            Page.VerifyRenderingInServerForm(Me)
        End If 

        ' For this example, render the BoxSet as  
        ' an unordered list of TextBox controls.            
        writer.RenderBeginTag(HtmlTextWriterTag.Ul)

        Dim item As Object
        For Each item In BoxSet

            Dim box As TextBox = CType(item, TextBox)

            ' Write each element as  
            ' <li><input type="text" value="string"><input/></li>
            writer.WriteBeginTag("li")
            writer.Write(">")
            writer.WriteBeginTag("input")
            writer.WriteAttribute("type", "text")
            writer.WriteAttribute("value", box.Text)
            writer.Write(">")
            writer.WriteEndTag("input")
            writer.WriteEndTag("li")
        Next item

        writer.RenderEndTag()

    End Sub 'Render
    End Class 'TextBoxSet 
End Namespace

The following code example demonstrates how to use the TextBoxSet control, defined in the previous example, and bind it to an AccessDataSource control.

<%@Page language="VB" %>
<%@ Register TagPrefix="aspSample" Namespace="Samples.AspNet.Controls.VB" 
    Assembly="Samples.AspNet.Controls.VB" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head>
    <title>TextBoxSet Data-Bound Control - VB Example</title>
  </head>

  <body>
    <form id="Form1" method="post" runat="server">

        <aspSample:textboxset
          id="TextBoxSet1"
          runat="server"
          datasourceid="AccessDataSource1" />

        <asp:accessdatasource
          id="AccessDataSource1"
          runat="server"
          datafile="Northwind.mdb"
          selectcommand="SELECT lastname FROM Employees" />

    </form>
  </body>
</html>

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0
Show: