Controlar eventos de DataAdapterHandling DataAdapter Events

DataAdapter de ADO.NET expone tres eventos que se pueden utilizar para responder a los cambios efectuados en los datos en el origen.The ADO.NET DataAdapter exposes three events that you can use to respond to changes made to data at the data source. En la siguiente tabla se muestran los eventos de DataAdapter.The following table shows the DataAdapter events.

EventoEvent DescripciónDescription
RowUpdating Está a punto de comenzar una operación UPDATE, INSERT o DELETE en una fila (mediante una llamada a uno de los métodos Update).An UPDATE, INSERT, or DELETE operation on a row (by a call to one of the Update methods) is about to begin.
RowUpdated Se ha completado una operación UPDATE, INSERT o DELETE en una fila (mediante una llamada a uno de los métodos Update).An UPDATE, INSERT, or DELETE operation on a row (by a call to one of the Update methods) is complete.
FillError Se ha producido un error durante una operación Fill.An error has occurred during a Fill operation.

RowUpdating y RowUpdatedRowUpdating and RowUpdated

El evento RowUpdating se activa antes de que se produzca la actualización de una fila del DataSet en el origen de datos.RowUpdating is raised before any update to a row from the DataSet has been processed at the data source. El evento RowUpdated se activa después de que se produzca la actualización de una fila del DataSet en el origen de datos.RowUpdated is raised after any update to a row from the DataSet has been processed at the data source. Por lo tanto, puede utilizar RowUpdating para modificar el comportamiento de la actualización antes de que tenga lugar, proporcionar un control adicional del proceso durante la actualización, conservar una referencia a la fila actualizada, cancelar la actualización actual y programarla como parte de un proceso por lotes que se ejecutará después, entre otras acciones.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 es útil para reaccionar cuando se producen errores y excepciones durante la actualización.RowUpdated is useful for responding to errors and exceptions that occur during the update. Puede agregar información de errores al DataSet, así como procedimientos de reintento, etcétera.You can add error information to the DataSet, as well as retry logic, and so on.

Los argumentos RowUpdatingEventArgs y RowUpdatedEventArgs que se pasan a los eventos RowUpdating y RowUpdated incluyen lo siguiente: una propiedad Command que hace referencia al objeto Command que se está utilizando para realizar la actualización; una propiedad Row que hace referencia al objeto DataRow que contiene la información actualizada; una propiedad StatementType para el tipo de actualización que se está llevando a cabo; el valor de TableMapping, si es pertinente y el valor de Status de la operación.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.

Puede utilizar la propiedad Status para determinar si se ha producido o no un error durante la operación y, si lo desea, controlar las acciones que se emprenden en las filas actuales y las resultantes de la operación.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. Cuando se produce el evento, la propiedad Status toma el valor Continue o ErrorsOccurred.When the event occurs, the Status property equals either Continue or ErrorsOccurred. En la tabla siguiente se muestran los valores que se pueden asignar a la propiedad Status para controlar las acciones posteriores en el proceso de actualización.The following table shows the values to which you can set the Status property in order to control later actions during the update.

StatusStatus DescripciónDescription
Continue Continuar la operación de actualización.Continue the update operation.
ErrorsOccurred Anular la operación de actualización e iniciar una excepción.Abort the update operation and throw an exception.
SkipCurrentRow Omitir la fila actual y continuar la operación de actualización.Ignore the current row and continue the update operation.
SkipAllRemainingRows Anular la operación de actualización sin iniciar una excepción.Abort the update operation but do not throw an exception.

Al establecer a la propiedad Status en el valor ErrorsOccurred se inicia una excepción.Setting the Status property to ErrorsOccurred causes an exception to be thrown. Puede controlar qué excepciones se inician si establece la propiedad Errors en la excepción que desee.You can control which exception is thrown by setting the Errors property to the desired exception. El uso de un valor distinto para la propiedad Status evita que se inicie una excepción.Using one of the other values for Status prevents an exception from being thrown.

También puede utilizar la propiedad ContinueUpdateOnError para controlar los errores producidos en las filas actualizadas.You can also use the ContinueUpdateOnError property to handle errors for updated rows. Cuando DataAdapter.ContinueUpdateOnError tiene el valor true y la actualización de una fila inicia una excepción, el texto de la excepción se coloca en la información RowError de la fila en cuestión y el proceso continúa sin que se inicie una excepción.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. De esta forma, puede responder a los errores cuando se complete el proceso Update, a diferencia del evento RowUpdated, que permite responder a los errores cuando se detectan.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.

En el ejemplo de código siguiente se muestra cómo se pueden agregar y quitar controladores de eventos.The following code sample shows how to both add and remove event handlers. El controlador de eventos RowUpdating mantiene un registro de todos los registros eliminados y una marca de tiempo asociada a cada uno de ellos.The RowUpdating event handler writes a log of all deleted records with a time stamp. El RowUpdated controlador de eventos agrega RowError información de error DataSeta la propiedad de la fila en ContinueUpdateOnError = trueel , suprime la excepción y continúa el procesamiento (reflejando el comportamiento de ).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

Cuando se produce un error durante una operación DataAdapter, el objeto FillError provoca el evento Fill.The DataAdapter issues the FillError event when an error occurs during a Fill operation. Este tipo de error suele producirse si al convertir los datos de la fila que se agrega a un tipo de .NET Framework se produce una pérdida de precisión.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.

Si el error se produce durante una operación Fill, la fila actual no se agrega al objeto DataTable.If an error occurs during a Fill operation, the current row is not added to the DataTable. El evento FillError permite resolver el error y agregar la fila o bien pasar por alto la fila excluida y continuar con la operación Fill.The FillError event enables you to resolve the error and add the row, or to ignore the excluded row and continue the Fill operation.

El objeto FillErrorEventArgs que se pasa al evento FillError puede contener varias propiedades que permiten reaccionar en caso de errores y resolverlos.The FillErrorEventArgs passed to the FillError event can contain several properties that enable you to respond to and resolve errors. En la tabla siguiente se muestran las propiedades del objeto FillErrorEventArgs.The following table shows the properties of the FillErrorEventArgs object.

PropiedadProperty DescripciónDescription
Errors Exception que se ha producido.The Exception that occurred.
DataTable Objeto DataTable que se estaba llenando cuando ocurrió el error.The DataTable object being filled when the error occurred.
Values Matriz de objetos que contiene los valores de la fila que se está agregando cuando se produce el error.An array of objects that contains the values of the row being added when the error occurred. Las referencias de orden de la matriz Values coinciden con las de las columnas de la fila que se está agregando.The ordinal references of the Values array correspond to the ordinal references of the columns of the row being added. Por ejemplo, Values[0] es el valor que se agrega en la primera columna de la fila.For example, Values[0] is the value that was being added as the first column of the row.
Continue Permite elegir si desea iniciar una excepción o no.Allows you to choose whether or not to throw an exception. Si establece la propiedad Continue en false, la operación Fill en curso se detiene y se inicia una excepción.Setting the Continue property to false will halt the current Fill operation, and an exception will be thrown. Si establece la propiedad Continue en true, la operación Fill continúa pese al error.Setting Continue to true continues the Fill operation despite the error.

En el siguiente ejemplo de código se agrega un controlador para el evento FillError del objeto DataAdapter.The following code example adds an event handler for the FillError event of the DataAdapter. En el código del evento FillError, el ejemplo determina si hay una posible pérdida de precisión y ofrece la posibilidad de reaccionar ante la excepción.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;  
  }  
}  

Consulte tambiénSee also