How MVVM Applies to Validation

If a user enters data that fails validation, LightSwitch summarizes the errors in a validation summary control. It also surrounds any offending controls with a red border to highlight the error (as shown in Figure 5-2).

These red borders are generated by the Silverlight control. Silverlight controls are bound to content items that are autogenerated by LightSwitch at runtime. These content items expose validation errors to the controls by implementing the INotifyDataErrorInfo interface.

So in keeping with the MVVM principles that were explained in Chapter 1, the View (Silverlight Control) performs only the red highlighting, and the actual validation logic is carried out by the View Model (the content item).

Identifying Where Validation Runs

LightSwitch can carry out validation on the client, on the server, or on both the client and server. It’s important to target the validation at the right tier. For example, if you want to write validation that relies heavily on data, it wouldn’t be efficient to download lots of data onto the client just to perform this task.

Custom validation requires you to click on the Write Code button and to write .NET code that applies your validation rules. To help you understand where validation takes place, Figure 5-4 illustrates the table and screen designers, highlights the three validation methods that you can choose, and shows you where LightSwitch carries out the validation.

Creating Validation Rules and Warnings

You can use custom validation to enforce mandatory rules or to simply provide optional warnings. The method for creating both types of validation is similar, so let’s begin by creating a validation warning.

The engineer table includes an optional email address field. To encourage users to enter email addresses for engineers, this example creates a validation rule that prompts the user to supply an email address if the user leaves it blank.

To begin, open the engineer table and select the EmailAddress property. Open the properties sheet, and click on the Custom Validation link that appears in the Validation Group. This opens the code window and reveals a method stub that contains the commented-out line results.AddPropertyError("<Error-Message>"). Uncommenting this line produces a validation error when LightSwitch validates the email address. So the key to building custom validation is to build conditional logic around this line of code.

To complete this sample, replace your code with the code that’s shown in Listing 5-1.

Listing 5-1.  Creating a Validation Warning

VB:
File: HelpDeskVBCommonUserCodeEngineer.vb
  
Private Sub EmailAddress_Validate(results As EntityValidationResultsBuilder)
   ' results.AddPropertyError("<Error-Message>")
   If String.IsNullOrEmpty(EmailAddress) Then                                  
      results.AddPropertyResult(
         "Providing an Email Address is recommended",
           ValidationSeverity.Informational)                                   
   End If
End Sub
  
C#:

File: HelpDeskCSCommonUserCodeEngineer.cs
  
partial void EmailAddress_Validate(EntityValidationResultsBuilder results)
{
    // results.AddPropertyError("<Error-Message>");
  
    if (System.String.IsNullOrEmpty (EmailAddress))                            
    {
        results.AddPropertyResult(
           "Providing an Email Address is recommended",
           ValidationSeverity.Informational);                                  
    }
}

Now run your application. Use the engineer screens that you created in Chapter 3 to create an engineer record without an email address. When you attempt to save the record, LightSwitch displays a validation warning that prevents you from saving. (See Figure 5-5.) Because this is just a warning, LightSwitch allows the user to save the record by clicking on the Save button again.    

Let’s examine the code in Listing 5-1. The first part tests for an empty or null email address. If this condition is true, the code raises a validation warning by calling the result object’s AddPropertyResult method . The first parameter allows you to supply the error that’s shown to the user.

The results object is of type EntityValidationResultsBuilder, and the methods that you can call are shown in Table 5-1.

The AddPropertyResult method that’s used in this example allows users to save their changes after viewing the validation warning. The AddEntityResult method also behaves in the same way.

Both methods allow you to supply a severity level that can be either ValidationSeverity.Informational or ValidationSeverity.Warning. If you choose the ValidationSeverity.Informational option, LightSwitch displays a blue information icon in the validation summary, whereas choosing the warning level produces a red exclamation point icon. (These icons may not be shown if you’ve chosen a nonstandard Shell.)

If you use the AddPropertyError or AddEntityError methods instead, users will not be able to save their changes until they enter data that conforms to the validation rules.

Comparing Against Other Properties

You can use custom validation to apply validation that depends on the values of other fields in the table.

The following example prevents users from entering an issue Close Date that’s earlier than the Create Date.

