Validate data in datasets

Validating data is the process of confirming that the values being entered into data objects conform to the constraints within a dataset's schema. The validation process also confirms that these values are following the rules that have been established for your application. It's a good practice to validate data prior to sending updates to the underlying database. This reduces errors as well as the potential number of round trips between an application and the database.

You can confirm that data that's being written to a dataset is valid by building validation checks into the dataset itself. The dataset can check the data no matter how the update is being performed — whether directly by controls in a form, within a component, or in some other way. Because the dataset is part of your application (unlike the database backend), it's a logical place to build application-specific validation.

The best place to add validation to your application is in the dataset's partial class file. In Visual Basic or Visual C#, open the Dataset Designer and double-click the column or table for which you want to create validation. This action automatically creates an ColumnChanging or RowChanging event handler. For more information, see How to: Validate Data During Column Changes or How to: Validate Data During Row Changes. For a complete example, see Walkthrough: Adding Validation to a Dataset.

Validate data

Validation within a dataset can be accomplished in the following ways:

• By creating your own application-specific validation that can check values in an individual data column during changes. For more information, see How to: Validate Data During Column Changes.

• By creating your own application-specific validation that can check data to values while an entire data row is changing. For more information, see How to: Validate Data During Row Changes.

• By creating keys, unique constraints, and so on as part of the actual schema definition of the dataset. For more information about incorporating validation into the schema definition, see Constraining a DataColumn to Contain Unique Values.

• By setting the properties of the DataColumn object's, such as MaxLength, AllowDBNull, and Unique.

  Several events are raised by the DataTable object when a change is occurring in a record:

• The ColumnChanging and ColumnChanged events are raised during and after each change to an individual column. The ColumnChanging event is useful when you want to validate changes in specific columns. Information about the proposed change is passed as an argument with the event. For more information, see How to: Validate Data During Column Changes.

• The RowChanging and RowChanged events are raised during and after any change in a row. The RowChanging event is more general. It indicates that a change is occurring somewhere in the row, but you don't know which column has changed. For more information, see How to: Validate Data During Row Changes.

  By default, each change to a column therefore raises four events. The first is the ColumnChanging and ColumnChanged events for the specific column that's being changed. Next are the RowChanging and RowChanged events. If multiple changes are being made to the row, the events will be raised for each change.

The event you choose depends on how granular you want the validation to be. If it's important that you catch an error immediately when a column changes, build validation by using the ColumnChanging event. Otherwise, use the RowChanging event, which might result in catching several errors at once. Additionally, if your data is structured so that the value of one column is validated based on the contents of another column, then perform your validation during the RowChanging event.

When records are updated, the DataTable object raises events that you can respond to as changes are occurring and after changes are made.

If your application uses a typed dataset, you can create strongly typed event handlers. This will add four additional typed events that you can create handlers for: dataTableNameRowChanging, dataTableNameRowChanged, dataTableNameRowDeleting, and dataTableNameRowDeleted. These typed event handlers pass an argument that includes the column names of your table that make code easier to write and read.

Data update events

The ColumnChanging, RowChanging, and RowDeleting events are raised during the update process. You can use these events to validate data or perform other types of processing. Because the update is in process during these events, you can cancel it by throwing an exception, which prevents the update from finishing.

The ColumnChanged, RowChanged and RowDeleted events are notification events that are raised when the update has finished successfully. These events are useful when you want to take further action based on a successful update.

Validate data during column changes

You can validate data when the value in a data column changes by responding to the ColumnChanging event. When raised, this event passes an event argument (ProposedValue) that contains the value that's being proposed for the current column. Based on the contents of e.ProposedValue, you can:

• Accept the proposed value by doing nothing.

• Reject the proposed value by setting the column error (SetColumnError) from within the column-changing event handler.

• Optionally use an ErrorProvider control to display an error message to the user. For more information, see ErrorProvider Component.

  Validation can also be performed during the RowChanging event. For more information, see How to: Validate Data During Row Changes.

Validate data during row changes

You can write code to verify that each column you want to validate contains data that meets the requirements of your application. Do this by setting the column to indicate that it contains an error if a proposed value is unacceptable. The following examples set a column error when the Quantity column is 0 or less. The row-changing event handlers should resemble the following examples.

To validate data when a row changes (Visual Basic)

1. Open your dataset in the Dataset Designer. For more information, see How to: Open a Dataset in the Dataset Designer.

2. Double-click the title bar of the table you want to validate. This action automatically creates the RowChanging event handler of the DataTable in the dataset's partial-class file.

   Tip

   Double-click to the left of the table name to create the row-changing event handler. If you double-click the table name, you can edit it.

   Private Sub Order_DetailsDataTable_Order_DetailsRowChanging(
       ByVal sender As System.Object, 
       ByVal e As Order_DetailsRowChangeEvent
     ) Handles Me.Order_DetailsRowChanging
   
       If CType(e.Row.Quantity, Short) <= 0 Then
           e.Row.SetColumnError("Quantity", "Quantity must be greater than 0")
       Else
           e.Row.SetColumnError("Quantity", "")
       End If
   End Sub
   

