Export (0) Print
Expand All
32 out of 59 rated this helpful - Rate this topic

DataTable Class

Represents one table of in-memory data.

For a list of all members of this type, see DataTable Members.

System.Object
   System.ComponentModel.MarshalByValueComponent
      System.Data.DataTable

[Visual Basic]
<Serializable>
Public Class DataTable
   Inherits MarshalByValueComponent
   Implements IListSource, ISupportInitialize, ISerializable
[C#]
[Serializable]
public class DataTable : MarshalByValueComponent, IListSource,
   ISupportInitialize, ISerializable
[C++]
[Serializable]
public __gc class DataTable : public MarshalByValueComponent,
   IListSource, ISupportInitialize, ISerializable
[JScript]
public
   Serializable
class DataTable extends MarshalByValueComponent implements
   IListSource, ISupportInitialize, ISerializable

Thread Safety

This type is safe for multithreaded read operations. You must synchronize any write operations.

Remarks

The DataTable is a central object in the ADO.NET library. Other objects that use the DataTable include the DataSet and the DataView.

When accessing DataTable objects, note that they are conditionally case-sensitive. For example, if one DataTable is named "mydatatable" and another is named "Mydatatable", a string used to search for one of the tables is regarded as case-sensitive. However, if "mydatatable" exists and "Mydatatable" does not, the search string is regarded as case-insensitive. For more information about working with DataTable objects, see Creating a DataTable.

If you are creating a DataTable programmatically, you must first define its schema by adding DataColumn objects to the DataColumnCollection (accessed through the Columns property). For more information about adding DataColumn objects, see Adding Columns to a Table.

To add rows to a DataTable, you must first use the NewRow method to return a new DataRow object. The NewRow method returns a row with the schema of the DataTable, as it is defined by the table's DataColumnCollection. The maximum number of rows that a DataTable can store is 16,777,216. For more information, see Adding Data to a Table.

The schema of a table is defined by the DataColumnCollection, the collection of DataColumn objects. The DataColumnCollection is accessed through the Columns property. See DataColumn and DataColumnCollection for more information about defining a schema for the table.

The DataTable contains a collection of Constraint objects that can be used to ensure the integrity of the data. For more information, see Adding Constraints to a Table.

To determine when changes are made to a table, use one of the following events: RowChanged, RowChanging, RowDeleting, and RowDeleted. For more information, see Working with DataTable Events.

When an instance of DataTable is created, some of the read/write properties are set to initial values. For a list of these values, see the DataTable constructor.

Note   The DataSet and DataTable objects inherit from MarshalByValueComponent, and support the ISerializable interface for remoting. These are the only ADO.NET objects that can be remoted.

Example

[Visual Basic, C#, C++] The following example creates two DataTable objects, one DataRelation object, and adds the new objects to a DataSet. The tables are then displayed in a DataGrid control by invoking the DataGrid.SetDataBinding method.

[Visual Basic] 
' Put the next line into the Declarations section.
 private myDataSet As DataSet 
 
 Private Sub MakeDataTables()
    ' Run all of the functions. 
    MakeParentTable()
    MakeChildTable()
    MakeDataRelation()
    BindToDataGrid()
 End Sub
 
 Private Sub MakeParentTable()
    ' Create a new DataTable.
    Dim myDataTable As DataTable = new DataTable("ParentTable")
    ' Declare variables for DataColumn and DataRow objects.
    Dim myDataColumn As DataColumn 
    Dim myDataRow As DataRow 
 
    ' Create new DataColumn, set DataType, ColumnName and add to DataTable.    
    myDataColumn = New DataColumn()
    myDataColumn.DataType = System.Type.GetType("System.Int32")
    myDataColumn.ColumnName = "id"
    myDataColumn.ReadOnly = True
    myDataColumn.Unique = True
    ' Add the Column to the DataColumnCollection.
    myDataTable.Columns.Add(myDataColumn)
 
    ' Create second column.
    myDataColumn = New DataColumn()
    myDataColumn.DataType = System.Type.GetType("System.String")
    myDataColumn.ColumnName = "ParentItem"
    myDataColumn.AutoIncrement = False
    myDataColumn.Caption = "ParentItem"
    myDataColumn.ReadOnly = False
    myDataColumn.Unique = False
    ' Add the column to the table.
    myDataTable.Columns.Add(myDataColumn)
 
    ' Make the ID column the primary key column.
    Dim PrimaryKeyColumns(0) As DataColumn
    PrimaryKeyColumns(0)= myDataTable.Columns("id")
    myDataTable.PrimaryKey = PrimaryKeyColumns
 
    ' Instantiate the DataSet variable.
    myDataSet = New DataSet()
    ' Add the new DataTable to the DataSet.
    myDataSet.Tables.Add(myDataTable)
 
    ' Create three new DataRow objects and add them to the DataTable
    Dim i As Integer
    For i = 0 to 2
       myDataRow = myDataTable.NewRow()
       myDataRow("id") = i
       myDataRow("ParentItem") = "ParentItem " + i.ToString()
       myDataTable.Rows.Add(myDataRow)
    Next i
 End Sub
 
 Private Sub MakeChildTable()
    ' Create a new DataTable.
    Dim myDataTable As DataTable = New DataTable("childTable")
    Dim myDataColumn As DataColumn 
    Dim myDataRow As DataRow 
 
    ' Create first column and add to the DataTable.
    myDataColumn = New DataColumn()
    myDataColumn.DataType= System.Type.GetType("System.Int32")
    myDataColumn.ColumnName = "ChildID"
    myDataColumn.AutoIncrement = True
    myDataColumn.Caption = "ID"
    myDataColumn.ReadOnly = True
    myDataColumn.Unique = True
    ' Add the column to the DataColumnCollection.
    myDataTable.Columns.Add(myDataColumn)
 
    ' Create second column.
    myDataColumn = New DataColumn()
    myDataColumn.DataType= System.Type.GetType("System.String")
    myDataColumn.ColumnName = "ChildItem"
    myDataColumn.AutoIncrement = False
    myDataColumn.Caption = "ChildItem"
    myDataColumn.ReadOnly = False
    myDataColumn.Unique = False
    myDataTable.Columns.Add(myDataColumn)
 
    ' Create third column.
    myDataColumn = New DataColumn()
    myDataColumn.DataType= System.Type.GetType("System.Int32")
    myDataColumn.ColumnName = "ParentID"
    myDataColumn.AutoIncrement = False
    myDataColumn.Caption = "ParentID"
    myDataColumn.ReadOnly = False
    myDataColumn.Unique = False
    myDataTable.Columns.Add(myDataColumn)
 
    myDataSet.Tables.Add(myDataTable)
    ' Create three sets of DataRow objects, five rows each, and add to DataTable.
    Dim i As Integer
    For i = 0 to 4
       myDataRow = myDataTable.NewRow()
       myDataRow("childID") = i
       myDataRow("ChildItem") = "Item " + i.ToString()
       myDataRow("ParentID") = 0 
       myDataTable.Rows.Add(myDataRow)
    Next i
    For i = 0 to 4
       myDataRow = myDataTable.NewRow()
       myDataRow("childID") = i + 5
       myDataRow("ChildItem") = "Item " + i.ToString()
       myDataRow("ParentID") = 1 
       myDataTable.Rows.Add(myDataRow)
    Next i
    For i = 0 to 4
       myDataRow = myDataTable.NewRow()
       myDataRow("childID") = i + 10
       myDataRow("ChildItem") = "Item " + i.ToString()
       myDataRow("ParentID") = 2 
       myDataTable.Rows.Add(myDataRow)
    Next i
 End Sub
 
 Private Sub MakeDataRelation()
    ' DataRelation requires two DataColumn (parent and child) and a name.
    Dim myDataRelation As DataRelation 
    Dim parentColumn As DataColumn 
    Dim childColumn As DataColumn 
    parentColumn = myDataSet.Tables("ParentTable").Columns("id")
    childColumn = myDataSet.Tables("ChildTable").Columns("ParentID")
    myDataRelation = new DataRelation("parent2Child", parentColumn, childColumn)
    myDataSet.Tables("ChildTable").ParentRelations.Add(myDataRelation)
 End Sub
 
 Private Sub BindToDataGrid()
    ' Instruct the DataGrid to bind to the DataSet, with the 
    ' ParentTable as the topmost DataTable.
    DataGrid1.SetDataBinding(myDataSet,"ParentTable")
 End Sub
 

[C#] 
// Put the next line into the Declarations section.
 private System.Data.DataSet myDataSet;
 
 private void MakeDataTables(){
    // Run all of the functions. 
    MakeParentTable();
    MakeChildTable();
    MakeDataRelation();
    BindToDataGrid();
 }
 
 private void MakeParentTable(){
    // Create a new DataTable.
    System.Data.DataTable myDataTable = new DataTable("ParentTable");
    // Declare variables for DataColumn and DataRow objects.
    DataColumn myDataColumn;
    DataRow myDataRow;
 
    // Create new DataColumn, set DataType, ColumnName and add to DataTable.    
    myDataColumn = new DataColumn();
    myDataColumn.DataType = System.Type.GetType("System.Int32");
    myDataColumn.ColumnName = "id";
    myDataColumn.ReadOnly = true;
    myDataColumn.Unique = true;
    // Add the Column to the DataColumnCollection.
    myDataTable.Columns.Add(myDataColumn);
 
    // Create second column.
    myDataColumn = new DataColumn();
    myDataColumn.DataType = System.Type.GetType("System.String");
    myDataColumn.ColumnName = "ParentItem";
    myDataColumn.AutoIncrement = false;
    myDataColumn.Caption = "ParentItem";
    myDataColumn.ReadOnly = false;
    myDataColumn.Unique = false;
    // Add the column to the table.
    myDataTable.Columns.Add(myDataColumn);
 
    // Make the ID column the primary key column.
    DataColumn[] PrimaryKeyColumns = new DataColumn[1];
    PrimaryKeyColumns[0] = myDataTable.Columns["id"];
    myDataTable.PrimaryKey = PrimaryKeyColumns;
 
    // Instantiate the DataSet variable.
    myDataSet = new DataSet();
    // Add the new DataTable to the DataSet.
    myDataSet.Tables.Add(myDataTable);
 
    // Create three new DataRow objects and add them to the DataTable
    for (int i = 0; i<= 2; i++){
       myDataRow = myDataTable.NewRow();
       myDataRow["id"] = i;
       myDataRow["ParentItem"] = "ParentItem " + i;
       myDataTable.Rows.Add(myDataRow);
    }
 }
 
 private void MakeChildTable(){
    // Create a new DataTable.
    DataTable myDataTable = new DataTable("childTable");
    DataColumn myDataColumn;
    DataRow myDataRow;
 
    // Create first column and add to the DataTable.
    myDataColumn = new DataColumn();
    myDataColumn.DataType= System.Type.GetType("System.Int32");
    myDataColumn.ColumnName = "ChildID";
    myDataColumn.AutoIncrement = true;
    myDataColumn.Caption = "ID";
    myDataColumn.ReadOnly = true;
    myDataColumn.Unique = true;
    // Add the column to the DataColumnCollection.
    myDataTable.Columns.Add(myDataColumn);
 
    // Create second column.
    myDataColumn = new DataColumn();
    myDataColumn.DataType= System.Type.GetType("System.String");
    myDataColumn.ColumnName = "ChildItem";
    myDataColumn.AutoIncrement = false;
    myDataColumn.Caption = "ChildItem";
    myDataColumn.ReadOnly = false;
    myDataColumn.Unique = false;
    myDataTable.Columns.Add(myDataColumn);
 
    // Create third column.
    myDataColumn = new DataColumn();
    myDataColumn.DataType= System.Type.GetType("System.Int32");
    myDataColumn.ColumnName = "ParentID";
    myDataColumn.AutoIncrement = false;
    myDataColumn.Caption = "ParentID";
    myDataColumn.ReadOnly = false;
    myDataColumn.Unique = false;
    myDataTable.Columns.Add(myDataColumn);
 
    myDataSet.Tables.Add(myDataTable);
    // Create three sets of DataRow objects, five rows each, and add to DataTable.
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable.NewRow();
       myDataRow["childID"] = i;
       myDataRow["ChildItem"] = "Item " + i;
       myDataRow["ParentID"] = 0 ;
       myDataTable.Rows.Add(myDataRow);
    }
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable.NewRow();
       myDataRow["childID"] = i + 5;
       myDataRow["ChildItem"] = "Item " + i;
       myDataRow["ParentID"] = 1 ;
       myDataTable.Rows.Add(myDataRow);
    }
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable.NewRow();
       myDataRow["childID"] = i + 10;
       myDataRow["ChildItem"] = "Item " + i;
       myDataRow["ParentID"] = 2 ;
       myDataTable.Rows.Add(myDataRow);
    }
 }
 
 private void MakeDataRelation(){
    // DataRelation requires two DataColumn (parent and child) and a name.
    DataRelation myDataRelation;
    DataColumn parentColumn;
    DataColumn childColumn;
    parentColumn = myDataSet.Tables["ParentTable"].Columns["id"];
    childColumn = myDataSet.Tables["ChildTable"].Columns["ParentID"];
    myDataRelation = new DataRelation("parent2Child", parentColumn, childColumn);
    myDataSet.Tables["ChildTable"].ParentRelations.Add(myDataRelation);
 }
 
 private void BindToDataGrid(){
    // Instruct the DataGrid to bind to the DataSet, with the 
    // ParentTable as the topmost DataTable.
    dataGrid1.SetDataBinding(myDataSet,"ParentTable");
 }

