實作角色提供者

ASP.NET

實作角色提供者

更新：2007 年 11 月

ASP.NET 角色管理能夠讓您的 ASP.NET 應用程式輕鬆地使用數種不同的角色提供者。您可以使用 .NET Framework 所提供的設定檔提供者，或是實作自己的提供者。

建立自訂角色提供者有兩個主要原因。

您需要將角色資訊存放在 .NET Framework 隨附之角色提供者所不支援的資料來源中，例如 FoxPro 資料庫、Oracle 資料庫、或其他資料來源。
您需要用來管理角色資訊的資料庫結構描述，與 .NET Framework 隨附提供者所使用的資料庫結構描述不同。一般範例是公司或網站的 SQL Server 資料庫中，已存在的授權資料。

必要的類別

若要實作角色提供者，請建立繼承自 System.Web.Security 命名空間之 RoleProvider 抽象類別的類別。RoleProvider 抽象類別繼承自 System.Configuration.Provider 命名空間的 ProviderBase 抽象類別。因此，您也必須實作 ProviderBase 類別的必要成員。下表列出您必須從 ProviderBase 和 RoleProvider 抽象類別實作的必要屬性和方法，以及每個屬性和方法的說明。若要檢閱每位成員的實作，請參閱提供給角色提供者實作範例的程式碼。

ProviderBase 成員

成員	說明
Initialize 方法	輸入提供者的名稱和組態設定的 NameValueCollection。用以設定提供者執行個體的屬性值，包括實作特定值以及組態檔 (Machine.config 或 Web.config) 中指定的選項。

RoleProvider 成員

