Manipulação de eventos de DataTable

O objeto DataTable fornece uma série de eventos que podem ser processados por um aplicativo. A tabela a seguir descreve os eventos DataTable.

Evento	Descrição
Initialized	Ocorre depois que o método EndInit de um DataTable é chamado. Esse evento destina-se principalmente a dar suporte a cenários de tempo de design.
ColumnChanged	Ocorre após a alteração bem-sucedida de um valor em um DataColumn.
ColumnChanging	Ocorre quando um valor tiver sido enviado para um DataColumn.
RowChanged	Ocorre depois que um valor de DataColumn ou o RowState de um DataRow no DataTable tiver sido alterado com êxito.
RowChanging	Ocorre quando uma alteração tiver sido enviada para um valor DataColumn ou o RowState de um DataRow no DataTable.
RowDeleted	Ocorre depois que um DataRow no DataTable tiver sido marcado como Deleted.
RowDeleting	Ocorre antes de um DataRow no DataTable ter sido marcado como Deleted.
TableCleared	Ocorre depois que uma chamada para o método Clear do DataTable tiver sido limpa com êxito a cada DataRow.
TableClearing	Ocorre depois que o método Clear é chamado, mas antes da operação Clear começar.
TableNewRow	Ocorre depois que uma nova DataRow é criada por uma chamada ao método NewRow do DataTable.
Disposed	Ocorre quando DataTable é Disposed. Herdado de MarshalByValueComponent.

Observação

A maioria das operações que adicionam ou excluem linhas não geram os eventos ColumnChanged e ColumnChanging. No entanto, o método ReadXml gera eventos ColumnChanged e ColumnChanging, a menos que XmlReadMode seja definido como DiffGram ou definido como Auto quando o documento XML que está sendo lido for DiffGram.

Aviso

Poderá ocorrer corrupção dos dados se os dados forem modificados em um DataSet dos quais o evento RowChanged é gerado. Nenhuma exceção será gerada se essa corrupção de dados ocorrer.

Eventos relacionados adicionais

A propriedade Constraints contém uma instância de ConstraintCollection. A classe ConstraintCollection expõe um evento CollectionChanged. Esse evento é acionado quando uma restrição é adicionada, modificada ou removida do ConstraintCollection.

A propriedade Columns contém uma instância de DataColumnCollection. A classe DataColumnCollection expõe um evento CollectionChanged. Esse evento é acionado quando uma DataColumn é adicionada, modificada ou removida do DataColumnCollection. As modificações que fazem com que o evento seja acionado incluem alterações no nome, tipo, expressão ou posição ordinal de uma coluna.

A propriedade Tables de um DataSet contém uma instância de DataTableCollection. A classe DataTableCollection expõe os eventos CollectionChanged e CollectionChanging. Esses eventos disparam quando um DataTable é adicionado ou removido de DataSet.

As alterações a DataRows também podem disparar eventos para um DataView associado. A classe DataView expõe um evento ListChanged que é acionado quando um valor DataColumn é alterado ou quando a composição ou a ordem de classificação do modo de exibição muda. A classe DataRowView expõe um evento PropertyChanged que é acionado quando um valor DataColumn associado é alterado.

sequência de operações

Esta é a sequência de operações que ocorre quando um DataRow é adicionado, modificado ou excluído:

1. Crie o registro proposto e aplique as alterações.

2. Verifique as restrições para colunas que não são de expressão.

3. Acione os eventos RowChanging ou RowDeleting, conforme aplicável.

4. Defina o registro proposto como o registro atual.

5. Atualize todos os índices associados.

6. Gere eventos ListChanged para objetos DataView e eventos PropertyChanged associados para objetos DataRowView associados.

7. Avalie todas as colunas de expressão, mas atrase a verificação de quaisquer restrições nessas colunas.

8. Gere eventos ListChanged para objetos DataView e eventos PropertyChanged associados para objetos DataRowView associados afetados pelas avaliações da coluna de expressão.

9. Gere os eventos RowChanged ou RowDeleted, conforme aplicável.

10. Verifique as restrições em colunas de expressão.

Observação

As alterações nas colunas de expressão nunca geram eventos DataTable. Alterações nas colunas de expressão apenas geram eventos DataView e DataRowView. As colunas de expressão podem ter dependências em várias outras colunas e podem ser avaliadas várias vezes durante uma única operação DataRow. Cada avaliação de expressão gera eventos e uma única operação DataRow pode gerar vários eventos ListChanged e PropertyChanged quando colunas de expressão são afetadas, possivelmente incluindo vários eventos para a mesma coluna de expressão.

