How to: Validate Data in a LightSwitch Application

Article
04/28/2015

By applying validation rules to an entity or table, you can ensure that properly formatted data is written to the data source for a Visual Studio LightSwitch application. A validation rule is a condition or constraint that the data in your application must comply with. If you can add one or more validation rules to an entity or table, an error appears if a user adds or changes data in a way that doesn't comply. Before a user can commit the data, the validation error must be fixed.

The following illustration shows a validation error message.

Validation error message

LightSwitch includes several built-in validation rules. You can configure these rules and apply them to an entity or a table without writing any code. You can also use code to define custom validation rules.

This topic contains the following sections:

Applying Predefined Validation Rules to a Field
Applying Custom Validation Rules to a Field
Applying Custom Validation Rules to Data in a Screen
Applying Validation Rules That Run When Data Is Saved

link to video For a related video demonstration, see How Do I: Write business rules for validation and calculated fields in a LightSwitch Application?.

Applying Predefined Validation Rules to a Field

LightSwitch includes several built-in validation rules that you can use without writing any custom code. You can apply these rules to individual fields of data or to any kind of update that users make to data in a screen.

To apply a predefined validation rule to a field

In Solution Explorer, open the shortcut menu for the entity or table to which you want to apply validation rules, and then choose Open.

The entity or table opens in the Data Designer.
In the Data Designer, choose the field that you want to validate.

Note

For applications that have been upgraded to Visual Studio 2012 Update 2, you can also choose the tier where you want the validation to occur from the buttons on the Perspective bar.
In the Properties window, in the Validation section, set the value of any the properties.

For information about the validation properties, see Reference: Data Designer Properties.

Applying Custom Validation Rules to a Field

You can define custom validation rules by writing code, and you can specify when LightSwitch enforces them. For example, you could specify that a rule is enforced immediately after a user enters a value in a field. As an alternative, you could specify that an entity or a table is evaluated only after all of its fields contain a value. This model makes sense when the validity of a value in one field relies on a valid value in another field in the same entity or table.

To apply a custom validation rule to a field

In Solution Explorer, open the shortcut menu for the entity or table to which you want to apply validation rules, and then choose Open.

The entity or table opens in the Data Designer.
In the Data Designer, choose the field that you want to validate.
In the Properties window, choose the Custom Validation link.

The Code Editor opens and generates a method that's named FieldName_Validate.
Add validation code to the FieldName_Validate method.

To enforce a validation rule immediately after a user provides a field value, call the AddPropertyError method of the results parameter.

The following example displays a validation message after a user sets the ShippedDate field of the Order entity to a date that's later than today.
```
Private Sub ShippedDate_Validate(results As EntityValidationResultsBuilder)
    If Me.ShippedDate > DateTime.Today Then
        results.AddPropertyError _
            ("Shipped date cannot be later than today")
    End If 

End Sub
```
```
partial void ShippedDate_Validate(EntityValidationResultsBuilder results)
{
    if (this.ShippedDate > DateTime.Today)
    {
        results.AddPropertyError("Shipped date cannot be later than today");
    }

}
```
Notice that you can highlight other properties for validation. For example, you could write validation code that runs when a user changes the zip code of a customer. If you pass the City property as a parameter to the AddPropertyError method, LightSwitch will highlight the City field. The text of your error could prompt the user to type the name of a city that matches the new zip code.

Note

By default, updates can't be committed to a data source until they conform to the validation rules. If you want to enable users to commit unevaluated updates, use the AddPropertyResult method instead of the AddPropertyError method. For the second parameter of the AddPropertyResult method, pass in either ValidationSeverity.Informational or ValidationSeverity.Warning.

To enforce a validation rule on an entity or a table, for example, when a user modifies a value in a field that relies on a valid value in another field, call the AddEntityError method of the results parameter. The following example compares the value of the RequiredDate field to the value of the OrderDate field. If the order date is later than the required date, this code displays a validation error message.
```
Private Sub RequiredDate_Validate(results As EntityValidationResultsBuilder)
    If Me.RequiredDate < Me.OrderDate Then
        results.AddEntityError _
            ("Required data cannot be earlier than the order date")
    End If 

End Sub
```
```
partial void RequiredDate_Validate(EntityValidationResultsBuilder results)
{
    if (this.RequiredDate < this.OrderDate)
    {
        results.AddEntityError
            ("Required data cannot be earlier than the order date"); 
    }

}
```

Applying Custom Validation Rules to Data in a Screen

You can specify custom validation rules that apply to a whole screen by adding custom code to the EntityOrTableName_Validate method in the screen code file. Your custom code runs when a user modifies (for example, adds or deletes) any data in the screen. These rules run before the data can be saved.

