Behandeln von DataAdapter-EreignissenHandling DataAdapter Events

Der ADO.NET-DataAdapter macht drei Ereignisse verfügbar, mit denen Sie auf Änderungen der Daten der Datenquelle reagieren können.The ADO.NET DataAdapter exposes three events that you can use to respond to changes made to data at the data source. In der folgenden Tabelle finden Sie eine Beschreibung dieser DataAdapter-Ereignisse.The following table shows the DataAdapter events.

eventEvent BeschreibungDescription
RowUpdating Es wird gerade ein Aktualisierungs-, Einfüge- oder Löschvorgang für eine Zeile eingeleitet (durch Aufrufen einer der Update-Methoden).An UPDATE, INSERT, or DELETE operation on a row (by a call to one of the Update methods) is about to begin.
RowUpdated Ein Update-, Einfüge- oder Löschvorgang für eine Zeile ist abgeschlossen (durch Aufrufen einer der Update-Methoden).An UPDATE, INSERT, or DELETE operation on a row (by a call to one of the Update methods) is complete.
FillError Während eines Fill-Vorgangs ist ein Fehler aufgetreten.An error has occurred during a Fill operation.

RowUpdating und RowUpdatedRowUpdating and RowUpdated

RowUpdating wird ausgelöst, bevor ein Update einer Zeile des DataSet-Objekts in der Datenquelle verarbeitet wurde.RowUpdating is raised before any update to a row from the DataSet has been processed at the data source. RowUpdated wird ausgelöst, nachdem ein Update einer Zeile des DataSet-Objekts in der Datenquelle verarbeitet wurde.RowUpdated is raised after any update to a row from the DataSet has been processed at the data source. Folglich können Sie mit dem RowUpdating-Ereignis das Verhalten von Updates ändern, bevor sie vorgenommen werden, zusätzliche Behandlungsoptionen beim Auftreten eines Updates anbieten, einen Verweis auf eine aktualisierte Zeile beibehalten, das aktuelle Update abbrechen und es für die spätere Verarbeitung in einem Stapelverarbeitungsprozess einplanen usw.As a result, you can use RowUpdating to modify update behavior before it happens, to provide additional handling when an update will occur, to retain a reference to an updated row, to cancel the current update and schedule it for a batch process to be processed later, and so on. RowUpdated ist hilfreich bei der Reaktion auf Fehler und Ausnahmen, die während des Updates auftreten.RowUpdated is useful for responding to errors and exceptions that occur during the update. Sie können dem DataSet Fehlerinformationen, eine Wiederholungslogik u. a. m. hinzufügen.You can add error information to the DataSet, as well as retry logic, and so on.

Die Argumente RowUpdatingEventArgs und RowUpdatedEventArgs, die an die Ereignisse RowUpdating und RowUpdated übergeben werden, enthalten Folgendes: eine Command-Eigenschaft, die auf das Command-Objekt verweist, das zur Ausführung des Updates verwendet wird, eine Row-Eigenschaft, die auf das DataRow-Objekt verweist, dass die aktualisierten Informationen enthält, eine StatementType-Eigenschaft zur Angabe der auszuführenden Updatestypen, die TableMapping, sofern zutreffend, und den Status des Vorgangs.The RowUpdatingEventArgs and RowUpdatedEventArgs arguments passed to the RowUpdating and RowUpdated events include the following: a Command property that references the Command object being used to perform the update; a Row property that references the DataRow object containing the updated information; a StatementType property for what type of update is being performed; the TableMapping, if applicable; and the Status of the operation.

Mit der Status-Eigenschaft können Sie ermitteln, ob während des Vorgangs ein Fehler aufgetreten ist, und gegebenenfalls die Aktionen für die aktuellen und die resultierenden Zeilen steuern.You can use the Status property to determine if an error has occurred during the operation and, if desired, to control the actions against the current and resulting rows. Wenn das Ereignis eintritt, entspricht die Status-Eigenschaft entweder Continue oder ErrorsOccurred.When the event occurs, the Status property equals either Continue or ErrorsOccurred. In der folgenden Tabelle sind die Werte dargestellt, die Sie für die Status-Eigenschaft festlegen können, um nachfolgende Aktionen während des Updates zu steuern.The following table shows the values to which you can set the Status property in order to control later actions during the update.