To create this rule, open the Issue table in the table designer and select the ClosedDateTime property. Open the properties sheet, click on the Custom Validation link, and enter the code that’s shown in Listing 5-2.

Listing 5-2.  Compare Validation

VB:
File: HelpDeskVBCommonUserCodeIssue.vb
  
Private Sub ClosedDateTime_Validate(results As EntityValidationResultsBuilder)
   If CreateDateTime > ClosedDateTime Then
      results.AddPropertyError("Closed Date cannot be before Create Date")
   End If
End Sub
  
C#:
File: HelpDeskCSCommonUserCodeIssue.cs
  
partial void ClosedDateTime_Validate(EntityValidationResultsBuilder results)
{
    if (this.CreateDateTime > this.ClosedDateTime )
    {
        results.AddPropertyError("Closed Date cannot be before Create Date");
    }
}

If you now run any screen that uses the Issue table, you’ll be unable to set the Closed Date field to a value that’s earlier than the  Create Date.

Mandating Data Using Conditions

You can very easily make fields mandatory: just select the Is Required check box for your property in the table designer. However, you might want to make a field mandatory based on some other condition, and to do this, you need to write custom validation.

The Issue table contains a ClosedDateTime field and a ClosedByEngineer field. If the user enters a ClosedByEngineer value, the ClosedDateTime field becomes mandatory. Otherwise, the CloseDateTime field can be left blank.

In the previous example, the properties sheet for the ClosedDateTime property shows a Custom Validation link that opens the code window and creates a method stub. The properties sheet for the ClosedByEngineer field doesn’t include a Custom Validation link. This is because ClosedByEngineer refers to a related item. It belongs on the many side of a (zero-or-1)-to-many relationship between the engineer table.

So to access the code window, you’ll need to select the ClosedByEngineer navigation property in the table designer and click on the Write Code button. When the drop-down menu appears, you’ll be able to validate ClosedByEngineer by selecting the ClosedByEngineer_Validate method that appears. (See Figure 5-6.) Now enter the code that’s shown in Listing 5-3.

Listing 5-3.  Making Fields Mandatory Based on Some Condition  

VB:
File: HelpDeskVBCommonUserCodeIssue.vb
  
Private Sub ClosedByEngineer_Validate(
     results As EntityValidationResultsBuilder)
   If ClosedByEngineer IsNot Nothing And
      ClosedDateTime.HasValue = False Then
         results.AddPropertyError("Closed Date must be entered")
   End If
End Sub
  
C#:
File: HelpDeskCSCommonUserCodeIssue.cs
  
partial void ClosedByEngineer_Validate(
    EntityValidationResultsBuilder results)
{
    if (ClosedByEngineer != null &&
       ClosedDateTime.HasValue == false)
    {
        results.AddPropertyError("Closed Date must be entered");
    }
}

Validating Patterns with Regular Expressions

Regular expressions (regexes) allow you to carry out validation that involves matching string patterns. You might use regexes to validate the formats of Social Security numbers, bank sort codes, postal codes, or domain names.

This technique uses the Regex class in the System.Text.RegularExpressions namespace. Listing 5-4 shows the code that you would use to validate the format of the Social Security Number field in the Engineer table.

Listing 5-4.  Regex Validation to Check Social Security Numbers

VB:
File: HelpDeskVBCommonUserCodeEngineer.vb
  
Imports System.Text.RegularExpressions
  
Private Sub SSN_Validate_Validate(
   results As EntityValidationResultsBuilder)
  
   Dim pattern As String =
       "^(?!000)([0-6]d{2}|7([0-6]d|7[012]))([ -]?)(?!00)dd3(?!0000)d{4}$"
   If (Not SSN Is Nothing) AndAlso
      (Regex.IsMatch(SSN, pattern) = False) Then                                    
         results.AddPropertyError(
            "Enter SSN in format 078-05-1120")
   End If
  
End Sub
  
C#:
File: HelpDeskCSCommonUserCodeEngineer.cs
  
using System.Text.RegularExpressions;
  
