Walkthrough: Validating User Input in a Web Forms Page
This walkthrough illustrates how to use ASP.NET validator controls to check user input in a Web page. You will work with some controls that perform all checking automatically, requiring no code. You will also create a custom validator with code that you write, which illustrates how you can add your own logic to the validation framework in the page. Finally, you will learn how you can validate user input conditionally, depending on choices that the user makes in a page.
In the walkthrough, you will create a page for a Web site that allows visitors to request a reservation. Because the purpose of the walkthrough is to illustrate validation, the nature of the reservation is not important (for example, if could be for a restaurant, a community center meeting room, or something else), and the page does not actually process the reservation.
The page you create will prompt the user for an e-mail address, the number of people to reserve for, and a preferred date. The page also allows the user to request a telephone confirmation of the reservation. (The default for this page, if implemented, would be e-mail confirmation.)
By default, the Web Forms page automatically validates that malicious users are not attempting to send script to your application even if you do not use validation controls. For more information, see Script Exploits Overview.
During this walkthrough, you will learn how to:
Use validator controls to check user input in an ASP.NET Web page.
Format the display of validation error messages.
Create custom validation by writing code.
A Visual Studio project with source code is available to accompany this topic: Download.
In order to complete this walkthrough, you will need:
Visual Studio or Microsoft Visual Web Developer Express.
If you are using Visual Studio, the walkthrough assumes that you selected the Web Development collection of settings when you started Visual Studio the first time. For more information, see How to: Select Web Development Environment Settings.
In the first part of the walkthrough, you will create a Web site and a page where you can work with styles. If you have already created a Web site in Visual Studio (for example, by working with the topic Walkthrough: Creating a Basic Web Page in Visual Studio ), you can use that Web site and skip to "Adding Controls" later in this walkthrough. Otherwise, create a new Web site.
This walkthrough uses a Web site project. You could use a Web application project instead. For information about the difference between these Web project types, see Web Application Projects versus Web Site Projects.
To create a file system Web site
Open Visual Studio or Visual Web Developer Express.
In the File menu, click New Web Site.
The New Web Site dialog box is displayed.
Under Installed Templates, click Visual Basic or Visual C# and then select ASP.NET Web Site.
In the Web location box, select File System, and then enter the name of the folder where you want to keep the pages for your Web site.
For example, type the folder name C:\WebSites.
Visual Studio creates a Web site project that includes prebuilt functionality for layout (a master page, the Default.aspx and About.aspx content pages, and a cascading style sheet), for Ajax (client script files), and for authentication (ASP.NET membership).
You will use only a few controls to prompt the user the information required for the reservation.
To add controls and text
In Solution Explorer, right-click the project and select Add New Item.
The Add New Item dialog box is displayed.
Under Installed Templates select Visual Basic or Visual C#, and then select Web Form.
Enter ValidationExample.aspx as the name for the new Web page and then click Add.
Switch to Design view.
Type a page heading such as Submit a Reservation and then press ENTER to create a new line below the heading.
From Standard group of the Toolbox, drag the following controls onto the page below the heading and set their properties as indicated. After each control is dropped on the page, press ENTER so that each control is on a separate line, and press ENTER twice before the Button control to leave room for additional controls to be added later.
Type text in front of the text boxes as captions.
Double-click the Submit Request button to create a handler for its Click event and then add code as shown in the following example:
Protected Sub buttonSubmit_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) If Page.IsValid Then labelMessage.Text = "Your reservation has been processed." End If End Sub
The button handler simply displays a message; it performs no actual processing. However, the message display will allow you to test the effect of validation later in the walkthrough.
In the .aspx page, switch to Design view, double-click a blank area in the page to create a Page_Load handler, and then add code as shown in the following example:
Protected Sub Page_Load(ByVal sender As Object, _ ByVal e As EventArgs) labelMessage.Text = "" End Sub
Each time the page loads, this code clears any message that may have been left over from a previous postback.
For your imaginary reservation system, you will want to enforce the following validation checks:
The e-mail address is required, and it must be formatted properly; for example, email@example.com. (It is generally not practical to check that an e-mail address is someone's real address; however, you can check that the address conforms to the proper pattern for e-mail addresses.)
The number of people is also required, and it must be numeric.
The preferred date is required.
You can add all of this validation using validator controls, which perform all of the checks for you and automatically display errors.
Later in the walkthrough you will add another check to be sure that users enter a valid date.
To add basic validation
In the .aspx page, switch to Design view.
From the Validation group of the Toolbox, drag a RequiredFieldValidator control and drop it next to the textEmail text box.
Set the following properties of the RequiredFieldValidator control:
Binds the validator control to the text box whose contents you want to validate.
Specifies that the control renders (and takes up space in the page) only if required in order to display an error.
E-mail address is required.
Provides text for a ValidationSummary control, which you will configure later in the walkthrough.
An asterisk is a conventional way of indicating that a field is required. This text is displayed in the validation control and is displayed only if there is an error.
As with radio buttons, you can group validators into groups that are treated as a unit. You will learn more about validation groups later in the walkthrough.
What you have done is added a test to be sure the user enters an e-mail address. The validator control performs all the checking and error display without requiring you to add code to the page.
Set the following properties of the RegularExpressionValidator control:
You are again validating the user's entry in the e-mail box.
E-mail addresses must be in the format of firstname.lastname@example.org.
This is a longer error message that is displayed by a ValidationSummary control.
This is a short error message that is displayed in the validation control.
Regular expressions constitute a language that can be used to find precisely defined patterns in strings. In the RegularExpressionValidator control, you define a regular expression for the pattern that is valid — in this case, the pattern for a valid e-mail address.
The Regular Expression Editor contains a list of commonly used regular expressions so that you can use the validator control without learning regular expression syntax.
In the Standard Expressions list, click Internet E-mail Address.
The regular expression for an e-mail address is put in the Validation Expression box.
Click OK to close the dialog box.
Add another RequiredFieldValidator control, using the instructions earlier in this procedure. However, this time bind it to the textNumberInParty text box and set its ErrorMessage property to Please indicate how many people are in your party.
Set the following properties of the RangeValidator control:
Enter a number between 1 and 20 for the number of people in your party.
In this case, an arbitrary but high value.
In this application, a reservation requires at least one person.
Enter a number between 1 and 20.
This RangeValidator control performs two functions: it ensures that the data a user enters is numeric, and it checks that the number is between the specified minimum and maximum values.
Testing the Page
You can now test the validator controls that you have so far.
To test basic validation
Press CTRL+F5 to run the page.
When the page appears in the browser, click the Submit Request button.
Check the validation on the textEmail text box by typing an invalid e-mail address, and then again with a valid e-mail address such as your own.
Check that you can enter only numeric values between 1 and 20 in the Number of people in party text box.
When you have entered valid values, click the Submit Request button. If the validation passes for all controls, you will see the message Your reservation has been processed.
After you have confirmed that validation is working as expected, close the browser.
If validation is not working as expected, double-check that you have made all the property settings listed above and then run the page again.
By default, validator controls display error text in-place; that is, they display the value of the control's Text property at the control's location in the page. At times you might want to display error information in different ways. The ASP.NET validator controls provide you with these additional options:
Summarize all validation errors in one place. You can do this in addition to or instead of showing in-place errors. Displaying error summaries also allows you to display longer error messages.
Display a pop-up message in the browser with error information. This option works only on script-enabled browsers.
You can add both of these display options using the ValidationSummary control. In this part of the walkthrough, you'll add both display features to the page.
To display validation information in alternative ways
From the Validation group of the Toolbox, drag a ValidationSummary control to the bottom of the page.
Run the page.
Perform the same testing you did earlier in the walkthrough.
For each error, you see error information in two places. A short error message (the validator's Text property value) is displayed where the validator control is. The longer error message (the control's ErrorMessage property value) is displayed in the ValidationSummary control.
Close the browser.
Run the page.
Perform the same tests.
This time, each error results in a pop-up message in the browser.
Close the browser.
The ASP.NET validation controls do not include a control that automatically checks for a valid date. However, you can use the CustomValidator control for that purpose. The custom validator allows you to write your own validation code to check for any condition your application requires. In this walkthrough, you will use the CustomValidator to check that the value the user enters into the textPreferredDate text box can be converted to a date value.
To use a CustomValidator control to check for a valid date
From the Validation group of the Toolbox, drag a CustomValidator control onto the page and position it next to the textPreferredDate text box.
Set the following properties of the CustomValidator control:
Protected Sub CustomValidator1_ServerValidate( _ ByVal source As Object, _ ByVal args As System.Web.UI.WebControls.ServerValidateEventArgs) Try DateTime.ParseExact(args.Value, "m/d/yyyy", _ System.Globalization.DateTimeFormatInfo.InvariantInfo) args.IsValid = True Catch args.IsValid = False End Try End Sub
This code runs when the user submits the page. The code interacts with the validator control using the ServerValidateEventArgs (args) object passed into the handler. The value that the user has entered into the textPreferredDate text box is passed as the args object's Value property. After you have checked whether the user's entry is valid, you set the args object's IsValid property to true or false. If you set it to false, the validator will display its error message.
In this example, the code uses a try-catch block to determine whether the user's entry can be converted into a DateTime object. If the user enters an invalid value (anything that does not conform to a date in the format m/d/yyyy), the DateTime object's ParseExact method throws an exception, and the Catch block is executed.
The sample code specifies that the format to be parsed is culture-independent. If you need to use the current culture, you can set provider to null.
In the Button_Click handler, add code as shown in the following example:
Protected Sub buttonSubmit_Click(ByVal sender As Object, _ ByVal e As System.EventArgs) If Page.IsValid Then labelMessage.Text = "Your reservation has been processed." Else labelMessage.Text = "Page is not valid." End If End Sub
When you use a CustomValidator control, you must check the Page.IsValid property in any server-side processing to be sure that all the validation checks have passed. The IsValid property returns the cumulative state of all the validator controls on the page. This property is used to make sure that all validation checks have passed any server-side processing.
You have now added the server-side code for the CustomValidator control to check for a valid date. As you know from earlier in the walkthrough, validator controls also check a user's entry using client script. You can add client script to the CustomValidator control as well. In effect, you write client script that duplicates the logic that your server-side validation performs. Writing client-side custom validation code is not always practical (for example, if the custom code validates a user's entry by looking in a server-side database). However, in this case you can create client-side code that performs essentially the same check that your server-side code is performing.
To add client script to the CustomValidator control
Open or switch to ValidationExample.aspx, and switch to Source view.
In the <head> element of the page, add the following client script block:
This code is similar to the server-side validation check, but not as strict. The user's entry is passed into the function as the args object's Value property, and you can set the object's IsValid property to indicate whether the value passes validation. In this example, the code checks to make sure valid numeric dates were entered.
Note that the code for the custom validation is slightly different in client script than it is in server code. ECMAScript does not provide exactly the same functionality as that in the .NET Framework. Therefore, the ECMAScript parses the entered text instead of the ParseExact code that you use on the server to check the date. However, the two validation checks (client and server) are similar enough to provide the functionality you need.
Put the insertion point in the asp:customvalidator element to select it.
In the Properties window, set the control's ClientValidationFunction property to validateDate, which is the name of the ECMAScript function that you just created.
You have now added a custom validation check that works both in client script to check the user's entry immediately and then again when the page is submitted to the server.
Testing Custom Validation
You can now test that your custom validation is working properly.
To test custom validation
Press CTRL+F5 to run the page.
Fill in an e-mail address and the number of people in the party so that the validation for those fields passes.
In the date text box, enter a string that is obviously not a date and then click the Submit Request button.
Your page performs a round trip to the Web server, where the server-side validation fails. The test for IsValid fails and labelMessage says "Page is not valid."
Fill in a valid date value (such as 11/17/2010) and click the button.
This time, the date value passes validation, so you see the confirmation message created in the button's Click handler.
Close the browser.
Run the page again and enter valid values for the e-mail address and number of people in the party.
Enter an invalid date value into the date text box and then press the TAB key. (Do not click the button.)
As soon as the date text box loses focus, the client-side validation script runs and you see an error message.
If you are using the auto-complete option in Internet Explorer, selecting a value from the auto-complete list will fill a value into the text box, but the client-side validator will not run.
Click the Submit Request button.
Because the client-side validation for the date text box has failed, the page is not submitted.
Correct the date value and press the TAB key again.
The error message disappears. You can now submit the form.
In the final part of the walkthrough, you will add some optional information to the reservation form. Users can check a box to indicate that they want telephone confirmation of their reservation. If they do, they must enter their telephone number. The page will therefore contain two additional controls: a check box and a text box.
As before, you will use validation to check the user's entries. You will use a RequiredFieldValidator control to be sure that users enter a phone number, and a RegularExpressionValidator control to check its format. The telephone number is optional; you need to check the phone number only if the user has selected the Confirm reservation by phone check box. You therefore will write some simple code that turns validation on or off for the telephone number depending on the state of the check box.
To add conditional validation
From the Standard group of the Toolbox, drag a CheckBox control onto the page above the Submit Request button, press ENTER to create an empty line below it, and set the following properties:
When the user clicks the check box, the page will perform a round trip and conditionally enable the text box and the validation for it.
Clicking the CheckBox will not automatically cause validation.
Confirm reservation by telephone.
Type text such as Telephone number: next to the phone number text box as a caption.
From the Validation group of the Toolbox, drag a RequiredFieldValidator onto the page next to the telephone number text box and set the following properties:
You did not set the ID of validator controls earlier in the walkthrough, but in this case you will be referring to the validator control in code, so you it is helpful to give it a mnemonic ID.
You must provide a phone number.
If this property is blank, the validator does not belong to the AllValidators group that you established for the other validator controls on the page. As a consequence, by default this validator is not checked when the buttonSubmit control is clicked.
Drag a RegularExpressionValidator control onto the page and set the following properties:
Phone number format is invalid
(Use the Regular Expression Editor dialog box to select U.S. Phone Number or another phone number expression.)
Double-click the checkPhoneConfirmation control to create a handler for its CheckedChanged event and then add code as shown in the following example:
Protected Sub checkPhoneConfirmation_CheckedChanged( _ ByVal sender As Object, _ ByVal e As System.EventArgs) If checkPhoneConfirmation.Checked = True Then textPhoneNumber.Enabled = True validatorRequiredPhoneNumber.ValidationGroup = "AllValidators" validatorRegExPhoneNumber.ValidationGroup = "AllValidators" Else textPhoneNumber.Enabled = False validatorRequiredPhoneNumber.ValidationGroup = "" validatorRegExPhoneNumber.ValidationGroup = "" End If End Sub
When the user clicks the check box, the two validators associated with the text box are added to the validation group that the other validator controls belong to. The effect is that all the validators on the page, including those for the phone number, will be checked when the user submits the page. If the user clears the check box, the validators are removed from the group and are therefore not processed when the Submit Request button is clicked.
Testing Conditional Validation
You can now test that conditional validation is working properly.
To test conditional validation
Press CTRL+F5 to run the page.
Enter information for the e-mail address, the number of people in the party, and the date.
Click Submit Request.
The page is submitted and you see the confirmation message.
Select the Confirm reservation by phone check box.
Click Submit Request again.
This time, you see an error message (a star next to the phone text box). When you clicked the check box, you enabled validation for the text box.
Enter an invalid phone number and then click Submit Request again to confirm that the text box will not accept an invalid phone number.
Enter a correctly formatted phone number and click the submit button to confirm that the validator control accepts well-formed data.
If you have selected U.S. Phone Number in the Regular Expression Editor for the ValidationExpression property of the RegularExpressionValidator control, a correctly formatted phone number consists of the area code (optional field with 3 numeric characters, enclosed in parentheses or followed by a dash), followed by a set of 3 numeric characters, a dash and then a set of 4 numeric characters. Valid examples are (425) 555-0123, 425-555-0123 or 555-0123.
The validation you added to the Web Forms page illustrates the basic concepts of Web validation controls.
An important aspect of validation is understanding how it helps you increase the security for your Web site. For details, see Overview of Web Application Security Threats