DataTable.Load Método

Definição

Preenche um DataTable com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataTable with values from a data source using the supplied IDataReader. Se o DataTable já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes.If the DataTable already contains rows, the incoming data from the data source is merged with the existing rows.

Sobrecargas

Load(IDataReader)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataTable with values from a data source using the supplied IDataReader. Se o DataTable já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes.If the DataTable already contains rows, the incoming data from the data source is merged with the existing rows.

Load(IDataReader, LoadOption)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataTable with values from a data source using the supplied IDataReader. Se o DataTable já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes de acordo com o valor do parâmetro loadOption.If the DataTable already contains rows, the incoming data from the data source is merged with the existing rows according to the value of the loadOption parameter.

Load(IDataReader, LoadOption, FillErrorEventHandler)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReader fornecido comum delegado de tratamento de erro.Fills a DataTable with values from a data source using the supplied IDataReader using an error-handling delegate.

Exemplos

O exemplo a seguir demonstra vários dos problemas envolvidos na chamada do método Load.The following example demonstrates several of the issues involved with calling the Load method. Primeiro, o exemplo se concentra em problemas de esquema, inclusive inferindo um esquema a partir do IDataReadercarregado e, em seguida, tratando esquemas incompatíveis e esquemas com colunas ausentes ou adicionais.First, the example focuses on schema issues, including inferring a schema from the loaded IDataReader, and then handling incompatible schemas, and schemas with missing or additional columns. Em seguida, o exemplo se concentra em problemas de dados, incluindo a manipulação das várias opções de carregamento.The example then focuses on data issues, including handling the various loading options.

Observação

Este exemplo mostra como usar uma das versões sobrecarregadas do Load.This example shows how to use one of the overloaded versions of Load. Para obter outros exemplos que possam estar disponíveis, consulte os tópicos de sobrecarga individuais.For other examples that might be available, see the individual overload topics.

static void Main()
{
    // This example examines a number of scenarios involving the 
    // DataTable.Load method.
    Console.WriteLine("Load a DataTable and infer its schema:");

    // The table has no schema. The Load method will infer the 
    // schema from the IDataReader:
    DataTable table = new DataTable();

    // Retrieve a data reader, based on the Customers data. In
    // an application, this data might be coming from a middle-tier
    // business object:
    DataTableReader reader = new DataTableReader(GetCustomers());

    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine("Load a DataTable from an incompatible IDataReader:");

    // Create a table with a single integer column. Attempt
    // to load data from a reader with a schema that is 
    // incompatible. Note the exception, determined
    // by the particular incompatibility:
    table = GetIntegerTable();
    reader = new DataTableReader(GetStringTable());
    try
    {
        table.Load(reader);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.GetType().Name + ":" + ex.Message);
    }

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has extra columns:");

    // Note that loading a reader with extra columns adds
    // the columns to the existing table, if possible:
    table = GetIntegerTable();
    reader = new DataTableReader(GetCustomers());
    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has missing columns:");

    // Note that loading a reader with missing columns causes 
    // the columns to be filled with null data, if possible:
    table = GetCustomers();
    reader = new DataTableReader(GetIntegerTable());
    table.Load(reader);
    PrintColumns(table);

    // Demonstrate the various possibilites when loading data into
    // a DataTable that already contains data.
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Demonstrate data considerations:");
    Console.WriteLine("Current value, Original value, (RowState)");
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Original table:");

    table = SetupModifiedRows();
    DisplayRowState(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine("Data in IDataReader to be loaded:");
    DisplayRowState(GetChangedCustomers());

    PerformDemo(LoadOption.OverwriteChanges);
    PerformDemo(LoadOption.PreserveChanges);
    PerformDemo(LoadOption.Upsert);

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

private static void DisplayRowState(DataTable table)
{
    for (int i = 0; i <= table.Rows.Count - 1; i++)
    {
        object current = "--";
        object original = "--";
        DataRowState rowState = table.Rows[i].RowState;

        // Attempt to retrieve the current value, which doesn't exist
        // for deleted rows:
        if (rowState != DataRowState.Deleted)
        {
            current = table.Rows[i]["Name", DataRowVersion.Current];
        }

        // Attempt to retrieve the original value, which doesn't exist
        // for added rows:
        if (rowState != DataRowState.Added)
        {
            original = table.Rows[i]["Name", DataRowVersion.Original];
        }
        Console.WriteLine("{0}: {1}, {2} ({3})", i, current, 
            original, rowState);
    }
}

private static DataTable GetChangedCustomers()
{
    // Create sample Customers table.
    DataTable table = new DataTable();

    // 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, "XXX" });
    table.Rows.Add(new object[] { 1, "XXX" });
    table.Rows.Add(new object[] { 2, "XXX" });
    table.Rows.Add(new object[] { 3, "XXX" });
    table.Rows.Add(new object[] { 4, "XXX" });
    table.AcceptChanges();
    return table;
}

private static DataTable GetCustomers()
{
    // 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));
    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 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;
}

private static void PerformDemo(LoadOption optionForLoad)
{

    // Load data into a DataTable, retrieve a DataTableReader containing
    // different data, and call the Load method. Depending on the
    // LoadOption value passed as a parameter, this procedure displays
    // different results in the DataTable.
    Console.WriteLine(" ============================= ");
    Console.WriteLine("table.Load(reader, {0})", optionForLoad);
    Console.WriteLine(" ============================= ");

    DataTable table = SetupModifiedRows();
    DataTableReader reader = new DataTableReader(GetChangedCustomers());
    table.RowChanging +=new DataRowChangeEventHandler(HandleRowChanging);

    table.Load(reader, optionForLoad);
    Console.WriteLine();
    DisplayRowState(table);
}

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

private static DataTable SetupModifiedRows()
{
    // Fill a DataTable with customer info, and 
    // then modify, delete, and add rows.

    DataTable table = GetCustomers();
    // Row 0 is unmodified.
    // Row 1 is modified.
    // Row 2 is deleted.
    // Row 3 is added.
    table.Rows[1]["Name"] = "Sydney";
    table.Rows[2].Delete();
    DataRow row = table.NewRow();
    row["ID"] = 3;
    row["Name"] = "Melony";
    table.Rows.Add(row);

    // Note that the code doesn't call
    // table.AcceptChanges()
    return table;
}

static void HandleRowChanging(object sender, DataRowChangeEventArgs e)
{
    Console.WriteLine(
        "RowChanging event: ID = {0}, action = {1}", e.Row["ID"], 
        e.Action);
}
Sub Main()
  Dim table As New DataTable()

  ' This example examines a number of scenarios involving the 
  ' DataTable.Load method.
  Console.WriteLine("Load a DataTable and infer its schema:")

  ' Retrieve a data reader, based on the Customers data. In
  ' an application, this data might be coming from a middle-tier
  ' business object:
  Dim reader As New DataTableReader(GetCustomers())

  ' The table has no schema. The Load method will infer the 
  ' schema from the IDataReader:
  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine("Load a DataTable from an incompatible IDataReader:")

  ' Create a table with a single integer column. Attempt
  ' to load data from a reader with a schema that is 
  ' incompatible. Note the exception, determined
  ' by the particular incompatibility:
  table = GetIntegerTable()
  reader = New DataTableReader(GetStringTable())
  Try
    table.Load(reader)
  Catch ex As Exception
    Console.WriteLine(ex.GetType.Name & ":" & ex.Message())
  End Try

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable with an IDataReader that has extra columns:")

  ' Note that loading a reader with extra columns adds
  ' the columns to the existing table, if possible:
  table = GetIntegerTable()
  reader = New DataTableReader(GetCustomers())
  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable with an IDataReader that has missing columns:")

  ' Note that loading a reader with missing columns causes 
  ' the columns to be filled with null data, if possible:
  table = GetCustomers()
  reader = New DataTableReader(GetIntegerTable())
  table.Load(reader)
  PrintColumns(table)

  ' Demonstrate the various possibilites when loading data into
  ' a DataTable that already contains data.
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Demonstrate data considerations:")
  Console.WriteLine("Current value, Original value, (RowState)")
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Original table:")

  table = SetupModifiedRows()
  DisplayRowState(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine("Data in IDataReader to be loaded:")
  DisplayRowState(GetChangedCustomers())

  PerformDemo(LoadOption.OverwriteChanges)
  PerformDemo(LoadOption.PreserveChanges)
  PerformDemo(LoadOption.Upsert)

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

Private Sub DisplayRowState(ByVal table As DataTable)
  For i As Integer = 0 To table.Rows.Count - 1
    Dim current As Object = "--"
    Dim original As Object = "--"
    Dim rowState As DataRowState = table.Rows(i).RowState

    ' Attempt to retrieve the current value, which doesn't exist
    ' for deleted rows:
    If rowState <> DataRowState.Deleted Then
      current = table.Rows(i)("Name", DataRowVersion.Current)
    End If

    ' Attempt to retrieve the original value, which doesn't exist
    ' for added rows:
    If rowState <> DataRowState.Added Then
      original = table.Rows(i)("Name", DataRowVersion.Original)
    End If
    Console.WriteLine("{0}: {1}, {2} ({3})", i, current, original, rowState)
  Next
End Sub

Private Function GetChangedCustomers() As DataTable
  ' Create sample Customers table.
  Dim table As New DataTable

  ' 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, "XXX"})
  table.Rows.Add(New Object() {1, "XXX"})
  table.Rows.Add(New Object() {2, "XXX"})
  table.Rows.Add(New Object() {3, "XXX"})
  table.Rows.Add(New Object() {4, "XXX"})
  table.AcceptChanges()
  Return table
End Function

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

  ' 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 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.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 PerformDemo(ByVal optionForLoad As LoadOption)

  ' Load data into a DataTable, retrieve a DataTableReader containing
  ' different data, and call the Load method. Depending on the
  ' LoadOption value passed as a parameter, this procedure displays
  ' different results in the DataTable.
  Console.WriteLine(" ============================= ")
  Console.WriteLine("table.Load(reader, {0})", optionForLoad)
  Console.WriteLine(" ============================= ")

  Dim table As DataTable = SetupModifiedRows()
  Dim reader As New DataTableReader(GetChangedCustomers())
  AddHandler table.RowChanging, New _
      DataRowChangeEventHandler(AddressOf HandleRowChanging)

  table.Load(reader, optionForLoad)
  Console.WriteLine()
  DisplayRowState(table)
End Sub

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

Private Function SetupModifiedRows() As DataTable
  ' Fill a DataTable with customer info, and 
  ' then modify, delete, and add rows.

  Dim table As DataTable = GetCustomers()
  ' Row 0 is unmodified.
  ' Row 1 is modified.
  ' Row 2 is deleted.
  ' Row 3 is added.
  table.Rows(1)("Name") = "Sydney"
  table.Rows(2).Delete()
  Dim row As DataRow = table.NewRow
  row("ID") = 3
  row("Name") = "Melony"
  table.Rows.Add(row)

  ' Note that the code doesn't call
  ' table.AcceptChanges()
  Return table
End Function

Private Sub HandleRowChanging(ByVal sender As Object, _
  ByVal e As System.Data.DataRowChangeEventArgs)
  Console.WriteLine( _
      "RowChanging event: ID = {0}, action = {1}", e.Row("ID"), _
      e.Action)
End Sub

Comentários

O método Load pode ser usado em vários cenários comuns, todos centrados 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, um DataTable).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 DataTable). Esses cenários descrevem o uso padrão de um DataTable, descrevendo seu comportamento de atualização e mesclagem.These scenarios describe standard usage for a DataTable, describing its update and merge behavior.

