System.Web 2.0.0.0 System.Object ASP.NET role management enables you to manage authorization for your application based on groups of users, referred to as roles. By assigning users to roles, you can control access to different parts or features of your Web application based on role instead of, or in addition to, specifying authorization based on user name. For example, an employee application might have roles such as Managers, Employees, Directors, and so on, where different privileges are specified for each role. Users can belong to more than one role. For example, if your site is a discussion forum, some users might be in the role of both Members and Moderators. You might define each role to have different privileges on the site, and a user who is in both roles would then have both sets of privileges. To enable role management for your ASP.NET application, use the roleManager element of the system.web section in the Web.config file for your application, as shown in the following example. <configuration> <connectionStrings> <add name="SqlServices" connectionString="Data Source=localhost;Initial Catalog=aspnetdb;Integrated Security=SSPI;" /> </connectionStrings> <system.web> <authentication mode="Forms" > <forms loginUrl="login.aspx" name=".ASPXFORMSAUTH" /> </authentication> <roleManager defaultProvider="SqlProvider" enabled="true" cacheRolesInCookie="true" cookieName=".ASPROLES" cookieTimeout="30" cookiePath="/" cookieRequireSSL="false" cookieSlidingExpiration="true" cookieProtection="All" > <providers> <add name="SqlProvider" type="System.Web.Security.SqlRoleProvider" connectionStringName="SqlServices" applicationName="SampleApplication" /> </providers> </roleManager> </system.web> </configuration> You can specify authorization rules in the configuration file for your Web application or programmatically in your code. For example, the following authorization section from a Web.config file requires users to log on (by denying anonymous users), and then allows only users in the Administrators role to have access. <authorization> <deny users="?" /> <allow roles="Administrators" /> <deny users="*" /> </authorization> If you use the authorization section in your application's Web.config file to specify authorization based on roles, users of your application must supply an authenticated user identity. You can authenticate users by using either Windows or Forms authentication. Anonymous users cannot be assigned to a role. Roles can be used independently of, or in conjunction with, the ASP.NET classes. To verify role membership programmatically, you can use the class or the property with the method, or you can use the property with the method. For sample code that programmatically checks role membership, see the Example section in this topic. The class also enables you to create and delete roles and to add users to or remove users from roles. If you have configured your application to use the class, you cannot modify roles or role membership. The class verifies membership in Windows security groups only. In this case, you must use Windows user account management rather than ASP.NET roles to create and delete groups and manage group membership. You can store role information in several data sources. You can use the class to retrieve role information based on membership in Windows groups. You can store role information in a SQL Server database by using the class. If you have existing role information, or want to store role information in and retrieve role information from a data source other than Windows, an Authorization Store, or SQL Server, you can implement a custom role provider by creating a class that inherits the abstract class. For more information, see Implementing a Role Provider. If a user's browser accepts cookies, you can store role information for that user in a cookie on the user's computer. On each page request, ASP.NET reads the role information for that user from the cookie. This can improve application performance by reducing the amount of communication required with the data source to retrieve role information. If the role information for a user is too long to store in a cookie, ASP.NET stores just the most recently used role information in the cookie and then looks up additional role information in the data source as required. If the user's browser does not support cookies or cookies are disabled, role information is not cached in a cookie. You can improve the reliability of the role names cached in a cookie by specifying a property when you configure ASP.NET roles. The default is All, which encrypts role names in the cookie and validates that the cookie contents have not been altered.

Manages user membership in roles for authorization checking in an ASP.NET application. This class cannot be inherited.

Method System.Void To be added. The method calls the default role provider to associate the specified users with the specified role at the data source. If your application uses the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is already in a specified role, the transaction is rolled back and no updates are performed. User names and role names cannot contain commas.

Adds the specified users to the specified role.

A string array of user names to add to the specified role. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to associate the specified users with the specified roles at the data source. If your application uses the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is already in a specified role, the transaction is rolled back and no updates are performed. User names and role names cannot contain commas.

Adds the specified users to the specified roles.