To validate data when a row changes (C#)

1. Open your dataset in the Dataset Designer. For more information, see How to: Open a Dataset in the Dataset Designer.

2. Double-click the title bar of the table you want to validate. This action creates a partial-class file for the DataTable.

   Note

   The Dataset Designer does not automatically create an event handler for the RowChanging event. You have to create a method to handle the RowChanging event, and run code to hook up the event in the table's initialization method.

3. Copy the following code into the partial class:

   public override void EndInit()
   {
       base.EndInit();
       Order_DetailsRowChanging += TestRowChangeEvent;
   }
   
   public void TestRowChangeEvent(object sender, Order_DetailsRowChangeEvent e)
   {
       if ((short)e.Row.Quantity <= 0)
       {
           e.Row.SetColumnError("Quantity", "Quantity must be greater than 0");
       }
       else
       {
           e.Row.SetColumnError("Quantity", "");
       }
   }
   

To retrieve changed rows

Each row in a data table has a RowState property that keeps track of the current state of that row by using the values in the DataRowState enumeration. You can return changed rows from a dataset or data table by calling the GetChanges method of a DataSet or DataTable. You can verify that changes exist prior to calling GetChanges by calling the HasChanges method of a dataset. For more information about HasChanges, see How to: Check for Changed Rows.

Calling the GetChanges method of a dataset or data table returns a new dataset or data table that contains only records that have been changed. If you want to get specific records — for example, only new records or only modified records — you can pass a value from the DataRowState enumeration as a parameter to the GetChanges method.

Use the DataRowVersion enumeration to access the different versions of a row (for example, the original values that were in a row prior to processing it).

To get all changed records from a dataset

• Call the GetChanges method of a dataset.

  The following example creates a new dataset called changedRecords and populates it with all the changed records from another dataset called dataSet1.

  DataSet changedRecords = dataSet1.GetChanges();
  

  Dim changedRecords As DataSet = DataSet1.GetChanges()
  

To get all changed records from a data table

• Call the GetChanges method of a DataTable.

  The following example creates a new data table called changedRecordsTable and populates it with all the changed records from another data table called dataTable1.

  DataTable changedRecordsTable = dataTable1.GetChanges();
  

  Dim changedRecordsTable As DataTable = dataTable1.GetChanges()
  

To get all records that have a specific row state

• Call the GetChanges method of a dataset or data table and pass a DataRowState enumeration value as an argument.

  The following example shows how to create a new dataset called addedRecords and populate it only with records that have been added to the dataSet1 dataset.

  DataSet addedRecords = dataSet1.GetChanges(DataRowState.Added);
  

  Dim addedRecords As DataSet = DataSet1.GetChanges(DataRowState.Added)
  

• The following example shows how to return all records that were recently added to the Customers table:

  private NorthwindDataSet.CustomersDataTable GetNewRecords()
  {
      return (NorthwindDataSet.CustomersDataTable)
          northwindDataSet1.Customers.GetChanges(DataRowState.Added);
  }
  

  Private Function GetNewRecords() As NorthwindDataSet.CustomersDataTable
  
      Return CType(NorthwindDataSet1.Customers.GetChanges(Data.DataRowState.Added),
          NorthwindDataSet.CustomersDataTable)
  End Function
  

Access the original version of a DataRow

When changes are made to data rows, the dataset retains both the original (DataRowVersion) and new (DataRowVersion) versions of the row. For example, before calling the AcceptChanges method, your application can access the different versions of a record (as defined in the DataRowVersion enumeration) and process the changes accordingly.

Passing the DataRowVersion value along with the column index (or column name as a string) returns the value from that column's particular row version. The changed column is identified during the ColumnChanging and ColumnChanged events. This is a good time to inspect the different row versions for validation purposes. However, if you have temporarily suspended constraints, those events won't be raised, and you will need to programmatically identify which columns have changed. You can do this by iterating through the Columns collection and comparing the different DataRowVersion values.

To get the original version of a record

• Access the value of a column by passing in the DataRowVersion of the row you want to return.

  The following example shows how to use a DataRowVersion value to get the original value of a CompanyName field in a DataRow:

  string originalCompanyName;
  originalCompanyName = northwindDataSet1.Customers[0]
      ["CompanyName", DataRowVersion.Original].ToString();
  

  Dim originalCompanyName = NorthwindDataSet1.Customers(0)(
     "CompanyName", DataRowVersion.Original).ToString()
  

Access the current version of a DataRow

To get the current version of a record

• Access the value of a column, and then add a parameter to the index that indicates which version of a row you want to return.

  The following example shows how to use a DataRowVersion value to get the current value of a CompanyName field in a DataRow:

  string currentCompanyName;
  currentCompanyName = northwindDataSet1.Customers[0]
      ["CompanyName", DataRowVersion.Current].ToString();
  

  Dim currentCompanyName = NorthwindDataSet1.Customers(0)(
      "CompanyName", DataRowVersion.Current).ToString()
  

See also

• How to: Validate Data in the Windows Forms DataGridView Control
• How to: Display Error Icons for Form Validation with the Windows Forms ErrorProvider Component