Up Validate
Documentation.Glossary » Validate » Perform a validation

Perform a validation

Last modified on August 15, 2012 17:22

In most cases, you will want to perform validation either when a property on one of your entities is set, or as part of a comprehensive validation of an object instance.


Property level validation

 

Property level validations should be run whenever the value of some property on an entity is set and that property has a verifier or verifiers associated with it. For a DevForce entity, this occurs automatically because internally DevForce calls either VerifierEngine.ExecuteBeforeSet or VerifierEngine.ExecuteAfterSet whenever a property is set. Which one is called is determined by the VerifierExecutionModes settings on each verifier. This occurs during the execution of the autogenerated call to the EntityProperty.SetValue method; an autogenerated code fragment is shown below:

C#
...
public string CompanyName {
 get { ... }
 set { PropertyMetadata.CompanyName.SetValue(this, value); }
}
VB
Public Property CompanyName() As String
 Get
  ...
 End Get
 Set(ByVal value As String)
    PropertyMetadata.CompanyName.SetValue(Me, value)
 End Set
End Property
This means that you will NOT have to write ANY code to perform property level validations on any DevForce generated entity type. 

If you are working with a custom property or an object type that is not a DevForce entity, you will need to write some of this scaffolding behavior yourself. For example:

C#
public String ShortName {
 get { return _shortName; }
   set {
      VerifierResultCollection verifierResults = _verifierEngine.ExecuteBeforeSet(this, "ShortName", value);
     if (verifierResults.Ok) {
        _shortName = value;
      } else {
       // Handle verifierResults here
     }
    }
  }
}
VB
Public Property ShortName() As String
 Get
   Return _shortName
 End Get
 Set(ByVal value As String)
   Dim verifierResults As VerifierResultCollection = __
      verifierEngine.ExecuteBeforeSet(Me, "ShortName", value)
   If verifierResults.Ok Then
      _shortName = value
   Else
     ' Handle verifierResults here
   End If
 End Set
End Property

Note that the ExecuteBeforeSet method above takes an object instance, a property name and a proposed value; the result is a VerifierResultCollection that contains a collection of individual VerifierResults as well as an aggregate Ok property. We have also assumed in the example above the availability of a VerifierEngine instance; _verifierEngine

DevForce actually does something a good deal more complex under the covers, because it calls both the ExecuteBeforeSet for 'beforeSet' verifiers and ExecuteAfterSet for 'afterSet' verifiers and interprets and handles verifier results in accordance with the VerifierOptions property of each verifier. Relevant VerifierOptions properties include ErrorNotificationMode, ErrorContinuationMode, TreatWarningsAsErrors and ShouldExitOnBeforeSetError

Instance level validation


Instance validation is much like property level validation except that you call the VerifierEngine's Execute method instead of the ExecuteBeforeSet or ExecuteAfterSet methods. As with those methods, Execute also returns a VerifierResultCollection, whose individual members are each a VerifierResult.

C#
VerifierResultCollection aVerifierResultCollection = _verifierEngine.Execute(anEmployee);
VB

Dim aVerifierResultCollection As VerifierResultCollection = _verifierEngine.Execute(anEmployee){{/code}}

Instance validation is called automatically by DevForce on the EntityServer just prior to the execution of a save, but most developers will want to call it programmatically in client side code as well. 

It is also possible to execute on demand a specified collection of verifiers, or a single verifier:

C#
Verifier birthDateVerifer = aVerifierEngine.GetVerifier(
 typeof(Employee), typeof(DateTimeRangeVerifier),
  Employee.EntityPropertyNames.BirthDate);
aVerifierResultCollection = aVerifierEngine.Execute(anEmployee,
 new List<Verifier>() { birthDateVerifer }, null);
VB
Dim birthDateVerifer As Verifier = aVerifierEngine.GetVerifier(GetType(Employee), GetType _
  (DateTimeRangeVerifier), Employee.EntityPropertyNames.BirthDate)