To apply a custom validation rule to data in a screen

In Solution Explorer, open the shortcut menu for the screen for which you want to specify a validation rule, and then choose Open.
At the top of the Screen Designer, choose the Write Code button.

The Code Editor opens.
In the Declarations list, choose EntityOrTableNameProperty _Validate.

A code block that's named EntityOrTableNameProperty_Validate appears in the code file.

Add your custom validation code to the EntityOrTableNameProperty_Validate method.

To enforce a validation rule after a user adds, deletes, or updates a row of data, call the AddScreenError method of the results parameter.

The following example prevents the deletion of customers who are located in the United States.

Private Sub Customers_Validate _
    (results As Microsoft.LightSwitch.Framework.Client.ScreenValidationResultsBuilder)
    If Me.DataWorkspace.NorthwindData.Details.HasChanges Then 
        Dim changeSet As EntityChangeSet = _
            Me.DataWorkspace.NorthwindData.Details.GetChanges()

        Dim entity As IEntityObject

        For Each entity In changeSet.DeletedEntities.OfType(Of Customer)()

            Dim cust As Customer = CType(entity, Customer)
            If cust.Country = "USA" Then
                entity.Details.DiscardChanges()
                results.AddScreenResult("Unable to remove this customer." & _
                    "Cannot delete customers that are located in the USA.", _
                     ValidationSeverity.Informational)
            End If 

        Next 
    End If 

End Sub

partial void Customers_Validate(ScreenValidationResultsBuilder results)
{
    if (this.DataWorkspace.NorthwindData.Details.HasChanges)
    {
        EntityChangeSet changeSet =
        this.DataWorkspace.NorthwindData.Details.GetChanges();
        foreach (IEntityObject entity in changeSet.DeletedEntities.OfType<Customer>())
        {
            Customer cust = (Customer)entity;
            if (cust.Country == "USA")
            {
                entity.Details.DiscardChanges();
                results.AddScreenResult("Unable to remove this customer. " +
                "Cannot delete customers that are located in the USA.",
                ValidationSeverity.Informational);
            }
        }
    }

}

Note

By default, updates can't be committed to a data source until they conform to the validation rules. If you want to enable users to commit unevaluated updates, use the AddScreenResult method instead of the AddScreenError method. For the second parameter of the AddScreenResult method, pass in either ValidationSeverity.Informational or ValidationSeverity.Warning.

Applying Validation Rules That Run When Data Is Saved

You can apply custom validation rules when a user saves data or when your code calls the SaveChanges method of a data source. This kind of validation runs exclusively on the server tier.

To apply validation rules that run when data is saved

In Solution Explorer, open the shortcut menu for the entity or table to which you want to apply validation rules, and then choose Open.

Note

For applications that have been upgraded to Visual Studio 2012 Update 2, on the Perspective bar, choose the Server tab.
In the command bar of the Data Designer, in the Write Code list, choose EntityOrTableName_Validate.

The Code Editor opens and generates a method that's named EntityOrTableName_Validate.

Add your custom validation code to the EntityOrTableName_Validate method.

Call the AddEntityError method of the results parameter.

The following example checks the credit status of a customer when a user saves a sales order. If the customer’s credit hasn't been approved by the financing department, a ValidationException is thrown.

Private Sub Orders_Validate _
    (entity As Order, results As  _
     Microsoft.LightSwitch.EntitySetValidationResultsBuilder)
    If Not CustomerCreditApproval(entity.Customer) Then
        results.AddEntityError("Customer Credit has not yet been approved")
    End If 

End Sub 
Private Function CustomerCreditApproval(ByVal entity As Customer) As Boolean 
    'Some custom code to check the customer’s credit status. 
    Return True 

End Function

partial void Orders_Validate
            (Order entity, EntitySetValidationResultsBuilder results)
        {
            if (!CustomerCreditApproval(entity.Customer))
            {
                results.AddEntityError
                    ("Customer Credit has not yet been approved");
            }
        }

        private bool CustomerCreditApproval(Customer entity)
        {
            //Some custom code to check the customer's credit status. 
            return true;
        }

Note

By default, when the exception is thrown, an error message appears, and the data remains in the current change set. If you want to change this behavior, you can handle the ValidationException in your code.

How to: Validate Data in a LightSwitch Application

Applying Predefined Validation Rules to a Field

To apply a predefined validation rule to a field

Applying Custom Validation Rules to a Field

To apply a custom validation rule to a field

Applying Custom Validation Rules to Data in a Screen

To apply a custom validation rule to data in a screen

Applying Validation Rules That Run When Data Is Saved

To apply validation rules that run when data is saved

See Also

Tasks

Concepts

Other Resources

Additional resources