Share via


Using Validation Block Attributes

Validation attributes (both the built-in Validation Application Block attributes and those described in the topic Using Data Annotation Attributes) can be used with various targets that include classes, fields, properties, methods, and (in limited cases) parameters. For information, see Validation Attribute Targets. There is also a set of attributes that allow you to change the behavior of other attributes. These are discussed in Validation Modifier Attributes. You can also specify the attributes you want to use in a separate metadata class. For more details of this, see Defining Attributes in Metadata Classes.

Using Validation Block Attributes to Define Validation Rule Sets

You can include Validation Application Block attributes in your code to define rule sets (you cannot specify named rule sets when you use .NET Data Annotation attributes). This is an alternative to using configuration or code. If you do not specify a name for an attribute validation rule, it is part of the default rule set. The following code example shows how to use attributes to define a rule set named "RuleSetA."

using Microsoft.Practices.EnterpriseLibrary.Common.Configuration;
using Microsoft.Practices.EnterpriseLibrary.Validation;
using Microsoft.Practices.EnterpriseLibrary.Validation.Validators;

public class Customer
{
  private string firstName;
  private string lastName;
  private DateTime dateOfBirth;
  private string email;
  private Address address;
  private int rewardPoints;

  [StringLengthValidator(1, 50, Ruleset="RuleSetA",
               MessageTemplate="First Name must be between 1 and 50 characters")]
  public string FirstName
  {
    get { return firstName; }
    set { firstName = value; }
  }

  [StringLengthValidator(1, 50, Ruleset = "RuleSetA", 
               MessageTemplate = "Last Name must be between 1 and 50 characters")]
  public string LastName
  {
    get { return lastName; }
    set { lastName = value; }
  }

  [RelativeDateTimeValidator(-120, DateTimeUnit.Year, -18, 
                   DateTimeUnit.Year, Ruleset="RuleSetA", 
                   MessageTemplate="Must be 18 years or older.")]
  public DateTime DateOfBirth
  {
    get { return dateOfBirth; }
    set { dateOfBirth = value; }
  }

  [RegexValidator(@"\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*", 
                 Ruleset = "RuleSetA")]
  public string Email
  {
    get { return email; }
    set { email = value; }
  }
    
  [ObjectValidator("ValidAddress", Ruleset="RuleSetA")]
  public Address Address
  {
    get { return address; }
    set { address = value; }
  }

  [RangeValidator(0, RangeBoundaryType.Inclusive, 1000000, 
        RangeBoundaryType.Inclusive, Ruleset="RuleSetA", 
        MessageTemplate="Rewards points cannot exceed 1,000,000")] 
  public int RewardPoints
  {
    get { return rewardPoints; }
    set { rewardPoints = value; }
  }

}
'Usage
Imports Microsoft.Practices.EnterpriseLibrary.Common.Configuration
Imports Microsoft.Practices.EnterpriseLibrary.Validation
Imports Microsoft.Practices.EnterpriseLibrary.Validation.Validators

Public Class Customer

  Private _firstName As String
  Private _lastName As String
  Private _dateOfBirth As DateTime
  Private _email As String
  Private _address As Address 
  Private _rewardPoints As Integer

  <StringLengthValidator(1, 50, Ruleset:="RuleSetA", _
              MessageTemplate:="First Name must be between 1 and 50 characters")> _
  Public Property FirstName() As String
    Get
      Return _firstName
    End Get
    Set(ByVal value As String)
      _firstName = value
    End Set
  End Property
 

  <StringLengthValidator(1, 50, Ruleset:="RuleSetA", _
               MessageTemplate:="Last Name must be between 1 and 50 characters")> _
  Public Property LastName() As String
    Get
      Return _lastName
    End Get
    Set(ByVal value As String)
      _lastName = value
    End Set
  End Property

  <RelativeDateTimeValidator(-120, DateTimeUnit.Year, -18, _
                   DateTimeUnit.Year, Ruleset:="RuleSetA", _
                   MessageTemplate:="Must be 18 years or older.")> _
  Public Property DateOfBirth() As DateTime
    Get
      Return _dateOfBirth
    End Get
    Set(ByVal value As DateTime)
      _dateOfBirth = value
    End Set
  End Property

  <RegexValidator("\w+([-+.']\w+)*@\w+([-.]\w+)*\.\w+([-.]\w+)*", _
                  MessageTemplate:="Invalid e-mail address", _
                  Ruleset:="RuleSetA")> _
  Public Property Email() As String
    Get
      Return _email
    End Get
    Set(ByVal value As String)
      _email = value
    End Set
  End Property

  <ObjectValidator("ValidAddress", Ruleset:="RuleSetA")> _
  Public Property Address() As Address
    Get
      Return _address
    End Get
    Set(ByVal value As Address)
      _address = value
    End Set
  End Property

  <RangeValidator(0, RangeBoundaryType.Inclusive, 1000000, _
        RangeBoundaryType.Inclusive, Ruleset:="RuleSetA", _
        MessageTemplate:="Rewards points cannot exceed 1,000,000")> _
  Public Property RewardPoints() As Integer
    Get
      Return _rewardPoints
    End Get
    Set(ByVal value As Integer)
      _rewardPoints = value
    End Set
  End Property