Um DataTable sincroniza ou atualiza com uma única fonte de dados primária.A DataTable synchronizes or updates with a single primary data source. O DataTable controla as alterações, permitindo a sincronização com a fonte de dados primária.The DataTable tracks changes, allowing synchronization with the primary data source. Além disso, um DataTable pode aceitar dados incrementais de uma ou mais fontes de dados secundárias.In addition, a DataTable can accept incremental data from one or more secondary data sources. A DataTable não é responsável por controlar as alterações a fim de permitir a sincronização com a fonte de dados secundária.The DataTable 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 DataTable de uma fonte de dados primária.Initialize DataTable from a primary data source. Nesse cenário, o usuário deseja inicializar um DataTable vazio com valores da fonte de dados primária.In this scenario, the user wants to initialize an empty DataTable with values from the primary data source. 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 pegar o DataTable preenchido no cenário anterior e executar uma sincronização incremental com a fonte de dados primária, preservando as modificações feitas no DataTable.In this scenario, the user wants to take the DataTable filled in the previous scenario and perform an incremental synchronization with the primary data source, preserving modifications made in the DataTable.

  • 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 método Load torna todos esses cenários possíveis.The Load method makes all these scenarios possible. Tudo, exceto uma das sobrecargas para esse método, permite que você especifique um parâmetro de opção de carregamento, indicando como as linhas já em um DataTable combinam com as linhas que estão sendo carregadas.All but one of the overloads for this method allows you to specify a load option parameter, indicating how rows already in a DataTable combine with rows being loaded. (A sobrecarga que não permite que você especifique o comportamento usa a opção de carregamento padrão.) A tabela a seguir descreve as três opções de carregamento fornecidas pela enumeração LoadOption.(The overload that doesn't allow you to specify the behavior uses the default load option.) 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)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataTable with values from a data source using the supplied IDataReader. Se o DataTable já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes.If the DataTable already contains rows, the incoming data from the data source is merged with the existing rows.

public:
 void Load(System::Data::IDataReader ^ reader);
public void Load (System.Data.IDataReader reader);
member this.Load : System.Data.IDataReader -> unit
Public Sub Load (reader As IDataReader)

Parâmetros

reader
IDataReader

Um IDataReader que fornece um conjunto de resultados.An IDataReader that provides a result set.

Exemplos

O exemplo a seguir demonstra vários dos problemas envolvidos na chamada do método Load.The following example demonstrates several of the issues involved with calling the Load method. Primeiro, o exemplo se concentra em problemas de esquema, inclusive inferindo um esquema a partir do IDataReadercarregado e, em seguida, tratando esquemas incompatíveis e esquemas com colunas ausentes ou adicionais.First, the example focuses on schema issues, including inferring a schema from the loaded IDataReader, and then handling incompatible schemas, and schemas with missing or additional columns. Em seguida, o exemplo chama o método Load, exibindo os dados antes e depois da operação de carregamento.The example then calls the Load method, displaying the data both before and after the load operation.

static void Main()
{
    // This example examines a number of scenarios involving the 
    // DataTable.Load method.
    Console.WriteLine("Load a DataTable and infer its schema:");

    // The table has no schema. The Load method will infer the 
    // schema from the IDataReader:
    DataTable table = new DataTable();

    // Retrieve a data reader, based on the Customers data. In
    // an application, this data might be coming from a middle-tier
    // business object:
    DataTableReader reader = new DataTableReader(GetCustomers());

    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable from an incompatible IDataReader:");

    // Create a table with a single integer column. Attempt
    // to load data from a reader with a schema that is 
    // incompatible. Note the exception, determined
    // by the particular incompatibility:
    table = GetIntegerTable();
    reader = new DataTableReader(GetStringTable());
    try 
    {
        table.Load(reader);
    } 
    catch (Exception ex) 
    { 
        Console.WriteLine(ex.GetType().Name + ":" + ex.Message);
    }

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has extra columns:");

    // Note that loading a reader with extra columns adds
    // the columns to the existing table, if possible:
    table = GetIntegerTable();
    reader = new DataTableReader(GetCustomers());
    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has missing columns:");

    // Note that loading a reader with missing columns causes 
    // the columns to be filled with null data, if possible:
    table = GetCustomers();
    reader = new DataTableReader(GetIntegerTable());
    table.Load(reader);
    PrintColumns(table);

    // Demonstrate the various possibilites when loading data 
    // into a DataTable that already contains data.
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Demonstrate data considerations:");
    Console.WriteLine("Current value, Original value, (RowState)");
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Original table:");

    table = SetupModifiedRows();
    DisplayRowState(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine("Data in IDataReader to be loaded:");
    DisplayRowState(GetChangedCustomers());

    // Load data into a DataTable, retrieve a DataTableReader 
    // containing different data, and call the Load method. 
    Console.WriteLine(" ============================= ");
    Console.WriteLine("table.Load(reader)");
    Console.WriteLine(" ============================= ");

    table = SetupModifiedRows();
    reader = new DataTableReader(GetChangedCustomers());
    table.Load(reader);
    DisplayRowState(table);

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

private static void DisplayRowState(DataTable table)
{
    for (int i = 0; i <= table.Rows.Count - 1; i++)
    {
        object current = "--";
        object original = "--";
        DataRowState rowState = table.Rows[i].RowState;

        // Attempt to retrieve the current value, which doesn't exist
        // for deleted rows:
        if (rowState != DataRowState.Deleted)
        {
            current = table.Rows[i]["Name", DataRowVersion.Current];
        }

        // Attempt to retrieve the original value, which doesn't exist
        // for added rows:
        if (rowState != DataRowState.Added)
        {
            original = table.Rows[i]["Name", DataRowVersion.Original];
        }
        Console.WriteLine("{0}: {1}, {2} ({3})", i, 
            current, original, rowState);
    }
}

private static DataTable GetChangedCustomers()
{
    // Create sample Customers table.
    DataTable table = new DataTable();

    // 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[] { 1, "XXX" });
    table.Rows.Add(new object[] { 2, "XXX" });
    table.Rows.Add(new object[] { 3, "XXX" });
    table.Rows.Add(new object[] { 4, "XXX" });
    table.Rows.Add(new object[] { 5, "XXX" });
    table.Rows.Add(new object[] { 6, "XXX" });
    table.AcceptChanges();
    return table;
}

private static DataTable GetCustomers()
{
    // 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));
    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[] { 1, "Mary" });
    table.Rows.Add(new object[] { 2, "Andy" });
    table.Rows.Add(new object[] { 3, "Peter" });
    table.Rows.Add(new object[] { 4, "Russ" });
    table.AcceptChanges();
    return table;
}

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[] { 5 });
    table.Rows.Add(new object[] { 6 });
    table.Rows.Add(new object[] { 7 });
    table.Rows.Add(new object[] { 8 });
    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.Rows.Add(new object[] { "Russ" });
    table.AcceptChanges();
    return table;
}

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

