DataSet.Load Method

Fills a DataSet with values from a data source using the supplied IDataReader.

This member is overloaded. For complete information about this member, including syntax, usage, and examples, click a name in the overload list.

  Name Description
Public method Load(IDataReader, LoadOption, DataTable[]) Fills a DataSet with values from a data source using the supplied IDataReader, using an array of DataTable instances to supply the schema and namespace information.
Public method Load(IDataReader, LoadOption, String[]) Fills a DataSet with values from a data source using the supplied IDataReader, using an array of strings to supply the names for the tables within the DataSet.
Public method Load(IDataReader, LoadOption, FillErrorEventHandler, DataTable[]) Fills a DataSet with values from a data source using the supplied IDataReader, using an array of DataTable instances to supply the schema and namespace information.
Top

The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

If the DataSet already contains rows, the incoming data from the data source is merged with the existing rows.

The Load method can be used in several common scenarios, all centered around getting data from a specified data source and adding it to the current data container (in this case, a DataSet). These scenarios describe standard usage for a DataSet, describing its update and merge behavior.

A DataSet synchronizes or updates with a single primary data source. The DataSet tracks changes, allowing synchronization with the primary data source. In addition, a DataSet can accept incremental data from one or more secondary data sources. The DataSet isn't responsible for tracking changes in order to allow synchronization with the secondary data source.

Given these two hypothetical data sources, a user is likely to require one of the following behaviors:

  • Initialize DataSet from a primary data source. In this scenario, the user wants to initialize an empty DataSet with values from the primary data source. One or more DataTable's contents are modified. Later the user intends to propagate changes back to the primary data source.

  • Preserve changes and re-synchronize from the primary data source. In this scenario, the user wants to take the DataSet filled in the previous scenario and perform an incremental synchronization with the primary data source, preserving modifications made in the DataSet.

  • Incremental data feed from secondary data sources. In this scenario, the user wants to merge changes from one or more secondary data sources, and propagate those changes back to the primary data source.

The Load method makes all these scenarios possible. This method allows you to specify a load option parameter, indicating how rows already in a DataTable combine with rows being loaded. The following table describes the three load options provided by the LoadOption enumeration. In each case, the description indicates the behavior when the primary key of a row in the incoming data matches the primary key of an existing row.

Load Option

Description

PreserveChanges (default)

Updates the original version of the row with the value of the incoming row.

OverwriteChanges

Updates the current and original versions of the row with the value of the incoming row.

Upsert

Updates the current version of the row with the value of the incoming row.

In general, the PreserveChanges and OverwriteChanges options are intended for scenarios in which the user needs to synchronize the DataSet and its changes with the primary data source. The Upsert option facilitates aggregating changes from one or more secondary data sources.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft