Use the System.Web.UI.WebControls.CustomValidator control to provide a user-defined validation function for an input control. The System.Web.UI.WebControls.CustomValidator control is a separate control from the input control it validates, which allows you to control where the validation message is displayed.

Validation controls always perform validation on the server. They also have complete client-side implementation that allows script-enabled browsers (such as Microsoft Internet Explorer 4.0 and later) to perform validation on the client. Client-side validation enhances the validation process by checking user input before it is sent to the server. This allows errors to be detected on the client before the form is submitted, thus avoiding the round trip of information necessary for server-side validation.

To create a server-side validation function, provide a handler for the CustomValidator.ServerValidate event that performs the validation. The string from the input control to validate can be accessed by using the ServerValidateEventArgs.Value property of the System.Web.UI.WebControls.ServerValidateEventArgs object passed into the event handler as a parameter. The result of the validation is then stored in the ServerValidateEventArgs.IsValid property of the System.Web.UI.WebControls.ServerValidateEventArgs object.

To create a client-side validation function, first add the server-side validation function described earlier. Next, add the client-side validation script function to the ASP.NET (.aspx) page.

If you are using Visual Basic Scripting Edition (VBScript), the function must be in this form:

 Sub ValidationFunctionName(source, arguments)

If you are using JScript, the function must be in this form:

 function ValidationFunctionName(source, arguments)

The source parameter is a reference to the <span> element rendered for the System.Web.UI.WebControls.CustomValidator control. This allows you to programmatically control the <span> tag, such as modifying the System.Windows.Forms.HtmlElement.InnerHtml attribute. The arguments parameter is an object with two properties: Value and IsValid. This parameter allows you to get the value of the control to validate and to indicate whether the value is valid based on your custom validation routine.

Use the CustomValidator.ClientValidationFunction property to specify the name of the client-side validation script function associated with the System.Web.UI.WebControls.CustomValidator control. Because the script function is executed on the client, the function must be in a language that the target browser supports, such as VBScript or JScript.

Like server-side validation, the string from the input control to validate is accessed by using the ServerValidateEventArgs.Value property of the arguments parameter. Return the result of the validation by setting the ServerValidateEventArgs.IsValid property of the arguments parameter.

Multiple validation controls can be used with an individual input control to validate different criteria. For example, you can apply multiple validation controls on a System.Web.UI.WebControls.TextBox control that allows the user to enter the quantity of items to add to a shopping cart. You can use a System.Web.UI.WebControls.CustomValidator control to ensure that the value specified is less than the amount in inventory and a System.Web.UI.WebControls.RequiredFieldValidator control to ensure that the user enters a value into the System.Web.UI.WebControls.TextBox control.

It is possible to use a System.Web.UI.WebControls.CustomValidator control without setting the BaseValidator.ControlToValidate property. This is commonly done when you are validating multiple input controls or validating input controls that cannot be used with validation controls, such as the System.Web.UI.WebControls.CheckBox control. In this case, the ServerValidateEventArgs.Value property of the arguments parameter passed to the event handler for the CustomValidator.ServerValidate event and to the client-side validation function always contains an empty string (""). However, these validation functions are still called, where appropriate, to determine validity on both the server and client. To access the value to validate, you must programmatically reference the input control you want to validate and then retrieve the value from the appropriate property. For example, to validate a System.Web.UI.WebControls.CheckBox control on the server, do not set the BaseValidator.ControlToValidate property of the validation control and use the following code for the handler for the CustomValidator.ServerValidate event.

Sub ServerValidation (source As object, args As ServerValidateEventArgs)
    args.IsValid = (CheckBox1.Checked = True)
 End Sub

void ServerValidation (object source, ServerValidateEventArgs args)
 {
    args.IsValid = (CheckBox1.Checked == true);
 }

For more information on validation controls, see System.Web.UI.WebControls.BaseValidator.

Accessibility

For information about how to configure this control so that it generates markup that conforms to accessibility standards, see Accessibility in Visual Studio 2010 and ASP.NET 4 and ASP.NET Controls and Accessibility.