ChangePassword Class

Provides a user interface that enable users to change their Web site password.

Namespace: System.Web.UI.WebControls
Assembly: System.Web (in system.web.dll)

public class ChangePassword : CompositeControl, INamingContainer
/** @attribute BindableAttribute(false) */ 
public class ChangePassword extends CompositeControl implements INamingContainer
public class ChangePassword extends CompositeControl implements INamingContainer
Not applicable.

Use the ChangePassword control on a page to enable your Web site users to change the passwords they use to log on to your Web site.


If you are not familiar with the set of login controls available in ASP.NET, read ASP.NET Login Controls Overview before continuing. For a list of other topics related to login controls and membership, see Managing Users By Using Membership.

Security noteSecurity Note:

Transmitting passwords over HTTP is a potential security threat. HTTP transmissions can be viewed or compromised by malicious users. To improve security when using login controls, you should use HTTPS protocol with secure sockets layer (SSL) encryption to ensure that the user's password cannot be read during postback. For more information, see Securing Login Controls.

The ChangePassword control uses the membership provider defined in the MembershipProvider property to change the password stored in the membership provider data store for the Web site. If you do not assign a membership provider, the ChangePassword control uses the default membership provider defined in the membership section of the Web.config file. The ChangePassword control enables users to perform the following actions:

  • Change their password if they are logged on.

  • Change their password if they are not logged on, as long as the page that contains the ChangePassword control allows anonymous access and the DisplayUserName property is true.

  • Change the password for a user account, even if they are logged on as a different user. This requires the DisplayUserName property to be true.

Setting the DisplayUserName property to true displays the User Name text box, which allows the user to type in a user name. If the user is logged on, the UserName control is populated with the name of the logged-on user. After the password for the given user name is changed, the user is logged on to the account associated with the changed password, even if the user was not logged on to that account previously.

Security noteSecurity Note:

Accepting user input is a potential security threat. Malicious users can send data that is intended to expose vulnerabilities or run programs that try generated passwords. To improve security when working with user input, you should use the validation features of your control and secure any data providers that are configured for your control. For more information, see Securing Login Controls, Basic Security Practices for Web Applications, and Securing Membership.

Sending E-mail Messages

The ChangePassword control can be configured to use e-mail services to send the new password to the user. To send e-mail messages to users from any of ASP.NET Web server controls, you must configure an e-mail server in the Web.config file for your application. For more information, see How to: Configure an SMTP Virtual Server.

E-mail messages are configured using the MailDefinition class. You must set the BodyFileName property to instruct ASP.NET to send e-mail.

Security noteSecurity Note:

Sending user account names or passwords in e-mail is a potential security threat. E-mail messages are typically sent in plain text and can be read by special network "sniffing" applications. To improve security, use the mitigations that are described in Securing Login Controls.


It is not possible to guarantee that a user will receive or view an e-mail. To verify that a user has received a notification by e-mail, consider providing a confirmation link in the e-mail that allows the user to confirm that the notification was received.


The ChangePassword control has two states, or views:

  • Change Password view   Requests the current password, and requires the user to type the new password twice for confirmation. If you allow users who are not logged on to change their passwords, set the DisplayUserName property to true to display the UserName control in Change Password view. The UserName control allows the user to provide their registered user name. If there is an error when changing the password, an error message is displayed in the Change Password view, allowing the user to try again.

  • Success view   Provides confirmation that the password has been changed.


The ChangePassword, Continue and Cancel functionality will be attached to any button with the correct command name regardless of which view the button is placed on. For example, a button with the commandname=changepassword on the Success view will attempt to change the password and result in an exception.

Styles and Templates

You can use an extensive set of style properties to customize the appearance of the ChangePassword control. Alternatively, you can apply custom templates to the two views if you need complete control over the appearance of the ChangePassword control. If you define a template for a view, the ControlStyle properties are applied. For a list of the controls that you must set in the view templates, see the ChangePasswordTemplate and SuccessTemplate properties. The ChangePassword control examines the content in the template and throws an exception if a required control is not found, is not named correctly, or is of the wrong type. For example, if you use the content in the template and set the DisplayUserName property to true, the ChangePassword will throw an exception if a TextBox or some other IEditableTextControl control is not found for the user name.

