DataSet.Load Método

Definição

Preenche um DataSet com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataSet with values from a data source using the supplied IDataReader.

Sobrecargas

Load(IDataReader, LoadOption, DataTable[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader fornecido, usando uma matriz de instâncias DataTable para fornecer o esquema e as informações de namespace.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.

Load(IDataReader, LoadOption, String[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader, usando uma matriz de cadeias de caracteres para fornecer os nomes das tabelas dentro de DataSet.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.

Load(IDataReader, LoadOption, FillErrorEventHandler, DataTable[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader fornecido, usando uma matriz de instâncias DataTable para fornecer o esquema e as informações de namespace.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.

Comentários

O método Load fornece uma técnica para preencher um único DataTable com dados, recuperado a partir de uma instância IDataReader.The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. Esse método fornece a mesma funcionalidade, mas permite que você carregue vários conjuntos de resultados de um IDataReader em várias tabelas dentro de um DataSet .This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

Se o DataSet já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes.If the DataSet already contains rows, the incoming data from the data source is merged with the existing rows.

O Load método pode ser usado em vários cenários comuns, tudo centrado em relação à obtenção de dados de uma fonte de dados especificada e à adição dele ao contêiner de dados atual (nesse caso, a DataSet ).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). Esses cenários descrevem o uso padrão para um DataSet , descrevendo seu comportamento de atualização e mesclagem.These scenarios describe standard usage for a DataSet, describing its update and merge behavior.

Um DataSet sincroniza ou atualiza com uma única fonte de dados primária.A DataSet synchronizes or updates with a single primary data source. O DataSet controla as alterações, permitindo a sincronização com a fonte de dados primária.The DataSet tracks changes, allowing synchronization with the primary data source. Além disso, um DataSet pode aceitar dados incrementais de uma ou mais fontes de dados secundárias.In addition, a DataSet can accept incremental data from one or more secondary data sources. O DataSet não é responsável por controlar as alterações a fim de permitir a sincronização com a fonte de dados secundária.The DataSet isn't responsible for tracking changes in order to allow synchronization with the secondary data source.

Dadas essas duas fontes de dados hipotéticas, um usuário deve exigir um dos seguintes comportamentos:Given these two hypothetical data sources, a user is likely to require one of the following behaviors:

  • Inicializar DataSet a partir de uma fonte de dados primária.Initialize DataSet from a primary data source. Nesse cenário, o usuário deseja inicializar um vazio DataSet com valores da fonte de dados primária.In this scenario, the user wants to initialize an empty DataSet with values from the primary data source. Um ou mais conteúdos de DataTable são modificados.One or more DataTable's contents are modified. Posteriormente, o usuário deseja propagar alterações de volta para a fonte de dados primária.Later the user intends to propagate changes back to the primary data source.

  • Preservar alterações e ressincronizar a partir da fonte de dados primária.Preserve changes and re-synchronize from the primary data source. Nesse cenário, o usuário deseja assumir o preenchimento do DataSet cenário anterior e executar uma sincronização incremental com a fonte de dados primária, preservando as modificações feitas no DataSet .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.

  • Feed de dados incremental das fontes de dados secundárias.Incremental data feed from secondary data sources. Nesse cenário, o usuário deseja mesclar alterações de uma ou mais fontes de dados secundárias e propaga essas alterações de volta para a fonte de dados primária.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.

O Load método torna todos esses cenários possíveis.The Load method makes all these scenarios possible. Esse método permite que você especifique um parâmetro de opção de carregamento, indicando como as linhas já estão em uma DataTable combinação com linhas sendo carregadas.This method allows you to specify a load option parameter, indicating how rows already in a DataTable combine with rows being loaded. A tabela a seguir descreve as três opções de carregamento fornecidas pela enumeração LoadOption.The following table describes the three load options provided by the LoadOption enumeration. Em cada caso, a descrição indica o comportamento quando a chave primária de uma linha nos dados de entrada corresponde à chave primária de uma linha existente.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.

Carregar OpçãoLoad Option DescriçãoDescription
PreserveChanges (padrão)PreserveChanges (default) Atualiza a versão original da linha com o valor da linha de entrada.Updates the original version of the row with the value of the incoming row.
OverwriteChanges Atualiza as versões atual e original da linha com o valor da linha de entrada.Updates the current and original versions of the row with the value of the incoming row.
Upsert Atualiza a versão atual da linha com o valor da linha de entrada.Updates the current version of the row with the value of the incoming row.

Em geral, as opções PreserveChanges e OverwriteChanges se destinam a cenários nos quais o usuário precisa sincronizar o DataSet e suas alterações com a fonte de dados primária.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. A opção Upsert facilita a agregação de alterações de uma ou mais fontes de dados secundárias.The Upsert option facilitates aggregating changes from one or more secondary data sources.

Load(IDataReader, LoadOption, DataTable[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader fornecido, usando uma matriz de instâncias DataTable para fornecer o esquema e as informações de namespace.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:
 void Load(System::Data::IDataReader ^ reader, System::Data::LoadOption loadOption, ... cli::array <System::Data::DataTable ^> ^ tables);
public void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption, params System.Data.DataTable[] tables);
member this.Load : System.Data.IDataReader * System.Data.LoadOption * System.Data.DataTable[] -> unit
Public Sub Load (reader As IDataReader, loadOption As LoadOption, ParamArray tables As DataTable())

Parâmetros

reader
IDataReader

Um IDataReader que fornece um ou vários conjuntos de resultados.An IDataReader that provides one or more result sets.

loadOption
LoadOption

Um valor da enumeração LoadOption que indica como as linhas que já estão nas instâncias DataTable em DataSet serão combinadas com linhas de entrada que compartilham a mesma chave primária.A value from the LoadOption enumeration that indicates how rows already in the DataTable instances within the DataSet will be combined with incoming rows that share the same primary key.

tables
DataTable[]

Uma matriz de instâncias DataTable, da qual o método Load(IDataReader, LoadOption, DataTable[]) recupera informações de nome e namespace.An array of DataTable instances, from which the Load(IDataReader, LoadOption, DataTable[]) method retrieves name and namespace information. Cada uma dessas tabelas deve ser um membro do DataTableCollection contido por este DataSet.Each of these tables must be a member of the DataTableCollection contained by this DataSet.

Exemplos

O exemplo a seguir cria um novo DataSet , adiciona duas DataTable instâncias ao DataSet e, em seguida, preenche o DataSet usando o Load método, recuperando dados de um DataTableReader que contém dois conjuntos de resultados.The following example creates a new DataSet, adds two DataTable instances to the DataSet, and then fills the DataSet using the Load method, retrieving data from a DataTableReader that contains two result sets. Por fim, o exemplo exibe o conteúdo das tabelas na janela do console.Finally, the example displays the contents of the tables in the console window.

static void Main()
{
    DataSet dataSet = new DataSet();

    DataTable customerTable = new DataTable();
    DataTable productTable = new DataTable();

    // This information is cosmetic, only.
    customerTable.TableName = "Customers";
    productTable.TableName = "Products";

    // Add the tables to the DataSet:
    dataSet.Tables.Add(customerTable);
    dataSet.Tables.Add(productTable);

    // Load the data into the existing DataSet.
    DataTableReader reader = GetReader();
    dataSet.Load(reader, LoadOption.OverwriteChanges,
        customerTable, productTable);

    // Print out the contents of each table:
    foreach (DataTable table in dataSet.Tables)
    {
        PrintColumns(table);
    }

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
}

private static DataTable GetCustomers()
{
    // Create sample Customers table.
    DataTable table = new DataTable();
    table.TableName = "Customers";

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID", typeof(int));
    table.Columns.Add("Name", typeof(string));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { 0, "Mary" });
    table.Rows.Add(new object[] { 1, "Andy" });
    table.Rows.Add(new object[] { 2, "Peter" });
    table.AcceptChanges();
    return table;
}

private static DataTable GetProducts()
{
    // Create sample Products table.
    DataTable table = new DataTable();
    table.TableName = "Products";

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID",
        typeof(int));
    table.Columns.Add("Name", typeof(string));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { 0, "Wireless Network Card" });
    table.Rows.Add(new object[] { 1, "Hard Drive" });
    table.Rows.Add(new object[] { 2, "Monitor" });
    table.Rows.Add(new object[] { 3, "CPU" });
    table.AcceptChanges();
    return table;
}

private static void PrintColumns(DataTable table)
{
    Console.WriteLine();
    Console.WriteLine(table.TableName);
    Console.WriteLine("=========================");
    // Loop through all the rows in the table:
    foreach (DataRow row in table.Rows)
    {
        for (int i = 0; i < table.Columns.Count; i++)
        {
            Console.Write(row[i] + " ");
        }
        Console.WriteLine();
    }
}

private static DataTableReader GetReader()
{
    // Return a DataTableReader containing multiple
    // result sets, just for the sake of this demo.
    DataSet dataSet = new DataSet();
    dataSet.Tables.Add(GetCustomers());
    dataSet.Tables.Add(GetProducts());
    return dataSet.CreateDataReader();
}
Sub Main()
    Dim dataSet As New DataSet

    Dim customerTable As New DataTable
    Dim productTable As New DataTable

    ' This information is cosmetic, only.
    customerTable.TableName = "Customers"
    productTable.TableName = "Products"

    ' Add the tables to the DataSet:
    dataSet.Tables.Add(customerTable)
    dataSet.Tables.Add(productTable)

    ' Load the data into the existing DataSet. 
    Dim reader As DataTableReader = GetReader()
    dataSet.Load(reader, LoadOption.OverwriteChanges, _
        customerTable, productTable)

    ' Print out the contents of each table:
    For Each table As DataTable In dataSet.Tables
        PrintColumns(table)
    Next

    Console.WriteLine("Press any key to continue.")
    Console.ReadKey()
End Sub

Private Function GetCustomers() As DataTable
    ' Create sample Customers table.
    Dim table As New DataTable
    table.TableName = "Customers"

    ' Create two columns, ID and Name.
    Dim idColumn As DataColumn = table.Columns.Add("ID", _
        GetType(Integer))
    table.Columns.Add("Name", GetType(String))

    ' Set the ID column as the primary key column.
    table.PrimaryKey = New DataColumn() {idColumn}

    table.Rows.Add(New Object() {0, "Mary"})
    table.Rows.Add(New Object() {1, "Andy"})
    table.Rows.Add(New Object() {2, "Peter"})
    table.AcceptChanges()
    Return table
End Function

Private Function GetProducts() As DataTable
    ' Create sample Products table, in order
    ' to demonstrate the behavior of the DataTableReader.
    Dim table As New DataTable
    table.TableName = "Products"

    ' Create two columns, ID and Name.
    Dim idColumn As DataColumn = table.Columns.Add("ID", _
        GetType(Integer))
    table.Columns.Add("Name", GetType(String))

    ' Set the ID column as the primary key column.
    table.PrimaryKey = New DataColumn() {idColumn}

    table.Rows.Add(New Object() {0, "Wireless Network Card"})
    table.Rows.Add(New Object() {1, "Hard Drive"})
    table.Rows.Add(New Object() {2, "Monitor"})
    table.Rows.Add(New Object() {3, "CPU"})
    Return table
End Function

Private Function GetReader() As DataTableReader
    ' Return a DataTableReader containing multiple
    ' result sets, just for the sake of this demo.
    Dim dataSet As New DataSet
    dataSet.Tables.Add(GetCustomers())
    dataSet.Tables.Add(GetProducts())
    Return dataSet.CreateDataReader()
End Function

Private Sub PrintColumns( _
   ByVal table As DataTable)

    Console.WriteLine()
    Console.WriteLine(table.TableName)
    Console.WriteLine("=========================")
    ' Loop through all the rows in the table.
    For Each row As DataRow In table.Rows
        For Each col As DataColumn In table.Columns
            Console.Write(row(col).ToString() & " ")
        Next
        Console.WriteLine()
    Next
End Sub

Comentários

O método Load fornece uma técnica para preencher um único DataTable com dados, recuperado a partir de uma instância IDataReader.The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. Esse método fornece a mesma funcionalidade, mas permite que você carregue vários conjuntos de resultados de um IDataReader em várias tabelas dentro de um DataSet .This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

Observação

A operação de carregamento falhará com uma InvalidOperationException se as colunas de dados de origem na entrada reader forem colunas computadas.The load operation will fail with an InvalidOperationException if any of the source data columns in the incoming reader are computed columns.

O loadOption parâmetro permite que você especifique como deseja que os dados importados interajam com os dados existentes e pode ser qualquer um dos valores da LoadOption enumeração.The loadOption parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the LoadOption enumeration. Consulte a documentação do DataTable Load método para obter mais informações sobre como usar esse parâmetro.See the documentation for the DataTableLoad method for more information on using this parameter.

O tables parâmetro permite que você especifique uma matriz de DataTable instâncias, indicando a ordem das tabelas correspondentes a cada conjunto de resultados carregado do leitor.The tables parameter allows you to specify an array of DataTable instances, indicating the order of the tables corresponding to each result set loaded from the reader. O Load método preenche cada DataTable instância fornecida com dados de um único conjunto de resultados do leitor de dados de origem.The Load method fills each supplied DataTable instance with data from a single result set from the source data reader. Depois de cada conjunto de resultados, o Load método passa para o próximo conjunto de resultados dentro do leitor, até que não haja mais nenhum conjunto de resultados.After each result set, the Load method moves on to the next result set within the reader, until there are no more result sets.

O esquema de resolução de nome para esse método é o mesmo que o seguido pelo Fill método da DbDataAdapter classe.The name resolution scheme for this method is the same as that followed by the Fill method of the DbDataAdapter class.

Confira também

Aplica-se a

Load(IDataReader, LoadOption, String[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader, usando uma matriz de cadeias de caracteres para fornecer os nomes das tabelas dentro de DataSet.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:
 void Load(System::Data::IDataReader ^ reader, System::Data::LoadOption loadOption, ... cli::array <System::String ^> ^ tables);
public void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption, params string[] tables);
member this.Load : System.Data.IDataReader * System.Data.LoadOption * string[] -> unit
Public Sub Load (reader As IDataReader, loadOption As LoadOption, ParamArray tables As String())

Parâmetros

reader
IDataReader

Um IDataReader que fornece um ou vários conjuntos de resultados.An IDataReader that provides one or more result sets.

loadOption
LoadOption

Um valor da enumeração LoadOption que indica como as linhas que já estão nas instâncias DataTable em DataSet serão combinadas com linhas de entrada que compartilham a mesma chave primária.A value from the LoadOption enumeration that indicates how rows already in the DataTable instances within the DataSet will be combined with incoming rows that share the same primary key.

tables
String[]

Uma matriz de cadeias de caracteres da qual o Load método recupera informações de nome de tabela.An array of strings, from which the Load method retrieves table name information.

Exemplos

O exemplo de aplicativo de console a seguir cria primeiro tabelas e carrega dados de um leitor em um DataSet , usando o Load método.The following Console application example first creates tables and loads data from a reader into a DataSet, using the Load method. Em seguida, o exemplo adiciona tabelas a um DataSet e tenta preencher as tabelas com dados de um DataTableReader .The example then adds tables to a DataSet and attempts to fill the tables with data from a DataTableReader. Neste exemplo, como os parâmetros passados para o Load método indicam um nome de tabela que não existe, o Load método cria uma nova tabela para corresponder ao nome passado como um parâmetro.In this example, because the parameters passed to the Load method indicate a table name that does not exist, the Load method creates a new table to match the name passed as a parameter. Depois que os dados tiverem sido carregados, o exemplo exibirá o conteúdo de todas as suas tabelas na janela do console.Once the data has been loaded, the example displays the contents of all its tables in the Console window.

static void Main()
{
    DataSet dataSet = new DataSet();

    DataTableReader reader = GetReader();

    // The tables listed as parameters for the Load method
    // should be in the same order as the tables within the IDataReader.
    dataSet.Load(reader, LoadOption.Upsert, "Customers", "Products");
    foreach (DataTable table in dataSet.Tables)
    {
        PrintColumns(table);
    }

    // Now try the example with the DataSet
    // already filled with data:
    dataSet = new DataSet();
    dataSet.Tables.Add(GetCustomers());
    dataSet.Tables.Add(GetProducts());

    // Retrieve a data reader containing changed data:
    reader = GetReader();

    // Load the data into the existing DataSet. Retrieve the order of the
    // the data in the reader from the
    // list of table names in the parameters. If you specify
    // a new table name here, the Load method will create
    // a corresponding new table.
    dataSet.Load(reader, LoadOption.Upsert,
        "NewCustomers", "Products");
    foreach (DataTable table in dataSet.Tables)
    {
        PrintColumns(table);
    }

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
}

private static DataTable GetCustomers()
{
    // Create sample Customers table.
    DataTable table = new DataTable();
    table.TableName = "Customers";

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID", typeof(int));
    table.Columns.Add("Name", typeof(string));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { 0, "Mary" });
    table.Rows.Add(new object[] { 1, "Andy" });
    table.Rows.Add(new object[] { 2, "Peter" });
    table.AcceptChanges();
    return table;
}

private static DataTable GetProducts()
{
    // Create sample Products table.
    DataTable table = new DataTable();
    table.TableName = "Products";

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID", typeof(int));
    table.Columns.Add("Name", typeof(string));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { 0, "Wireless Network Card" });
    table.Rows.Add(new object[] { 1, "Hard Drive" });
    table.Rows.Add(new object[] { 2, "Monitor" });
    table.Rows.Add(new object[] { 3, "CPU" });
    table.AcceptChanges();
    return table;
}

private static void PrintColumns(DataTable table)
{
    Console.WriteLine();
    Console.WriteLine(table.TableName);
    Console.WriteLine("=========================");
    // Loop through all the rows in the table:
    foreach (DataRow row in table.Rows)
    {
        for (int i = 0; i < table.Columns.Count; i++)
        {
            Console.Write(row[i] + " ");
        }
        Console.WriteLine();
    }
}

private static DataTableReader GetReader()
{
    // Return a DataTableReader containing multiple
    // result sets, just for the sake of this demo.
    DataSet dataSet = new DataSet();
    dataSet.Tables.Add(GetCustomers());
    dataSet.Tables.Add(GetProducts());
    return dataSet.CreateDataReader();
}
Sub Main()
  Dim dataSet As New DataSet
  Dim table As DataTable

  Dim reader As DataTableReader = GetReader()

  ' The tables listed as parameters for the Load method 
  ' should be in the same order as the tables within the IDataReader.
  dataSet.Load(reader, LoadOption.Upsert, "Customers", "Products")
  For Each table In dataSet.Tables
    PrintColumns(table)
  Next

  ' Now try the example with the DataSet
  ' already filled with data:
  dataSet = New DataSet
  dataSet.Tables.Add(GetCustomers())
  dataSet.Tables.Add(GetProducts())

  ' Retrieve a data reader containing changed data:
  reader = GetReader()

  ' Load the data into the existing DataSet. Retrieve the order of the
  ' the data in the reader from the
  ' list of table names in the parameters. If you specify
  ' a new table name here, the Load method will create
  ' a corresponding new table.
  dataSet.Load(reader, LoadOption.Upsert, "NewCustomers", "Products")
  For Each table In dataSet.Tables
    PrintColumns(table)
  Next

  Console.WriteLine("Press any key to continue.")
  Console.ReadKey()
End Sub

Private Function GetCustomers() As DataTable
  ' Create sample Customers table.
  Dim table As New DataTable
  table.TableName = "Customers"

  ' Create two columns, ID and Name.
  Dim idColumn As DataColumn = table.Columns.Add("ID", GetType(Integer))
  table.Columns.Add("Name", GetType(String))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {0, "Mary"})
  table.Rows.Add(New Object() {1, "Andy"})
  table.Rows.Add(New Object() {2, "Peter"})
  table.AcceptChanges()
  Return table
End Function

Private Function GetProducts() As DataTable
  ' Create sample Products table, in order
  ' to demonstrate the behavior of the DataTableReader.
  Dim table As New DataTable
  table.TableName = "Products"

  ' Create two columns, ID and Name.
  Dim idColumn As DataColumn = table.Columns.Add("ID", GetType(Integer))
  table.Columns.Add("Name", GetType(String))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {0, "Wireless Network Card"})
  table.Rows.Add(New Object() {1, "Hard Drive"})
  table.Rows.Add(New Object() {2, "Monitor"})
  table.Rows.Add(New Object() {3, "CPU"})
  Return table
