ActiveDirectoryMembershipProvider.FindUsersByEmail メソッド

.NET Framework クラス ライブラリ リファレンス

ActiveDirectoryMembershipProvider.FindUsersByEmail メソッド

メモ : このメソッドは、.NET Framework version 2.0 で新しく追加されたものです。

ユーザーの電子メール アドレスに基づいて、Active Directory データ ストアからメンバシップ ユーザーのコレクションを返します。

名前空間: System.Web.Security
アセンブリ: System.Web (system.web.dll 内)
構文

Visual Basic (宣言)

Public Overrides Function
 FindUsersByEmail ( _
    emailToMatch As String, _
    pageIndex As Integer, _
    pageSize As Integer, _
    <OutAttribute> ByRef totalRecords As
 Integer _
) As MembershipUserCollection

Visual Basic (使用法)

Dim instance As ActiveDirectoryMembershipProvider
Dim emailToMatch As String
Dim pageIndex As Integer
Dim pageSize As Integer
Dim totalRecords As Integer
Dim returnValue As MembershipUserCollection

returnValue = instance.FindUsersByEmail(emailToMatch, pageIndex, pageSize, totalRecords)

C#

public override MembershipUserCollection FindUsersByEmail (
    string emailToMatch,
    int pageIndex,
    int pageSize,
    out int totalRecords
)

C++

public:
virtual MembershipUserCollection^ FindUsersByEmail (
    String^ emailToMatch, 
    int pageIndex, 
    int pageSize, 
    [OutAttribute] int% totalRecords
) override

J#

public MembershipUserCollection FindUsersByEmail (
    String emailToMatch, 
    int pageIndex, 
    int pageSize, 
    /** @attribute OutAttribute() */ /** @ref */ int totalRecords
)

JScript

JScript では、値型の引数は参照渡しされません。

パラメータ

emailToMatch

検索する電子メール アドレスまたは電子メール アドレスの一部。

pageIndex

取得する結果のページのインデックス。pageIndex は 0 から始まります。

pageSize

取得する結果のページのサイズ。

totalRecords

このメソッドから制御が戻るとき、コレクション内のユーザーの総数を格納します。このパラメータは初期化せずに渡されます。

戻り値
pageIndex で指定されたページから始まる pageSizeMembershipUser インスタンスを格納している MembershipUserCollection。

例外

例外の種類	条件
InvalidOperationException	ActiveDirectoryMembershipProvider インスタンスが初期化される前に FindUsersByEmail メソッドが呼び出されました。
ArgumentException	emailToMatch が空です。 または emailToMatch が 256 文字を超えています。 または pageIndex が 0 未満です。 または pageSize が 1 未満です。 または pageSize に pageIndex をかけて、pageSize を足してから 1 を引いた値が MaxValue を超えています。
NotSupportedException	EnableSearchMethods プロパティが false です。

解説

FindUsersByEmail メソッドは、emailToMatch パラメータに一致するユーザー レコードを格納している MembershipUserCollection を Active Directory ストアから取得します。ユーザー レコードは、電子メール アドレスを基準に昇順に並べ替えて返されます。

emailToMatch パラメータは 256 文字に制限されます。

ActiveDirectoryMembershipProvider クラスは、clientSearchTimeout 構成値と serverSearchTimeout 構成値の両方を使用して検索を実行します。ActiveDirectoryMembershipProvider クラスでは、1 ページあたり 512 行のページを使用してディレクトリ サーバーを検索するため、ActiveDirectoryMembershipProvider クラスがフェッチする結果の各ページにタイムアウトが適用されます。たとえば、検索クエリの結果が 1,000 行のデータの場合、ActiveDirectoryMembershipProvider クラスでは、この情報を 2 ページのデータとしてフェッチします。したがって、ActiveDirectoryMembershipProvider クラスがデータの 2 ページ目を要求したとき、クライアントおよび検索のタイムアウトのカウントが 0 から開始されます。

FindUsersByEmail メソッドによって返される結果は、pageIndex パラメータおよび pageSize パラメータによって制限されます。pageSize パラメータには、MembershipUserCollection で返す MembershipUser インスタンスの最大数を指定します。pageIndex パラメータには、取得する結果のページ番号を指定します。最初のページは 0 で表されます。

totalRecords パラメータは、Active Directory データ ストアで見つかった一致するメンバシップ ユーザーの総数に設定される out パラメータです。たとえば、構成されているデータ ストアに 13 人のユーザーが存在し、pageIndex 値が 1 で pageSize が 5 である場合、MembershipUserCollection の戻り値には 6 番目から 10 番目までのユーザーが含まれます。totalRecords パラメータは、13 に設定されます。

ユーザーの検索を許可するかどうかを制御するには、membership 要素 (ASP.NET 設定スキーマ) 要素の enableSearchMethods 属性を使用してアプリケーションの構成ファイルで EnableSearchMethods プロパティを設定します。EnableSearchMethods プロパティを false に設定すると、FindUsersByEmail メソッドで NotSupportedException 例外がスローされます。

プロバイダは、接続文字列で指定された検索位置を開始点としてサブツリー検索を実行します。接続文字列の詳細については、ActiveDirectoryMembershipProvider クラスのトピックを参照してください。

ActiveDirectoryMembershipProvider クラスによって実行される検索クエリがディレクトリ サーバーのパフォーマンスに悪影響を与えないことを確認するまでは、本番システムで検索機能を有効にしないことをお勧めします。ActiveDirectoryMembershipProvider クラスは状態のない Web 環境での使用を意図しているので、基になる System.DirectoryServices API によって公開されるページング最適化処理を使用できません。このため、サイズの大きなディレクトリに対する検索時のページング操作はかなり負荷がかかるので、避ける必要があります。検索操作は常に、接続文字列で構成されたディレクトリ サーバーに対して実行されます。接続文字列でドメインが指定されている場合は、自動選択されたサーバーに対して検索操作が実行されます。プロバイダの検索メソッドでは、グローバル カタログは使用されません。

プラットフォーム

Windows 98, Windows 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

開発プラットフォームの中には、.NET Framework によってサポートされていないバージョンがあります。サポートされているバージョンについては、「システム要件」を参照してください。

バージョン情報

.NET Framework
サポート対象 : 2.0

参照

関連項目
ActiveDirectoryMembershipProvider クラス
ActiveDirectoryMembershipProvider メンバ
System.Web.Security 名前空間
その他の技術情報
メンバシップの概要