StatusStatus BeschreibungDescription
Continue Setzt den Aktualisierungsvorgang fort.Continue the update operation.
ErrorsOccurred Bricht den Updatevorgang ab und löst eine Ausnahme aus.Abort the update operation and throw an exception.
SkipCurrentRow Ignoriert die aktuelle Zeile und setzt den Aktualisierungsvorgang fort.Ignore the current row and continue the update operation.
SkipAllRemainingRows Bricht den Aktualisierungsvorgang ab, löst jedoch keine Ausnahme aus.Abort the update operation but do not throw an exception.

Durch das Festlegen der Status-Eigenschaft auf ErrorsOccurred wird eine Ausnahme ausgelöst.Setting the Status property to ErrorsOccurred causes an exception to be thrown. Welche Ausnahme ausgelöst wird, können Sie steuern, indem Sie für die Errors-Eigenschaft die gewünschte Ausnahme angeben.You can control which exception is thrown by setting the Errors property to the desired exception. Wenn Sie einen der anderen Werte für Status verwenden, wird keine Ausnahme ausgelöst.Using one of the other values for Status prevents an exception from being thrown.

Sie können auch die ContinueUpdateOnError-Eigenschaft verwenden, um Fehler für aktualisierte Zeilen zu behandeln.You can also use the ContinueUpdateOnError property to handle errors for updated rows. Wenn für DataAdapter.ContinueUpdateOnError der Wert true angegeben ist und das Updates einer Zeile eine Ausnahme auslöst, wird der Text der Ausnahme in die RowError-Information der entsprechenden Zeile aufgenommen. Die Verarbeitung wird fortgesetzt, ohne dass eine Ausnahme ausgelöst wird.If DataAdapter.ContinueUpdateOnError is true, when an update to a row results in an exception being thrown, the text of the exception is placed into the RowError information of the particular row, and processing continues without throwing an exception. Auf diese Weise können Sie auf Fehler reagieren, wenn Update abgeschlossen wurde. Dagegen können Sie beim RowUpdated-Ereignis auf den Fehler reagieren, sobald er festgestellt wird.This enables you to respond to errors when the Update is complete, in contrast to the RowUpdated event, which enables you to respond to errors when the error is encountered.

Im folgenden Codebeispiel wird dargestellt, wie Ereignishandler hinzugefügt und entfernt werden.The following code sample shows how to both add and remove event handlers. Der RowUpdating-Ereignishandler schreibt ein Protokoll aller gelöschten Datensätze und versieht die Löschvorgangaufzeichnungen jeweils mit einem Timestamp.The RowUpdating event handler writes a log of all deleted records with a time stamp. Der RowUpdated -Ereignishandler fügt Fehlerinformationen RowError zur-Eigenschaft der Zeile in der DataSethinzu, unterdrückt die Ausnahme und setzt die Verarbeitung fort (Spiegelung ContinueUpdateOnErrordes Verhaltens von = true).The RowUpdated event handler adds error information to the RowError property of the row in the DataSet, suppresses the exception, and continues processing (mirroring the behavior of ContinueUpdateOnError = true).

' Assumes that connection is a valid SqlConnection object.  
Dim custAdapter As SqlDataAdapter = New SqlDataAdapter( _  
  "SELECT CustomerID, CompanyName FROM Customers", connection)  
  
' Add handlers.  
AddHandler custAdapter.RowUpdating, New SqlRowUpdatingEventHandler( _  
  AddressOf OnRowUpdating)  
AddHandler custAdapter.RowUpdated, New SqlRowUpdatedEventHandler(  
  AddressOf OnRowUpdated)  
  