Aviso

Não lance um NullReferenceException dentro do manipulador de eventos RowChanged. Se um NullReferenceException for lançado dentro do evento RowChanged de um DataTable, DataTable será corrompido.

Exemplo

O exemplo a seguir demonstra como criar manipuladores de eventos para os eventos RowChanged, RowChanging, RowDeleted, RowDeleting, ColumnChanged, ColumnChanging, TableNewRow, TableCleared e TableClearing. Cada manipulador de eventos exibe a saída na janela do console quando é acionado.

static void DataTableEvents()
{
    DataTable table = new("Customers");
    // Add two columns, id and name.
    table.Columns.Add("id", typeof(int));
    table.Columns.Add("name", typeof(string));

    // Set the primary key.
    table.Columns["id"].Unique = true;
    table.PrimaryKey = new DataColumn[] { table.Columns["id"] };

    // Add a RowChanged event handler.
    table.RowChanged += Row_Changed;

    // Add a RowChanging event handler.
    table.RowChanging += Row_Changing;

    // Add a RowDeleted event handler.
    table.RowDeleted += Row_Deleted;

    // Add a RowDeleting event handler.
    table.RowDeleting += Row_Deleting;

    // Add a ColumnChanged event handler.
    table.ColumnChanged +=
        Column_Changed;

    // Add a ColumnChanging event handler.
    table.ColumnChanging +=
        Column_Changing;

    // Add a TableNewRow event handler.
    table.TableNewRow +=
        Table_NewRow;

    // Add a TableCleared event handler.
    table.TableCleared +=
        Table_Cleared;

    // Add a TableClearing event handler.
    table.TableClearing +=
        Table_Clearing;

    // Add a customer.
    DataRow row = table.NewRow();
    row["id"] = 1;
    row["name"] = "Customer1";
    table.Rows.Add(row);

    table.AcceptChanges();

    // Change the customer name.
    table.Rows[0]["name"] = "ChangedCustomer1";

    // Delete the row.
    table.Rows[0].Delete();

    // Clear the table.
    table.Clear();
}

static void Row_Changed(object sender, DataRowChangeEventArgs e) =>
    Console.WriteLine("Row_Changed Event: name={0}; action={1}",
        e.Row["name"], e.Action);

static void Row_Changing(object sender, DataRowChangeEventArgs e) =>
    Console.WriteLine("Row_Changing Event: name={0}; action={1}",
        e.Row["name"], e.Action);

static void Row_Deleted(object sender, DataRowChangeEventArgs e) =>
    Console.WriteLine("Row_Deleted Event: name={0}; action={1}",
        e.Row["name", DataRowVersion.Original], e.Action);

static void Row_Deleting(object sender,
DataRowChangeEventArgs e) =>
    Console.WriteLine("Row_Deleting Event: name={0}; action={1}",
        e.Row["name"], e.Action);

static void Column_Changed(object sender, DataColumnChangeEventArgs e) =>
    Console.WriteLine("Column_Changed Event: ColumnName={0}; RowState={1}",
        e.Column.ColumnName, e.Row.RowState);

static void Column_Changing(object sender, DataColumnChangeEventArgs e) =>
    Console.WriteLine("Column_Changing Event: ColumnName={0}; RowState={1}",
        e.Column.ColumnName, e.Row.RowState);

static void Table_NewRow(object sender,
    DataTableNewRowEventArgs e) =>
    Console.WriteLine("Table_NewRow Event: RowState={0}",
        e.Row.RowState.ToString());

static void Table_Cleared(object sender, DataTableClearEventArgs e) =>
    Console.WriteLine("Table_Cleared Event: TableName={0}; Rows={1}",
        e.TableName, e.Table.Rows.Count.ToString());

static void Table_Clearing(object sender, DataTableClearEventArgs e) =>
    Console.WriteLine("Table_Clearing Event: TableName={0}; Rows={1}",
        e.TableName, e.Table.Rows.Count.ToString());