End Function

Private Function GetReader() As DataTableReader
  ' Return a DataTableReader containing multiple
  ' result sets, just for the sake of this demo.
  Dim dataSet As New DataSet
  dataSet.Tables.Add(GetCustomers())
  dataSet.Tables.Add(GetProducts())
  Return dataSet.CreateDataReader()
End Function

Private Sub PrintColumns( _
   ByVal table As DataTable)

  Console.WriteLine()
  Console.WriteLine(table.TableName)
  Console.WriteLine("=========================")
  ' Loop through all the rows in the table.
  For Each row As DataRow In table.Rows
    For Each col As DataColumn In table.Columns
      Console.Write(row(col).ToString() & " ")
    Next
    Console.WriteLine()
  Next
End Sub

Comentários

O método Load fornece uma técnica para preencher um único DataTable com dados, recuperado a partir de uma instância IDataReader.The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. Esse método fornece a mesma funcionalidade, mas permite que você carregue vários conjuntos de resultados de um IDataReader em várias tabelas dentro de um DataSet .This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

Observação

A operação de carregamento falhará com uma InvalidOperationException se as colunas de dados de origem na entrada reader forem colunas computadas.The load operation will fail with an InvalidOperationException if any of the source data columns in the incoming reader are computed columns.

O loadOption parâmetro permite que você especifique como deseja que os dados importados interajam com os dados existentes e pode ser qualquer um dos valores da LoadOption enumeração.The loadOption parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the LoadOption enumeration. Consulte a documentação do Load método para obter mais informações sobre como usar esse parâmetro.See the documentation for the Load method for more information on using this parameter.

