Roles 類別

定義

命名空間:

System.Web.Security

組件:

System.Web.dll

管理角色中的使用者成員資格，以在 ASP.NET 應用程式中執行授權檢查。 此類別無法獲得繼承。

public ref class Roles abstract sealed

public static class Roles

type Roles = class

Public Class Roles

繼承

Object

Roles

範例

下列範例顯示設定為同時使用 ASP.NET 成員資格和 ASP.NET 角色的應用程式 Web.config 檔案，以及使用 SqlRoleProvider 將成員資格和角色資訊儲存在 SQL Server 資料庫中。 使用者會使用窗體驗證進行驗證，而且只有系統管理員角色中的使用者才能存取應用程式。

<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>

下列程式代碼範例會以程序設計方式檢查登入的使用者是否處於 Administrators 角色，再允許用戶檢視其他使用者的角色。

備註

ASP.NET 角色管理可讓您根據使用者群組來管理應用程式的授權，稱為角色。 藉由將使用者指派給角色，您可以根據角色控制 Web 應用程式不同部分或功能的存取，而不是根據使用者名稱指定授權。 例如，員工應用程式可能會有經理、員工、主管等角色，其中會為每個角色指定不同的許可權。

使用者可以隸屬於一個以上的角色。 例如，如果您的網站是討論論壇，有些使用者可能同時處於成員和仲裁者的角色。 您可以定義每個角色在站臺上有不同的許可權，而兩個角色中的用戶接著會有這兩組許可權。

若要啟用 ASP.NET 應用程式的角色管理，請使用應用程式 Web.config 檔案中 區段的 system.webroleManager 元素，如下列範例所示。

