Create a custom verifier

DevForce ships with a number of pre-defined verifiers that can be customized in a variety of ways: examples include the DateTimeRangeVerifier, the RegexVerifier, the StringLengthVerifier, the RequiredValueVerifier, and a number of others. In addition, it defines a generic DelegateVerifier<T> that provides unlimited verification capabilities: you can use it to define any sort of rule you need or can imagine. 

There are several ways to create a verifier, but in general the easiest ways involve starting with an existing one and modifying it to suit.

Creating a customized version of a standard (provided) verifier

The method GetHireDateRangeVerifier below illustrates the creation of a 'customized' verifier by simply creating one of the standard DevForce verifiers with specific parameters, in this case, the  DateTimeRangeVerifier. Other provided verifiers include many others that are specific to .NET simple types, including DecimalRangeVerifier, DoubleRangeVerifier, Int32RangeVerifier, and so forth. There is a ListVerifier, a Regex Verifier, a NamedRegexPattern verifier, and a number of others. All are defined in the IdeaBlade.Validation namespace. 

The constructor for the DateTimeRangeVerifier provides for all of the configuration we need. It permits us to specify the target business object type for the rule, the property on that type whose setting will trigger the running of the rule, whether a non-null value is required when that property is set, and the dates that define the valid range:

If you need to improve upon the default message produced by the above verifier, you can take control of the messaging by setting the verifier’s VerifierArgs.ErrorMessageInfo.Error. For example, if you insert the following statement right before the return statement in the above method, your message will be the one users see:

Subclassing a pre-defined verifier

Another way to create a custom verifier is to subclass one of the pre-defined verifiers that are in the IdeaBlade.Validation namespace. In the following code samples below, we will create a custom verifier that checks that a given GUID property does NOT equal Guid.Empty. We will do this by subclassing a PropertyValueVerifier to define a custom class called NotEmptyGuidVerifier.

Step 1: Create the custom NotEmptyGuidVerifier class by inheriting it from the PropertyValueVerifier class. The constructor takes 2 parameters, an entityType and a propertyName. This allows us to pass any entity and any Guid property.

Step 2: Wrap the NotEmptyGuidVerifier class in a method that returns a Verifier. We will call this method "CheckForEmptyGuidVerifier".

Step 3: Add the method to the list of Verifiers that is defined inside the VerifierProvider" class that implements the IVerifierProvider interface. Note that in this example, we are using the verifier to validate an Order.CustomerID property (presumably of type GUID).

Step 4: And finally, let's test our newly created verifier.

Now let’s recap what we just did.

1. We created our generic verifier by subclassing a PropertyValueVerifier class that is pre-defined in the IdeaBlade.Validation namespace.
2. We wrap up the class inside a method that returns a Verifier. This is a required signature to add the verifier to the VerifierEngine.
3. We add the method to the list of Verifiers that is defined inside a class that implements an IVerifierProvider interface. In our example, this class is called VerifierProvider.
4. Using a TestMethod, we test the Verifier by retrieving anOrder and assigning its CustomerID to Guid.Empty. The Assert.IsTrue method should succeed as anOrder.EntityAspect.ValidationErrors.Count should be more than 0.
   
   

Creating a completely custom verifier using the DelegateVerifier

Despite the imposing name, the DelegateVerifier is really just a completely custom verifier. With this verifier you define the type of the object to verify, when and how to apply the verifier, and the validation to be performed.  The DelegateVerifier is particularly useful for verifying multiple properties on a type, and for cross-type validation.

When you create the custom verifier you provide a VerifierCondition, which is really just a function which performs the actual validation wanted.  The function returns a VerifierResult, indicating whether the validation succeeded or not.

You can also provide the constructor with the an ApplicabilityConstraint. Another imposing term, but it's just a function which given an object and some "context", determines whether the verifier should be run, in other words, whether it's applicable. 

As with other verifiers, you can also set the VerifierOptions. These options control when the verifier will be executed, and what to do when a validations fails.

The verifier also needs one or more "triggers", one or more members, either on the type to be verified or another type, which "trigger" validation.  Usually a trigger is the setter for a property, but it can also be a method call.  If the custom validation isn't actually triggered by a property set but instead only on the object as a whole, the triggers can indicate the properties of interest.

Triggers

Consider a constraint that specifies that the HireDate for an Employee must be later than the Employee’s BirthDate. That seems a pretty reasonable requirement, but suppose when the user enters a HireDate of today, this rule is found to have been violated. But the Employee really was hired today, and the problem is that the BirthDate previously entered for the Employee was in error, specifying the year 2015 when it should have said 1985. If we prevent the new HireDate value from being entered into that property, we’ll subject the user to a lot of unnecessary work. She’ll have to clear the new HireDate, even though it is entirely correct, and then go fix the BirthDate value, and then come back and re-enter the new HireDate value, even though she got it right the first time. Users don’t have a lot of tolerance for this sort of thing! It’s confusing, irritating, or often both.

