Table Mapping in Data Adapters
When a data adapter reads data from a data source, it determines where to put the data in the corresponding dataset table (or tables) using a table mapping. The mapping links the names of columns in the source with those in the dataset table. For example, information from a column called au_id in the data source might belong in a column called author_id_number in the dataset table.
Note
In the previous version of Visual Studio, data adapters were used for communicating between an application and a database. While data adapters are still a main component of .NET Framework Data Providers (ADO.NET), TableAdapters are designer-generated components that simplify the process of moving data between your application and a database. For more information on working with TableAdapters, see TableAdapter Overview.
By default, when you use Visual Studio tools to generate a dataset from information in a data source, the dataset elements have the same names as they have in the source. However, there are times when the names in the data source and the data set will not match:
The dataset was created from an existing schema that uses different names.
You want to change data element names in the dataset for convenience, readability, translation to or from a foreign language, or another reason.
You want to control the names of typed data members when you generate a dataset from the adapter.
Table Mappings Structure
Table mappings are established using the adapter's TableMappings property, which is a collection of items of type DataTableMapping. There is one DataTableMapping object for each set of tables being mapped. Normally there is just one such item, because adapters are normally associated only with a single source table and a single dataset table. (However, a stored procedure can return multiple row sets; if so, the second and subsequent tables are mapped using the second and subsequent mappings in the TableMappings collection.)
Each mapping item in turn contains properties to identify the data-source table, the dataset table, and a ColumnMappings property containing items that represent the actual mappings.
Table Mapping in Action
When you call a data adapter's Fill method, the adapter goes through the following process to determine where in the dataset to write the data:
The adapter looks up each source column name in the TableMappings object.
When it finds the source column name, it gets the matching (mapped) name for the corresponding column in the dataset table.
Using the name it got from Step 2, the adapter writes the data from the source column to the corresponding dataset column.
There are a variety of conditions that can prevent the adapter from following the process outlined above. The two primary ones are:
No mapping can be found for a source column. This might be because there is nothing defined for the TableMappings property, or because a specific column is not mapped.
The column to be written is not defined in the dataset's schema, whether or not it is mapped in the TableMappings property.
The adapter supports two properties that allow you specify what should happen when either of these situations occurs. The situations are not necessarily error conditions, because the adapter can still fill the dataset even if either situation occurs.
The MissingMappingAction property allows you to specify what action the adapter should take if the mapping is missing. Possible settings are:
Passthrough - the adapter attempts to load the column into a dataset column of the same name. If there is no dataset column of that name, the behavior depends on the MissingSchemaAction enumeration setting (see below).
Ignore - columns that are not mapped properly are not loaded into the dataset.
Error - raises an error.
The MissingSchemaAction property allows you to specify what should happen when the adapter tries to write data to a column that is not defined in the dataset's schema. Possible values are:
Add - the table or column is added to the schema and to the dataset.
AddWithKey - the table or column is added to the dataset and schema along with information about the primary key.
Ignore - the table or column not represented in the dataset schema is not added to the dataset.
Error - the adapter raises an error.
You generally set both properties in conjunction to accommodate your application's specific needs. Setting the MissingMappingAction property to Passthrough and the MissingSchemaAction property to Add has the effect of automatically duplicating the table and column names from the source in the dataset.
Conversely, you might specify error checking in applications where the dataset schema is strictly defined. In such a case, getting data from a source without a clearly defined target column in the dataset might constitute violation of a business rule or other error.
You specify Ignore when you want to ensure that the only data loaded into the dataset is that which you have explicitly defined in the schema or mapped in the TableMappings property. This is useful if the adapter calls a stored procedure or SQL statement that returns more columns than you need in the dataset.
See Also
Tasks
How to: Map Data-Source Columns to Dataset Data-Table Columns
Concepts
Populating a DataSet from a DataAdapter (ADO.NET)
Creating Data Applications by Using Visual Studio