ActiveDirectoryMembershipProvider.FindUsersByName 方法

定義

命名空間:

System.Web.Security

組件:

System.Web.dll

根據使用者名稱從 Active Directory 資料存放區傳回使用者集合。

public:
 override System::Web::Security::MembershipUserCollection ^ FindUsersByName(System::String ^ usernameToMatch, int pageIndex, int pageSize, [Runtime::InteropServices::Out] int % totalRecords);

public override System.Web.Security.MembershipUserCollection FindUsersByName (string usernameToMatch, int pageIndex, int pageSize, out int totalRecords);

override this.FindUsersByName : string * int * int * int -> System.Web.Security.MembershipUserCollection

Public Overrides Function FindUsersByName (usernameToMatch As String, pageIndex As Integer, pageSize As Integer, ByRef totalRecords As Integer) As MembershipUserCollection

參數

usernameToMatch

String

要搜尋的使用者名稱或使用者名稱的一部分。

pageIndex

Int32

要傳回的結果網頁索引。 pageIndex 以零為起始。

pageSize

Int32

要傳回的結果網頁大小。

totalRecords

Int32

這個方法返回時，會包含集合中傳回的資料錄總數。 這個參數會以未初始化的狀態傳遞。

傳回

MembershipUserCollection

MembershipUserCollection，包含 pageSizeMembershipUser 執行個體，從 pageIndex 指定的頁面開始。

例外狀況

InvalidOperationException

FindUsersByName(String, Int32, Int32, Int32) 方法的呼叫，會在初始化 ActiveDirectoryMembershipProvider 執行個體之前進行。

ArgumentException

usernameToMatch 為空白，或超過使用者名稱的最大長度 (通常是 256 個字元)。

-或-

usernameToMatch 包含逗號。

-或-

pageIndex 小於 0。

-或-

pageSize 小於 1。

-或-

pageSize 乘以 pageIndex、加上 pageSize、減 1 大於 Int32.MaxValue。

ArgumentNullException

usernameToMatch 為 null。

NotSupportedException

EnableSearchMethods 屬性為 false。

備註

方法 FindUsersByName 會 MembershipUserCollection 傳回實例，其中包含 Active Directory 資料存放區中符合 userNameToMatch 參數之所有使用者名稱的用戶記錄。 記錄會依使用者名稱依字母順序傳回。

方法傳 FindUsersByName 回的結果會受到 pageIndex 和 pageSize 參數的限制。 參數pageSize會指定要在 中MembershipUserCollection傳回的MembershipUser實例數目上限。 參數 pageIndex 會指定要傳回的結果頁面，其中0 (零) 表示第一頁。

參數 totalRecords 是一個 out 參數，設定為 Active Directory 資料存放區中找到的相符成員資格用戶總數。 例如，如果已設定的數據存放區有13個使用者，且 pageIndex 值為1 pageSize 且值為5，則傳回的 MembershipUserCollection 會包含第六到第十個使用者。 參數 totalRecords 會設定為 13。

您可以控制是否允許搜尋使用者，方法是在enableSearchMethods應用程式的組態檔中使用成員資格元素的 屬性來設定 EnableSearchMethods 屬性， (ASP.NET 設定架構) 元素。 將 EnableSearchMethods 屬性值設定為 false 會導致 FindUsersByName 方法擲回例外狀況 NotSupportedException 。

提供者會使用從連接字串中指定的搜尋點開始的子樹搜尋。 ActiveDirectoryMembershipProvider如需連接字串的詳細資訊，請參閱 類別主題。

建議您在確認 類別發出的 ActiveDirectoryMembershipProvider 搜尋查詢不會對目錄伺服器的效能造成負面影響之前，才啟用在生產系統上搜尋。 由於 類別 ActiveDirectoryMembershipProvider 是針對無狀態 Web 環境所設計，因此無法使用基礎 System.DirectoryServices API 所公開的分頁優化。 這表示在搜尋大型目錄期間的分頁作業非常昂貴，因此應該避免。 搜尋作業一律會針對連接字串中設定的目錄伺服器發出，或在指向網域的連接字串的情況下自動選取的伺服器發出。 提供者不會針對其搜尋方法使用全域編錄。

另請參閱

• ASP.NET 成員資格簡介