EntityService validation

Abstract

Describes validation features used to enforce custom business rules and protect the server from potentially unsafe input.

EntityService provides validation features that you use to enforce custom business rules and protect the server from potentially unsafe input.

The validation mechanism employed by the EntityService uses types defined in the System.ComponentModel.DataAnnotations namespace. You define business objects as POCO classes, and optionally apply attributes to the public properties to define the custom validation requirements of the data type.

Validation takes place on the client prior to it submitting data to the server, and it takes place on the server when the server receives the data as well. The server emits metadata in response to an HTTP OPTIONS request to notify the client JavaScript library about the validators defined for the specified business object.

Basic validators

Sitecore.Services.Client provides the following validators:

The following code snippet shows how you can apply attributes to the public properties of a business object to support data validation:

public class SimpleEntity : EntityIdentity
{
  [Required]
  [StringLength(10, ErrorMessage = "Names should be between 1 and 10 characters")]
  public string Name { get; set; }
}

Extend validation

You can extend the validation mechanism, and you can define new validators and apply these to business object types.

In addition to the basic set of validators in Sitecore.Services.Client, there is a contrib project. This project contains an example validator extension that supports checking email addresses. You can find this project at https://github.com/Sitecore-Community/Sitecore.Services.Contrib.

Define a new validator type

You can define a new validator by providing a server-side implementation for the type and a client-side validation script.

Server-side implementation

Define a validator by creating a class that derives from System.ComponentModel.DataAnnotations.ValidationAttribute and implement your custom validation logic.
The MSDN article How to: Customize Data Field Validation in the Data Model Using Custom Attributes contains useful information.

Define a metadata emitter by creating a class that derives from Sitecore.Services.Core.MetaData.ValidationMetaDataBase<T> where <T> is your validator type. You can override the virtual method Describe(ValidationAttribute attribute, string filedName) to customize the metadata that is emitted in response to an OPTIONS request.

For example:

public class RegularExpressionMetaData : ValidationMetaDataBase<RegularExpressionAttribute>
{
    public RegularExpressionMetaData()
        : base("regex")
    {
    }
    public override Dictionary<string, object> Describe(ValidationAttribute attribute, string fieldName)
    {
        var metadata = base.Describe(attribute, fieldName);
        var regularExpressionAttribute = (RegularExpressionAttribute)attribute;
        metadata.Add("param", regularExpressionAttribute.Pattern);
        return metadata;
    }
}

Sitecore.Services.Client uses the AssemblyScannerValidationMetaDataProvider implementation of IValidationMetaDataProvider by default. On application startup, this class scans assemblies in the bin folder of your website for types that provide validation metadata.

If you have specified validation attributes on business objects and no corresponding type that provides metadata for the validation is found, a warning is written in the Sitecore log when the attribute is encountered and the EntityService ignores the attribute.

Client implementation

The JavaScript library that interacts with the EntityService needs to know how to handle all the validators that are in the site for client-side validation to work. When you add a custom validator, you must supply a client-side implementation of the validation logic.

You put the client-side validation logic in a JavaScript file in the folder specified by the Sitecore.Extensions.Validation.FolderPath configuration setting. The default setting is \sitecore\shell\client\Services\Assets\lib\extensions\validators.

When the EntityService JavaScript library first meets a custom validator in the service metadata response, it will make a call to the MetaDataScript controller (sitecore/api/ssc/script/metadata) to retrieve the JavaScript file that contains the client-side logic for that validation attribute.