成員	說明
ApplicationName 屬性	應用程式的名稱，使用組態檔 (Web.config) 中所指定的角色資訊。ApplicationName 會搭配相關使用者資訊存放在資料來源中，用以查詢使用者資訊。請參閱本主題稍後的 ApplicationName 章節，以獲取詳細資訊。如果沒有明確指定的話，這個屬性是讀寫並且預設值為 ApplicationPath。
AddUsersToRoles 方法	輸入使用者名稱和角色名稱的清單，並且在已設定 ApplicationName 的資料來源中，將這些清單以指定的角色與指定的使用者產生關聯。如果已設定 ApplicationName 的任何指定角色名稱或使用者名稱不存在，您應該擲回 ProviderException。如果任何指定的使用者名稱或角色名稱是空白字串，就應該擲回 ArgumentException；如果任何指定的使用者名稱或角色名稱是 null (在 Visual Basic 中是 Nothing)，就應該擲回 ArgumentNullException。如果資料來源支援交易，您應該在交易中包含每個加入作業；如果任何加入作業失敗，就復原交易或擲回例外狀況。
CreateRole 方法	輸入角色名稱，並且將已設定 ApplicationName 的指定角色加入資料來源。如果已設定 ApplicationName 的指定角色名稱已存在，就應該擲回 ProviderException。如果指定的角色名稱是空白字串、包含逗號或超過資料來源允許的最大長度，就應該擲回 ArgumentException；如果指定的角色名稱是 null (在 Visual Basic 中是 Nothing)，就應該擲回 ArgumentNullException。
DeleteRole 方法	輸入角色名稱，以及表示如果仍然有使用者與角色相關聯時，是否要擲回例外狀況的布林值 (Boolean)。DeleteRole 會從已設定 ApplicationName 的資料來源中刪除指定角色。如果 throwOnPopulatedRole 參數是 true，並且角色名稱參數識別的角色有一或多個成員，就擲回 ProviderException 並且不刪除角色。如果 throwOnPopulatedRole 參數是 false，不論角色是否為空白都將之刪除。當您從資料來源刪除角色時，請確定同時刪除使用者名稱與設定 ApplicationName 之已刪除角色間的任何關聯。如果指定的角色名稱不存在或是空白字串，您應該擲回 ArgumentException。如果指定的角色名稱是 null (在 Visual Basic 中是 Nothing)，您應該擲回 ArgumentNullException。
FindUsersInRole 方法	輸入要搜尋的角色名稱和使用者名稱，然後傳回角色中的使用者清單，其中使用者名稱符合已設定 ApplicationName 提供的 usernameToMatch。萬用字元的支援，根據資料來源特性所提供。使用者是以使用者名稱字母順序傳回。如果資料來源中不存在指定的角色名稱，建議您擲回 ProviderException。
GetAllRoles 方法	從資料來源傳回角色名稱清單。只會擷取指定 ApplicationName 的角色。如果已設定 ApplicationName 的角色不存在，您應該傳回沒有項目的字串陣列。
GetRolesForUser 方法	輸入使用者名稱，然後從資料來源傳回與指定使用者相關聯的角色名稱。只會擷取設定 ApplicationName 的角色。如果已設定 ApplicationName 的指定使用者角色不存在，您應該傳回沒有項目的字串陣列。如果指定的使用者名稱是空白字串，您應該擲回 ArgumentException。如果指定的使用者名稱是 null (在 Visual Basic 中是 Nothing)，您應該擲回 ArgumentNullException。
GetUsersInRole 方法	輸入角色名稱，然後從資料來源傳回與角色相關聯的使用者名稱。只會擷取設定 ApplicationName 的角色。如果已設定 ApplicationName 的指定角色名稱不存在，您應該擲回 ProviderException。如果沒有使用者與已設定 ApplicationName 之指定角色相關聯，您應該傳回沒有項目的字串陣列。如果指定的角色名稱是空白字串、包含逗號、或超過資料來源允許的角色名稱最大長度，就應該擲回 ArgumentException。如果指定的角色名稱是 null (在 Visual Basic 中是 Nothing)，您應該擲回 ArgumentNullException。
IsUserInRole 方法	輸入使用者名稱和角色名稱，並且判斷目前登入的使用者是否與設定 ApplicationName 的資料來源角色相關聯。如果已設定 ApplicationName 的指定角色名稱或使用者名稱不存在，您應該擲回 ProviderException。如果指定的使用者名稱或角色名稱是空白字串，就應該擲回 ArgumentException；如果指定的使用者名稱或角色名稱是 null (在 Visual Basic 中是 Nothing)，就應該擲回 ArgumentNullException。
RemoveUsersFromRoles 方法	輸入使用者名稱和角色名稱的清單，並且在已設定 ApplicationName 的資料來源中，從指定角色移除指定使用者的關聯。如果已設定 ApplicationName 的任何指定角色名稱或使用者名稱不存在，您應該擲回 ProviderException。如果任何指定的使用者名稱或角色名稱是空白字串，就應該擲回 ArgumentException；如果任何指定的使用者名稱或角色名稱是 null (在 Visual Basic 中是 Nothing)，就應該擲回 ArgumentNullException。如果資料來源支援交易，您應該在交易中包含每個移除作業；如果任何移除作業失敗，就復原交易或擲回例外狀況。
RoleExists 方法	輸入角色名稱，並且判斷已設定 ApplicationName 的資料來源中是否存在此角色名稱。如果指定的角色名稱不存在或是空白字串，您應該擲回 ArgumentException。如果指定的角色名稱是 null (在 Visual Basic 中是 Nothing)，建議您擲回 ArgumentNullException。

ApplicationName

角色提供者會為每個應用程式存放唯一的角色資訊。當使用者名稱重複時，這能夠讓多個 ASP.NET 應用程式在不發生衝突的情況下使用相同資料來源。此外，多個 ASP.NET 應用程式可以藉由指定相同的 ApplicationName，使用相同的角色資料來源。

因為角色提供者會為每個應用程式存放唯一的角色資訊，所以需要確定資料結構描述包含應用程式名稱，而且查詢和更新也需要包含應用程式名稱。例如，下列命令是用來擷取資料庫中的角色名稱，並且確定查詢中包含 ApplicationName。

SELECT Rolename FROM Roles 
  WHERE Rolename = 'Administrators' AND ApplicationName = 'MyApplication'

執行緒安全

針對應用程式組態中指定的每個角色提供者，ASP.NET 會產生單一角色提供者執行個體，用以處理由 HttpApplication 物件所處理的所有要求。因此，您可以同時執行多個要求。ASP.NET 並不確保對提供者呼叫的執行緒安全。您需要撰寫提供者程式碼，確保執行緒安全。例如，您應該在呼叫的成員 (例如 AddUsersToRoles) 中建立資料庫連接或開啟要編輯的檔案，而不是當呼叫 Initialize 方法時開啟檔案或資料庫連接。

請參閱

概念

角色提供者實作範例

設定角色的安全性

其他資源

使用角色管理授權