' Set DataAdapter command properties, fill DataSet, and modify DataSet.  
  
custAdapter.Update(custDS, "Customers")  
  
' Remove handlers.  
RemoveHandler custAdapter.RowUpdating, _  
  New SqlRowUpdatingEventHandler(AddressOf OnRowUpdating)  
RemoveHandler custAdapter.RowUpdated, _  
  New SqlRowUpdatedEventHandler(AddressOf OnRowUpdated)  
  
Private Shared Sub OnRowUpdating(sender As Object, _  
  args As SqlRowUpdatingEventArgs)  
  If args.StatementType = StatementType.Delete Then  
    Dim tw As System.IO.TextWriter = _  
  System.IO.File.AppendText("Deletes.log")  
    tw.WriteLine( _  
      "{0}: Customer {1} Deleted.", DateTime.Now, args.Row(_  
      "CustomerID", DataRowVersion.Original))  
    tw.Close()  
  End If  
End Sub  
  
Private Shared Sub OnRowUpdated( _  
  sender As Object, args As SqlRowUpdatedEventArgs)  
  If args.Status = UpdateStatus.ErrorsOccurred  
    args.Status = UpdateStatus.SkipCurrentRow  
    args.Row.RowError = args.Errors.Message  
  End If  
End Sub  
// Assumes that connection is a valid SqlConnection object.  
SqlDataAdapter custAdapter = new SqlDataAdapter(  
  "SELECT CustomerID, CompanyName FROM Customers", connection);  
  
// Add handlers.  
custAdapter.RowUpdating += new SqlRowUpdatingEventHandler(OnRowUpdating);  
custAdapter.RowUpdated += new SqlRowUpdatedEventHandler(OnRowUpdated);  
  
// Set DataAdapter command properties, fill DataSet, modify DataSet.  
  
custAdapter.Update(custDS, "Customers");  
  
// Remove handlers.  
custAdapter.RowUpdating -= new SqlRowUpdatingEventHandler(OnRowUpdating);  
custAdapter.RowUpdated -= new SqlRowUpdatedEventHandler(OnRowUpdated);  
  
protected static void OnRowUpdating(  
  object sender, SqlRowUpdatingEventArgs args)  
{  
  if (args.StatementType == StatementType.Delete)  
  {  
    System.IO.TextWriter tw = System.IO.File.AppendText("Deletes.log");  
    tw.WriteLine(  
      "{0}: Customer {1} Deleted.", DateTime.Now,   
       args.Row["CustomerID", DataRowVersion.Original]);  
    tw.Close();  
  }  
}  
  
protected static void OnRowUpdated(  
  object sender, SqlRowUpdatedEventArgs args)  
{  
  if (args.Status == UpdateStatus.ErrorsOccurred)  
  {  
    args.Row.RowError = args.Errors.Message;  
    args.Status = UpdateStatus.SkipCurrentRow;  
  }  
}  

FillErrorFillError

Der DataAdapter gibt das FillError-Ereignis aus, wenn während des Fill-Vorgangs ein Fehler auftritt.The DataAdapter issues the FillError event when an error occurs during a Fill operation. Dieser Fehlertyp tritt auf, wenn die Daten in der hinzugefügten Zeile nicht ohne Präzisionsverlust in einen .NET Framework-Typ konvertiert werden konnten.This type of error commonly occurs when the data in the row being added could not be converted to a .NET Framework type without some loss of precision.

Wenn während eines Fill-Vorgangs ein Fehler auftritt, wird der DataTable die aktuelle Zeile nicht hinzugefügt.If an error occurs during a Fill operation, the current row is not added to the DataTable. Mit dem FillError-Ereignis können Sie den Fehler auflösen und die Zeile hinzufügen oder die betreffende Zeile ignorieren und den Fill-Vorgang fortsetzen.The FillError event enables you to resolve the error and add the row, or to ignore the excluded row and continue the Fill operation.