A string array of user names to add to the specified roles. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to associate the specified user with the specified role at the data source. User names and role names cannot contain commas.

Adds the specified user to the specified role.

The user name to add to the specified role. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to associate the specified user with the specified roles at the data source. If your application uses the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is already in a specified role, the transaction is rolled back and no updates are performed. User names and role names cannot contain commas.

Adds the specified user to the specified roles.

The user name to add to the specified roles. 2.0.0.0 Property System.String To be added. The property is used by the class to associate users and roles with different applications. This enables multiple applications to use the same data source to store user and role information without running into conflicts between duplicate user names or duplicate role names. Multiple ASP.NET applications can use the same data source by specifying the same value in the property. You can set the property programmatically, or you can set it declaratively in the configuration file for the Web application by using the applicationName attribute. If your Web application is using the class and a value is not specified for the applicationName attribute in the configuration file, the property value for the current property is used. Because a single default role provider instance is used for all of the requests served by an object, you can have multiple requests executing concurrently and attempting to set the property value. The property is not thread safe for multiple writes, and changing the property value can result in unexpected behavior for multiple users of an application. You should avoid writing code to allow users to set the property, unless required. An example of an application where setting the property may be required is an administrative application that manages role data for multiple applications. Such an application should be a single-user application and not a Web application.

Gets or sets the name of the application to store and retrieve role information for.

2.0.0.0 Property System.Boolean To be added. When the property is set to true in the Web.config file, role information for each user is stored in a cookie. When role management checks to see whether a user is in a particular role, the roles cookie is checked before the role provider is called to check the list of roles at the data source. The cookie is dynamically updated to cache the most recently validated role names. You can improve the reliability of the role names cached in a cookie by specifying a property when you configure ASP.NET roles. The default is All, which encrypts role names in the cookie and validates that the cookie contents have not been altered. Because role names can be cached apart from the data source, it is possible that changes to role management at the data source would not be reflected in the cached values. In this case, the user must close and re-open their browser to clear the cached cookie value.

Gets a value indicating whether the current user's roles are cached in a cookie.

2.0.0.0 Property System.String To be added. You can specify the name of the cookie where roles are cached for your application by setting the cookieName attribute in the Web.config file for your ASP.NET application. This is useful when you want to uniquely identify a cookie for your application or when a cookie is shared across multiple applications, such as a domain cookie.

Gets the name of the cookie where role names are cached.

2.0.0.0 Property System.String To be added. You can specify the path of the cookie where roles are cached for your application by setting the cookiePath attribute in the Web.config file for your ASP.NET application. For more information on cookie paths, see .

Gets the path for the cached role names cookie.

2.0.0.0 Property System.Web.Security.CookieProtection To be added. You can specify the protection of the cookie where roles are cached for your application by setting the cookieProtection attribute in the Web.config file for your ASP.NET application. The cookieProtection attribute takes a enumeration value that indicates whether the role names are encrypted, validated, both, or neither.

Gets a value that indicates how role names cached in a cookie are protected.

2.0.0.0 Property System.Boolean To be added. You can specify whether SSL (Secure Sockets Layer) is required to return the role names cookie to the server in your application by setting the cookieRequireSSL attribute in the Web.config file for your ASP.NET application. For more information, see .

Gets a value indicating whether the role names cookie requires SSL in order to be returned to the server.

2.0.0.0 Property System.Boolean To be added. You can specify whether role names cookie expiration date and time will be reset with each response by using the cookieSlidingExpiration attribute in the Web.config file for your ASP.NET application. If true, the cookie expiration will initially be set to the current date and time plus the in minutes. While the user continues to actively use the ASP.NET application, the expiration date and time of the cookie will be automatically refreshed if there is less than half of the remaining. For more information, see the property.

Indicates whether the role names cookie expiration date and time will be reset periodically.

2.0.0.0 Property System.Int32 To be added. The property is used when the property is true and specifies the time-to-live in minutes for the roles cookie. To set the value, add the cookieTimeout attribute to the roleManager element in the Web.config file for the ASP.NET application and specify an integer value. If is false, this property is ignored.