[C++] 
// Put the next line into the Declarations section.
private:
 System::Data::DataSet* myDataSet;
 
 void MakeDataTables(){
    // Run all of the functions. 
    MakeParentTable();
    MakeChildTable();
    MakeDataRelation();
    BindToDataGrid();
 }
 
 void MakeParentTable(){
    // Create a new DataTable.
    System::Data::DataTable* myDataTable = new DataTable(S"ParentTable");
    // Declare variables for DataColumn and DataRow objects.
    DataColumn* myDataColumn;
    DataRow* myDataRow;
 
    // Create new DataColumn, set DataType, ColumnName and add to DataTable.    
    myDataColumn = new DataColumn();
    myDataColumn->DataType = System::Type::GetType(S"System.Int32");
    myDataColumn->ColumnName = S"id";
    myDataColumn->ReadOnly = true;
    myDataColumn->Unique = true;
    // Add the Column to the DataColumnCollection.
    myDataTable->Columns->Add(myDataColumn);
 
    // Create second column.
    myDataColumn = new DataColumn();
    myDataColumn->DataType = System::Type::GetType(S"System.String");
    myDataColumn->ColumnName = S"ParentItem";
    myDataColumn->AutoIncrement = false;
    myDataColumn->Caption = S"ParentItem";
    myDataColumn->ReadOnly = false;
    myDataColumn->Unique = false;
    // Add the column to the table.
    myDataTable->Columns->Add(myDataColumn);
 
    // Make the ID column the primary key column.
    DataColumn* PrimaryKeyColumns[] = new DataColumn*[1];
    PrimaryKeyColumns->Item[0] = myDataTable->Columns->Item[S"id"];
    myDataTable->PrimaryKey = PrimaryKeyColumns;
 
    // Instantiate the DataSet variable.
    myDataSet = new DataSet();
    // Add the new DataTable to the DataSet.
    myDataSet->Tables->Add(myDataTable);
 
    // Create three new DataRow objects and add them to the DataTable
    for (int i = 0; i<= 2; i++){
       myDataRow = myDataTable->NewRow();
       myDataRow->Item[S"id"] = __box(i);
       myDataRow->Item[S"ParentItem"] = String::Format( S"ParentItem {0}", __box(i));
       myDataTable->Rows->Add(myDataRow);
    }
 }
 
 void MakeChildTable(){
    // Create a new DataTable.
    DataTable* myDataTable = new DataTable(S"childTable");
    DataColumn* myDataColumn;
    DataRow* myDataRow;
 
    // Create first column and add to the DataTable.
    myDataColumn = new DataColumn();
    myDataColumn->DataType= System::Type::GetType(S"System.Int32");
    myDataColumn->ColumnName = S"ChildID";
    myDataColumn->AutoIncrement = true;
    myDataColumn->Caption = S"ID";
    myDataColumn->ReadOnly = true;
    myDataColumn->Unique = true;
    // Add the column to the DataColumnCollection.
    myDataTable->Columns->Add(myDataColumn);
 
    // Create second column.
    myDataColumn = new DataColumn();
    myDataColumn->DataType= System::Type::GetType(S"System.String");
    myDataColumn->ColumnName = S"ChildItem";
    myDataColumn->AutoIncrement = false;
    myDataColumn->Caption = S"ChildItem";
    myDataColumn->ReadOnly = false;
    myDataColumn->Unique = false;
    myDataTable->Columns->Add(myDataColumn);
 
    // Create third column.
    myDataColumn = new DataColumn();
    myDataColumn->DataType= System::Type::GetType(S"System.Int32");
    myDataColumn->ColumnName = S"ParentID";
    myDataColumn->AutoIncrement = false;
    myDataColumn->Caption = S"ParentID";
    myDataColumn->ReadOnly = false;
    myDataColumn->Unique = false;
    myDataTable->Columns->Add(myDataColumn);
 
    myDataSet->Tables->Add(myDataTable);
    // Create three sets of DataRow objects, five rows each, and add to DataTable.
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable->NewRow();
       myDataRow->Item[S"childID"] = __box(i);
       myDataRow->Item[S"ChildItem"] = String::Format( S"Item {0}", __box(i));
       myDataRow->Item[S"ParentID"] = __box(0);
       myDataTable->Rows->Add(myDataRow);
    }
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable->NewRow();
       myDataRow->Item[S"childID"] = __box(i + 5);
       myDataRow->Item[S"ChildItem"] = String::Format( S"Item {0}", __box(i));
       myDataRow->Item[S"ParentID"] = __box(1);
       myDataTable->Rows->Add(myDataRow);
    }
    for(int i = 0; i <= 4; i ++){
       myDataRow = myDataTable->NewRow();
       myDataRow->Item[S"childID"] = __box(i + 10);
       myDataRow->Item[S"ChildItem"] = String::Format( S"Item {0}", __box(i));
       myDataRow->Item[S"ParentID"] = __box(2);
       myDataTable->Rows->Add(myDataRow);
    }
 }
 
 void MakeDataRelation(){
    // DataRelation requires two DataColumn (parent and child) and a name.
    DataRelation* myDataRelation;
    DataColumn* parentColumn;
    DataColumn* childColumn;
    parentColumn = myDataSet->Tables->Item[S"ParentTable"]->Columns->Item[S"id"];
    childColumn = myDataSet->Tables->Item[S"ChildTable"]->Columns->Item[S"ParentID"];
    myDataRelation = new DataRelation(S"parent2Child", parentColumn, childColumn);
    myDataSet->Tables->Item[S"ChildTable"]->ParentRelations->Add(myDataRelation);
 }
 
 void BindToDataGrid(){
    // Instruct the DataGrid to bind to the DataSet, with the 
    // ParentTable as the topmost DataTable.
    dataGrid1->SetDataBinding(myDataSet,S"ParentTable");
 }

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Data

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

Assembly: System.Data (in System.Data.dll)

See Also

DataTable Members | System.Data Namespace | DataColumnCollection | DataColumn | DataRow | DataSet | DataView | DataRowCollection

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.