O tables parâmetro permite que você especifique uma matriz de nomes de tabela, indicando a ordem das tabelas correspondentes a cada conjunto de resultados carregado do leitor.The tables parameter allows you to specify an array of table names, indicating the order of the tables corresponding to each result set loaded from the reader. O Load método tenta localizar uma tabela dentro do DataSet nome correspondente encontrado na matriz de nomes de tabela, em ordem.The Load method attempts to find a table within the DataSet matching the name found in the array of table names, in order. Se uma tabela correspondente for encontrada, essa tabela será carregada com o conteúdo do conjunto de resultados atual.If a matching table is found, that table is loaded with the content of the current result set. Se nenhuma tabela correspondente for encontrada, uma tabela será criada usando o nome fornecido na matriz de nomes de tabela e o esquema da nova tabela será inferido do conjunto de resultados.If no matching table is found, a table is created using the name supplied in the array of table names, and the new table's schema is inferred from the result set. Depois de cada conjunto de resultados, o Load método passa para o próximo conjunto de resultados dentro do leitor, até que não haja mais nenhum conjunto de resultados.After each result set, the Load method moves on to the next result set within the reader, until there are no more result sets.

O namespace padrão associado a DataSet , se houver, está associado a cada recém-criado DataTable .The default namespace associated with DataSet, if any, is associated with each newly created DataTable. O esquema de resolução de nome para esse método é o mesmo que o seguido pelo Fill método da DbDataAdapter classe.The name resolution scheme for this method is the same as that followed by the Fill method of the DbDataAdapter class.

