Roles 类
定义
管理角色中的用户成员资格,以便在 ASP.NET 应用程序中进行授权检查。Manages user membership in roles for authorization checking in an ASP.NET application. 此类不能被继承。This class cannot be inherited.
public ref class Roles abstract sealed
public static class Roles
type Roles = class
Public Class Roles
- 继承
-
Roles
示例
下面的示例演示了配置为同时使用 ASP.NET 和 ASP.NET 角色并使用将 SqlRoleProvider 成员身份和角色信息存储在 SQL Server 数据库中的应用程序的 Web.config 文件。The following example shows the Web.config file for an application configured to use both ASP.NET membership and ASP.NET roles and to use the SqlRoleProvider to store membership and role information in a SQL Server database. 使用 forms 身份验证对用户进行身份验证,并且仅允许管理员角色中的用户访问应用程序。Users are authenticated with forms authentication and only users in the Administrators role are allowed access to the application.
<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>
<authorization>
<deny users="?" />
<allow roles="Administrators" />
<deny users="*" />
</authorization>
<membership defaultProvider="AspNetSqlProvider" userIsOnlineTimeWindow="15">
</membership>
<roleManager defaultProvider="SqlProvider"
enabled="true"
cacheRolesInCookie="true"
cookieName=".ASPROLES"
cookieTimeout="30"
cookiePath="/"
cookieRequireSSL="true"
cookieSlidingExpiration="true"
cookieProtection="All" >
<providers>
<clear />
<add
name="SqlProvider"
type="System.Web.Security.SqlRoleProvider"
connectionStringName="SqlServices"
applicationName="SampleApplication" />
</providers>
</roleManager>
</system.web>
</configuration>
下面的代码示例以编程方式检查登录用户是否是管理员角色,然后允许用户查看其他用户的角色。The following code example programmatically checks whether the logged-on user is in the Administrators role before allowing the user to view other users' roles.
注解
ASP.NET 角色管理使你可以基于用户组(称为角色)来管理应用程序的授权。ASP.NET role management enables you to manage authorization for your application based on groups of users, referred to as roles. 将用户分配到角色后,你可以根据角色(而不是基于用户名指定授权)来控制对 Web 应用程序的不同部分或功能的访问。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.
若要为 ASP.NET 应用程序启用角色管理,请使用 system.web 应用程序的 Web.config 文件中部分的 roleManager 元素,如下面的示例中所示。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>
你可以在 Web 应用程序的配置文件中或在代码中以编程方式指定授权规则。You can specify authorization rules in the configuration file for your Web application or programmatically in your code. 例如,Web.config 文件中的以下 授权 部分要求用户通过拒绝) 匿名用户登录 (,然后仅允许管理员角色中的用户拥有访问权限。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>
如果你使用 authorization 应用程序的 Web.config 文件中的部分指定基于角色的授权,则你的应用程序的用户必须提供经过身份验证的用户标识。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. 可以使用 Windows 或 Forms 身份验证对用户进行身份验证。You can authenticate users by using either Windows or Forms authentication. 不能将匿名用户分配到角色。Anonymous users cannot be assigned to a role. 角色可以单独使用,也可以与 ASP.NET 类一起使用 Membership 。Roles can be used independently of, or in conjunction with, the ASP.NET Membership classes.
若要以编程方式验证角色成员身份,可以将 Roles 类或 Page.User 属性与 IsUserInRole 方法一起使用,也可以将 Page.User 属性与方法一起使用 IPrincipal.IsInRole 。To verify role membership programmatically, you can use the Roles class or the Page.User property with the IsUserInRole method, or you can use the Page.User property with the IPrincipal.IsInRole method. 有关以编程方式检查角色成员身份的示例代码,请参阅本主题中的 "示例" 部分。For sample code that programmatically checks role membership, see the Example section in this topic.
Roles类还允许您创建和删除角色,并向角色添加用户或从中删除用户。The Roles class also enables you to create and delete roles and to add users to or remove users from roles.
备注
如果已将应用程序配置为使用 WindowsTokenRoleProvider 类,则不能修改角色或角色成员身份。If you have configured your application to use the WindowsTokenRoleProvider class, you cannot modify roles or role membership. WindowsTokenRoleProvider类只验证 Windows 安全组中的成员身份。The WindowsTokenRoleProvider class verifies membership in Windows security groups only. 在这种情况下,你必须使用 Windows 用户帐户管理而不是 ASP.NET 角色来创建和删除组以及管理组成员身份。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.
可以使用类根据 WindowsTokenRoleProvider Windows 组中的成员身份检索角色信息。You can use the WindowsTokenRoleProvider class to retrieve role information based on membership in Windows groups.
您可以使用类将角色信息存储在 SQL Server 数据库中 SqlRoleProvider 。You can store role information in a SQL Server database by using the SqlRoleProvider class.
如果你有现有的角色信息,或想要在中存储角色信息并从 Windows、授权存储或 SQL Server 之外的数据源中检索角色信息,则可以通过创建继承抽象类的类来实现自定义角色提供程序 RoleProvider 。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 RoleProvider abstract class. 有关详细信息,请参阅 实现角色提供程序。For more information, see Implementing a Role Provider.
如果用户的浏览器接受 cookie,则可以在用户计算机上的 cookie 中存储该用户的角色信息。If a user's browser accepts cookies, you can store role information for that user in a cookie on the user's computer. 在每个页面请求上,ASP.NET 从 cookie 读取该用户的角色信息。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. 如果用户的角色信息太长,无法存储在 cookie 中,则 ASP.NET 会将最近使用的角色信息存储在 cookie 中,然后根据需要在数据源中查找其他角色信息。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. 如果用户的浏览器不支持 cookie 或 cookie 处于禁用状态,则不会在 cookie 中缓存角色信息。If the user's browser does not support cookies or cookies are disabled, role information is not cached in a cookie.
你可以通过在 CookieProtectionValue 配置 ASP.NET 角色时指定属性来提高 cookie 中缓存的角色名称的可靠性。You can improve the reliability of the role names cached in a cookie by specifying a CookieProtectionValue property when you configure ASP.NET roles. 默认值 CookieProtectionValue 为 All ,它将加密 cookie 中的角色名称并验证 cookie 内容是否未被更改。The default CookieProtectionValue is All, which encrypts role names in the cookie and validates that the cookie contents have not been altered.
属性
| ApplicationName |
获取或设置要存储和检索其角色信息的应用程序的名称。Gets or sets the name of the application to store and retrieve role information for. |
| CacheRolesInCookie |
获取一个值,该值指示当前用户的角色是否已缓存在某个 Cookie 中。Gets a value indicating whether the current user's roles are cached in a cookie. |
| CookieName |
获取在其中缓存角色名称的 Cookie 的名称。Gets the name of the cookie where role names are cached. |
| CookiePath |
获取缓存角色名称的 Cookie 的路径。Gets the path for the cached role names cookie. |
| CookieProtectionValue |
获取一个指示如何保护在 Cookie 中缓存的角色名称的值。Gets a value that indicates how role names cached in a cookie are protected. |
| CookieRequireSSL |
获取一个值,该值指示角色名称 Cookie 是否需要 SSL 以便返回到服务器。Gets a value indicating whether the role names cookie requires SSL in order to be returned to the server. |
| CookieSlidingExpiration |
指示是否将要定期重置角色名称 Cookie 的到期日期和时间。Indicates whether the role names cookie expiration date and time will be reset periodically. |
| CookieTimeout |
获取角色 Cookie 到期前的分钟数。Gets the number of minutes before the roles cookie expires. |
| CreatePersistentCookie |
获取一个值,该值指示角色名称 Cookie 是基于会话的还是持久性的。Gets a value indicating whether the role-names cookie is session-based or persistent. |
| Domain |
获取角色名称 Cookie 的域的值。Gets the value of the domain of the role-names cookie. |
| Enabled |
获取或设置用来指示是否为当前 Web 应用程序启用角色管理的值。Gets or sets a value indicating whether role management is enabled for the current Web application. |
| MaxCachedResults |
获取要为用户缓存的角色名称的最大数量。Gets the maximum number of role names to be cached for a user. |
| Provider |
获取应用程序的默认角色提供程序。Gets the default role provider for the application. |
| Providers |
获取 ASP.NET 应用程序的角色提供程序的集合。Gets a collection of the role providers for the ASP.NET application. |
方法
| AddUsersToRole(String[], String) |
将指定的用户添加到指定的角色中。Adds the specified users to the specified role. |
| AddUsersToRoles(String[], String[]) |
将指定的用户添加到指定的角色中。Adds the specified users to the specified roles. |
| AddUserToRole(String, String) |
将指定的用户添加到指定的角色中。Adds the specified user to the specified role. |
| AddUserToRoles(String, String[]) |
将指定的用户添加到指定的角色中。Adds the specified user to the specified roles. |
| CreateRole(String) |
将新的角色添加到数据源。Adds a new role to the data source. |
| DeleteCookie() |
删除在其中缓存角色名称的 Cookie。Deletes the cookie where role names are cached. |
| DeleteRole(String) |
从数据源移除一个角色。Removes a role from the data source. |
| DeleteRole(String, Boolean) |
从数据源移除一个角色。Removes a role from the data source. |
| FindUsersInRole(String, String) |
获取属于指定角色的用户的列表,其中用户名包含要匹配的指定用户名。Gets a list of users in a specified role where the user name contains the specified user name to match. |
| GetAllRoles() |
获取应用程序的所有角色的列表。Gets a list of all the roles for the application. |
| GetRolesForUser() |
获取当前登录的用户所属角色的列表。Gets a list of the roles that the currently logged-on user is in. |
| GetRolesForUser(String) |
获取一个用户所属角色的列表。Gets a list of the roles that a user is in. |
| GetUsersInRole(String) |
获取属于指定角色的用户的列表。Gets a list of users in the specified role. |
| IsUserInRole(String) |
获取一个值,该值指示当前登录的用户是否属于指定的角色。Gets a value indicating whether the currently logged-on user is in the specified role. API 只能在 ASP.NET 请求线程的上下文内进行调用,在该批准的使用情况下,它是线程安全的。The API is only intended to be called within the context of an ASP.NET request thread, and in that sanctioned use case it is thread-safe. |
| IsUserInRole(String, String) |
获取一个指示指定用户是否属于指定角色的值。Gets a value indicating whether the specified user is in the specified role. API 只能在 ASP.NET 请求线程的上下文内进行调用,在该批准的使用情况下,它是线程安全的。The API is only intended to be called within the context of an ASP.NET request thread, and in that sanctioned use case it is thread-safe. |
| RemoveUserFromRole(String, String) |
从指定的角色中移除指定的用户。Removes the specified user from the specified role. |
| RemoveUserFromRoles(String, String[]) |
从指定的角色中移除指定的用户。Removes the specified user from the specified roles. |
| RemoveUsersFromRole(String[], String) |
从指定的角色中移除指定的用户。Removes the specified users from the specified role. |
| RemoveUsersFromRoles(String[], String[]) |
移除指定角色中的指定用户名。Removes the specified user names from the specified roles. |
| RoleExists(String) |
获取一个值,该值指示指定的角色名称是否已存在于角色数据源中。Gets a value indicating whether the specified role name already exists in the role data source. |