private static DataTable SetupModifiedRows()
{
    // Fill a DataTable with customer info, and 
    // then modify, delete, and add rows.

    DataTable table = GetCustomers();
    // Row 0 is unmodified.
    // Row 1 is modified.
    // Row 2 is deleted.
    // Row 5 is added.
    table.Rows[1]["Name"] = "Sydney";
    table.Rows[2].Delete();
    DataRow row = table.NewRow();
    row["ID"] = 5;
    row["Name"] = "Melony";
    table.Rows.Add(row);

    // Note that the code doesn't call
    // table.AcceptChanges()
    return table;
}
Sub Main()
  ' This example examines a number of scenarios involving the 
  ' DataTable.Load method.
  Console.WriteLine("Load a DataTable and infer its schema:")

  ' The table has no schema. The Load method will infer the 
  ' schema from the IDataReader:
  Dim table As New DataTable()

  ' Retrieve a data reader, based on the Customers data. In
  ' an application, this data might be coming from a middle-tier
  ' business object:
  Dim reader As New DataTableReader(GetCustomers())

  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable from an incompatible IDataReader:")

  ' Create a table with a single integer column. Attempt
  ' to load data from a reader with a schema that is 
  ' incompatible. Note the exception, determined
  ' by the particular incompatibility:
  table = GetIntegerTable()
  reader = New DataTableReader(GetStringTable())
  Try
    table.Load(reader)
  Catch ex As Exception
    Console.WriteLine(ex.GetType.Name & ":" & ex.Message())
  End Try

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable with an IDataReader that has extra columns:")

  ' Note that loading a reader with extra columns adds
  ' the columns to the existing table, if possible:
  table = GetIntegerTable()
  reader = New DataTableReader(GetCustomers())
  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
      Console.WriteLine( _
          "Load a DataTable with an IDataReader that has missing columns:")

  ' Note that loading a reader with missing columns causes 
  ' the columns to be filled with null data, if possible:
  table = GetCustomers()
  reader = New DataTableReader(GetIntegerTable())
  table.Load(reader)
  PrintColumns(table)

  ' Demonstrate the various possibilites when loading data into
  ' a DataTable that already contains data.
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Demonstrate data considerations:")
  Console.WriteLine("Current value, Original value, (RowState)")
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Original table:")

  table = SetupModifiedRows()
  DisplayRowState(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine("Data in IDataReader to be loaded:")
  DisplayRowState(GetChangedCustomers())

  ' Load data into a DataTable, retrieve a DataTableReader 
  ' containing different data, and call the Load method. 
  Console.WriteLine(" ============================= ")
  Console.WriteLine("table.Load(reader)")
  Console.WriteLine(" ============================= ")

  table = SetupModifiedRows()
  reader = New DataTableReader(GetChangedCustomers())
  table.Load(reader)
  DisplayRowState(table)

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

Private Sub DisplayRowState(ByVal table As DataTable)
  For i As Integer = 0 To table.Rows.Count - 1
    Dim current As Object = "--"
    Dim original As Object = "--"
    Dim rowState As DataRowState = table.Rows(i).RowState

    ' Attempt to retrieve the current value, which doesn't exist
    ' for deleted rows:
    If rowState <> DataRowState.Deleted Then
      current = table.Rows(i)("Name", DataRowVersion.Current)
    End If

    ' Attempt to retrieve the original value, which doesn't exist
    ' for added rows:
    If rowState <> DataRowState.Added Then
      original = table.Rows(i)("Name", DataRowVersion.Original)
    End If
    Console.WriteLine("{0}: {1}, {2} ({3})", i, _
      current, original, rowState)
  Next
End Sub

Private Function GetChangedCustomers() As DataTable
  ' Create sample Customers table.
  Dim table As New DataTable

  ' 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() {1, "XXX"})
  table.Rows.Add(New Object() {2, "XXX"})
  table.Rows.Add(New Object() {3, "XXX"})
  table.Rows.Add(New Object() {4, "XXX"})
  table.Rows.Add(New Object() {5, "XXX"})
  table.Rows.Add(New Object() {6, "XXX"})
  table.AcceptChanges()
  Return table
End Function

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

  ' 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() {1, "Mary"})
  table.Rows.Add(New Object() {2, "Andy"})
  table.Rows.Add(New Object() {3, "Peter"})
  table.Rows.Add(New Object() {4, "Russ"})
  table.AcceptChanges()
  Return table
End Function

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() {5})
  table.Rows.Add(New Object() {6})
  table.Rows.Add(New Object() {7})
  table.Rows.Add(New Object() {8})
  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.Rows.Add(New Object() {"Russ"})
  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

Private Function SetupModifiedRows() As DataTable
  ' Fill a DataTable with customer info, and 
  ' then modify, delete, and add rows.

  Dim table As DataTable = GetCustomers()
  ' Row 0 is unmodified.
  ' Row 1 is modified.
  ' Row 2 is deleted.
  ' Row 5 is added.
  table.Rows(1)("Name") = "Sydney"
  table.Rows(2).Delete()
  Dim row As DataRow = table.NewRow
  row("ID") = 5
  row("Name") = "Melony"
  table.Rows.Add(row)

  ' Note that the code doesn't call
  ' table.AcceptChanges()
  Return table
End Function

Comentários

O método Load consome o primeiro conjunto de resultados do IDataReadercarregado e, após a conclusão bem-sucedida, define a posição do leitor para o próximo conjunto de resultados, se houver.The Load method consumes the first result set from the loaded IDataReader, and after successful completion, sets the reader's position to the next result set, if any. Ao converter dados, o método Load usa as mesmas regras de conversão que o método DbDataAdapter.Fill.When converting data, the Load method uses the same conversion rules as the DbDataAdapter.Fill method.

O método Load deve levar em conta três problemas específicos ao carregar os dados de uma instância de IDataReader: esquema, dados e operações de evento.The Load method must take into account three specific issues when loading the data from an IDataReader instance: schema, data, and event operations. Ao trabalhar com o esquema, o método Load pode encontrar condições, conforme descrito na tabela a seguir.When working with the schema, the Load method may encounter conditions as described in the following table. As operações de esquema ocorrem para todos os conjuntos de resultados importados, mesmo aqueles que não contêm dados.The schema operations take place for all imported result sets, even those containing no data.