The following table lists the ChangePassword control style properties and describes which UI element they affect. For a list of the properties to which each style applies, see the individual style property.

ChangePassword style property

UI element


Cancel button on the Change Password view.


Change Password button on the Change Password view.


Continue button on the Success view.


Error text displayed to the user.


Hyperlinks to other pages.


Instructional text on the page that describes how to use the ChangePassword control.


Labels for all input fields, such as text boxes.


Hints for providing an acceptable password for the Web site.


Text displayed to the user when the password has been successfully changed.


Text entry input fields.


Titles for the Change Password and Success views.

Validation Groupings

The ChangePassword control uses a validation group so that other fields on the same page as the ChangePassword control can be validated separately. By default, the ID property of the ChangePassword control is used as the name of the validation group. For example, a ChangePassword control with the ID "ChangePassword1" will use a validation group name of ChangePassword1 as well. To set the validation group that the ChangePassword control is part of, you must create a template with the control, and then change the validation group name.

To show error messages if a user leaves a TextBox control empty, add a ValidationSummary control to the page. Set the ValidationGroup property of the ValidationSummary control to the ID property of the ChangePassword control.


If the ChangePassword control is not customized with templates, the AccessKey property of the ChangePassword control applies to the first text box in the control. If the ChangePassword control is customized with templates, then the AccessKey property is ignored. In that case, set the AccessKey property of each template child control directly. The TabIndex property is rendered on all the TextBox controls in the ChangePassword control. If the ChangePassword control is customized with templates, then the TabIndex property is ignored.

The markup rendered by default for this control might not conform to accessibility standards such as the Web Content Accessibility Guidelines 1.0 (WCAG) priority 1 guidelines. For example, using CancelDestinationPageUrl or SuccessPageUrl result in a page refresh which is contrary to the accessibility requirement to not refresh a page when clicking a button or link on a page. For details about accessibility support for this control, see ASP.NET Controls and Accessibility.

Accessing Controls During Page_Load and Page_Init

ChangePassword control properties represented by text boxes, such as UserName and CurrentPassword, are accessible during all phases of the page life cycle. In particular, during the Page_Init and Page_Load phases, these properties have the same value they had when the ChangePassword control was rendered. If the user changes the value of the UserName property by modifying the UserName text box, the new value will be available when the changed event is raised, which occurs after the Page_Load phase. Therefore, if you set the value of the UserName property in the Page_Init phase or Page_Load phase and provide a custom handler for a ChangePassword event, any change that the user makes in the UserName text box overrides the value set in the Page_Init or Page_Load phase.

The following code example shows how to set the NewPasswordRegularExpression property to define a regular expression that checks passwords to ensure that they meet the following criteria:

  • Are greater than six characters.

  • Contain at least one digit.

  • Contain at least one special (non-alphanumeric) character.

The password requirements contained in the PasswordHintText property are displayed to the user.

If the password entered by the user does not meet the requirements of the NewPasswordRegularExpression property, the text contained in the NewPasswordRegularExpressionErrorMessage property is displayed to the user. If a new password is not entered, the text contained in the NewPasswordRequiredErrorMessage property is displayed to the user.


The new password must meet the minimum requirements set by the membership provider in the MinRequiredPasswordLength, MinRequiredNonAlphanumericCharacters, and PasswordStrengthRegularExpression properties. If the password does not meet these requirements, the ChangePasswordError event is raised.

<%@ page language="C#"%>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<script runat="server">


<html xmlns="" >
<head runat="server">
  <title>Change Password with Validation</title>
  <form id="form1" runat="server">
  <asp:changepassword id="ChangePassword1" runat="server"
  PasswordHintText = 
    "Please enter a password at least 7 characters long, 
    containing a number and one special character."
  NewPasswordRegularExpression =
  NewPasswordRegularExpressionErrorMessage =
    "Error: Your password must be at least 7 characters long, 
    and contain at least one number and one special character." >

  • AspNetHostingPermission  for operating in a hosted environment. Demand value: LinkDemand; Permission value: Minimal.
  • AspNetHostingPermission  for operating in a hosted environment. Demand value: InheritanceDemand; Permission value: Minimal.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0