API Reference
LdapEngine
Lightweight LDAP access layer with DC health tracking, quick probes, and sane defaults for timeouts/referrals/paging. Prefer this over ad-hoc DirectoryEntry/DirectorySearcher usage.
Inheritance
- Object
- LdapEngine
Constructors
public LdapEngine(AdxLdapOptions options) #Creates a new instance of LdapEngine.
Parameters
- options ADPlayground.LdapEngine.AdxLdapOptions
- Engine options.
Methods
public Void BanDc(String dc, TimeSpan ttl) #VoidTemporarily bans a domain controller from selection (e.g., after a timeout) for the specified TTL.
Parameters
- dc System.String
- Domain controller host name.
- ttl System.TimeSpan
- Ban duration.
public virtual DirectoryEntry CreateEntry(String domainName, String distinguishedName) #DirectoryEntryCreates a DirectoryEntry bound to a preferred DC, falling back to a serverless LDAP path when none is available.
Parameters
- domainName System.String
- DNS domain name used to pick a DC.
- distinguishedName System.String
- DN to bind.
Returns
Configured DirectoryEntry.
public IEnumerable<String> GetPreferredDcs(String domain) #IEnumerable<String>Returns domain controllers ordered by recent health observations and host policy.
Parameters
- domain System.String
- DNS domain name; when null or empty, returns an empty sequence.
Returns
Preferred DC names.
public Boolean IsDcBanned(String dc) #BooleanReturns true when a DC is currently banned by the engine.
Parameters
- dc System.String
public Boolean QuickRootDsePing(String dc, Int32 timeoutMs = 1000, Boolean banOnFailure = true) #BooleanQuick RootDSE availability check against a specific DC with tight timeouts. Bans the DC on failure when banOnFailure is true.
Parameters
- dc System.String
- Domain controller host name.
- timeoutMs System.Int32 = 1000
- Overall timeout budget in milliseconds.
- banOnFailure System.Boolean = true
- When true, bans the DC for a short period on failure.
Returns
True when the DC responds to a rootDSE query or quick ping.
public IEnumerable<SearchResult> SearchAnyDc(String domain, String baseDn, String filter, String[] propertiesToLoad, SearchScope scope = Subtree, Int32 pageSize = 1000, Int32 attemptTimeoutMs = 0, Nullable<Int32> maxBatch = null, Boolean suppressNotFound = false, Int32 sizeLimit = 0, SecurityMasks securityMasks = None) #IEnumerable<SearchResult>Searches across preferred DCs and returns the first successful result set. Uses pre-probes and small concurrent batches to avoid hammering unhealthy DCs.
Parameters
- domain System.String
- DNS domain name.
- baseDn System.String
- Base distinguished name.
- filter System.String
- RFC 2254 LDAP filter.
- propertiesToLoad System.String[]
- Attributes to request.
- scope System.DirectoryServices.SearchScope = Subtree
- Search scope (default Subtree).
- pageSize System.Int32 = 1000
- Page size (default 1000).
- attemptTimeoutMs System.Int32 = 0
- Per‑attempt timeout used for probes and search (ms). Default derives from host policy.
- maxBatch System.Nullable{System.Int32} = null
- Max concurrent DCs per batch.
- suppressNotFound System.Boolean = false
- When true, suppresses LDAP_NO_SUCH_OBJECT warnings for missing bases and returns an empty set.
- sizeLimit System.Int32 = 0
- Optional server-side size limit (0 = no limit).
- securityMasks System.DirectoryServices.SecurityMasks = None
- Security masks to request (e.g., Owner).
Returns
First successful set of results (may be empty).
public virtual IEnumerable<SearchResult> SearchDomain(String domainName, String baseDn, String filter, String[] propertiesToLoad, SearchScope scope = Subtree, Int32 pageSize = 1000, CancellationToken cancellationToken = null, Int32 sizeLimit = 0, SecurityMasks securityMasks = None) #IEnumerable<SearchResult>Searches a domain by racing a small batch of DCs, then falling back to guarded sequential attempts.
Parameters
- domainName System.String
- DNS domain name.
- baseDn System.String
- Base distinguished name.
- filter System.String
- RFC 2254 LDAP filter.
- propertiesToLoad System.String[]
- Attributes to request.
- scope System.DirectoryServices.SearchScope = Subtree
- Search scope (default Subtree).
- pageSize System.Int32 = 1000
- Page size (default 1000).
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
- sizeLimit System.Int32 = 0
- Optional server-side size limit (0 = no limit).
- securityMasks System.DirectoryServices.SecurityMasks = None
- Security masks to request (e.g., Owner).
Returns
Results from the first healthy DC, or empty when none succeed within budget.
public virtual Task<IEnumerable<SearchResult>> SearchDomainAsync(String domainName, String baseDn, String filter, String[] propertiesToLoad, SearchScope scope = Subtree, Int32 pageSize = 1000, CancellationToken cancellationToken = null, Int32 sizeLimit = 0, SecurityMasks securityMasks = None) #Task<IEnumerable<SearchResult>>Asynchronously searches a domain by racing a small batch of DCs, then falling back to guarded sequential attempts.
Parameters
- domainName System.String
- DNS domain name.
- baseDn System.String
- Base distinguished name.
- filter System.String
- RFC 2254 LDAP filter.
- propertiesToLoad System.String[]
- Attributes to request.
- scope System.DirectoryServices.SearchScope = Subtree
- Search scope (default Subtree).
- pageSize System.Int32 = 1000
- Page size (default 1000).
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
- sizeLimit System.Int32 = 0
- Optional server-side size limit (0 = no limit).
- securityMasks System.DirectoryServices.SecurityMasks = None
- Security masks to request (e.g., Owner).
Returns
Results from the first healthy DC, or empty when none succeed within budget.
public virtual IEnumerable<SearchResult> SearchOnDc(String dc, String baseDn, String filter, String[] propertiesToLoad, SearchScope scope = Subtree, Int32 pageSize = 1000, CancellationToken cancellationToken = null, Boolean suppressNotFound = false, Int32 sizeLimit = 0, SecurityMasks securityMasks = None) #IEnumerable<SearchResult>Executes a search against a specific DC with paging and configured timeouts.
Parameters
- dc System.String
- Domain controller host name.
- baseDn System.String
- Base distinguished name for the search.
- filter System.String
- RFC 2254 LDAP filter.
- propertiesToLoad System.String[]
- Attributes to request.
- scope System.DirectoryServices.SearchScope = Subtree
- Search scope (default Subtree).
- pageSize System.Int32 = 1000
- Page size (default 1000).
- cancellationToken System.Threading.CancellationToken = null
- Cancellation token.
- suppressNotFound System.Boolean = false
- When true, suppresses LDAP_NO_SUCH_OBJECT warnings for missing bases and returns an empty set.
- sizeLimit System.Int32 = 0
- Optional server-side size limit (0 = no limit).
- securityMasks System.DirectoryServices.SecurityMasks = None
- Security masks to request (e.g., Owner).
Returns
Streamed SearchResult records.
Inherited Methods
Properties
Extension Methods
public static DirectorySearcher CreateRootSearcher(LdapEngine engine, String domainName, String filter, Int32 pageSize = 1000) #DirectorySearcherCreates a DirectorySearcher at the domain root with engine defaults.
Parameters
- engine ADPlayground.LdapEngine.LdapEngine
- LDAP engine.
- domainName System.String
- DNS domain name.
- filter System.String
- RFC 2254 LDAP filter.
- pageSize System.Int32 = 1000
- Page size (default 1000).
Returns
Configured DirectorySearcher.
public static DirectorySearcher CreateSearcher(LdapEngine engine, String domainName, String distinguishedName, String filter, SearchScope scope = Subtree, Int32 pageSize = 1000) #DirectorySearcherCreates a DirectorySearcher rooted at the specified DN on a preferred DC with engine timeouts/referrals/page size.
Parameters
- engine ADPlayground.LdapEngine.LdapEngine
- LDAP engine.
- domainName System.String
- DNS domain name (chooses DC).
- distinguishedName System.String
- Base DN for the search.
- filter System.String
- RFC 2254 LDAP filter.
- scope System.DirectoryServices.SearchScope = Subtree
- Search scope (default Subtree).
- pageSize System.Int32 = 1000
- Page size (default 1000).
Returns
Configured DirectorySearcher.