CondiçãoCondition ComportamentoBehavior
O DataTable não tem Esquema.The DataTable has no schema. O método Load infere o esquema com base no conjunto de resultados do IDataReaderimportado.The Load method infers the schema based on the result set from the imported IDataReader.
O DataTable tem um esquema, mas ele é incompatível com o esquema carregado.The DataTable has a schema, but it is incompatible with the loaded schema. O método Load gera uma exceção correspondente ao erro específico que ocorre ao tentar carregar dados no esquema incompatível.The Load method throws an exception corresponding to the particular error that occurs when attempting to load data into the incompatible schema.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém colunas que não existem no DataTable.The schemas are compatible, but the loaded result set schema contains columns that do not exist in the DataTable. O método Load adiciona as colunas extras ao esquema de DataTable.The Load method adds the extra columns to DataTable's schema. O método gera uma exceção se as colunas correspondentes no DataTable e o conjunto de resultados carregado não forem compatíveis com o valor.The method throws an exception if corresponding columns in the DataTable and the loaded result set are not value compatible. O método também recupera informações de restrição do conjunto de resultados para todas as colunas adicionadas.The method also retrieves constraint information from the result set for all added columns. Exceto para o caso da restrição PRIMARY KEY, essas informações de restrição serão usadas somente se o DataTable atual não contiver nenhuma coluna no início da operação de carregamento.Except for the case of Primary Key constraint, this constraint information is used only if the current DataTable does not contain any columns at the start of the load operation.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém menos colunas do que o DataTable.The schemas are compatible, but the loaded result set schema contains fewer columns than does the DataTable. Se uma coluna ausente tiver um valor padrão definido ou o tipo de dados da coluna for anulável, o método Load permitirá que as linhas sejam adicionadas, substituindo o valor padrão ou null para a coluna ausente.If a missing column has a default value defined or the column's data type is nullable, the Load method allows the rows to be added, substituting the default or null value for the missing column. Se nenhum valor padrão ou null puder ser usado, o método Load lançará uma exceção.If no default value or null can be used, then the Load method throws an exception. Se nenhum valor padrão específico tiver sido fornecido, o método Load usará o valor de null como o valor padrão implícito.If no specific default value has been supplied, the Load method uses the null value as the implied default value.

Antes de considerar o comportamento do método Load em termos de operações de dados, considere que cada linha dentro de uma DataTable mantém o valor atual e o valor original para cada coluna.Before considering the behavior of the Load method in terms of data operations, consider that each row within a DataTable maintains both the current value and the original value for each column. Esses valores podem ser equivalentes, ou podem ser diferentes se os dados na linha tiverem sido alterados desde o preenchimento da DataTable.These values may be equivalent, or may be different if the data in the row has been changed since filling the DataTable. Para obter mais informações, consulte Estados de linha e versões de linha.For more information, see Row States and Row Versions.

Esta versão do método Load tenta preservar os valores atuais em cada linha, deixando o valor original intacto.This version of the Load method attempts to preserve the current values in each row, leaving the original value intact. (Se você quiser ter um controle mais preciso sobre o comportamento dos dados de entrada, consulte DataTable.Load.) Se a linha existente e a linha de entrada contiverem valores de chave primária correspondentes, a linha será processada usando seu valor de estado de linha atual, caso contrário, será tratada como uma nova linha.(If you want finer control over the behavior of incoming data, see DataTable.Load.) If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row.

Em termos de operações de evento, o evento de RowChanging ocorre antes de cada linha ser alterada e o evento de RowChanged ocorre depois que cada linha é alterada.In terms of event operations, the RowChanging event occurs before each row is changed, and the RowChanged event occurs after each row has been changed. Em cada caso, a propriedade Action da instância de DataRowChangeEventArgs passada para o manipulador de eventos contém informações sobre a ação específica associada ao evento.In each case, the Action property of the DataRowChangeEventArgs instance passed to the event handler contains information about the particular action associated with the event. Esse valor de ação depende do estado da linha antes da operação de carregamento.This action value depends on the state of the row before the load operation. Em cada caso, ambos os eventos ocorrem e a ação é a mesma para cada um.In each case, both events occur, and the action is the same for each. A ação pode ser aplicada à versão atual ou original de cada linha, ou ambos, dependendo do estado de linha atual.The action may be applied to either the current or original version of each row, or both, depending on the current row state.

A tabela a seguir exibe o comportamento do método Load.The following table displays behavior for the Load method. A linha final (rotulada "(não está presente)") descreve o comportamento de linhas de entrada que não correspondem a nenhuma linha existente.The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Cada célula nesta tabela descreve o valor atual e o original para um campo dentro de uma linha, junto com a DataRowState para o valor após a conclusão do método Load.Each cell in this table describes the current and original value for a field within a row, along with the DataRowState for the value after the Load method has completed. Nesse caso, o método não permite que você indique a opção de carregamento e usa o padrão, PreserveChanges.In this case, the method doesn't allow you to indicate the load option, and uses the default, PreserveChanges.

DataRowState existenteExisting DataRowState Valores após Load método e ação de eventoValues after Load method, and event action
AddedAdded Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

RowAction = ChangeOriginalRowAction = ChangeOriginal
Modificado emModified Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

RowAction = ChangeOriginalRowAction = ChangeOriginal
DeletedDeleted Current = <não disponível >Current = <Not available>

Original = <> de entradaOriginal = <Incoming>

Estado = <excluído >State = <Deleted>

RowAction = ChangeOriginalRowAction = ChangeOriginal
UnchangedUnchanged Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
(Não está presente)(Not present) Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal

Os valores em uma DataColumn podem ser restritos por meio do uso de propriedades como ReadOnly e AutoIncrement.Values in a DataColumn can be constrained through use of properties such as ReadOnly and AutoIncrement. O método Load manipula essas colunas de uma maneira consistente com o comportamento definido pelas propriedades da coluna.The Load method handles such columns in a manner that is consistent with the behavior defined by the column's properties. A restrição somente leitura em um DataColumn é aplicável somente para alterações que ocorrem na memória.The read only constraint on a DataColumn is applicable only for changes that occur in memory. O método Load substitui os valores de coluna somente leitura, se necessário.The Load method's overwrites the read-only column values, if needed.

Para determinar qual versão do campo de chave primária usar para comparar a linha atual com uma linha de entrada, o método Load usa a versão original do valor de chave primária dentro de uma linha, se existir.To determine which version of the primary key field to use for comparing the current row with an incoming row, the Load method uses the original version of the primary key value within a row, if it exists. Caso contrário, o método Load usará a versão atual do campo de chave primária.Otherwise, the Load method uses the current version of the primary key field.

Veja também

Load(IDataReader, LoadOption)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReaderfornecido.Fills a DataTable with values from a data source using the supplied IDataReader. Se o DataTable já contiver linhas, os dados de entrada da fonte de dados serão mesclados com as linhas existentes de acordo com o valor do parâmetro loadOption.If the DataTable already contains rows, the incoming data from the data source is merged with the existing rows according to the value of the loadOption parameter.

public:
 void Load(System::Data::IDataReader ^ reader, System::Data::LoadOption loadOption);
public void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption);
member this.Load : System.Data.IDataReader * System.Data.LoadOption -> unit
Public Sub Load (reader As IDataReader, loadOption As LoadOption)

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 no DataTable sã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 are combined with incoming rows that share the same primary key.

Exemplos

O exemplo a seguir demonstra vários dos problemas envolvidos na chamada do método Load.The following example demonstrates several of the issues involved with calling the Load method. Primeiro, o exemplo se concentra em problemas de esquema, inclusive inferindo um esquema a partir do IDataReadercarregado e, em seguida, tratando esquemas incompatíveis e esquemas com colunas ausentes ou adicionais.First, the example focuses on schema issues, including inferring a schema from the loaded IDataReader, and then handling incompatible schemas, and schemas with missing or additional columns. Em seguida, o exemplo se concentra em problemas de dados, incluindo a manipulação das várias opções de carregamento.The example then focuses on data issues, including handling the various loading options.

