Added Get-ADSIObject

Get-ADSIObject.ps1

@@ -0,0 +1,257 @@
+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
+    }
+}