Gets the number of minutes before the roles cookie expires.

2.0.0.0 Property System.Boolean To be added. The property value is set in the configuration for an ASP.NET application using the createPersistentCookie attribute of the roleManager configuration element. When false, the role-names cookie is a session cookie, that is, the cookie is lost when the browser is closed. When true, the role-names cookie is a persistent cookie that is available across multiple browser sessions. The persistent cookie expiration date and time are set to the current date and time plus the value in minutes.

Gets a value indicating whether the role-names cookie is session-based or persistent.

2.0.0.0 Method System.Void To be added. The method adds a role name to the data source. calls the method of the default role provider to add the specified role to the data source. Role names cannot contain commas.

Adds a new role to the data source.

2.0.0.0 Method System.Void The method clears the contents of the cookie that is used to cache role names. For more information on caching role names, see .

Deletes the cookie where role names are cached.

2.0.0.0 Method System.Boolean To be added. The method removes a role name from the data source. calls the method of the default role provider to remove the specified role from the data source. If the role identified by the parameter has one or more members, then an exception will be thrown and the role will not be deleted.

Removes a role from the data source.

true if was deleted from the data source; otherwise, false. 2.0.0.0 Method System.Boolean To be added. The method removes a role name from the data source. calls the method of the default role provider to remove the specified role from the data source. If is true, then an exception will be thrown and the role will not be deleted if the role identified by the parameter has one or more members. If is false, then the role will be deleted whether it is empty or not.

Removes a role from the data source.

true if was deleted from the data source; otherwise; false. If true, throws an exception if has one or more members. 2.0.0.0 Property System.String To be added. The property value is set in the configuration for an ASP.NET application using the domain attribute of the roleManager configuration element. If no value is specified in the configuration for the domain attribute, the property returns null and the role-names cookie domain defaults to the behavior of the property.

Gets the value of the domain of the role-names cookie.

2.0.0.0 Property System.Boolean To be added. To be added.

Gets or sets a value indicating whether role management is enabled for the current Web application.

2.0.0.0 Method System.String[] To be added. returns a list of users in a role where the user name contains a match of the supplied for the configured applicationName. For example, if the parameter is set to "user," then the users "user1," "user2," "user3," and so on are returned. Users are returned in alphabetical order by user name. The performs its search using a LIKE clause against the parameter. Any wildcards that are supported by SQL Server in LIKE clauses can be used in the parameter value.

Gets a list of users in a specified role where the user name contains the specified user name to match.

A string array containing the names of all the users whose user name matches and who are members of the specified role. The user name to search for. 2.0.0.0 Method System.String[] The method calls the method of the default role provider to get a list of all the roles from the data source for an application. Only the roles for the application that is specified in the property are retrieved.

Gets a list of all the roles for the application.

A string array containing the names of all the roles stored in the data source for the application. 2.0.0.0 Method System.String[] The method calls the method of the default role provider to retrieve from the data source the roles that the currently logged-on user is in. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. If is true, then the results of the method may be returned from the role cache rather than the specified role provider.

Gets a list of the roles that the currently logged-on user is in.

A string array containing the names of all the roles that the currently logged-on user is in. 2.0.0.0 Method System.String[] The method calls the method of the default role provider to retrieve from the data source the roles that the user is in. Only the roles for the application that is specified in the property are retrieved. If is equal to the current logged-on user and is true, the results of the method may be returned from the role cache rather than the specified .

Gets a list of the roles that a user is in.

A string array containing the names of all the roles that the specified user is in. The user to return a list of roles for. 2.0.0.0 Method System.String[] To be added. The method calls the method of the default role provider to retrieve the user names associated with a role from the data source. Only the roles for the application that is specified in the property are retrieved.

Gets a list of users in the specified role.