static void Main()
{
    // This example examines a number of scenarios involving the 
    // DataTable.Load method.
    Console.WriteLine("Load a DataTable and infer its schema:");

    // The table has no schema. The Load method will infer the 
    // schema from the IDataReader:
    DataTable table = new DataTable();

    // Retrieve a data reader, based on the Customers data. In
    // an application, this data might be coming from a middle-tier
    // business object:
    DataTableReader reader = new DataTableReader(GetCustomers());

    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable from an incompatible IDataReader:");

    // Create a table with a single integer column. Attempt
    // to load data from a reader with a schema that is 
    // incompatible. Note the exception, determined
    // by the particular incompatibility:
    table = GetIntegerTable();
    reader = new DataTableReader(GetStringTable());
    try
    {
        table.Load(reader);
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.GetType().Name + ":" + ex.Message);
    }

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has extra columns:");

    // Note that loading a reader with extra columns adds
    // the columns to the existing table, if possible:
    table = GetIntegerTable();
    reader = new DataTableReader(GetCustomers());
    table.Load(reader);
    PrintColumns(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine(
        "Load a DataTable with an IDataReader that has missing columns:");

    // Note that loading a reader with missing columns causes 
    // the columns to be filled with null data, if possible:
    table = GetCustomers();
    reader = new DataTableReader(GetIntegerTable());
    table.Load(reader);
    PrintColumns(table);

    // Demonstrate the various possibilites when loading data into
    // a DataTable that already contains data.
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Demonstrate data considerations:");
    Console.WriteLine("Current value, Original value, (RowState)");
    Console.WriteLine(" ============================= ");
    Console.WriteLine("Original table:");

    table = SetupModifiedRows();
    DisplayRowState(table);

    Console.WriteLine(" ============================= ");
    Console.WriteLine("Data in IDataReader to be loaded:");
    DisplayRowState(GetChangedCustomers());

    PerformDemo(LoadOption.OverwriteChanges);
    PerformDemo(LoadOption.PreserveChanges);
    PerformDemo(LoadOption.Upsert);

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

private static void DisplayRowState(DataTable table)
{
    for (int i = 0; i <= table.Rows.Count - 1; i++)
    {
        object current = "--";
        object original = "--";
        DataRowState rowState = table.Rows[i].RowState;

        // Attempt to retrieve the current value, which doesn't exist
        // for deleted rows:
        if (rowState != DataRowState.Deleted)
        {
            current = table.Rows[i]["Name", DataRowVersion.Current];
        }

        // Attempt to retrieve the original value, which doesn't exist
        // for added rows:
        if (rowState != DataRowState.Added)
        {
            original = table.Rows[i]["Name", DataRowVersion.Original];
        }
        Console.WriteLine("{0}: {1}, {2} ({3})", i, 
            current, original, rowState);
    }
}

private static DataTable GetChangedCustomers()
{
    // Create sample Customers table.
    DataTable table = new DataTable();

    // 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, "XXX" });
    table.Rows.Add(new object[] { 1, "XXX" });
    table.Rows.Add(new object[] { 2, "XXX" });
    table.Rows.Add(new object[] { 3, "XXX" });
    table.Rows.Add(new object[] { 4, "XXX" });
    table.AcceptChanges();
    return table;
}

private static DataTable GetCustomers()
{
    // 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));
    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 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;
}

private static void PerformDemo(LoadOption optionForLoad)
{

    // Load data into a DataTable, retrieve a DataTableReader containing
    // different data, and call the Load method. Depending on the
    // LoadOption value passed as a parameter, this procedure displays
    // different results in the DataTable.
    Console.WriteLine(" ============================= ");
    Console.WriteLine("table.Load(reader, {0})", optionForLoad);
    Console.WriteLine(" ============================= ");

    DataTable table = SetupModifiedRows();
    DataTableReader reader = new DataTableReader(GetChangedCustomers());
    table.RowChanging +=new DataRowChangeEventHandler(HandleRowChanging);

    table.Load(reader, optionForLoad);
    Console.WriteLine();
    DisplayRowState(table);
}

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

private static DataTable SetupModifiedRows()
{
    // Fill a DataTable with customer info, and 
    // then modify, delete, and add rows.

    DataTable table = GetCustomers();
    // Row 0 is unmodified.
    // Row 1 is modified.
    // Row 2 is deleted.
    // Row 3 is added.
    table.Rows[1]["Name"] = "Sydney";
    table.Rows[2].Delete();
    DataRow row = table.NewRow();
    row["ID"] = 3;
    row["Name"] = "Melony";
    table.Rows.Add(row);

    // Note that the code doesn't call
    // table.AcceptChanges()
    return table;
}

static void HandleRowChanging(object sender, DataRowChangeEventArgs e)
{
    Console.WriteLine(
        "RowChanging event: ID = {0}, action = {1}", e.Row["ID"], e.Action);
}
Sub Main()
  Dim table As New DataTable()

  ' This example examines a number of scenarios involving the
  '  DataTable.Load method.
  Console.WriteLine("Load a DataTable and infer its schema:")

  ' Retrieve a data reader, based on the Customers data. In
  ' an application, this data might be coming from a middle-tier
  ' business object:
  Dim reader As New DataTableReader(GetCustomers())

  ' The table has no schema. The Load method will infer the 
  ' schema from the IDataReader:
  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable from an incompatible IDataReader:")

  ' Create a table with a single integer column. Attempt
  ' to load data from a reader with a schema that is 
  ' incompatible. Note the exception, determined
  ' by the particular incompatibility:
  table = GetIntegerTable()
  reader = New DataTableReader(GetStringTable())
  Try
    table.Load(reader)
  Catch ex As Exception
    Console.WriteLine(ex.GetType.Name & ":" & ex.Message())
  End Try

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable with an IDataReader that has extra columns:")

  ' Note that loading a reader with extra columns adds
  ' the columns to the existing table, if possible:
  table = GetIntegerTable()
  reader = New DataTableReader(GetCustomers())
  table.Load(reader)
  PrintColumns(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine( _
      "Load a DataTable with an IDataReader that has missing columns:")

  ' Note that loading a reader with missing columns causes 
  ' the columns to be filled with null data, if possible:
  table = GetCustomers()
  reader = New DataTableReader(GetIntegerTable())
  table.Load(reader)
  PrintColumns(table)

  ' Demonstrate the various possibilites when loading data into
  ' a DataTable that already contains data.
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Demonstrate data considerations:")
  Console.WriteLine("Current value, Original value, (RowState)")
  Console.WriteLine(" ============================= ")
  Console.WriteLine("Original table:")

  table = SetupModifiedRows()
  DisplayRowState(table)

  Console.WriteLine(" ============================= ")
  Console.WriteLine("Data in IDataReader to be loaded:")
  DisplayRowState(GetChangedCustomers())

  PerformDemo(LoadOption.OverwriteChanges)
  PerformDemo(LoadOption.PreserveChanges)
  PerformDemo(LoadOption.Upsert)

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

Private Sub DisplayRowState(ByVal table As DataTable)
  For i As Integer = 0 To table.Rows.Count - 1
    Dim current As Object = "--"
    Dim original As Object = "--"
    Dim rowState As DataRowState = table.Rows(i).RowState

    ' Attempt to retrieve the current value, which doesn't exist
    ' for deleted rows:
    If rowState <> DataRowState.Deleted Then
      current = table.Rows(i)("Name", DataRowVersion.Current)
    End If

    ' Attempt to retrieve the original value, which doesn't exist
    ' for added rows:
    If rowState <> DataRowState.Added Then
      original = table.Rows(i)("Name", DataRowVersion.Original)
    End If
    Console.WriteLine("{0}: {1}, {2} ({3})", i, _
      current, original, rowState)
  Next
End Sub

Private Function GetChangedCustomers() As DataTable
  ' Create sample Customers table.
  Dim table As New DataTable

  ' 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, "XXX"})
  table.Rows.Add(New Object() {1, "XXX"})
  table.Rows.Add(New Object() {2, "XXX"})
  table.Rows.Add(New Object() {3, "XXX"})
  table.Rows.Add(New Object() {4, "XXX"})
  table.AcceptChanges()
  Return table
End Function

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

  ' 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 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.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 PerformDemo(ByVal optionForLoad As LoadOption)

  ' Load data into a DataTable, retrieve a DataTableReader containing
  ' different data, and call the Load method. Depending on the
  ' LoadOption value passed as a parameter, this procedure displays
  ' different results in the DataTable.
  Console.WriteLine(" ============================= ")
  Console.WriteLine("table.Load(reader, {0})", optionForLoad)
  Console.WriteLine(" ============================= ")

  Dim table As DataTable = SetupModifiedRows()
  Dim reader As New DataTableReader(GetChangedCustomers())
  AddHandler table.RowChanging, New _
      DataRowChangeEventHandler(AddressOf HandleRowChanging)

  table.Load(reader, optionForLoad)
  Console.WriteLine()
  DisplayRowState(table)
End Sub

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

Private Function SetupModifiedRows() As DataTable
  ' Fill a DataTable with customer info, and 
  ' then modify, delete, and add rows.

  Dim table As DataTable = GetCustomers()
  ' Row 0 is unmodified.
  ' Row 1 is modified.
  ' Row 2 is deleted.
  ' Row 3 is added.
  table.Rows(1)("Name") = "Sydney"
  table.Rows(2).Delete()
  Dim row As DataRow = table.NewRow
  row("ID") = 3
  row("Name") = "Melony"
  table.Rows.Add(row)

  ' Note that the code doesn't call
  ' table.AcceptChanges()
  Return table
End Function

Private Sub HandleRowChanging(ByVal sender As Object, _
      ByVal e As System.Data.DataRowChangeEventArgs)
  Console.WriteLine( _
      "RowChanging event: ID = {0}, action = {1}", e.Row("ID"), e.Action)
End Sub

Comentários

O método Load consome o primeiro conjunto de resultados do IDataReadercarregado e, após a conclusão bem-sucedida, define a posição do leitor para o próximo conjunto de resultados, se houver.The Load method consumes the first result set from the loaded IDataReader, and after successful completion, sets the reader's position to the next result set, if any. Ao converter dados, o método Load usa as mesmas regras de conversão que o método Fill.When converting data, the Load method uses the same conversion rules as the Fill method.

O método Load deve levar em conta três problemas específicos ao carregar os dados de uma instância de IDataReader: esquema, dados e operações de evento.The Load method must take into account three specific issues when loading the data from an IDataReader instance: schema, data, and event operations. Ao trabalhar com o esquema, o método Load pode encontrar condições, conforme descrito na tabela a seguir.When working with the schema, the Load method may encounter conditions as described in the following table. As operações de esquema ocorrem para todos os conjuntos de resultados importados, mesmo aqueles que não contêm dados.The schema operations take place for all imported result sets, even those containing no data.

CondiçãoCondition ComportamentoBehavior
O DataTable não tem Esquema.The DataTable has no schema. O método Load infere o esquema com base no conjunto de resultados do IDataReaderimportado.The Load method infers the schema based on the result set from the imported IDataReader.
O DataTable tem um esquema, mas ele é incompatível com o esquema carregado.The DataTable has a schema, but it is incompatible with the loaded schema. O método Load gera uma exceção correspondente ao erro específico que ocorre ao tentar carregar dados no esquema incompatível.The Load method throws an exception corresponding to the particular error that occurs when attempting to load data into the incompatible schema.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém colunas que não existem no DataTable.The schemas are compatible, but the loaded result set schema contains columns that don't exist in the DataTable. O método Load adiciona as colunas extras ao esquema de DataTable.The Load method adds the extra columns to DataTable's schema. O método gera uma exceção se as colunas correspondentes no DataTable e o conjunto de resultados carregado não forem compatíveis com o valor.The method throws an exception if corresponding columns in the DataTable and the loaded result set are not value compatible. O método também recupera informações de restrição do conjunto de resultados para todas as colunas adicionadas.The method also retrieves constraint information from the result set for all added columns. Exceto para o caso da restrição PRIMARY KEY, essas informações de restrição serão usadas somente se o DataTable atual não contiver nenhuma coluna no início da operação de carregamento.Except for the case of Primary Key constraint, this constraint information is used only if the current DataTable does not contain any columns at the start of the load operation.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém menos colunas do que o DataTable.The schemas are compatible, but the loaded result set schema contains fewer columns than does the DataTable. Se uma coluna ausente tiver um valor padrão definido ou o tipo de dados da coluna for anulável, o método Load permitirá que as linhas sejam adicionadas, substituindo o valor padrão ou nulo da coluna ausente.If a missing column has a default value defined or the column's data type is nullable, the Load method allows the rows to be added, substituting the default or null value for the missing column. Se nenhum valor padrão ou NULL puder ser usado, o método Load lançará uma exceção.If no default value or null can be used, then the Load method throws an exception. Se nenhum valor padrão específico tiver sido fornecido, o método Load usará o valor nulo como o valor padrão implícito.If no specific default value has been supplied, the Load method uses the null value as the implied default value.

Antes de considerar o comportamento do método Load em termos de operações de dados, considere que cada linha dentro de uma DataTable mantém o valor atual e o valor original para cada coluna.Before considering the behavior of the Load method in terms of data operations, consider that each row within a DataTable maintains both the current value and the original value for each column. Esses valores podem ser equivalentes, ou podem ser diferentes se os dados na linha tiverem sido alterados desde o preenchimento da DataTable.These values may be equivalent, or may be different if the data in the row has been changed since filling the DataTable. Consulte Estados de linha e versões de linha para obter mais informações.See Row States and Row Versions for more information.

Nessa chamada de método, o parâmetro LoadOption especificado influencia o processamento dos dados de entrada.In this method call, the specified LoadOption parameter influences the processing of the incoming data. Como o método Load deve tratar o carregamento de linhas que têm a mesma chave primária que as linhas existentes?How should the Load method handle loading rows that have the same primary key as existing rows? Ele deve modificar os valores atuais, os valores originais ou ambos?Should it modify current values, original values, or both? Esses problemas e muito mais, são controlados pelo parâmetro loadOption.These issues, and more, are controlled by the loadOption parameter.

Se a linha existente e a linha de entrada contiverem valores de chave primária correspondentes, a linha será processada usando seu valor de estado de linha atual, caso contrário, será tratada como uma nova linha.If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row.

Em termos de operações de evento, o evento de RowChanging ocorre antes de cada linha ser alterada e o evento de RowChanged ocorre depois que cada linha é alterada.In terms of event operations, the RowChanging event occurs before each row is changed, and the RowChanged event occurs after each row has been changed. Em cada caso, a propriedade Action da instância de DataRowChangeEventArgs passada para o manipulador de eventos contém informações sobre a ação específica associada ao evento.In each case, the Action property of the DataRowChangeEventArgs instance passed to the event handler contains information about the particular action associated with the event. Esse valor de ação varia, dependendo do estado da linha antes da operação de carregamento.This action value varies, depending on the state of the row before the load operation. Em cada caso, ambos os eventos ocorrem e a ação é a mesma para cada um.In each case, both events occur, and the action is the same for each. A ação pode ser aplicada à versão atual ou original de cada linha, ou ambos, dependendo do estado de linha atual.The action may be applied to either the current or original version of each row, or both, depending on the current row state.

A tabela a seguir exibe o comportamento do método Load quando chamado com cada um dos valores de LoadOption e também mostra como os valores interagem com o estado da linha para a linha que está sendo carregada.The following table displays behavior for the Load method when called with each of the LoadOption values, and also shows how the values interact with the row state for the row being loaded. A linha final (rotulada "(não está presente)") descreve o comportamento de linhas de entrada que não correspondem a nenhuma linha existente.The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Cada célula nesta tabela descreve o valor atual e o original para um campo dentro de uma linha, junto com a DataRowState para o valor após a conclusão do método Load.Each cell in this table describes the current and original value for a field within a row, along with the DataRowState for the value after the Load method has completed.

DataRowState existenteExisting DataRowState UpsertUpsert OverwriteChangesOverwriteChanges PreserveChanges (comportamento padrão)PreserveChanges (Default behavior)
AddedAdded Current = <> de entradaCurrent = <Incoming>

Original =-<não disponível >Original = -<Not available>

Estado = <adicionado >State = <Added>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

RowAction = ChangeOriginalRowAction = ChangeOriginal
Modificado emModified Current = <> de entradaCurrent = <Incoming>

Original = <> existenteOriginal = <Existing>

Estado = <modificado >State = <Modified>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

Action = ChangeOriginalRowAction =ChangeOriginal
DeletedDeleted (O carregamento não afeta as linhas excluídas)(Load does not affect deleted rows)

Atual =---Current = ---

Original = <> existenteOriginal = <Existing>

Estado = <excluído >State = <Deleted>

(A nova linha é adicionada com as seguintes características)(New row is added with the following characteristics)

Current = <> de entradaCurrent = <Incoming>

Original = <não disponível >Original = <Not available>

Estado = <adicionado >State = <Added>

RowAction = AddRowAction = Add
Desfazer excluir eUndo delete and

Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <não disponível >Current = <Not available>

Original = <> de entradaOriginal = <Incoming>

Estado = <excluído >State = <Deleted>

RowAction = ChangeOriginalRowAction = ChangeOriginal
UnchangedUnchanged Current = <> de entradaCurrent = <Incoming>

Original = <> existenteOriginal = <Existing>

Se o novo valor for igual ao valor existente, entãoIf new value is the same as the existing value then

Estado = <inalterado >State = <Unchanged>

Action = NothingRowAction = Nothing

ElseElse

Estado = <modificado >State = <Modified>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Não presente)Not present) Current = <> de entradaCurrent = <Incoming>