A verifier that applies to BirthDate doesn’t have to be triggered by a change to that property. You can, instead – or additionally – specify that you want it called when the value of HireDate is changed. You can even set it to be triggered by a change to a property of some other type; and not just any instance of that type, but one that happens to be specifically related. For example, suppose you have a rule that says that the OrderDate on an Order taken by Employee X must be greater than or equal to that Employee’s HireDate. You could define this rule (as a verifier) on the Employee type, but specify that it should be triggered not only by a change to Employee.HireDate, but equally by a change to the OrderDate property of any Order written by that Employee!

Example

With some terminology out of the way, let's look at a simple sample.  Here we'll define a custom verifier for the Employee class to require that the employee's birth date precedes her hire date.  The VerifierCondition is simple:  the BirthDate must fall before the HireDate.  The triggers are the "BirthDate" and "HireDate" properties on the Employee, and options here tell the engine that verification should be performed after either of these properties is set, and for instance-level validation.

In the above code we define a DelegateVerifier that returns, as always a VerifierResult. We add two triggers to our verifier, since it tests the relative value of two different properties, and we want a change in either to result in re-application of our validity test.

BeforeSet Versus AfterSet Execution and Its Interaction With ErrorNotificationMode

Note that we have also the VerifierExecutionModes for this verifier set to InstanceAndOnAfterSetTriggers . This doesn’t matter so much if the VerifierErrorNotificationMode is set at the default of Notify . Under that setting a verification failure will not result in an exception that blocks the commitment of the proposed value into the business object. But if, on the other hand, the VerifierErrorNotificationMode were set to ThrowException  or NotifyAndThrowException  then running the verifier in AfterSet  rather than BeforeSet  mode would be essential.

To understand why, consider what would happen if a user discovered that both the HireDate and BirthDate values currently set for a given Employee were incorrect, even though valid according to the “born before hired” rule. To correct them, she needs to change both values; but, upon changing the BirthDate value, the verifier was executed and discovered that the new BirthDate value caused the HireDate and BirthDate values to be invalid relative to one another. The user planned to correct this problem by entering a new HireDate value which would bring the two values back into relative validity. But if the verifier triggered by the BirthDate change ran BeforeSet and threw an exception, the proposed new value would be prevented by the exception from entering the business object. The user might then try entering the new HireDate value first; but this might also cause a BeforeSet exception. So she would, in fact, be unable to correct the property values for the invalid Employee.

It is therefore a good idea to set the VerifierOptions for such a cross-property verifier so that either
   1) The verifier runs AfterSet.
      or
   2) The VerifierErrorNotificationMode is set to Notify. 

Thus any validation failure will not throw an exception during and before the 'set' of a temporarily invalid but necessary intermediate value. 

Cross-Type Verifiers

A cross-type verifier defines a rule whose application requires the inspection of at least one business object of a type different than the business object being validated. For example, suppose you have a rule that says the OrderDate on any Order may not be earlier than the HireDate of the Employee writing the Order. Clearly the application of this rule requires the inspection of at least one Order and one Employee. If the change that triggers the verifier is to the Employee.HireDate rather than the OrderDate of an Order, then all Orders associated with the changed Employee must be checked.

Note that such a verifier needs to have multiple triggers associated with it. In the case of our example, it should be executed whenever either the HireDate of an Employee, or the OrderDate of an Order, is changed.

There is another issue with such a verifier: where should it be defined? DevForce initiates its discovery process for the verifiers associated with a particular type when the first instance of that type is retrieved into the cache. So if we define our Employee.HireDate / Order.OrderDate verifier in the Employee class, it will be discovered automatically when the first Employee is retrieved during a given application session. But if an Order is retrieved and changed before any Employee is downloaded, the verifier will not be discovered and will not be run. The same issue exists, in reverse, if we choose to define the verifier in the Order class. Now if we retrieve and change an Employee before retrieving any Orders, again the verifier won’t be discovered, since it is not defined on the Order type.

The solution to this conundrum is to order DevForce explicitly to discover the verifiers for any type that may have verifiers involving a type other than itself. For example, to get EntityManager _em1 to discover the verifiers for the Order type, you can use the following statement:

This should be done before there is any chance that one of the verifiers defined in the Order class might be needed for some other type.

We'll define a DelegateVerifier for the cross-type validation to be performed in our sample.  We're defining the verifier for the Order class, and then defining triggers for both the OrderDate property of Order and the HireDate property of Employee.  We also define the "path" from Employee to Orders.  We could have inverted this setup and defined the verifier for the Employee type; it doesn't really matter to DevForce.

Creating a custom verifier attribute for your custom verifier

The easiest way to create your own custom attribute is to inherit from one of our pre-defined verifier attribute classes. Below is an example of inheriting from a PropertyValueVerifierAttribute class by extending the NotEmptyGuidVerifier above.

You can then apply the attribute to the fields in your buddy class.