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

範例

以下範例展示了一個應用程式的 Web.config 檔案，該應用程式設定為同時使用 ASP.NET 成員與 ASP.NET 角色，並用 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>

以下程式碼範例程式化檢查已登入使用者是否處於管理員角色，然後允許使用者查看其他使用者的角色。

備註

ASP.NET 角色管理讓您能根據稱為角色的使用者群組來管理應用程式的授權。 透過指派使用者角色，你可以根據角色控制對網頁應用程式不同部分或功能的存取，而非僅僅根據使用者名稱指定授權。 例如，員工應用程式可能有經理、員工、董事等角色，每個角色會指定不同的權限。

使用者可以屬於多個角色。 舉例來說，如果你的網站是一個討論區，有些用戶可能會同時擔任會員和版主的角色。 你可以定義每個角色在網站上擁有不同的權限，而同時處於兩個角色的使用者就會擁有這兩組權限。

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

<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.config 檔案中的 授權 區段要求使用者登入（拒絕匿名使用者），然後只允許管理員角色的使用者存取。

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

若您使用 authorization 應用程式 Web.config 檔案中的區塊來指定基於角色的授權，使用者必須提供已認證的使用者身份。 你可以透過 Windows 或 Forms 認證來驗證使用者。 匿名使用者無法被指派到角色。 角色可以獨立於 ASP.NET Membership 類別使用，也可以與之結合使用。

要在程式上驗證角色成員資格，你可以用 Roles 類別或 Page.User 屬性搭配 IsUserInRole 方法，或者用 Page.User 屬性搭配 IPrincipal.IsInRole 方法。 關於程式化檢查角色成員身份的範例程式碼，請參見本主題中的範例部分。

這個 Roles 類別還能讓你建立和刪除角色，以及新增或移除角色中的使用者。

備註

如果你已經設定應用程式使用該 WindowsTokenRoleProvider 類別，就無法修改角色或角色成員身份。 該 WindowsTokenRoleProvider 類別僅驗證 Windows 安全群組的成員身份。 此時，您必須使用 Windows 使用者帳號管理，而非 ASP.NET 角色來建立、刪除群組及管理群組成員。

你可以將角色資訊儲存在多個資料來源中。

• 你可以用這個 WindowsTokenRoleProvider 類別根據 Windows 群組的成員身份取得角色資訊。

• 你可以透過使用 class SqlRoleProvider 將角色資訊儲存在 SQL Server 資料庫中。

• 如果你已有現有的角色資訊，或想將角色資訊儲存在 Windows、授權儲存庫或 SQL Server 以外的資料來源中並取得角色資訊，你可以透過建立繼承 RoleProvider 抽象類別的類別來實作自訂的角色提供者。 欲了解更多資訊，請參閱 「角色提供者的實施」。

如果使用者的瀏覽器接受 Cookie，你可以將該用戶的角色資訊儲存在使用者電腦上的 Cookie 中。 在每個頁面請求中，ASP.NET 會從 Cookie 讀取該使用者的角色資訊。 這能透過減少與資料來源的通訊量來提升應用程式效能，以取得角色資訊。 如果使用者的角色資訊太長無法儲存在 Cookie 中，ASP.NET 會只在 cookie 中儲存最近使用的角色資訊，然後根據需要在資料來源中查詢更多角色資訊。 若使用者瀏覽器不支援 Cookie，或 Cookie 被停用，角色資訊不會被快取在 Cookie 中。

你可以透過設定 CookieProtectionValue Cookie 中快取的角色名稱來提升 ASP.NET 角色名稱的可靠性。 預設 CookieProtectionValue 為 All，它會加密 cookie 中的角色名稱，並驗證 cookie 內容未被更改。

屬性

名稱	Description
ApplicationName	取得或設定應用程式名稱以儲存及檢索角色資訊。
CacheRolesInCookie	會取得一個值，表示目前使用者的角色是否被快取在 cookie 中。
CookieName	取得角色名稱快取的 cookie 名稱。
CookiePath	取得快取角色名稱 cookie 的路徑。
CookieProtectionValue	會獲得一個值，表示 Cookie 中快取的角色名稱如何受到保護。
CookieRequireSSL	會獲得一個值，指示角色名稱 cookie 是否需要 SSL 才能回傳到伺服器。
CookieSlidingExpiration	指示角色名稱、cookie 的到期日和時間是否會定期重置。
CookieTimeout	會獲得角色餅乾到期前的分鐘數。
CreatePersistentCookie	會取得一個值，表示角色名稱 cookie 是基於會話的還是持久的。
Domain	取得角色名稱 cookie 網域的值。
Enabled	取得或設定一個值，指示目前網頁應用程式是否啟用角色管理。
MaxCachedResults	取得使用者需快取的最大角色名稱數量。
Provider	會取得該應用程式的預設角色提供者。
Providers	取得 ASP.NET 申請中的角色提供者集合。

方法

名稱	Description
AddUsersToRole(String[], String)	將指定的使用者加入指定的角色。
AddUsersToRoles(String[], String[])	將指定的使用者加入指定的角色。
AddUserToRole(String, String)	將指定的使用者加入指定的角色。
AddUserToRoles(String, String[])	將指定的使用者加入指定的角色。
CreateRole(String)	為資料來源新增一個角色。
DeleteCookie()	刪除快取角色名稱的 cookie。
DeleteRole(String, Boolean)	從資料來源中移除一個角色。
DeleteRole(String)	從資料來源中移除一個角色。
FindUsersInRole(String, String)	取得指定角色的使用者清單，該角色的使用者名稱包含指定的名稱以匹配。
GetAllRoles()	會列出申請中所有職缺。
GetRolesForUser()	會取得目前登入使用者所處的角色清單。
GetRolesForUser(String)	會拿到使用者所處角色的清單。
GetUsersInRole(String)	會取得指定角色的使用者清單。
IsUserInRole(String, String)	會取得一個值，表示指定的使用者是否處於指定角色。 API 僅設計用於 ASP.NET 請求執行緒的情境中呼叫，且在該授權使用情境下是執行緒安全的。
IsUserInRole(String)	會取得一個值，表示目前登入的使用者是否處於指定角色。 API 僅設計用於 ASP.NET 請求執行緒的情境中呼叫，且在該授權使用情境下是執行緒安全的。
RemoveUserFromRole(String, String)	將指定的使用者從指定角色中移除。
RemoveUserFromRoles(String, String[])	將指定的使用者從指定角色中移除。
RemoveUsersFromRole(String[], String)	將指定的使用者從指定角色中移除。
RemoveUsersFromRoles(String[], String[])	移除指定角色中指定的使用者名稱。
RoleExists(String)	會取得一個值，表示指定的角色名稱是否已存在於角色資料來源中。

另請參閱

• 理解 ASP.NET 角色管理