Original = <não disponível >Original = <Not available>

Estado = <adicionado >State = <Added>

RowAction = AddRowAction = Add
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal

Os valores em uma DataColumn podem ser restritos por meio do uso de propriedades como ReadOnly e AutoIncrement.Values in a DataColumn can be constrained through use of properties such as ReadOnly and AutoIncrement. O método Load manipula essas colunas de uma maneira consistente com o comportamento definido pelas propriedades da coluna.The Load method handles such columns in a manner that is consistent with the behavior defined by the column's properties. A restrição somente leitura em um DataColumn é aplicável somente para alterações que ocorrem na memória.The read only constraint on a DataColumn is applicable only for changes that occur in memory. O método Load substitui os valores de coluna somente leitura, se necessário.The Load method's overwrites the read-only column values, if needed.

Se você especificar as opções OverwriteChanges ou PreserveChanges ao chamar o método Load, será feita a suposição que os dados de entrada sejam provenientes da fonte de dados primária do DataTable, e a DataTable controlará as alterações e poderá propagar as alterações de volta para a fonte de dados.If you specify the OverwriteChanges or PreserveChanges options when calling the Load method, then the assumption is made that the incoming data is coming from the DataTable's primary data source, and the DataTable tracks changes and can propagate the changes back to the data source. Se você selecionar a opção Upsert, supõe-se que os dados são provenientes de uma fonte de dados secundária, como os dados fornecidos por um componente de camada intermediária, talvez alterado por um usuário.If you select the Upsert option, it is assumed that the data is coming from one of a secondary data source, such as data provided by a middle-tier component, perhaps altered by a user. Nesse caso, a suposição é que a intenção é agregar dados de uma ou mais fontes de dados no DataTablee, em seguida, talvez propague os dados de volta para a fonte de dados primária.In this case, the assumption is that the intent is to aggregate data from one or more data sources in the DataTable, and then perhaps propagate the data back to the primary data source. O parâmetro LoadOption é usado para determinar a versão específica da linha a ser usada para comparação de chave primária.The LoadOption parameter is used for determining the specific version of the row that is to be used for primary key comparison. A tabela a seguir fornece os detalhes.The table below provides the details.

