Simple function to search Active Directory

ADFunctions.psm1

function Search-AD {
<#
    .Synopsis
    Function to search Active Directory using specified filter.

    .Description
    Function uses selected LDAP filter to search Active Directory.
    It doesn't have any external dependencies and is using ADSISearcher class.
    User can specify attributes that should be retrieved and SearchRoot.

    .Example
    Search-AD
    Finds all objects matchi default filter: (name=*)

    .Example
    Search-AD -Filter Name=Bart*, extensionAttribute10=USER
    Finds all objects that have a Name starting with 'Bart' and with extensionAttribute10 equal to 'USER'.
    Default properties (Name, ADSPath) are returned.

    .Example
    Search-AD -Filter extensionAttribute10=USER -Properties givenName, sn, Title
    Finds all objects that have extensionAttribute10 equal to 'USER' and retrieves properties: givenName, sn and title.

    .Example
    Search-AD -Filter extensionAttribute10=USER -Properties Name, memberof[] -SearchRoot 'OU=AMS,OU=Optiver Production,DC=comp,DC=Optiver,DC=com'
    Finds all objects that have extensionAttribute10 equal to 'USER' and retrieves properties: Name and memberof.
    Using '[]' notation forces the use of collection for memberOf property.
    Speficied SearchRoot is used to limit the results.
#>
    [CmdletBinding(
        SupportsPaging
    )] 
    param (
        # Filter used to limit the results (use LDAP filter). 
        [ValidateNotNullOrEmpty()]
        [string[]]$Filter = '(name=*)',

        # Properties retrieved from Active Directory object (use AD attributes).
        [string[]]$Properties = @('Name','ADSPath'),
    
        # Root of the Active Directory search (use LDAP path).
        [string[]]$SearchRoot 
    ) 
    if ($SearchRoot) {
        $rootPath = 
            if ($SearchRoot -match ',') {
                $SearchRoot[0].ToUpper()
            } else {
                ($SearchRoot -join ',').ToUpper()
            }
        if (-not $rootPath.StartsWith('LDAP://')) {
            $root = [ADSI]"LDAP://$rootPath"
        }
    } else { 
        $root = [ADSI]'' 
    } 
    $LDAP = '(&({0}))' -f ($Filter -join ')(') 
    $collectionOrNot = [ordered]@{}
    foreach ($item in $Properties) {
        if ($item -match '\[\]$') {
            $collectionOrNot.Add(
                ($item -replace '\[\]$'),
                $true
            )
        } else {
            $collectionOrNot.Add(
                $item,
                $false
            )
        }
    } 
    $list = @($collectionOrNot.Keys)

    $first = $PSCmdlet.PagingParameters.First
    $skip = $PSCmdlet.PagingParameters.Skip

    Write-Verbose "First: $first - Skip: $skip"

    if ($first -ne [UInt64]::MaxValue) {
        $sizeLimit = $first + $skip
        Write-Verbose "sizeLimit = $sizeLimit"
    }

    if ($sizeLimit -ge 1000) {
        Write-Warning "Size limit ($sizeLimit) has to be lower than 1000 - returning all objects"
        $sizeLimit = 0
    }

    (New-Object ADSISearcher -ArgumentList @( 
        $root, 
        $LDAP, 
        $list 
    ) -Property @{ 
        PageSize = 1000 
        SizeLimit = $sizeLimit
    }).FindAll() | ForEach-Object {
        if ($skip) {
            $skip--
            return
        } 
        $objectProperties = [ordered]@{}
        foreach ($property in $list) {
            if ($collectionOrNot.$property) {
                $objectProperties.Add( 
                    $property, 
                    @($_.Properties[$property])
                )
            } else {
                $objectProperties.Add( 
                    $property, 
                    (-join $_.Properties[$property])
                )
            } 
        }
        if ($objectProperties.Keys.Count -eq 1) {
            # No point in sending object with single property... (eew)
            $objectProperties[0]
        } else {
            New-Object PSObject -Property $objectProperties
        }
    } 
}