Gestion des événements de DataTableHandling DataTable Events

L'objet DataTable fournit une série d'événements pouvant être traités par une application.The DataTable object provides a series of events that can be processed by an application. Le tableau ci-dessous décrit les événements DataTable.The following table describes DataTable events.

ÉvénementEvent DescriptionDescription
Initialized Se produit après que la méthode EndInit d'un DataTable a été appelée.Occurs after the EndInit method of a DataTable is called. Cet événement est destiné principalement à prendre en charge les scénarios au moment du design.This event is intended primarily to support design-time scenarios.
ColumnChanged Se produit après qu'une valeur a été modifiée avec succès dans un DataColumn.Occurs after a value has been successfully changed in a DataColumn.
ColumnChanging Se produit quand une valeur a été proposée pour un DataColumn.Occurs when a value has been submitted for a DataColumn.
RowChanged Se produit après qu'une valeur DataColumn ou le RowState d'un DataRow ont été modifiés avec succès dans le DataTable.Occurs after a DataColumn value or the RowState of a DataRow in the DataTable has been changed successfully.
RowChanging Se produit quand une modification a été proposée pour une valeur DataColumn ou le RowState d'un DataRow dans le DataTable.Occurs when a change has been submitted for a DataColumn value or the RowState of a DataRow in the DataTable.
RowDeleted Se produit après qu'un DataRow dans le DataTable a été marqué comme Deleted.Occurs after a DataRow in the DataTable has been marked as Deleted.
RowDeleting Se produit avant qu'un DataRow dans le DataTable soit marqué comme Deleted.Occurs before a DataRow in the DataTable is marked as Deleted.
TableCleared Se produit après qu'un appel à la méthode Clear du DataTable a effacé avec succès chaque DataRow.Occurs after a call to the Clear method of the DataTable has successfully cleared every DataRow.
TableClearing Se produit après que la méthode Clear a été appelée mais avant que l'opération Clear commence.Occurs after the Clear method is called but before the Clear operation begins.
TableNewRow Se produit après la création d'un nouveau DataRow par un appel à la méthode NewRow du DataTable.Occurs after a new DataRow is created by a call to the NewRow method of the DataTable.
Disposed Se produit lorsque le DataTable a la valeur Disposed.Occurs when the DataTable is Disposed. Hérité de l'objet MarshalByValueComponent.Inherited from MarshalByValueComponent.

Notes

La plupart des opérations qui ajoutent ou suppriment des lignes ne déclenchent pas les événements ColumnChanged et ColumnChanging.Most operations that add or delete rows do not raise the ColumnChanged and ColumnChanging events. Toutefois, la méthode ReadXml déclenche les événements ColumnChanged et ColumnChanging, à moins que XmlReadMode ait la valeur DiffGram ou Auto lorsque le document XML lu est un DiffGram.However, the ReadXml method does raise ColumnChanged and ColumnChanging events, unless the XmlReadMode is set to DiffGram or is set to Auto when the XML document being read is a DiffGram.

Avertissement

Les données peuvent être endommagées si elles sont modifiées dans un DataSet à partir duquel l'événement RowChanged est déclenché.Data corruption can occur if data is modified in a DataSet from which the RowChanged event is raised. Aucune exception n'est levée en cas d'endommagement de ce type.No exception will be raised if such data corruption occurs.

La propriété Constraints détient une instance ConstraintCollection.The Constraints property holds a ConstraintCollection instance. La classe ConstraintCollection expose un événement CollectionChanged.The ConstraintCollection class exposes a CollectionChanged event. Cet événement se déclenche lorsqu'une contrainte est ajoutée, modifiée ou supprimée dans ConstraintCollection.This event fires when a constraint is added, modified, or removed from the ConstraintCollection.

La propriété Columns détient une instance DataColumnCollection.The Columns property holds a DataColumnCollection instance. La classe DataColumnCollection expose un événement CollectionChanged.The DataColumnCollection class exposes a CollectionChanged event. Cet événement se déclenche lorsqu'un DataColumn est ajouté, modifié ou supprimé dans DataColumnCollection.This event fires when a DataColumn is added, modified, or removed from the DataColumnCollection. Les modifications à l'origine du déclenchement de l'événement incluent des modifications du nom, du type, de l'expression ou de la position ordinale d'une colonne.Modifications that cause the event to fire include changes to the name, type, expression or ordinal position of a column.

La propriété Tables d'un DataSet détient une instance DataTableCollection.The Tables property of a DataSet holds a DataTableCollection instance. La classe DataTableCollection expose un événement CollectionChanged et un événement CollectionChanging.The DataTableCollection class exposes both a CollectionChanged and a CollectionChanging event. Ces événements se déclenchent lorsqu'un DataTable est ajouté ou supprimé dans le DataSet.These events fire when a DataTable is added to or removed from the DataSet.

Les modifications apportées aux DataRows peuvent également déclencher des événements pour un DataView associé.Changes to DataRows can also trigger events for an associated DataView. La classe DataView expose un événement ListChanged qui se déclenche lorsqu'une valeur DataColumn change ou lorsque la composition ou l'ordre de tri de la vue changent.The DataView class exposes a ListChanged event that fires when a DataColumn value changes or when the composition or sort order of the view changes. La classe DataRowView expose un événement PropertyChanged qui se déclenche lorsqu'une valeur DataColumn associée change.The DataRowView class exposes a PropertyChanged event that fires when an associated DataColumn value changes.