A string array containing the names of all the users who are members of the specified role. 2.0.0.0 Method System.Boolean To be added. The method calls the method of the default role provider to determine whether the currently logged-on user is associated with a role from the data source for the application that is specified in the property. The currently logged-on user is identified by the property of the current , or by for non-HTTP hosting environments. If no user is logged on, an exception will be thrown. Only the roles for the application that is specified in the property are retrieved. If is true, then may be checked against the roles cache rather than the specified role provider.

Gets a value indicating whether the currently logged-on user is in the specified role.

true if the currently logged-on user is in the specified role; otherwise, false. 2.0.0.0 Method System.Boolean To be added. The method calls the method of the default role provider to determine whether a user name is associated with a role from the data source for the application that is specified in the property. If is equal to the current logged-on user and the property value is true, may be checked against the role cache rather than the specified .

Gets a value indicating whether the specified user is in the specified role.

true if the specified user is in the specified role; otherwise, false. The name of the user to search for. 2.0.0.0 Property System.Int32 To be added. The property is set using the maxCachedResults configuration attribute. The value of the maxCachedResults configuration attribute must be set to an integer value greater than zero.

Gets the maximum number of role names to be cached for a user.

2.0.0.0 Property System.Web.Security.RoleProvider To be added. The property enables you to directly reference the default role provider for an application. This is commonly used to access custom members of the role provider that are not part of the abstract class. For example, the class includes an overload of the method that enables you to determine whether a user is in a common Windows role by using a enumeration value. A reference to the class for an application can be obtained by using the property and can be cast as a in order to refer to the overload. If multiple role providers are configured for an application, you can access different role providers using the collection.

Gets the default role provider for the application.

2.0.0.0 Property System.Web.Security.RoleProviderCollection To be added. The property references all the role providers enabled for an application, including any providers added in the Web.config file. You can control which role providers are available for an application by using the providers element of the roleManager section in the Web.config file for your application. The following example shows a roleManager section that removes any existing providers (such as those specified in the Machine.config file) and adds a instance as the role provider for the application. <configuration> <connectionStrings> <add name="SqlServices" connectionString="Data Source=MySqlServer;Integrated Security=SSPI;Initial Catalog=aspnetdb;" /> </connectionStrings> <system.web> <roleManager defaultProvider="SqlProvider" enabled="true" cacheRolesInCookie="true" cookieName=".ASPROLES" cookieTimeout="30" cookiePath="/" cookieRequireSSL="false" cookieSlidingExpiration="true" cookieProtection="Encrypted"> <providers> <clear/> <add name="SqlProvider" type="System.Web.Security.SqlRoleProvider" connectionStringName="SqlServices" applicationName="MyApplication" /> </providers> </roleManager> </system.web> </configuration> You can obtain a strongly typed reference to a provider from the collection by indexing the role provider by name and casting it as the desired type. You can obtain a reference to the default provider for an application using the property.

Gets a collection of the role providers for the ASP.NET application.

2.0.0.0 Method System.Void To be added. The method calls the default role provider to remove the specified user from the specified role at the data source.

Removes the specified user from the specified role.

The user to remove from the specified role. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to remove the specified user from the specified roles at the data source. If the application is configured to use the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is not in a specified role, the transaction is rolled back and no updates are performed.

Removes the specified user from the specified roles.

The user to remove from the specified roles. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to remove the specified users from the specified role at the data source. If the application uses the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is not in a specified role, the transaction is rolled back and no updates are performed.

Removes the specified users from the specified role.

A string array of user names to remove from the specified roles. 2.0.0.0 Method System.Void To be added. The method calls the default role provider to remove the specified users from the specified roles at the data source. If the application uses the class, the database updates that are performed during the call to the method are made within a transaction. If an error is encountered, such as a user name that is not in a specified role, the transaction is rolled back and no updates are performed.

Removes the specified user names from the specified roles.

A string array of user names to remove from the specified roles. 2.0.0.0 Method System.Boolean To be added. The method calls the RoleExists method of the default role provider to determine whether a role name exists in the data source for the application that is specified in the property.

Gets a value indicating whether the specified role name already exists in the role data source.

true if the role name already exists in the data source; otherwise, false. 2.0.0.0