The Validation Handler

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

The Validation Handler provides the capability to test whether the value provided for the selected property, or the values specified for the parameters of the selected method, are valid against specific rules. This handler uses the Validation Application Block, taking advantage of the wide range of rules that it supports.

The Validation Handler applies the validation before invoking the method or setting the property of the target object. If validation fails, the Validation Handler aborts execution of the pre-processing handler pipeline, does not invoke the method or set the property, and raises an ArgumentValidationException.

Note

The Validation Handler will always initialize the Validation Application Block using the default configuration source, even if you instantiate the handler yourself in code and specify an alternative configuration source.

Behavior of the Validation Handler

In more detail, the Validation Handler does the following:

• It reads details of any custom rule set to use, and the "specification source" (rule location), from the Policy Injection Application Block configuration.

• It looks for validation attributes explicitly specified on parameters, such as in the following example.

  public void Deposit([RangeValidator(typeof(Decimal), "0.0",
                       RangeBoundaryType.Exclusive, "0.0", 
                       RangeBoundaryType.Ignore)] decimal depositAmount)
  {
    balance += depositAmount;
  }
  

  'Usage
  Public Sub Deposit(<RangeValidator(typeof(Decimal), "0.0", _
                       RangeBoundaryType.Exclusive, "0.0", _
                       RangeBoundaryType.Ignore)> decimal depositAmount)
    balance += depositAmount
  End Sub
  

• It looks for validation attached to parameter types using a rule set specified in the handler's configuration. For example, if the method accepts a custom type such as Customer or Order as a parameter, the handler will look for a rule set defined within that custom class and validate the instance accordingly. The SpecificationSource property controls where the handler will look for custom rule sets.

• It validates the parameters according to the discovered validators.

• If validation succeeds, it allows the next handler to execute.

• If validation fails, it creates an exception, wraps it in a message, and returns it to the previous handler, which may act on it. The exception ultimately returns to the caller.

Configuration Settings of the Validation Handler

The following configuration settings are available for the Validation Handler:

• Ruleset (String). This is the rule set name to use for all target object types. An empty string causes the handler to use the default rule set.
• SpecificationSource (SpecificationSource). This is where the handler will look for validation rules. It is a value from the SpecificationSource enumeration. Valid values are Both, Attributes, Configuration, and ParameterAttributesOnly. The default setting is Both.
• Order (Integer). This value specifies the position of the handler within the policy handler chain. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain. To specify an explicit order, set the Order property for each handler starting from 1. If you specify the same value for the Order property of two handlers in the same policy, the application block will add them to the policy handler chain in the order defined in the configuration.

The next procedure describes how to configure the Validation Handler using the Configuration Console or the Visual Studio Configuration Editor.

To configure the Validation Handler

1. Right-click the Handlers node in the Enterprise Library Configuration Console or Visual Studio Configuration Editor, point to New, and then click Validation Call Handler.
2. In the right pane of the Enterprise Library Configuration Console, or in the Visual Studio Properties window, select the Name property, and then change the default name to the name you want to use for the new handler.
3. If you need to use validation rules stored in a custom class, select the RuleSet property, and then specify the class where the rules reside.
4. If you specify a custom RuleSet property value, select the SpecificationSource property, and then select a value from the drop-down list that indicates where to find the custom rules within the custom class. The options are Configuration, Attributes, ParameterAttributesOnly, and Both.
5. (Optional) Enter a numeric value for the Order property if you want to specify the position of the handler within the policy handler chain. Set the Order property for each handler starting from 1.

Attribute-based Targeting with the Validation Handler

The following code shows the use of the ValidationCallHandler attribute on a simple method. This attribute can also be applied to the class declaration; in which case, it applies to all members of that class. The attribute accepts a parameter containing the name of the rule set to use for validation, as defined in the application configuration. If omitted, the handler uses the default validation rule set.

[ValidationCallHandler("ruleset-name")]
public void Deposit(decimal depositAmount)
{
  balance += depositAmount;
}

[ValidationCallHandler()]
public void Withdraw(decimal withdrawAmount)
{
  balance -= withdrawAmount;
}

'Usage
<ValidationCallHandler("ruleset-name")> _
Public Sub Deposit(Decimal depositAmount)
  balance += depositAmount
End Sub

<ValidationCallHandler()> _
Public Sub Withdraw(Decimal withdrawAmount)
  balance -= withdrawAmount
End Sub

The following table describes the properties of the ValidationCallHandlerAttribute class.

Property	Description
SpecificationSource	A value from the SpecificationSource enumeration that defines the locations where the handler will look for validation rules. Valid values are Attributes, Configuration, ParameterAttributesOnly, and Both.
Order	Integer. The position of the handler within the policy handler chain, starting from 1. The default value is zero, which means that there is no explicit order specified for the handler in relation to other handlers in the same handler chain.

To set these properties using an attribute, add them as parameters to the attribute declaration, as shown in the following code.

[ValidationCounterCallHandler("ruleset-name", SpecificationSource=SpecificationSource.Both]

'Usage
<ValidationCounterCallHandler("ruleset-name", SpecificationSource:=SpecificationSource.Both)>

Validating Parameters with Attribute-based Targeting

When you use the Validation Call Handler, you can specify the name of a rule set when use an Object Validator to validate individual parameters of a method, as shown in the following code.

[ValidationCallHandler]
public void SomeMethod(
            [RegexValidator("...")] String x,
            [ObjectValidator("RulesetName")] String y) 
{ 
  ... 
}

'Usage
<ValidationCallHandler> _
Public Sub SomeMethod( _
            <RegexValidator("...")> x As String, _
            <ObjectValidator("RulesetName")> y As String) 
End Sub