Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

ActiveDirectoryMembershipProvider.FindUsersByEmail Method

Returns a collection of membership users from the Active Directory data store based on the user's e-mail address.

Namespace:  System.Web.Security
Assembly:  System.Web (in System.Web.dll)
[DirectoryServicesPermissionAttribute(SecurityAction.Assert, Unrestricted = true)]
[DirectoryServicesPermissionAttribute(SecurityAction.InheritanceDemand, Unrestricted = true)]
[DirectoryServicesPermissionAttribute(SecurityAction.Demand, Unrestricted = true)]
public override MembershipUserCollection FindUsersByEmail(
	string emailToMatch,
	int pageIndex,
	int pageSize,
	out int totalRecords
)

Parameters

emailToMatch
Type: System.String

E-mail address or portion of e-mail address to search for.

pageIndex
Type: System.Int32

The index of the page of results to return. pageIndex is zero-based.

pageSize
Type: System.Int32

The size of the page of results to return.

totalRecords
Type: System.Int32

When this method returns, contains the total number of users returned in the collection. This parameter is passed uninitialized.

Return Value

Type: System.Web.Security.MembershipUserCollection
A MembershipUserCollection containing pageSizeMembershipUser instances beginning at the page specified by pageIndex.
ExceptionCondition
InvalidOperationException

The FindUsersByEmail method is called before the ActiveDirectoryMembershipProvider instance is initialized.

ArgumentException

emailToMatch is empty.

- or -

emailToMatch exceeds 256 characters.

- or -

pageIndex is less than 0.

- or -

pageSize is less than 1.

- or -

pageSize multiplied by pageIndex, plus pageSize, minus 1 is greater than MaxValue.

NotSupportedException

The EnableSearchMethods property is false.

The FindUsersByEmail method gets a MembershipUserCollection containing the user records from the Active Directory store that match the emailToMatch parameters. The user records are returned sorted in ascending order by e-mail address.

The emailToMatch parameter is limited to 256 characters.

The ActiveDirectoryMembershipProvider class will issue the search using both the clientSearchTimeout and serverSearchTimeout configuration values. Since the ActiveDirectoryMembershipProvider class performs searches against the directory server using pages with 512 rows per page, the time-outs apply to each page of results fetched by the ActiveDirectoryMembershipProvider class. For example, if a search query results in 1,000 rows of data, the ActiveDirectoryMembershipProvider class will fetch this information as two pages of data. This means that the client and search time-outs will start counting from zero when the ActiveDirectoryMembershipProvider class requests the second page of data.

The results returned by the FindUsersByEmail method are constrained by the pageIndex and pageSize parameters. The pageSize parameter specifies the maximum number of MembershipUser instances to return in the MembershipUserCollection. The pageIndex parameter specifies which page of results to return, where 0 (zero) indicates the first page.

The totalRecords parameter is an out parameter that is set to the total number of matching membership users found in the Active Directory data store. For example, if there are 13 users for the configured data store, and the pageIndex value was 1 with a pageSize of 5, the MembershipUserCollection returned would contain the sixth through the tenth users. The totalRecords parameter would be set to 13.

You can control whether to allow searching for users, by setting the EnableSearchMethods property in the application's configuration file using the enableSearchMethods attribute of the membership Element (ASP.NET Settings Schema) element. Setting the EnableSearchMethods property to false causes the FindUsersByEmail method to throw a NotSupportedException exception.

The provider uses a subtree search starting at the search point specified in the connection string. See the ActiveDirectoryMembershipProvider class topic for more information about connection strings.

We recommend that you do not enable searching on production systems until you have confirmed that the search queries issued by the ActiveDirectoryMembershipProvider class do not adversely impact your directory server's performance. Since the ActiveDirectoryMembershipProvider class is designed for a stateless Web environment, it is unable to use the paging optimizations exposed by the underlying System.DirectoryServices APIs. This means that paging operations during searches against large directories are very expensive and should be avoided. Search operations are always issued against the directory server configured in the connection string, or an automatically selected server in the case of a connection string pointing at a domain. The provider does not use a global catalog for its search methods.

.NET Framework

Supported in: 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.