Die an das FillErrorEventArgs-Ereignis übergebenen FillError können mehrere Eigenschaften enthalten, mit denen Sie auf Fehler reagieren und diese auflösen können.The FillErrorEventArgs passed to the FillError event can contain several properties that enable you to respond to and resolve errors. In der folgenden Tabelle werden die Eigenschaften des FillErrorEventArgs-Objekts dargestellt.The following table shows the properties of the FillErrorEventArgs object.

EigenschaftProperty BeschreibungDescription
Errors Die Exception, die aufgetreten ist.The Exception that occurred.
DataTable Das DataTable-Objekt, das ausgefüllt wurde, als der Fehler auftrat.The DataTable object being filled when the error occurred.
Values Ein Array aus Objekten, das die Werte der beim Eintreten des Fehlers hinzugefügten Zeile enthält.An array of objects that contains the values of the row being added when the error occurred. Die Ordinalzahlverweise des Values-Arrays entsprechen den Ordinalzahlverweisen der Spalten der hinzugefügten Zeile.The ordinal references of the Values array correspond to the ordinal references of the columns of the row being added. So ist z. B. Values[0] der Wert, der als erste Spalte der Zeile hinzugefügt wurde.For example, Values[0] is the value that was being added as the first column of the row.
Continue Sie können festlegen, ob eine Ausnahme ausgelöst werden soll oder nicht.Allows you to choose whether or not to throw an exception. Durch das Festlegen der Continue-Eigenschaft auf false wird der aktuelle Fill-Vorgang angehalten, und es wird eine Ausnahme ausgelöst.Setting the Continue property to false will halt the current Fill operation, and an exception will be thrown. Durch das Festlegen der Continue-Eigenschaft auf true wird der Fill-Vorgang trotz des Fehlers fortgesetzt.Setting Continue to true continues the Fill operation despite the error.

Im folgenden Codebeispiel wird ein Ereignishandler für das FillError-Ereignis DataAdapter hinzugefügt.The following code example adds an event handler for the FillError event of the DataAdapter. Im FillError-Ereigniscode bestimmt das Beispiel, ob die Möglichkeit von Präzisionsverlust besteht, und bietet die Chance, auf die Ausnahme zu reagieren.In the FillError event code, the example determines if there is the potential for precision loss, providing the opportunity to respond to the exception.

AddHandler adapter.FillError, New FillErrorEventHandler( _  
  AddressOf FillError)  
  
Dim dataSet As DataSet = New DataSet  
adapter.Fill(dataSet, "ThisTable")  
  
Private Shared Sub FillError(sender As Object, _  
  args As FillErrorEventArgs)  
  If args.Errors.GetType() Is Type.GetType("System.OverflowException") Then  
    ' Code to handle precision loss.  
    ' Add a row to table using the values from the first two columns.  
    DataRow myRow = args.DataTable.Rows.Add(New Object() _  
      {args.Values(0), args.Values(1), DBNull.Value})  
    ' Set the RowError containing the value for the third column.  
    myRow.RowError = _  
      "OverflowException encountered. Value from data source: " & _  
      args.Values(2)  
    args.Continue = True  
  End If  
End Sub  
adapter.FillError += new FillErrorEventHandler(FillError);  
  
DataSet dataSet = new DataSet();  
adapter.Fill(dataSet, "ThisTable");  
  
protected static void FillError(object sender, FillErrorEventArgs args)  
{  
  if (args.Errors.GetType() == typeof(System.OverflowException))  
  {  
    // Code to handle precision loss.  
    //Add a row to table using the values from the first two columns.  
    DataRow myRow = args.DataTable.Rows.Add(new object[]  
       {args.Values[0], args.Values[1], DBNull.Value});  
    //Set the RowError containing the value for the third column.  
    myRow.RowError =   
       "OverflowException Encountered. Value from data source: " +  
       args.Values[2];  
    args.Continue = true;  
  }  
}  

Siehe auchSee also