DirectorySearcher
The DirectorySearcher class is used to perform LDAP search queries against Active Directory.
The class can only be used in PowerShell scripts executed on the server side. You can use it in scripts executed by business rules, custom commands, scheduled tasks, and Reports.
Inheritance: The DirectorySearcher class implements the IAdmDirectorySearcher interface.
Namespace: Softerra.Adaxes.Adsi.Search
Constructors
-
Constructor
-
Description
-
DirectorySearcher()
-
Initializes a new instance of the DirectorySearcher class.
Methods
-
Method
-
Description
-
ExecuteSearch()
-
Performs a directory search and returns an instance of the IAdmSearchResultIterator2 interface that can be used to iterate through search results.
-
AppendFilter()
-
Appends the given LDAP search filter with the AND operator.
Properties
-
Property
-
Description
-
Pipelined
-
Gets a value indicating whether to apply access control to search results.
-
SearchParameters
-
Gets or sets the parameters for the directory search.
-
BaseObjectPath
-
Gets or sets the path of the directory object from which the search begins.
Details
DirectorySearcher()
Initializes a new instance of the DirectorySearcher class.
DirectorySearcher()
ExecuteSearch()
Performs a directory search and returns an instance of the IAdmSearchResultIterator2 interface that can be used to iterate through search results.
public IAdmSearchResultIterator2 ExecuteSearch()
Exceptions
-
COMException
-
Server encountered an error during search.
-
InvalidOperationException
-
-
ADS path of the search base object is not specified or does not contain a valid server identifier. The ADS path must be specified in the SearchParameters::BaseObjectPath property. The exception will not be thrown if SearchParameters::VirtualRoot is set to TRUE.
-
The type of the search base object defined in the SearchParameters::BaseObjectPath property is NamespaceRoot or Schema. The exception will not be thrown if SearchParameters::VirtualRoot is set to TRUE.
-
The SearchParameters::Filter property is not specified.
-
The SearchParameters::AttributeScopeQuery property is specified, but the scope of the search is not limited to the search base object. When attribute scope query is used, the SearchParameters::SearchScope property must be set to ADS_SCOPE_BASE.
-
The SearchParameters::Sort property is used to sort the results, but the name of the property to sort by is not specified. When sorting is enabled, the name of the property to sort by must be specified in SearchParameters::PropertyName.
-
The DirSync control is used, but the search scope is not set to ADS_SCOPE_SUBTREE.
-
The search is performed using the virtual list view (VLV) control, but options for sorting results are not specified. Use the SearchParameters::Sort property to specify how to sort search results.
-
Examples
The following code sample searches for users whose Department is Sales and exports their names and descriptions to a CSV file. The script can be executed as a part of a business rule, custom command, or scheduled task.
$csvFilePath = "\\SERVER\Share\Report.csv"
# Create an instance of the DirectorySearcher class
$searcher = New-Object "Softerra.Adaxes.Adsi.Search.DirectorySearcher" $NULL, $False
# Specify search parameters
# Limit the search to the OU on which a business rule, scheduled task or custom command is executed
$searcher.SearchParameters.BaseObjectPath = $Context.TargetObject.AdsPath
$searcher.SearchParameters.Filter = "(&(objectCategory=person)(objectClass=user)(department=Sales))"
$searcher.SearchParameters.SearchScope = "ADS_SCOPE_SUBTREE"
$searcher.SetPropertiesToLoad(@("name", "description"))
try
{
# Execute search
$searchResultIterator = $searcher.ExecuteSearch()
# Fetch results
$searchResults = $searchResultIterator.FetchAll()
$csv = @()
foreach ($searchResult in $searchResults)
{
$htable = @{
Name = $searchResult.Properties["name"].Value;
Description = $searchResult.Properties["description"].Value;
}
$userInfo = New-Object PSObject -Property $htable
$csv += $userInfo
}
# Export to CSV
$csv | Export-Csv $csvFilePath -NoTypeInformation
}
finally
{
# Release resources used by the search
$searchResultIterator.Dispose()
}
AppendFilter()
Appends the given LDAP search filter with the AND operator.
public void AppendFilter(String filter)
Parameters
The filter parameter specifies the LDAP filter to append.
Examples
The following code sample creates a filter out of the two given ones.
# Create an instance of the DirectorySearcher class
$searcher = New-Object "Softerra.Adaxes.Adsi.Search.DirectorySearcher" $NULL, $False
# Specify search filter
$searcher.SearchParameters.Filter = "(objectClass=contact)" # Contacts
# Append search filter
$searcher.AppendFilter("(mail=*)") # Contacts with email address
# Add a record into Execution Log
$Context.LogMessage("Search filter: " + $searcher.SearchParameters.Filter, "Information")
# Result: (&(mail=*)(objectClass=contact))
Pipelined
Gets a value indicating whether to apply access control to search results. If TRUE, results will be returned according to the security roles assigned to the user on behalf of which the operation is executed. If FALSE, all results will be returned.
- Type:
- Boolean
- Access:
- Read-only
SearchParameters
Gets or sets the parameters for the directory search.
- Type:
- SearchParameters
- Access:
- Read/Write
BaseObjectPath
Gets or sets the path of the directory object from which the search begins. The path must be a valid ADS path string.
- Type:
- String
- Access:
- Read/Write
Requirements
Minimum required version: 2017.1