Confira também

Aplica-se a

Load(IDataReader, LoadOption, FillErrorEventHandler, DataTable[])

Preenche um DataSet com valores de uma fonte de dados usando o IDataReader fornecido, usando uma matriz de instâncias DataTable para fornecer o esquema e as informações de namespace.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:
 virtual void Load(System::Data::IDataReader ^ reader, System::Data::LoadOption loadOption, System::Data::FillErrorEventHandler ^ errorHandler, ... cli::array <System::Data::DataTable ^> ^ tables);
public virtual void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption, System.Data.FillErrorEventHandler? errorHandler, params System.Data.DataTable[] tables);
public virtual void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption, System.Data.FillErrorEventHandler errorHandler, params System.Data.DataTable[] tables);
abstract member Load : System.Data.IDataReader * System.Data.LoadOption * System.Data.FillErrorEventHandler * System.Data.DataTable[] -> unit
override this.Load : System.Data.IDataReader * System.Data.LoadOption * System.Data.FillErrorEventHandler * System.Data.DataTable[] -> unit
Public Overridable Sub Load (reader As IDataReader, loadOption As LoadOption, errorHandler As FillErrorEventHandler, ParamArray tables As DataTable())

Parâmetros

reader
IDataReader

Um IDataReader que fornece um ou vários conjuntos de resultados.An IDataReader that provides one or more result sets.

