29.3 Collections Reference

TableMappings

DataTableMappingCollection dtmc = DataAdapter.TableMappings;

Accesses a collection of DataTableMapping objects that map the data source table names to DataSet table names. This allows different table names to be used during change reconciliation. An empty collection is returned if no mappings exist.

Example

The following example shows how to set up a TableMapping and a ColumnMapping:

SqlDataAdapter da;

// ... code to set up the data adapter

// map the DataSet table MyOrders to the data source table Orders
DataTableMapping dtm = da.TableMappings.Add("Orders", "MyOrders");

// map the DataSet column MyOrderID (in the DataSet MyOrders table)
// to the data source column OrderID (in the data source Orders table)
dtm.ColumnMappings.Add("MyOrderID", "OrderID");

The DataTableMappingCollection and DataColumnMappingCollection collections have an AddRange( ) method that allows an array of mappings to be added in a single statement, as shown in the following example:

// map the CustomerID and EmployeeID columns from the data source
dtm.ColumnMappings.AddRange(new DataColumnMapping[] {
    new DataColumnMapping("MyCustomerID", "CustomerID"),
    new DataColumnMapping("MyEmployeeID", "EmployeeID")});

Mappings can be removed from both the DataTableMappingCollection and DataColumnMappingCollection objects using the Remove( ), RemoveAt( ), or Clear( ) methods. The following example demonstrates using these methods with the DataTableMappingCollection; using the methods with the DataColumnMappingCollection is similar.

SqlDataAdapter da;

// ... code to set up the DataAdapter da

// map the DataSet table MyOrders to the data source table Orders
DataTableMapping dtm = da.TableMappings.Add("Orders", "MyOrders");

// The next three commands remove the mapping just added

// remove the table mapping just added, using a reference to the
// DataTableMapping object
da.TableMappings.Remove(dtm);

// use RemoveAt to remove the DataTableMapping s
da.TableMappings.RemoveAt(0);

// use RemoveAt with the data source table name
da.TableMappings.RemoveAt("Orders");

// use Clear method to remove all mappings
da.TableMappings.Clear();

Notes

A mapping is created by adding a DataTableMapping object to the DataTableMappingCollection collection. This maps a table in the data source to a table with different name in the DataSet.

Each DataTableMapping object contains a DataColumnMappingCollection object that is accessed through its ColumnMappings property. The collection controls how columns in the data source are mapped to DataColumn objects in the DataTable. The column mapping applies only for the table mapped by the DataTableMapping. A column mapping is created by adding a DataColumnMapping object to the DataColumnMappingCollection collection. This maps a column in the data source to a column with a different name in the DataSet.

Both table and column mappings can be used by the Fill( ) and FillSchema( ) methods when retrieving data, and by the Update( ) method when submitting DataSet changes back to the data source. The Fill( ) method always uses mapping information if it's available; the FillSchema( ) method lets you choose whether to use the mapping information.

If incoming data source table and column names don't match DataSet object names, and mapping isn't performed, the MissingMappingAction property of the DataAdapter determines what action is taken when data is retrieved using the Fill( ) method. Similarly, if incoming data source table and column names don't match DataSet object names, and mapping isn't performed, the MissingSchemaAction property of the data adapter determines what action is taken when the schema is retrieved using the FillSchema( ) or Fill( ) method.

DataTableMappingCollection

The commonly used public properties of the DataTableMappingCollection are listed and described in Table 29-8.

Table 29-8. DataTableMappingCollection public properties

Property

Description

Count

Gets the number of items in the DataTableMappingCollection.

Item

Gets the DataTableMapping for the specified index. If the value isn't found, null is returned. In C#, the Item property is the indexer of the class.

The commonly used public methods of the DataTableMappingCollection are listed and described in Table 29-9.

Table 29-9. DataTableMappingCollection public methods

Method

Description

Add(  )

Adds a DataTableMapping object to the collection.

AddRange(  )

Adds the objects in the array of DataTableMapping objects to the end of the collection.

Clear(  )

Removes all items from the collection.

Contains(  )

Returns a Boolean value indicating whether a DataTableMapping with the specified name exists in the collection.

CopyTo(  )

Copies the elements of the collection to the specified array.

GetByDataSetTable(  )

Returns the DataTableMapping object from the collection matching the specified DataSet table name.