Private Sub DataTableEvents()

    Dim table As New DataTable("Customers")
    ' Add two columns, id and name.
    table.Columns.Add("id", Type.GetType("System.Int32"))
    table.Columns.Add("name", Type.GetType("System.String"))

    ' Set the primary key.
    table.Columns("id").Unique = True
    table.PrimaryKey = New DataColumn() {table.Columns("id")}

    ' Add a RowChanged event handler.
    AddHandler table.RowChanged, _
           New DataRowChangeEventHandler(AddressOf Row_Changed)

    ' Add a RowChanging event handler.
    AddHandler table.RowChanging, _
           New DataRowChangeEventHandler(AddressOf Row_Changing)

    ' Add a RowDeleted event handler.
    AddHandler table.RowDeleted, New _
           DataRowChangeEventHandler(AddressOf Row_Deleted)

    ' Add a RowDeleting event handler.
    AddHandler table.RowDeleting, New _
           DataRowChangeEventHandler(AddressOf Row_Deleting)

    ' Add a ColumnChanged event handler.
    AddHandler table.ColumnChanged, _
           New DataColumnChangeEventHandler(AddressOf Column_Changed)

    ' Add a ColumnChanging event handler for the table.
    AddHandler table.ColumnChanging, New _
           DataColumnChangeEventHandler(AddressOf Column_Changing)

    ' Add a TableNewRow event handler.
    AddHandler table.TableNewRow, New _
           DataTableNewRowEventHandler(AddressOf Table_NewRow)

    ' Add a TableCleared event handler.
    AddHandler table.TableCleared, New _
           DataTableClearEventHandler(AddressOf Table_Cleared)

    ' Add a TableClearing event handler.
    AddHandler table.TableClearing, New _
           DataTableClearEventHandler(AddressOf Table_Clearing)

    ' Add a customer.
    Dim row As DataRow = table.NewRow()
    row("id") = 1
    row("name") = "Customer1"
    table.Rows.Add(row)

    table.AcceptChanges()

    ' Change the customer name.
    table.Rows(0).Item("name") = "ChangedCustomer1"

    ' Delete the row.
    table.Rows(0).Delete()

    ' Clear the table.
    table.Clear()
End Sub


Private Sub Row_Changed(ByVal sender As Object, _
    ByVal e As DataRowChangeEventArgs)
    Console.WriteLine("Row_Changed Event: name={0}; action={1}", _
     e.Row("name"), e.Action)
End Sub

Private Sub Row_Changing(ByVal sender As Object, _
    ByVal e As DataRowChangeEventArgs)
    Console.WriteLine("Row_Changing Event: name={0}; action={1}", _
     e.Row("name"), e.Action)
End Sub

Private Sub Row_Deleted(ByVal sender As Object, _
    ByVal e As DataRowChangeEventArgs)
    Console.WriteLine("Row_Deleted Event: name={0}; action={1}", _
     e.Row("name", DataRowVersion.Original), e.Action)
End Sub

Private Sub Row_Deleting(ByVal sender As Object, _
    ByVal e As DataRowChangeEventArgs)
    Console.WriteLine("Row_Deleting Event: name={0}; action={1}", _
       e.Row("name"), e.Action)
End Sub

Private Sub Column_Changed(ByVal sender As Object, _
    ByVal e As DataColumnChangeEventArgs)
    Console.WriteLine("Column_Changed Event: ColumnName={0}; RowState={1}", _
       e.Column.ColumnName, e.Row.RowState)
End Sub

Private Sub Column_Changing(ByVal sender As Object, _
    ByVal e As DataColumnChangeEventArgs)
    Console.WriteLine("Column_Changing Event: ColumnName={0}; RowState={1}", _
       e.Column.ColumnName, e.Row.RowState)
End Sub

Private Sub Table_NewRow(ByVal sender As Object, _
ByVal e As DataTableNewRowEventArgs)
    Console.WriteLine("Table_NewRow Event: RowState={0}", _
       e.Row.RowState.ToString())
End Sub

Private Sub Table_Cleared(ByVal sender As Object, _
    ByVal e As DataTableClearEventArgs)
    Console.WriteLine("Table_Cleared Event: TableName={0}; Rows={1}", _
       e.TableName, e.Table.Rows.Count.ToString())
End Sub

Private Sub Table_Clearing(ByVal sender As Object, _
    ByVal e As DataTableClearEventArgs)
    Console.WriteLine("Table_Clearing Event: TableName={0}; Rows={1}", _
       e.TableName, e.Table.Rows.Count.ToString())
End Sub

Confira também

• Manipulando dados em uma DataTable
• Manipulação de eventos DataAdapter
• Manipular eventos do DataSet
• Visão geral do ADO.NET