loadOption
LoadOption

Um valor da enumeração LoadOption que indica como as linhas que já estão nas instâncias DataTable em DataSet serão combinadas com linhas de entrada que compartilham a mesma chave primária.A value from the LoadOption enumeration that indicates how rows already in the DataTable instances within the DataSet will be combined with incoming rows that share the same primary key.

errorHandler
FillErrorEventHandler

Um delegado FillErrorEventHandler a ser chamado quando ocorrer um erro ao carregar os dados.A FillErrorEventHandler delegate to call when an error occurs while loading data.

tables
DataTable[]

Uma matriz de instâncias DataTable, da qual o método Load(IDataReader, LoadOption, FillErrorEventHandler, DataTable[]) recupera informações de nome e namespace.An array of DataTable instances, from which the Load(IDataReader, LoadOption, FillErrorEventHandler, DataTable[]) method retrieves name and namespace information.

Exemplos

O exemplo a seguir adiciona uma tabela a um DataSet e tenta usar o Load método para carregar dados de um DataTableReader que contém um esquema incompatível.The following example adds a table to a DataSet, and then attempts to use the Load method to load data from a DataTableReader that contains an incompatible schema. Em vez de interceptar o erro, este exemplo usa um FillErrorEventHandler delegado para investigar e manipular o erro.Rather than trapping the error, this example uses a FillErrorEventHandler delegate to investigate and handle the error. A saída é exibida na janela do console.The output is displayed in the console window.