Ordre des opérationsSequence of Operations

Voici l'ordre des opérations qui se produisent lorsqu'un DataRow est ajouté, modifié ou supprimé :Here is the sequence of operations that occur when a DataRow is added, modified, or deleted:

  1. Créez l'enregistrement proposé et appliquez les modifications éventuelles.Create the proposed record and apply any changes.

  2. Vérifiez les contraintes pour les colonnes autres que les colonnes d'expression.Check constraints for non-expression columns.

  3. Déclenchez les événements RowChanging ou RowDeleting selon les besoins.Raise the RowChanging or RowDeleting events as applicable.

  4. Définissez l'enregistrement proposé comme enregistrement en cours.Set the proposed record to be the current record.

  5. Mettez à jour les index associés éventuels.Update any associated indexes.

  6. Déclenchez les événements ListChanged pour les objets DataView associés et les événements PropertyChanged pour les objets DataRowView associés.Raise ListChanged events for associated DataView objects and PropertyChanged events for associated DataRowView objects.

  7. Évaluez toutes les colonnes d'expression, mais retardez la vérification des contraintes éventuelles sur ces colonnes.Evaluate all expression columns, but delay checking any constraints on these columns.

  8. Déclenchez les événements ListChanged pour les objets DataView associés et les événements PropertyChanged pour les objets DataRowView associés affectés par les évaluations des colonnes d'expression.Raise ListChanged events for associated DataView objects and PropertyChanged events for associated DataRowView objects affected by the expression column evaluations.

  9. Déclenchez les événements RowChanged ou RowDeleted selon les besoins.Raise RowChanged or RowDeleted events as applicable.

  10. Vérifiez les contraintes sur les colonnes d'expression.Check constraints on expression columns.

Notes

Des modifications apportées aux colonnes d'expression ne déclenchent jamais des événements DataTable.Changes to expression columns never raise DataTable events. Des modifications apportées aux colonnes d'expression déclenchent uniquement des événements DataView et DataRowView.Changes to expression columns only raise DataView and DataRowView events. Les colonnes d'expression peuvent avoir des dépendances sur plusieurs autres colonnes et peuvent être évaluées plusieurs fois au cours d'une même opération DataRow.Expression columns can have dependencies on multiple other columns, and can be evaluated multiple times during a single DataRow operation. Chaque évaluation d'expression déclenche des événements et une opération DataRow individuelle peut déclencher plusieurs événements ListChanged et PropertyChanged lorsque des colonnes d'expression sont affectées, dont éventuellement plusieurs événements pour une même colonne d'expression.Each expression evaluation raises events, and a single DataRow operation can raise multiple ListChanged and PropertyChanged events when expression columns are affected, possibly including multiple events for the same expression column.

Avertissement

Ne levez pas de NullReferenceException à l'intérieur du gestionnaire d'événements RowChanged.Do not throw a NullReferenceException within the RowChanged event handler. Si une NullReferenceException est levée à l'intérieur de l'événement RowChanged d'une DataTable, DataTable sera corrompue.If a NullReferenceException is thrown within the RowChanged event of a DataTable, then the DataTable will be corrupted.

ExempleExample

L'exemple ci-dessous montre comment créer des gestionnaires d'événements pour les événements RowChanged, RowChanging, RowDeleted, RowDeleting, ColumnChanged, ColumnChanging, TableNewRow, TableCleared et TableClearing.The following example demonstrates how to create event handlers for the RowChanged, RowChanging, RowDeleted, RowDeleting, ColumnChanged, ColumnChanging, TableNewRow, TableCleared, and TableClearing events. Chaque gestionnaire d'événements affiche la sortie dans la fenêtre de console lorsqu'il est déclenché.Each event handler displays output in the console window when it is fired.

static void DataTableEvents()
{
    DataTable table = new DataTable("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 += new DataRowChangeEventHandler(Row_Changed);

    // Add a RowChanging event handler.
    table.RowChanging += new DataRowChangeEventHandler(Row_Changing);

    // Add a RowDeleted event handler.
    table.RowDeleted += new DataRowChangeEventHandler(Row_Deleted);

    // Add a RowDeleting event handler.
    table.RowDeleting += new DataRowChangeEventHandler(Row_Deleting);

    // Add a ColumnChanged event handler.
    table.ColumnChanged += new
        DataColumnChangeEventHandler(Column_Changed);

    // Add a ColumnChanging event handler.
    table.ColumnChanging += new
        DataColumnChangeEventHandler(Column_Changing);

    // Add a TableNewRow event handler.
    table.TableNewRow += new
        DataTableNewRowEventHandler(Table_NewRow);

    // Add a TableCleared event handler.
    table.TableCleared += new
        DataTableClearEventHandler(Table_Cleared);

    // Add a TableClearing event handler.
    table.TableClearing += new
        DataTableClearEventHandler(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();
}


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

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

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

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

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

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

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

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

private 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

Voir aussiSee also