<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 應用程式的組態檔中指定授權規則，或在程式代碼中以程式設計方式指定。 例如，來自 Web.config 檔案的下列 授權 區段會要求使用者拒絕匿名使用者) 登入 (，然後只允許系統管理員角色中的使用者具有存取權。

<authorization>
  <deny users="?" />
  <allow roles="Administrators" />
  <deny users="*" />
</authorization>

如果您使用應用程式 Web.config 檔案中的 區 authorization 段來根據角色指定授權，則應用程式的用戶必須提供已驗證的使用者身分識別。 您可以使用 Windows 或 Forms 驗證來驗證使用者。 匿名用戶無法指派給角色。 角色可以與 ASP.NET Membership 類別分開使用或搭配使用。

若要以程式設計方式驗證角色成員資格，您可以使用 Roles 類別或 Page.User 屬性搭配 IsUserInRole 方法，也可以搭配 方法使用 Page.User 屬性 IPrincipal.IsInRole 。 如需以程式設計方式檢查角色成員資格的範例程式代碼，請參閱本主題中的範例一節。

類別 Roles 也可讓您建立和刪除角色，以及將使用者新增至角色或從角色中移除使用者。

注意

如果您已將應用程式設定為使用 WindowsTokenRoleProvider 類別，則無法修改角色或角色成員資格。 類別 WindowsTokenRoleProvider 只會驗證 Windows 安全組中的成員資格。 在此情況下，您必須使用 Windows 用戶帳戶管理，而不是 ASP.NET 角色來建立和刪除群組及管理群組成員資格。

您可以將角色資訊儲存在數個數據源中。

• 您可以使用 WindowsTokenRoleProvider 類別，根據 Windows 群組的成員資格來擷取角色資訊。

• 您可以使用 類別，將角色資訊儲存在 SQL Server 資料庫中 SqlRoleProvider 。

• 如果您有現有的角色資訊，或想要將角色資訊儲存在 中，並從 Windows、授權存放區或 SQL Server 以外的數據源擷取角色資訊，您可以建立繼承抽象類的 RoleProvider 類別來實作自定義角色提供者。 如需詳細資訊，請參閱 實作角色提供者。

如果使用者的瀏覽器接受 Cookie，您可以將該使用者的角色資訊儲存在用戶電腦上的 Cookie 中。 在每個頁面要求上，ASP.NET 從Cookie讀取該使用者的角色資訊。 這可藉由減少數據源所需的通訊量來擷取角色資訊，以改善應用程式效能。 如果使用者的角色資訊太長而無法儲存在 Cookie 中，ASP.NET 只會儲存 Cookie 中最近使用的角色資訊，然後視需要在數據源中查閱其他角色資訊。 如果使用者的瀏覽器不支援 Cookie 或 Cookie 已停用，則不會在 Cookie 中快取角色資訊。

您可以在設定 ASP.NET 角色時指定 CookieProtectionValue 屬性，以改善 Cookie 中快取的角色名稱可靠性。 預設值 CookieProtectionValue 為 All，它會加密 Cookie 中的角色名稱，並驗證 Cookie 內容尚未變更。

屬性

ApplicationName	取得或設定應用程式的名稱，以儲存及擷取角色資訊。
CacheRolesInCookie	取得值，指出目前使用者的角色是否在 Cookie 中快取。
CookieName	取得快取角色名稱之 Cookie 的名稱。
CookiePath	取得快取角色名稱 Cookie 的路徑。
CookieProtectionValue	取得值，表示如何保護在 Cookie 中快取的角色名稱。
CookieRequireSSL	取得值，指出角色名稱 Cookie 是否需要 SSL 才能傳回至伺服器。
CookieSlidingExpiration	指出是否定期重設角色名稱 Cookie 的到期日和時間。
CookieTimeout	取得角色 Cookie 過期前的分鐘數。
CreatePersistentCookie	取得值，指出角色名稱 Cookie 是否以工作階段為基礎，或為永續性。
Domain	取得角色名稱 Cookie 的網域值。
Enabled	取得或設定值，指出是否已啟用目前 Web 應用程式的角色管理。
MaxCachedResults	取得要為使用者快取角色名稱的最大數目。
Provider	取得應用程式的預設角色提供者。
Providers	取得 ASP.NET 應用程式的角色提供者集合。

方法

AddUsersToRole(String[], String)	將指定的使用者加入指定的角色。
AddUsersToRoles(String[], String[])	將指定的使用者加入指定的角色。
AddUserToRole(String, String)	將指定的使用者加入指定的角色。
AddUserToRoles(String, String[])	將指定的使用者加入指定的角色。
CreateRole(String)	將新角色加入資料來源。
DeleteCookie()	刪除快取角色名稱的 Cookie。
DeleteRole(String)	從資料來源中移除角色。
DeleteRole(String, Boolean)	從資料來源中移除角色。
FindUsersInRole(String, String)	取得指定角色中的使用者清單，其中使用者名稱包含要符合的指定使用者名稱。
GetAllRoles()	取得應用程式所有角色的清單。
GetRolesForUser()	取得目前登入的使用者所屬的角色清單。
GetRolesForUser(String)	取得使用者所屬角色的清單。
GetUsersInRole(String)	取得指定角色的使用者清單。
IsUserInRole(String)	取得值，指出目前登入的使用者是否在指定的角色中。 API 僅適合在 ASP.NET 要求執行緒的內容當中呼叫，且在此種允許的使用案例中可保障執行緒安全。
IsUserInRole(String, String)	取得值，指出指定使用者是否在指定的角色中。 API 僅適合在 ASP.NET 要求執行緒的內容當中呼叫，且在此種允許的使用案例中可保障執行緒安全。
RemoveUserFromRole(String, String)	從指定角色中移除指定的使用者。
RemoveUserFromRoles(String, String[])	從指定角色中移除指定的使用者。
RemoveUsersFromRole(String[], String)	從指定角色中移除指定的使用者。
RemoveUsersFromRoles(String[], String[])	從指定的角色移除指定的使用者名稱。
RoleExists(String)	取得值，指出指定的角色名稱是否已存在於角色資料來源中。

另請參閱

• 瞭解角色管理 ASP.NET