Opção de carregamentoLoad option Versão de DataRow usada para comparação de chave primáriaDataRow version used for primary key comparison
OverwriteChanges Versão Original, caso exista, ou a versão AtualOriginal version, if it exists, otherwise Current version
PreserveChanges Versão Original, caso exista, ou a versão AtualOriginal version, if it exists, otherwise Current version
Upsert Versão atual, se existir, versão original do contrárioCurrent version, if it exists, otherwise Original version

Veja também

Load(IDataReader, LoadOption, FillErrorEventHandler)

Preenche um DataTable com valores de uma fonte de dados usando o IDataReader fornecido comum delegado de tratamento de erro.Fills a DataTable with values from a data source using the supplied IDataReader using an error-handling delegate.

public:
 virtual void Load(System::Data::IDataReader ^ reader, System::Data::LoadOption loadOption, System::Data::FillErrorEventHandler ^ errorHandler);
public virtual void Load (System.Data.IDataReader reader, System.Data.LoadOption loadOption, System.Data.FillErrorEventHandler errorHandler);
abstract member Load : System.Data.IDataReader * System.Data.LoadOption * System.Data.FillErrorEventHandler -> unit
override this.Load : System.Data.IDataReader * System.Data.LoadOption * System.Data.FillErrorEventHandler -> unit
Public Overridable Sub Load (reader As IDataReader, loadOption As LoadOption, errorHandler As FillErrorEventHandler)

Parâmetros

reader
IDataReader

Um IDataReader que fornece um conjunto de resultados.A IDataReader that provides a result set.

loadOption
LoadOption

Um valor da enumeração LoadOption que indica como as linhas que já estão no DataTable sã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 are 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.

Exemplos

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:
    DataTable table = GetIntegerTable();
    DataTableReader reader = new DataTableReader(GetStringTable());
    table.Load(reader, LoadOption.OverwriteChanges, FillErrorHandler);

    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 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:
  table = GetIntegerTable()
  Dim reader As New DataTableReader(GetStringTable())
  table.Load(reader, LoadOption.OverwriteChanges, _
      AddressOf FillErrorHandler)

  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 consome o primeiro conjunto de resultados do IDataReadercarregado e, após a conclusão bem-sucedida, define a posição do leitor para o próximo conjunto de resultados, se houver.The Load method consumes the first result set from the loaded IDataReader, and after successful completion, sets the reader's position to the next result set, if any. Ao converter dados, o método Load usa as mesmas regras de conversão que o método DbDataAdapter.Fill.When converting data, the Load method uses the same conversion rules as the DbDataAdapter.Fill method.

O método Load deve levar em conta três problemas específicos ao carregar os dados de uma instância de IDataReader: esquema, dados e operações de evento.The Load method must take into account three specific issues when loading the data from an IDataReader instance: schema, data, and event operations. Ao trabalhar com o esquema, o método Load pode encontrar condições, conforme descrito na tabela a seguir.When working with the schema, the Load method may encounter conditions as described in the following table. As operações de esquema ocorrem para todos os conjuntos de resultados importados, mesmo aqueles que não contêm dados.The schema operations take place for all imported result sets, even those containing no data.

CondiçãoCondition ComportamentoBehavior
O DataTable não tem Esquema.The DataTable has no schema. O método Load infere o esquema com base no conjunto de resultados do IDataReaderimportado.The Load method infers the schema based on the result set from the imported IDataReader.
O DataTable tem um esquema, mas ele é incompatível com o esquema carregado.The DataTable has a schema, but it is incompatible with the loaded schema. O método Load gera uma exceção correspondente ao erro específico que ocorre ao tentar carregar dados no esquema incompatível.The Load method throws an exception corresponding to the particular error that occurs when attempting to load data into the incompatible schema.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém colunas que não existem no DataTable.The schemas are compatible, but the loaded result set schema contains columns that don't exist in the DataTable. O método Load adiciona as colunas extras ao esquema de DataTable.The Load method adds the extra column(s) to DataTable's schema. O método gera uma exceção se as colunas correspondentes no DataTable e o conjunto de resultados carregado não forem compatíveis com o valor.The method throws an exception if corresponding columns in the DataTable and the loaded result set are not value compatible. O método também recupera informações de restrição do conjunto de resultados para todas as colunas adicionadas.The method also retrieves constraint information from the result set for all added columns. Exceto para o caso da restrição PRIMARY KEY, essas informações de restrição serão usadas somente se o DataTable atual não contiver nenhuma coluna no início da operação de carregamento.Except for the case of Primary Key constraint, this constraint information is used only if the current DataTable does not contain any columns at the start of the load operation.
Os esquemas são compatíveis, mas o esquema do conjunto de resultados carregado contém menos colunas do que o DataTable.The schemas are compatible, but the loaded result set schema contains fewer columns than does the DataTable. Se uma coluna ausente tiver um valor padrão definido ou o tipo de dados da coluna for anulável, o método Load permitirá que as linhas sejam adicionadas, substituindo o valor padrão ou nulo da coluna ausente.If a missing column has a default value defined or the column's data type is nullable, the Load method allows the rows to be added, substituting the default or null value for the missing column. Se nenhum valor padrão ou NULL puder ser usado, o método Load lançará uma exceção.If no default value or null can be used, then the Load method throws an exception. Se nenhum valor padrão específico tiver sido fornecido, o método Load usará o valor nulo como o valor padrão implícito.If no specific default value has been supplied, the Load method uses the null value as the implied default value.