partial void SSN_Validate(
    EntityValidationResultsBuilder results)
{
    string pattern =
       @"^(?!000)([0-6]d{2}|7([0-6]d|7[012]))([ -]?)(?!00)dd3(?!0000)d{4}$";
    if (SSN !=null && !Regex.IsMatch(SSN, pattern))                                 
    {
        results.AddPropertyError(
            "Enter SSN in format 078-05-1120");
    }
}

This code highlights the use of the IsMatch method . This method allows you to pass in an expression, and the method returns a Boolean result that indicates whether a match is found.

Checking Against Child Collections

When you’re writing custom validation, you can use code to access child collections and records. In this example, the HelpDesk system stores documents that are related to each issue. Each issue can have many documents, and the documents are stored in a table called IssueDocument.

You can write custom validation that enforces a maximum of ten documents per issue. This allows you to preserve storage space on the server.

Just like the Closed Engineer example earlier in the chapter, the IssueDocument property is a navigation property. But unlike the earlier example, the Issue table belongs on the zero-or-1 end of a (zero-or-1)-to-many relationship.

For these types of navigation properties, LightSwitch doesn’t allow you to write property-level navigation that runs on both the client and server. Instead, you need to create entity (or data-service) validation that runs only on the server.

To create this validation, open the Issue table and click the Write Code button. Select the Issues_Validate method that belongs in the General Methods group (as shown in Figure 5-7). Now enter the code that’s shown in Listing 5-6.

Listing 5-6.  Validating the Counts of Child Items

VB:
File: HelpDeskVBServerUserCodeApplicationDataService.vb
  
Private Sub Issues_Validate(
    entity As Issue, results As EntitySetValidationResultsBuilder)
  
   If entity.IssueDocuments.Count() > 10 Then
      results.AddEntityError(
         "Issues can only contain a maximum of 10 documents")
   End If
  
End Sub
  
C#:
File: HelpDeskCSServerUserCodeApplicationDataService.cs
  
partial void Issues_Validate(Issue entity, EntitySetValidationResultsBuilder results)
{
    if (entity.IssueDocuments.Count() > 10)
    {
        results.AddEntityError(
            "Issues can only contain a maximum of 10 documents");
    }
}

The code in Listing 5-6 shows how you can apply an aggregate function to a child collection. When you call the Count function on a navigation property, LightSwitch produces the count by retrieving all related issue document records. Because each issue document record can be large, this type of validation is ideally suited to running on the server.

Enforcing Uniqueness and Preventing Duplicates

LightSwitch allows you to define a unique field by selecting the Is Unique check box for the field in the table designer. If you select the Is Unique check box for more than one field in a table, LightSwitch creates a combination index for the set of fields that you’ve selected.

You may want to enforce uniqueness on two or more fields independently within a table. In this example, the Engineer table contains Social Security Number and Security Clearance Reference Number fields. For every row in the Engineer table, both of these fields must be unique.

To apply this validation, open the Engineer table in the table designer and select the ClearanceReference property. From the properties sheet, click on the Custom Validation link and enter the code that’s shown in Listing 5-7.

Listing 5-7.  Enforcing Unique Records

VB:
File: HelpDeskVBCommonUserCodeEngineer.vb
  