static void Main()
{
    // Attempt to load data from a data reader in which
    // the schema is incompatible with the current schema.
    // If you use exception handling, you won't get the chance
    // to examine each row, and each individual table,
    // as the Load method progresses.
    // By taking advantage of the FillErrorEventHandler delegate,
    // you can interact with the Load process as an error occurs,
    // attempting to fix the problem, or simply continuing or quitting
    // the Load process.:
    DataSet dataSet = new DataSet();
    DataTable table = GetIntegerTable();
    dataSet.Tables.Add(table);
    DataTableReader reader = new DataTableReader(GetStringTable());
    dataSet.Load(reader, LoadOption.OverwriteChanges,
        FillErrorHandler, table);

    Console.WriteLine("Press any key to continue.");
    Console.ReadKey();
}

private static DataTable GetIntegerTable()
{
    // Create sample Customers table, in order
    // to demonstrate the behavior of the DataTableReader.
    DataTable table = new DataTable();

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID", typeof(int));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { 4 });
    table.Rows.Add(new object[] { 5 });
    table.AcceptChanges();
    return table;
}

private static DataTable GetStringTable()
{
    // Create sample Customers table, in order
    // to demonstrate the behavior of the DataTableReader.
    DataTable table = new DataTable();

    // Create two columns, ID and Name.
    DataColumn idColumn = table.Columns.Add("ID", typeof(string));

    // Set the ID column as the primary key column.
    table.PrimaryKey = new DataColumn[] { idColumn };

    table.Rows.Add(new object[] { "Mary" });
    table.Rows.Add(new object[] { "Andy" });
    table.Rows.Add(new object[] { "Peter" });
    table.AcceptChanges();
    return table;
}