Antes de considerar o comportamento do método Load em termos de operações de dados, considere que cada linha dentro de uma DataTable mantém o valor atual e o valor original para cada coluna.Before considering the behavior of the Load method in terms of data operations, consider that each row within a DataTable maintains both the current value and the original value for each column. Esses valores podem ser equivalentes, ou podem ser diferentes se os dados na linha tiverem sido alterados desde o preenchimento da DataTable.These values may be equivalent, or may be different if the data in the row has been changed since filling the DataTable. Consulte Estados de linha e versões de linha para obter mais informações.See Row States and Row Versions for more information.

Nessa chamada de método, o parâmetro LoadOption especificado influencia o processamento dos dados de entrada.In this method call, the specified LoadOption parameter influences the processing of the incoming data. Como o método Load deve tratar o carregamento de linhas que têm a mesma chave primária que as linhas existentes?How should the Load method handle loading rows that have the same primary key as existing rows? Ele deve modificar os valores atuais, os valores originais ou ambos?Should it modify current values, original values, or both? Esses problemas e muito mais, são controlados pelo parâmetro loadOption.These issues, and more, are controlled by the loadOption parameter.

Se a linha existente e a linha de entrada contiverem valores de chave primária correspondentes, a linha será processada usando seu valor de estado de linha atual, caso contrário, será tratada como uma nova linha.If the existing row and the incoming row contain corresponding primary key values, the row is processed using its current row state value, otherwise it's treated as a new row.

Em termos de operações de evento, o evento de RowChanging ocorre antes de cada linha ser alterada e o evento de RowChanged ocorre depois que cada linha é alterada.In terms of event operations, the RowChanging event occurs before each row is changed, and the RowChanged event occurs after each row has been changed. Em cada caso, a propriedade Action da instância de DataRowChangeEventArgs passada para o manipulador de eventos contém informações sobre a ação específica associada ao evento.In each case, the Action property of the DataRowChangeEventArgs instance passed to the event handler contains information about the particular action associated with the event. Esse valor de ação varia, dependendo do estado da linha antes da operação de carregamento.This action value varies, depending on the state of the row before the load operation. Em cada caso, ambos os eventos ocorrem e a ação é a mesma para cada um.In each case, both events occur, and the action is the same for each. A ação pode ser aplicada à versão atual ou original de cada linha, ou ambos, dependendo do estado de linha atual.The action may be applied to either the current or original version of each row, or both, depending on the current row state.

A tabela a seguir exibe o comportamento do método Load quando chamado com cada um dos valores de LoadOption e também mostra como os valores interagem com o estado da linha para a linha que está sendo carregada.The following table displays behavior for the Load method when called with each of the LoadOption values, and also shows how the values interact with the row state for the row being loaded. A linha final (rotulada "(não está presente)") descreve o comportamento de linhas de entrada que não correspondem a nenhuma linha existente.The final row (labeled "(Not present)") describes the behavior for incoming rows that don't match any existing row. Cada célula nesta tabela descreve o valor atual e o original para um campo dentro de uma linha, junto com a DataRowState para o valor após a conclusão do método Load.Each cell in this table describes the current and original value for a field within a row, along with the DataRowState for the value after the Load method has completed.

DataRowState existenteExisting DataRowState UpsertUpsert OverwriteChangesOverwriteChanges PreserveChanges (comportamento padrão)PreserveChanges (Default behavior)
AddedAdded Current = <> de entradaCurrent = <Incoming>

Original =-<não disponível >Original = -<Not available>

Estado = <adicionado >State = <Added>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

RowAction = ChangeOriginalRowAction = ChangeOriginal
Modificado emModified Current = <> de entradaCurrent = <Incoming>

Original = <> existenteOriginal = <Existing>

Estado = <modificado >State = <Modified>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> existenteCurrent = <Existing>

Original = <> de entradaOriginal = <Incoming>

Estado = <modificado >State = <Modified>

Action = ChangeOriginalRowAction =ChangeOriginal
xcluídoeleted (O carregamento não afeta as linhas excluídas)(Load does not affect deleted rows)

Atual =---Current = ---

Original = <> existenteOriginal = <Existing>

Estado = <excluído >State = <Deleted>

(A nova linha é adicionada com as seguintes características)(New row is added with the following characteristics)

Current = <> de entradaCurrent = <Incoming>

Original = <não disponível >Original = <Not available>

Estado = <adicionado >State = <Added>

RowAction = AddRowAction = Add
Desfazer excluir eUndo delete and

Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <não disponível >Current = <Not available>

Original = <> de entradaOriginal = <Incoming>

Estado = <excluído >State = <Deleted>

RowAction = ChangeOriginalRowAction = ChangeOriginal
UnchangedUnchanged Current = <> de entradaCurrent = <Incoming>

Original = <> existenteOriginal = <Existing>

Se o novo valor for igual ao valor existente, entãoIf new value is the same as the existing value then

Estado = <inalterado >State = <Unchanged>

Action = NothingRowAction = Nothing

ElseElse

Estado = <modificado >State = <Modified>

RowAction = ChangeRowAction = Change
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Não presente)Not present) Current = <> de entradaCurrent = <Incoming>

Original = <não disponível >Original = <Not available>

Estado = <adicionado >State = <Added>

RowAction = AddRowAction = Add
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal
Current = <> de entradaCurrent = <Incoming>

Original = <> de entradaOriginal = <Incoming>

Estado = <inalterado >State = <Unchanged>

RowAction = ChangeCurrentAndOriginalRowAction = ChangeCurrentAndOriginal

Os valores em uma DataColumn podem ser restritos por meio do uso de propriedades como ReadOnly e AutoIncrement.Values in a DataColumn can be constrained through use of properties such as ReadOnly and AutoIncrement. O método Load manipula essas colunas de uma maneira consistente com o comportamento definido pelas propriedades da coluna.The Load method handles such columns in a manner that is consistent with the behavior defined by the column's properties. A restrição somente leitura em um DataColumn é aplicável somente para alterações que ocorrem na memória.The read only constraint on a DataColumn is applicable only for changes that occur in memory. O método Load substitui os valores de coluna somente leitura, se necessário.The Load method's overwrites the read-only column values, if needed.

Se você especificar as opções OverwriteChanges ou PreserveChanges ao chamar o método Load, será feita a suposição que os dados de entrada sejam provenientes da fonte de dados primária do DataTable, e a DataTable controlará as alterações e poderá propagar as alterações de volta para a fonte de dados.If you specify the OverwriteChanges or PreserveChanges options when calling the Load method, then the assumption is made that the incoming data is coming from the DataTable's primary data source, and the DataTable tracks changes and can propagate the changes back to the data source. Se você selecionar a opção Upsert, supõe-se que os dados são provenientes de uma fonte de dados secundária, como os dados fornecidos por um componente de camada intermediária, talvez alterado por um usuário.If you select the Upsert option, it is assumed that the data is coming from one of a secondary data source, such as data provided by a middle-tier component, perhaps altered by a user. Nesse caso, a suposição é que a intenção é agregar dados de uma ou mais fontes de dados no DataTablee, em seguida, talvez propague os dados de volta para a fonte de dados primária.In this case, the assumption is that the intent is to aggregate data from one or more data sources in the DataTable, and then perhaps propagate the data back to the primary data source. O parâmetro LoadOption é usado para determinar a versão específica da linha a ser usada para comparação de chave primária.The LoadOption parameter is used for determining the specific version of the row that is to be used for primary key comparison. A tabela a seguir fornece os detalhes.The table below provides the details.

Opção de carregamentoLoad option Versão de DataRow usada para comparação de chave primáriaDataRow version used for primary key comparison
OverwriteChanges Versão Original, caso exista, ou a versão AtualOriginal version, if it exists, otherwise Current version
PreserveChanges Versão Original, caso exista, ou a versão AtualOriginal version, if it exists, otherwise Current version
Upsert Versão atual, se existir, versão original do contrárioCurrent version, if it exists, otherwise Original version

O parâmetro errorHandler é um delegado FillErrorEventHandler 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 parâmetro FillErrorEventArgs passado para o procedimento fornece propriedades que permitem recuperar informações sobre o erro que ocorreu, a linha atual de dados e o DataTable sendo preenchido.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 parâmetro FillErrorEventArgs fornece uma propriedade Continue: defina essa propriedade como true para indicar que você tratou o erro e deseja continuar 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. Defina a propriedade como false para indicar que você deseja interromper o processamento.Set the property to false to indicate that you wish to halt processing. Lembre-se de que a definição da propriedade como 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.

Veja também

Aplica-se a