How to: Validate Data in a LightSwitch Application
For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.
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.
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
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 theresults
parameter.The following example displays a validation message after a user sets the
ShippedDate
field of theOrder
entity to a date that's later than today.partial void ShippedDate_Validate(EntityValidationResultsBuilder results) { if (this.ShippedDate > DateTime.Today) { results.AddPropertyError("Shipped date cannot be 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
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 theAddPropertyError
method, LightSwitch will highlight theCity
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 theAddPropertyError
method. For the second parameter of theAddPropertyResult
method, pass in eitherValidationSeverity.Informational
orValidationSeverity.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 theresults
parameter. The following example compares the value of theRequiredDate
field to the value of theOrderDate
field. If the order date is later than the required date, this code displays a validation error message.partial void RequiredDate_Validate(EntityValidationResultsBuilder results) { if (this.RequiredDate < this.OrderDate) { results.AddEntityError ("Required data cannot be earlier than the order date"); } }
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
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 theresults
parameter.The following example prevents the deletion of customers who are located in the United States.
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); } } } }
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
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 theAddScreenError
method. For the second parameter of theAddScreenResult
method, pass in eitherValidationSeverity.Informational
orValidationSeverity.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 theresults
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.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; }
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
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.
See Also
Overview of Data Validation in LightSwitch Applications
Data: The Information Behind Your Application
Performing Data-Related Tasks by Using Code
Working with Data-Related Objects in Code
How to: Handle Data Events
How to: Define Data Fields