GetTableMappingBy-SchemaAction(  )

Returns a reference to a DataColumnMapping object with the specified source and DataSet table names, and with the specified MissingMappingAction.

IndexOf(  )

Returns the index of the specified DataTableMapping. A value of -1 is returned if the DataTableMapping doesn't exist in the collection.

IndexOfDataSetTable(  )

Returns the index of the DataTableMapping object with the specified DataSet table name.

Insert(  )

Inserts a DataTableMapping object at the end of the collection.

Remove(  )

Removes the specified DataTableMapping from the collection. An ArgumentException is generated if the specified DataTableMapping doesn't exist in the collection.

RemoveAt(  )

Removes the DataTableMapping at the specified index from the collection. An ArgumentException is raised if the collection doesn't have a DataTableMapping at the specified index.

DataTableMapping class

The commonly used public properties of the DataTableMapping class are listed and described in Table 29-10.

Table 29-10. DataTableMapping public properties

Property

Description

ColumnMappings

Gets the DataColumnMappingCollection for the DataTable.

DataSetTable

Gets or sets the table name in the DataSet to map to.

SourceTable

Gets or sets the table name in the data source to map from.

The commonly used public methods of the DataTableMapping class are listed and described in Table 29-11.

Table 29-11. DataTableMapping public methods

Method

Description

GetColumnMappingBy-SchemaAction(  )

Returns a DataColumnMapping for the specified DataTable using the given MissingMappingAction and DataColumnName arguments.

GetDataTableBySchema-Action(  )

Returns a DataTable for the specified DataSet and MissingMappingAction arguments.

DataColumnMappingCollection

The DataColumnMappingCollection is returned by the ColumnMappings collection property of the TableMappings class. It maps the names of columns in the DataSet to columns in the data source with different names.

The commonly used public properties of the DataColumnMappingCollection are listed and described in Table 29-12.

Table 29-12. DataColumnMappingCollection public properties

Property

Description

Count

Gets the number of items in the DataColumnMappingCollection.

Item

Gets an object containing the value for the specified index. If the value isn't found, attempting to get it returns null. In C#, the Item property is the indexer of the class.

The commonly used public methods of the DataColumnMappingCollection are listed and described in Table 29-13.

Table 29-13. DataColumnMappingCollection public methods

Method

Description

Add(  )

Adds a DataColumnMapping object to the collection.

AddRange(  )

Adds the objects in the array of DataColumnMapping objects to the end of the collection.

Clear(  )

Removes all items from the collection.

Contains(  )

Returns a Boolean value indicating whether a DataColumnMapping with the specified name exists in the collection.

CopyTo(  )

Copies the elements of the collection to the specified array.

GetByDataSetColumn(  )

Returns the DataColumnMapping object from the collection matching the specified DataSet table name.

GetColumnMappingBy-SchemaAction(  )

Returns a DataColumnMapping for the specified DataColumnMappingCollection for the specified source column name and MissingMappingAction arguments.

IndexOf(  )

Returns the index of the specified DataColumnMapping. A value of -1 is returned if the DataColumnMapping doesn't exist in the collection.

IndexOfDataSetColumn(  )

Returns the zero-based index of the DataColumnMapping object with the specified DataSet table name.

Insert(  )

Inserts a DataColumnMapping object at the end of the collection.

Remove(  )

Removes the specified DataColumnMapping from the collection. An ArgumentException is generated if the specified DataColumnMapping doesn't exist in the collection.

RemoveAt(  )

Removes the DataColumnMapping at the specified index from the collection. An ArgumentException is raised if the collection doesn't have a DataColumnMapping at the specified index.

DataColumnMapping class

The commonly used public properties of the DataColumnMapping class are listed and described in Table 29-14.

Table 29-14. DataColumnMapping public properties

Property

Description

DataSetColumn

Gets or sets the name of the column in the DataSet to map to.

SourceColumn

Gets or sets the name of the column in the data source to map from.

The commonly used public methods of the DataColumnMapping class are listed and described in Table 29-15.

Table 29-15. DataColumnMapping public method

Method

Description

GetDataColumnBySchemaAction(  )

Returns a DataColumn from the given DataTable for the specified DataColumn data type and the MissingSchemaAction arguments.



    Part I: ADO.NET Tutorial
    Part II: ADO.NET Core Classes
    Part III: API Quick Reference