static void FillErrorHandler(object sender, FillErrorEventArgs e)
{
    // You can use the e.Errors value to determine exactly what
    // went wrong.
    if (e.Errors.GetType() == typeof(System.FormatException))
    {
        Console.WriteLine("Error when attempting to update the value: {0}",
            e.Values[0]);
    }

    // Setting e.Continue to True tells the Load
    // method to continue trying. Setting it to False
    // indicates that an error has occurred, and the
    // Load method raises the exception that got
    // you here.
    e.Continue = true;
}
Sub Main()
  Dim dataSet As New DataSet
  Dim table As New DataTable()

  ' Attempt to load data from a data reader in which
  ' the schema is incompatible with the current schema.
  ' If you use exception handling, you won't get the chance
  ' to examine each row, and each individual table,
  ' as the Load method progresses.
  ' By taking advantage of the FillErrorEventHandler delegate,
  ' you can interact with the Load process as an error occurs,
  ' attempting to fix the problem, or simply continuing or quitting
  ' the Load process.:
  dataSet = New DataSet()
  table = GetIntegerTable()
  dataSet.Tables.Add(table)
  Dim reader As New DataTableReader(GetStringTable())
  dataSet.Load(reader, LoadOption.OverwriteChanges, _
      AddressOf FillErrorHandler, table)

  Console.WriteLine("Press any key to continue.")
  Console.ReadKey()
End Sub

Private Sub FillErrorHandler(ByVal sender As Object, _
  ByVal e As FillErrorEventArgs)
  ' You can use the e.Errors value to determine exactly what
  ' went wrong.
  If e.Errors.GetType Is GetType(System.FormatException) Then
    Console.WriteLine("Error when attempting to update the value: {0}", _
      e.Values(0))
  End If

  ' Setting e.Continue to True tells the Load
  ' method to continue trying. Setting it to False
  ' indicates that an error has occurred, and the 
  ' Load method raises the exception that got 
  ' you here.
  e.Continue = True
End Sub

Private Function GetIntegerTable() As DataTable
  ' Create sample table with a single Int32 column.
  Dim table As New DataTable

  Dim idColumn As DataColumn = table.Columns.Add("ID", _
      GetType(Integer))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {4})
  table.Rows.Add(New Object() {5})
  table.TableName = "IntegerTable"
  table.AcceptChanges()
  Return table