aVerifierResultCollection = aVerifierEngine.Execute(anEmployee, New List _
  (Of Verifier)() From {birthDateVerifer}, Nothing)

However, this is unlikely to be a common operation in your application.

Examine the validation results

 

You can examine a collection of VerifiersResults. Each VerifierResult consists of the following readonly properties:

PropertyProperty TypeDescription
ResultCodeVerifierResultCodeA classification of the result of this validation, primarily a classification of the type of the success or failure of the operation.
MessageStringA description of the result.
VerifierVerifierThe verifier that this VerifierResult resulted from. This will be null (Nothing in VB) if this is a "remote" VerifierResult.
TargetInstanceObjectThe object instance that was validated to get this result.
VerifierOptions VerifierOptionsThe VerifierOptions on the Verifier that was executed to get this result
VerifierContextVerifierContextThe VerifierContext under which this validation was run. This will be null (Nothing in VB) if this is a "remote" VerifierResult.
TriggerContextTriggerContextThe TriggerContext under which this validation was run. The TriggerContext contains information about the timing (BeforeSet, AfterSet) of the validation among other things.
PropertyNamesICollection<String> List of names of properties involved in this validation.

The  VerifierResultCode enumeration consist of the following values: 

ValueDescription
OkWas this a successful validation.
ErrorWas this a failed validation.
OkWarningWas this is a "warning" result. Whether this is treated as a success or failure depends on the VerifierOptions.ShouldTreatWarningsAsErrors flag.
OkNotApplicableWhether this result occured because the validation was not applicable to the data; 
ErrorInsufficientData Whether this result occured because of insufficient data.

The following methods on the VerifierResult class provide a shorthand mechanism for accessing the actual enumerated values shown above: 

MethodSuccess
or Failure
Description
IsOkSuccessWas this a successful validation.
IsErrorFailureWas this a failed validation.
IsWarningEitherWas this is a "warning" result. Whether this is treated as a success or failure depends on the VerifierOptions.ShouldTreatWarningsAsErrors flag.
IsNotApplicableSuccessWhether this result occured because the validation was not applicable to the data; 
IsInsufficientDataFailureWhether this result occured because of insufficient data.

So for example the following two expressions mean the same thing:

C#
ValidationResultCode vrc = ...
var isError = (vrc == ValidationResultCode.Error);
// is same as
var isError = vrc.IsError();
VB
Dim vrc As ValidationResultCode =...var isError = (vrc Is ValidationResultCode.Error)
' is same as
Dim isError = vrc.IsError()

Note that both the Verifier and the VerifierContext properties will be null for any VerifierResult that occurs as a part of a "remote" validation.  A "remote" validation is one where the validation occurs on the EntityServer instead of on the client.  This is because, in such validations, the Verifier and its VerifierContext only exist on the EntityServer and we may not want these verifiers to be accessible to the client.  In this case, we only want the results of the validation.

Example

The following code, for example, iterates through a collection of VerifierResults, captures the Message property value of each one that represents an error. (Note that a Verifier always returns a VerifierResult when executed, regardless of whether an error was found.)

C#
bool foundErrors = false;
foreach (VerifierResult aVerifierResult in aVerifierResultCollection) {
if (aVerifierResult.IsError) {
    foundErrors = true;
    _localOutput.Append(string.Format("\tValidation Failure: {0}\n",
    aVerifierResult.Message));
  }
}
VB
Dim foundErrors As Boolean = False
For Each aVerifierResult As VerifierResult In aVerifierResultCollection
 If aVerifierResult.IsError Then
    foundErrors = True
    _localOutput.Append(String.Format(vbTab & _
     "Validation Failure: {0}" & vbLf, aVerifierResult.Message))
 End If
Next aVerifierResult
Tags: Validation
Created by DevForce on October 06, 2010 15:14

This wiki is licensed under a Creative Commons 2.0 license. XWiki Enterprise 3.2 - Documentation. Copyright © 2015 IdeaBlade