April 4, 2011, 8:16 a.m.
posted by pumi
Accessing the Membership and Roles Features in Code
The membership and roles system is implemented through a series of classes within the .NET Framework, and you can access these classes to read and set properties, and to call methods, in your code if you need to bypass or complement the built-in membership and role features of ASP.NET. The following are the three main classes:
We will briefly look at the members of each class to give you an idea of the kind of things you can accomplish in your code.
The Membership Class
The Membership class exposes a set of static properties that refer to the currently logged in user. The properties equate to those you saw in machine.config that control how the membership system behaves. It includes properties such as EnablePasswordReset, EnablePassword Retrieval, MinRequiredPasswordLength, and RequiresQuestionAnd Answer.
The Membership Methods
There is a range of methods that allow you to get information about and manipulate the current user, and to find and get information about other users.
Create and Delete a User
Membership.CreateUser(user-name, password) Membership.CreateUser(user-name, password, email) Membership.DeleteUser(name)
Get a Reference to a User
You can get a reference to a single user as a MembershipUser instance using one of the overloads of the GetUser method. Setting the is-online parameter to true means that the LastActivity property is updated in the membership system as well:
MembershipUser thisUser = Membership.GetUser() MembershipUser thisUser = Membership.GetUser(user-name) MembershipUser thisUser = Membership.GetUser(is-online) MembershipUser thisUser = Membership.GetUser(user-name, is-online)
Find or Get a List of Users
To find users by name or e-mail address, or to get a list of all users, you use one of the following methods. All return a MembershipUser Collection instance, which you can iterate through to get a reference to each MembershipUser instance, or bind directly to a list control to display the user details.
MembershipUserCollection list = Membership.FindUsersByName(user-name) MembershipUserCollection list = Membership.FindUsersByEmail(email) MembershipUserCollection list = Membership.GetAllUsers()
Get the User Name from an E-mail Address
String user-name = Membership.GetUserNameByEmail(email)
Determine the Number of Users Online
If you want to know how many users are online, you can call the following method:
Int32 count = Membership.GetNumberOfUsersOnline()
The Membership Event
There is one event raised by the Membership class that occurs when the current user account is created or the user's password is changed or reset. The ValidatingPassword event passes to its event handler an instance of the ValidatePasswordEventArgs class, which exposes properties that indicate the user name, the new password, whether this is a new user account, information on why the update failed if it did, and a Cancel parameter that you can set to TRue to prevent the update taking place.
Validating a User
As a simple example of using the Membership class, the code fragment shown in Listing 11.13 checks if the user name and password are valid, and if so calls the RedirectFromLoginPage method of the FormsAuthentication class to redirect the user to the next page. If authentication fails, the code displays a message.
A full list of the properties and methods of the Membership class is available at http://msdn2.microsoft.com/library/system.web.security.membership_members.
For details of the FormsAuthentication class, see http://msdn2.microsoft.com/library/k3fc21xw(en-US,VS.80).aspx.
A Simple Example of Validating a User in Code
The MembershipUser Class
The MembershipUser class represents a single user within the ASP.NET membership system, obtained from one of the Find or Get methods of the Membership class. It exposes properties that you can read or set to update this user. The property names are self-explanatory, and include LastLogin Date, CreationDate, LastActivityDate, LastPasswordChangedDate, Email, IsApproved, PasswordQuestion, and UserName.
After you update any of these properties, you must call the static UpdateUser method of the Membership class to push the changes back into the membership system. This approach means that updating several properties only requires one call to the database to perform the update.
The MembershipUser Methods
The following methods are available.
To get the password for a user, so that you can perform custom validation, use one of the overloads of the GetPassword methoddepending on whether the membership system is configured to require users to provide a security question and answer:
String password = this-user.GetPassword() String password = this-user.GetPassword(answer)
To change the password of a user, call the ChangePassword method:
Boolean worked = this-user.ChangePassword(oldPassword, newPassword)
Change Security Q/A
Boolean worked = this-user.ChangePasswordQuestionAndAnswer(password, question, answer)
Finally, to reset the password when it cannot be retrieved (when EnablePasswordReset is true and EnablePasswordRetrieval is false) use the ResetPassword method. This returns the newly generated random password:
String newPassword = this-user.ResetPassword() String newPassword = this-user.ResetPassword(answer)
A full list of the properties and methods of the MembershipUser class is available at http://msdn2.microsoft.com/library/system.web.security.membershipuser_members.
The Roles Class
The Roles class provides methods that you can use to modify the roles in your application, get information about which users are in a role, add users to a role, and remove them from a role.
To create or delete roles, you use the CreateRole and DeleteRole methods:
Get Role Names Lists
You use several different methods and overloads to get lists of role names as a String array. If you do not specify a user name for the GetrolesForUser method, it assumes the current user:
String role-names = Roles.GetAllRoles() String role-names = Roles.GetRolesForUser() String role-names = Roles.GetRolesForUser(user-name) String user-names = Roles.GetUsersInRole(role-name) String user-names = Roles.FindUsersInRole(role-name, user-name)
Check if User Is in Role
Boolean result = Roles.IsUserInRole(role-name) Boolean result = Roles.IsUserInRole(user-name, role-name)
Add Users to Roles
You can add users to roles with one of the overloads of the Add User(s)ToRole(s) methods. The relationship between users and roles is many-to-many, in that a user can be in more than one role, and a role contains more than one user. Therefore, there are methods that take single and an array of user names and/or role names:
Roles.AddUserToRole(user-name, role-name) Roles.AddUserToRoles(user-name, role-names) Roles.AddUsersToRole(user-names, role-name) Roles.AddUsersToRoles(user-names, role-names)
Remove Users from Roles
To remove users from roles, you use one of the equivalent overloads of the RemoveUser(s)FromRole method:
Roles.RemoveUserFromRole(user-name, role-name) Roles.RemoveUserFromRoles(user-name, role-names) Roles.RemoveUsersFromRole(user-names, role-name) Roles.RemoveUsersFromRoles(user-names, role-names)
A full list of the properties and methods of the Roles class is available at http://msdn2.microsoft.com/library/system.web.security.roles_members.