Private Sub ClearanceReference_Validate(results As EntityValidationResultsBuilder)
  
   If Len(Me.ClearanceReference) > 0 Then
      Dim duplicateOnServer = (
          From eng In
          Me.DataWorkspace.ApplicationData.Engineers.Cast(Of Engineer)()
          Where
          eng.Id <> Me.Id AndAlso
          eng.ClearanceReference.Equals(Me.ClearanceReference,
              StringComparison.CurrentCultureIgnoreCase)
          ).ToArray()                                                                  
  
      Dim duplicateOnClients = (
          From eng In
          Me.DataWorkspace.ApplicationData.Details.GetChanges().
             OfType(Of Engineer)()
          Where
          eng IsNot Me AndAlso
          eng.ClearanceReference.Equals(Me.ClearanceReference,
             StringComparison.CurrentCultureIgnoreCase)
          ).ToArray()                                                              
  
      Dim deletedOnClient = Me.DataWorkspace.ApplicationData.Details.GetChanges().
         DeletedEntities.OfType(Of Engineer)().ToArray()                           
      Dim anyDuplicates = duplicateOnServer.Union(duplicateOnClients).Distinct().
         Except(deletedOnClient).Any()
  
      If anyDuplicates Then
         results.AddPropertyError("
            The clearance reference already exists")                               
      End If
  
   End If
  
End Sub
  
C#:
File: HelpDeskCSCommonUserCodeEnginner.cs
  
partial void ClearanceReference_Validate(EntityValidationResultsBuilder results)
{
    if (ClearanceReference!=null &&
        ClearanceReference.Length > 0)
    {
        var duplicatesOnServer = (
            from eng in
                this.DataWorkspace.ApplicationData.Engineers.Cast<Engineer>()
            where (eng.Id != this.Id ) &&
            eng.ClearanceReference.Equals(this.ClearanceReference,
                StringComparison.CurrentCultureIgnoreCase)
            select eng
                ).ToArray();                                                       
  
        var duplicatesOnClient = (
            from eng in
                this.DataWorkspace.ApplicationData.Details.GetChanges().
               OfType<Engineer>()
            where (eng != this) &&
            eng.ClearanceReference.Equals(this.ClearanceReference,
               StringComparison.CurrentCultureIgnoreCase)
            select eng
                ).ToArray();                                                       
  
        var deletedOnClient =
           this.DataWorkspace.ApplicationData.Details.GetChanges().
              DeletedEntities.OfType<Engineer>().ToArray();                        
  
        var anyDuplicates =
           duplicatesOnServer.Union(duplicatesOnClient).
              Distinct().Except(deletedOnClient).Any();
  
        if (anyDuplicates)
        {
            results.AddPropertyError(
                "The clearance reference already exists");                             
        }
    }
}

This code might seem trickier than you first expect. This is because you need to check for duplicates on the client (the user might enter several new engineers in a datagrid) in addition to checking for duplicates on the server.

First, the code checks that no server records match the clearance reference number that’s been entered by the user . It uses a where clause that excludes the ID of the current record—if not, the query would return a match for the identical record on the server.

Next, it checks for duplicate clearance reference numbers that have been entered by the user on the client . It then performs a query that returns any deleted records .

If duplicate records were found on the server or client but are also marked as deleted, the clearance number passes validation. If not, the code raises a property error that prevents the user from saving the record .

Validating Deletions on the Server

Validating deletions by using screen validation is relatively simple. I included the last example to highlight its simplicity, but it’s far from ideal. Relying on the client to perform validation isn’t good practice. If you want to apply the deletion rule throughout your application, you’ll need to write code in every single place where users can delete an issue. But if you want to validate deletions on the server, the process can be quite complex.

This complexity arises because LightSwitch doesn’t apply validation rules on deleted entities during the save pipeline process. If it did, your users would be forced to fill in all mandatory fields, even just to delete a record!

In this example, you’ll learn how to apply a slightly different deletion rule that includes a check on child records. The HelpDesk system allows engineers to respond to issues by adding records into a table called IssueResponse. If the response requires some input from the user, the engineer would set a field called AwaitingClient to true.

The following example shows you how to prevent issues from being deleted if there are responses that are awaiting client. This process consists of at least two parts (and optionally three):

1. Carry out the validation check in the entity set’s Validate method.
2. If errors are found, raise an exception in the entity set’s Deleting method.
3. On the client, undelete the records that have failed validation (Optional).

To create the code in your entity set’s validate method, open the Issue table in the table designer, click on the Write Code button, and select the Validate method. Enter the code that’s shown in the first part of Listing 5-10.

Next, create a screen that’s based on the Issue table. Choose the Editable Grid Screen template, and name your screen EditableIssuesGrid. When the screen designer opens, click the Write Code button, and select the SaveError method. Enter the code that’s shown in the second part of Listing 5-10.

Listing 5-10.  Validating Deletions on the Server

VB:
File: HelpDeskVBServerUserCodeApplicationDataService.vb
  
Private Sub Issues_Validate(entity As Issue,
     results As Microsoft.LightSwitch.EntitySetValidationResultsBuilder)
  
    ' Check for validation errors for deletions
   If entity.Details.EntityState = EntityState.Deleted Then                        
      If entity.IssueResponses.Where(
         Function(s) s.AwaitingClient).Any() Then                                  
          results.AddEntityError(
             "Cannot delete issues with responses awaiting client.")               
      End If
   End If
  
End Sub

Private Sub Issues_Deleting(entity As Issue)

    ' Check for validation errors for deletions
   If entity.Details.ValidationResults.Errors.Any Then
      Throw New ValidationException(Nothing,
         Nothing, entity.Details.ValidationResults)                                    
   End If
   ' Cascade delete children because delete rule is Restricted
   For Each resp In entity.IssueResponses
      resp.Delete()                                                                    
   Next

End Sub

File:HelpDeskVBClientUserCodeEditableIssuesGrid.vb

' This is the screen code
Private Sub EditableIssuesGrid_SaveError(
    exception As Exception, ByRef handled As Boolean)

   ' Un-delete deleted records that had server-side validation errors
   Dim validationExc = TryCast(exception, ValidationException)

   If validationExc IsNot Nothing Then
      Dim entities = From v In validationExc.ValidationResults
         Let e = TryCast(v.Target, IEntityObject)
           Where e IsNot Nothing AndAlso
              e.Details.EntityState = EntityState.Deleted
      Select e
      For Each e In entities
         e.Details.DiscardChanges()
      Next
   End If

End Sub

C#:
File: HelpDeskCSServerUserCodeApplicationDataService.cs

partial void Issues_Validate(Issue entity, EntitySetValidationResultsBuilder results)
{
    if (entity.Details.EntityState == EntityState.Deleted)                             
    {
        if (entity.IssueResponses.Where(s => s.AwaitingClient).Any())                  
        {
            results.AddEntityError(
                "Cannot delete issues with responses awaiting client.");               
        }
    }
}
  
partial void Issues_Deleting(Issue entity)
{
    // Check for validation errors for deletions
    if (entity.Details.ValidationResults.Errors.Any())
    {
        throw new ValidationException(
           null, null, entity.Details.ValidationResults);                          
    }
  
    // Cascade delete children because delete rule is Restricted
    foreach (var childResp in entity.IssueResponses)
    {
        childResp.Delete();                                                        
    }
}
  
File:HelpDeskCSClientUserCodeEditableIssuesGrid.cs
// This is the screen code
  
partial void EditableIssuesGrid_SaveError(
   Exception exception, ref bool handled)
{
    ValidationException validationExc =
       (exception as ValidationException);
    if (validationExc != null)
    {
  
        var entities = from v in validationExc.ValidationResults
                       let e = (v.Target as IEntityObject)
                       where (e != null &&
                          e.Details.EntityState == EntityState.Deleted)
                       select e;
  
        foreach (IEntityObject e in entities)
        {
            e.Details.DiscardChanges();
        }
    }
}

The server-side Validate method checks the EntityState to see whether the issue is marked as deleted . If this condition is true, the code queries the IssueResponses navigation property to find any related issue-response records that have their AwaitingClient property set to true. If one or more records exist, the code calls the AddEntityError method to record the fact that the entity has failed validation . Chapter 6 will explain the LINQ syntax and Any operator in more detail.

Because LightSwitch ignores validation errors on deleted entities, code execution continues into the pre-process entities phase of the save pipeline. (See Figure 4-10.) Here, the save pipeline executes the code in the Deleting method, and the code raises an exception if the AddEntityError method was called in the Validate method . By raising an exception here, the save pipeline aborts the transaction and executes the SaveChanges_ExecuteFailed method. This prevents the record from being deleted.

An important point is that if you want to perform validation against child records during a delete, you need to turn off the Cascade Delete option on the relationship (that is, set it to Restricted). If not, the save pipeline deletes any related child records prior to calling the validate method and you won’t be able to access any issue-response records in the validate method of your issue entity.

Because of this, the code manually carries out the cascade delete behavior by deleting the child records in the deleting method .

The second part of the code in Listing 5-10 refers to screen code that handles the save error event. This code finds the deleted entities and undeletes those entities. This allows the user to clearly see that the deletion has failed. Note that if you allow users to delete items other than issues, you should modify the screen code so that it checks that the deleted item is an issue before undeleting it.