NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

DataSet Class

Represents an in-memory cache of data.

Object
   Component
      DataSet

[Visual Basic]
Public Class DataSet
   Inherits Component
   Implements IListSource
[C#]
public class DataSet : Component, IListSource
[C++]
public __gc class DataSet : public Component, IListSource
[JScript]
public class DataSet extends Component, IListSource

Remarks

The DataSet is a major component of the ADO+ architecture. It can be helpful to consider it an in-memory cache of data retrieved from a database. The DataSet consists of a collection of tables, relationships, and constraints. DataTable objects can be related to each other through DataRelation objects. UniqueConstraint and ForeignKeyConstraint objects ensure data integrity by enforcing data-specific rules.

In a stereotypical implementation, the steps would proceed in this manner:

  1. Build and fill each table in a DataSet with data from a DBMS using a SQLDataSetCommand or ADODataSetCommand.
  2. Change the data in individual DataTable objects by adding, updating, or deleting DataRow objects.
  3. Invoke the GetChanges method to create a second DataSet that features only the changes to the data.
  4. Check for errors in the second DataSet by examining its HasErrors property which informs you if any table in the set has errors.
  5. If errors are present, check the HasErrors property of each DataTable. If the table has errors, invoke the DataTable class's GetErrors method to return an array of DataRow objects with errors.
  6. On each DataRow examine the RowError property for specific data.
  7. Reconcile the errors, if possible.
  8. Invoke the Merge method to merge the changes from the second DataSet into the first.
  9. Call the System.Data.DBDataSetCommand.Update method of the System.Data.SQLDataSetCommand (or System.Data.ADODataSetCommand), passing the merged DataSet as an argument.
  10. Invoke the AcceptChanges on the DataSet. Alternatively, invoke RejectChanges to cancel the changes.

While DataTable objects contain the actual data, the RelationsCollection allows you to navigate though the table hierarchy. The tables are contained in a TablesCollection accessed through the Tables property.

A DataSet persists and depersists data as XML documents. Because of this, the data can be transported across HTTP and used by any application, on any platform, that is XML-enabled.

In an application where more than one view of a DataSet is needed, create a DataSetView with customized TableSetting objects. To customize the view of the current DataSet, add TableSetting objects to the DataSetView returned by the DefaultView property.

If you use the Visual Studio Class Designer, classes are automatically created that derive from DataSet, DataTable, and DataRow. With such a set of derived classes, the methods and properties are retained, but custom methods are generated to help you easily navigate through the tables of the DataSet.

For example, the generic Visual Basic code below:

' Get the DataTable named Customers.
Dim myTable As DataTable
myTable = DataSet1.Tables("Customers")

becomes

' A class named Customers, derived from DataTable.
Dim CustTable As Customers
CustTable = DataSet1.Customers

Methods are also created for adding new rows. For example, to add a row with a generic DataSet:

Dim myNewRow As DataRow
myNewRow = DataSet1.Tables("Customers").NewRow
myNewRow("fName") = "John"
myNewRow("lName")= "Smith"
DataSet1.Tables("Customers").Rows.Add(myNewRow)

With a derived class:

DataSet1.Customers.AddCustomerRow("John", "Smith")

The a FindRow method is also created. In a generic DataSet, this code:

Dim foundRow As DataRow
foundRow = DataSet1.Tables("Customers").FindRows("Name","Bob")

becomes

Dim foundRow As DataRow
foundRow = DataSet1.Customers.FindByName("Bob")

Requirements

Namespace: System.Data

Assembly: System.Data.dll

Example [Visual Basic]

The following example consists of several methods that work together to create and fill a DataSet from the Northwind database installed as a sample database with SQLServer 7.

[Visual Basic]

Private Sub GetSupplierProducts()
   ' 1 Create the connection using a function named CreateConnection.
   Dim cn As SQL.SQLConnection = CreateConnection _
   ("Provider=SQLOLEDB.1;Persist Security Info = False;" & _
   "Initial Catalog = Northwind;Data Source = corp;User ID = sa;")
   ' NOTE: you can also use an ADO.ADOConnection to create a connection.
    
    ' 2 Create a DataSet.
   Dim myDS As New DataSet
   myDS.DataSetName = "SuppliersProducts"

   ' 3 Create a SQL Command. Set ActiveConnection and CommandText.
   Dim CmdText As String
   SQLCommand = "SELECT * FROM Suppliers"
   Dim SQLcmd As SQL.SQLCommand = CreateCommand(cn, SQLCommand)

   ' 4 Create and configure SQLDataSetCommand.
   Dim SQLdsCmd As SQL.SQLDataSetCommand = New SQL.SQLDataSetCommand
   SQLdsCmd.SelectCommand = SQLcmd
   ' Add a DataTableMapping to ADODataSetCommand.
   SQLdsCmd.TableMappings.Add "Table", "Suppliers"
   ' Invoke FillDataSet
   dscmd.FillDataSet myDS

   ' Get second table.
   Dim c2 As ADO.ADOCommand = New ADO.ADOCommand
   Dim dsCmd2 As ADO.ADODataSetCommand = New ADO.ADODataSetCommand
   ' Use the same connection.
   c2.ActiveConnection = cn
   c2.CommandText = "SELECT * FROM Products"
   dscmd2.SelectCommand = c2

   dscmd2.TableMappings.Add("Table", "Products")
   dscmd2.FillDataSet myDS

   ' Create a relation
   Dim r As DataRelation
   r = New DataRelation("suppliers2products", myDS.Tables("Suppliers").Columns("SupplierID"), myDS.Tables("Products").Columns("SupplierID"))
   myDS.Relations.Add(r)

   ' Create DataView
   Dim dv As DataView
   dv = New DataView(myds.Tables(0))
   Dim t As DataTable
   t = dv.Table

   dv.Begin
  ' Bind DataGrid to DataSource and invoke PopulateColumns.
   DataGrid1.DataSource = dv
   DataGrid1.Text = "Suppliers And Products"
   DataGrid1.PopulateColumns
End Sub

Private Function CreateConnection(cnStg) As SQL.SQLConnection
   ' 1 Create the connection.
   Dim connString As String
   connString = cnStg 
   Dim cn As SQL.SQLConnection = New SQL.SQLConnection(connString)
   cn.Open ' Open the connection.
   CreateConnection = cn
End Function

Private Function CreateCommand(cn As SQL.SQLConnection, selString As String) As SQL.SQLCommand
    Dim c As SQL.SQLCommand = New SQL.SQLCommand
    c.ActiveConnection = cn
    c.CommandText = selString
    CreateCommand = c
End Function

See Also

DataSet Members | System.Data Namespace | ADODataSetCommand | DataTable | DataRelation | DataRow | DataSetView | DataView | SQLDataSetCommand | ForeignKeyConstraint | UniqueConstraint