End Class

This code defines a class named Customer that includes a number of properties such as FirstName and LastName. Attributes that are attached to these properties associate them with validators. For example, the StringLengthValidator attribute is attached to the FirstName property and associates it with the StringLengthValidator class. This attribute includes two constructor parameters that constrain the length of the value contained in the FirstName field, a parameter that specifies the rule set to apply, and a parameter that defines the message template. The message template contains the message that is returned if validation fails.

The Ruleset parameter of the validation attributes indicates that the application block will use "RuleSetA" instead of the anonymous, default rule set. In this example, the ObjectValidator attribute is a part of the "RuleSetA" rule set and refers to the "RuleSetA" rule set of the Address class.

Validation Attribute Targets

Validation attributes can be used with various targets. The following table lists the targets and describes how the validators associated with the attributes behave.

Target

Behavior of associated validator

Class

The validator checks the object. Typically, these attributes are custom type-level validators supplied by the user. The supplied validators, with the exception of the Not Null validator, object collection validator, and composite validators, can only be used at the member level and not the class level.

Field

The validator checks the value of the field.

Property

The validator checks the value of the get property.

Method

The validator checks the return value of the method. A validator attribute can only be applied to methods that take no arguments.

Parameter

The Validation Application Block ignores attributes attached to parameters except for WCF and the Policy Injection Application Block Validation Call Handler.

Validation Modifier Attributes

Validation modifier attributes allow you to change the way validation attributes behave. The validation modifier attributes are the following:

  • ValidatorComposition
  • IgnoreNulls
  • HasSelfValidation
  • SelfValidation

The ValidatorComposition attribute allows you to provide a composite validator as an attribute. With it, you can override the default behavior that occurs when you use more than one validator attribute. You can specify either CompositionType.And or CompositionType.Or as an argument to this attribute. The default composition type is AND. The default behavior is the same as if you do not use the attribute. Typically, you use the AND composition type when the logic is complex and requires OR operations as well as AND operations.

You can have a composite validator within the context of Enterprise Library Configuration, Enterprise Library Validation Application Block, and DatAnnotations. When using DataAnnotations attributes, the composite validator can only be an implicit AND of the attributes. For Validation Application Block attributes, the composite validator is formed by using an AND of the attributes by default. The composite validator logic can be changed through the ValidatorComposition attribute.

Enterprise Library Configuration does not rely on attributes. Configuration has its own structure for composing validators. The validator that will actually be used incorporates the rules from these three sources by using a logical AND of the rules. The result is independent of how the validators from each source are composed.

The IgnoreNulls attribute specifies that the other validators will not be called if the value that you are checking is null.

The following table shows some examples of how you can combine attributes to achieve the equivalent of the common ways you might use of the And and Or validators in a configuration rule set.

Attributes

Equivalent in Configuration

[ValidatorX]

[ValidatorY]

[ValidatorZ]

And Composite Validator

  • Validator X
  • Validator Y
  • Validator Z

[ValidatorComposition(CompositionType.Or)]

[ValidatorX]

[ValidatorY]

[ValidatorZ]

Or Composite Validator

  • Validator X
  • Validator Y
  • Validator Z

[IgnoreNulls]

[ValidatorX]

[ValidatorY]

Or Composite Validator

  • Not Null Validator (Negated)
  • And Composite Validator
    • Validator X
    • Validator Y

The HasSelfValidation attribute marks a class that contains Self validation logic. The SelfValidation attribute marks Self validation methods within that class. For more information, see Using Self Validation.