End Function

Private Function GetStringTable() As DataTable
  ' Create sample table with a single String column.
  Dim table As New DataTable

  Dim idColumn As DataColumn = table.Columns.Add("ID", _
      GetType(String))

  ' Set the ID column as the primary key column.
  table.PrimaryKey = New DataColumn() {idColumn}

  table.Rows.Add(New Object() {"Mary"})
  table.Rows.Add(New Object() {"Andy"})
  table.Rows.Add(New Object() {"Peter"})
  table.AcceptChanges()
  Return table
End Function

Private Sub PrintColumns( _
   ByVal table As DataTable)

  ' Loop through all the rows in the DataTableReader.
  For Each row As DataRow In table.Rows
    For Each col As DataColumn In table.Columns
      Console.Write(row(col).ToString() & " ")
    Next
    Console.WriteLine()
  Next
End Sub

Comentários

O método Load fornece uma técnica para preencher um único DataTable com dados, recuperado a partir de uma instância IDataReader.The Load method provides a technique for filling a single DataTable with data, retrieved from an IDataReader instance. Esse método fornece a mesma funcionalidade, mas permite que você carregue vários conjuntos de resultados de um IDataReader em várias tabelas dentro de um DataSet .This method provides the same functionality, but allows you to load multiple result sets from an IDataReader into multiple tables within a DataSet.

Observação

A operação de carregamento falhará com uma InvalidOperationException se as colunas de dados de origem na entrada reader forem colunas computadas.The load operation will fail with an InvalidOperationException if any of the source data columns in the incoming reader are computed columns.

O loadOption parâmetro permite que você especifique como deseja que os dados importados interajam com os dados existentes e pode ser qualquer um dos valores da LoadOption enumeração.The loadOption parameter allows you to specify how you want the imported data to interact with existing data, and can be any of the values from the LoadOption enumeration. Consulte a documentação do DataTable Load método para obter mais informações sobre como usar esse parâmetro.See the documentation for the DataTableLoad method for more information on using this parameter.

O errorHandler parâmetro é um FillErrorEventHandler delegado que se refere a um procedimento que é chamado quando ocorre um erro durante o carregamento de dados.The errorHandler parameter is a FillErrorEventHandler delegate that refers to a procedure that is called when an error occurs while loading data. O FillErrorEventArgs parâmetro passado para o procedimento fornece propriedades que permitem que você recupere informações sobre o erro que ocorreu, a linha atual de dados e a DataTable que está sendo preenchida.The FillErrorEventArgs parameter passed to the procedure provides properties that allow you to retrieve information about the error that occurred, the current row of data, and the DataTable being filled. Usando esse mecanismo delegado, em vez de um bloco try/catch mais simples, o permite que você determine o erro, manipule a situação e continue o processamento se desejar.Using this delegate mechanism, rather than a simpler try/catch block, allows you to determine the error, handle the situation, and continue processing if you like. O FillErrorEventArgs parâmetro fornece uma Continue Propriedade: defina essa propriedade como true para indicar que você tratou o erro e deseja continuar o processamento; defina a propriedade como false para indicar que você deseja interromper o processamento.The FillErrorEventArgs parameter supplies a Continue property: set this property to true to indicate that you have handled the error and wish to continue processing; set the property to false to indicate that you wish to halt processing. Lembre-se de que a configuração da propriedade false faz com que o código que disparou o problema gere uma exceção.Be aware that setting the property to false causes the code that triggered the problem to throw an exception.

O tables parâmetro permite que você especifique uma matriz de DataTable instâncias, indicando a ordem das tabelas correspondentes a cada conjunto de resultados carregado do leitor.The tables parameter allows you to specify an array of DataTable instances, indicating the order of the tables corresponding to each result set loaded from the reader. O Load método preenche cada DataTable instância fornecida com dados de um único conjunto de resultados do leitor de dados de origem.The Load method fills each supplied DataTable instance with data from a single result set from the source data reader. Depois de cada conjunto de resultados, o Load método passa para o próximo conjunto de resultados dentro do leitor, até que não haja mais nenhum conjunto de resultados.After each result set, the Load method moves on to the next result set within the reader, until there are no more result sets.

O esquema de resolução de nome para esse método é o mesmo que o seguido pelo Fill método da DbDataAdapter classe.The name resolution scheme for this method is the same as that followed by the Fill method of the DbDataAdapter class.

Confira também

Aplica-se a