Get-ADSIObject.ps1

function Get-ADSIObject {  
    <#
    .SYNOPSIS
	    Get AD object (user, group, etc.) via ADSI.

    .DESCRIPTION
	    Get AD object (user, group, etc.) via ADSI.

        Invoke a specify an LDAP Query, or search based on samaccountname and/or objectcategory

    .FUNCTIONALITY
        Active Directory

    .PARAMETER samAccountName
        Specific samaccountname to filter on

    .PARAMETER ObjectCategory
        Specific objectCategory to filter on
    
    .PARAMETER Query
        LDAP filter to invoke

    .PARAMETER Path
        LDAP Path.  e.g. contoso.com, DomainController1

        LDAP:// is prepended when omitted

    .PARAMETER Property
        Specific properties to query for
 
    .PARAMETER Limit
        If specified, limit results to this size

    .PARAMETER Credential
        Credential to use for query

        If specified, the Path parameter must be specified as well.

    .PARAMETER As
        SearchResult        = results directly from DirectorySearcher
        DirectoryEntry      = Invoke GetDirectoryEntry against each DirectorySearcher object returned
        PSObject (Default)  = Create a PSObject with expected properties and types

    .EXAMPLE
        Get-ADSIObject jdoe
        # Find an AD object with the samaccountname jdoe

    .EXAMPLE
        Get-ADSIObject -Query "(&(objectCategory=Group)(samaccountname=domain admins))"
        # Find an AD object meeting the specified criteria

    .EXAMPLE
        Get-ADSIObject -Query "(objectCategory=Group)" -Path contoso.com
        # List all groups at the root of contoso.com
    
    .EXAMPLE
        Echo jdoe, cmonster | Get-ADSIObject -property mail -ObjectCategory User | Select -expandproperty mail
        # Find an AD object for a few users, extract the mail property only

    .EXAMPLE
        $DirectoryEntry = Get-ADSIObject TESTUSER -as DirectoryEntry
        $DirectoryEntry.put(‘Title’,’Test’) 
        $DirectoryEntry.setinfo()

        #Get the AD object for TESTUSER in a usable form (DirectoryEntry), set the title attribute to Test, and make the change.

    .LINK
        https://gallery.technet.microsoft.com/scriptcenter/Get-ADSIObject-Portable-ae7f9184

    #>	
    [cmdletbinding(DefaultParameterSetName='SAM')]
    Param(
        [Parameter( Position=0,
                    Mandatory = $true,
                    ValueFromPipeline=$true,
                    ValueFromPipelineByPropertyName=$true,
                    ParameterSetName='SAM')]
        [string[]]$samAccountName = "*",

        [Parameter( Position=1,
                    ParameterSetName='SAM')]
        [string[]]$ObjectCategory = "*",

        [Parameter( ParameterSetName='Query',
                    Mandatory = $true )]
        [string]$Query = $null,

        [string]$Path = $Null,

        [string[]]$Property = $Null,

        [int]$Limit,

        [System.Management.Automation.PSCredential]$Credential,

        [validateset("PSObject","DirectoryEntry","SearchResult")]
        [string]$As = "PSObject"
    )

    Begin 
    {
        #Define parameters for creating the object
        $Params = @{
            TypeName = "System.DirectoryServices.DirectoryEntry"
            ErrorAction = "Stop"
        }

        #If we have an LDAP path, add it in.
            if($Path){

                if($Path -notlike "^LDAP")
                {
                    $Path = "LDAP://$Path"
                }
            
                $Params.ArgumentList = @($Path)

                #if we have a credential, add it in
                if($Credential)
                {
                    $Params.ArgumentList += $Credential.UserName
                    $Params.ArgumentList += $Credential.GetNetworkCredential().Password
                }
            }
            elseif($Credential)
            {
                Throw "Using the Credential parameter requires a valid Path parameter"
            }

        #Create the domain entry for search root
            Try
            {
                Write-Verbose "Bound parameters:`n$($PSBoundParameters | Format-List | Out-String )`nCreating DirectoryEntry with parameters:`n$($Params | Out-String)"
                $DomainEntry = New-Object @Params
            }
            Catch
            {
                Throw "Could not establish DirectoryEntry: $_"
            }
            $DomainName = $DomainEntry.name

        #Set up the searcher
            $Searcher = New-Object -TypeName System.DirectoryServices.DirectorySearcher
            $Searcher.PageSize = 1000
            $Searcher.SearchRoot = $DomainEntry
            if($Limit)
            {
                $Searcher.SizeLimit = $limit
            }
            if($Property)
            {
                foreach($Prop in $Property)
                {
                    $Searcher.PropertiesToLoad.Add($Prop) | Out-Null
                }
            }

        #Define a function to get ADSI results from a specific query
        Function Get-ADSIResult
        {
            [cmdletbinding()]
            param(
                [string[]]$Property = $Null,
                [string]$Query,
                [string]$As,
                $Searcher
            )
            
            #Invoke the query
                $Results = $null
                $Searcher.Filter = $Query
                $Results = $Searcher.FindAll()
            
            #If SearchResult, just spit out the results.
                if($As -eq "SearchResult")
                {
                    $Results
                }
            #If DirectoryEntry, invoke GetDirectoryEntry
                elseif($As -eq "DirectoryEntry")
                {
                    $Results | ForEach-Object { $_.GetDirectoryEntry() }
                }
            #Otherwise, get properties from the object
                else
                {
                    $Results | ForEach-Object {
                
                        #Get the keys.  They aren't an array, so split them up, remove empty, and trim just in case I screwed something up...
                            $object = $_
                            #cast to array of strings or else PS2 breaks when we select down the line
                            [string[]]$properties = ($object.properties.PropertyNames) -split "`r|`n" | Where-Object { $_ } | ForEach-Object { $_.Trim() }
            
                        #Filter properties if desired
                            if($Property)
                            {
                                $properties = $properties | Where-Object {$Property -Contains $_}
                            }
            
                        #Build up an object to output.  Loop through each property, extract from ResultPropertyValueCollection
                            #Create the object, PS2 compatibility.  can't just pipe to select, props need to exist
                                $hash = @{}
                                foreach($prop in $properties)
                                {
                                    $hash.$prop = $null
                                }
                                $Temp = New-Object -TypeName PSObject -Property $hash | Select -Property $properties
                        
                            foreach($Prop in $properties)
                            {
                                Try
                                {
                                    $Temp.$Prop = foreach($item in $object.properties.$prop)
                                    {
                                        $item
                                    }
                                }
                                Catch
                                {
                                    Write-Warning "Could not get property '$Prop': $_"
                                }   
                            }
                            $Temp
                    }
                }
        }
    }
    Process
    {
        #Set up the query as defined, or look for a samaccountname.  Probably a cleaner way to do this...
            if($PsCmdlet.ParameterSetName -eq 'Query'){
                Write-Verbose "Working on Query '$Query'"
                Get-ADSIResult -Searcher $Searcher -Property $Property -Query $Query -As $As
            }
            else
            {
                foreach($AccountName in $samAccountName)
                {
                    #Build up the LDAP query...
                        $QueryArray = @( "(samAccountName=$AccountName)" )
                        if($ObjectCategory)
                        {
                            [string]$TempString = ( $ObjectCategory | ForEach-Object {"(objectCategory=$_)"} ) -join ""
                            $QueryArray += "(|$TempString)"
                        }
                        $Query = "(&$($QueryArray -join ''))"
                    Write-Verbose "Working on built Query '$Query'"
                    Get-ADSIResult -Searcher $Searcher -Property $Property -Query $Query -As $As
                }
            }
    }
    End
    {
        $Searcher = $null
        $DomainEntry = $null
    }
}