functions/objectcategories/Find-DMObjectCategoryItem.ps1
|
function Find-DMObjectCategoryItem { <# .SYNOPSIS Searches for items that are part of an object category. .DESCRIPTION Searches for items that are part of an object category. Caution: A combination of inefficient filters and large scope can lead to significant performance delays in large environments! .PARAMETER Name The name of the object category to search items for. .PARAMETER Property Properties to include when retrieving matching items. Ensure the property is legal for all potential matches. .PARAMETER Server The server / domain to work with. .PARAMETER Credential The credentials to use for this operation. .PARAMETER EnableException This parameters disables user-friendly warnings and enables the throwing of exceptions. This is less user friendly, but allows catching exceptions in calling scripts. .EXAMPLE PS C:\> Find-DMObjectCategoryItem -Name 'CAServer' Find all objects that are part of the CAServer category. #> [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [string] $Name, [string[]] $Property, [PSFComputer] $Server, [PSCredential] $Credential, [switch] $EnableException ) begin { $parameters = $PSBoundParameters | ConvertTo-PSFHashtable -Include Server, Credential $parameters['Debug'] = $false } process { $category = $script:objectCategories[$Name] if (-not $category) { Stop-PSFFunction -String 'Find-DMObjectCategoryItem.Category.NotFound' -StringValues $Name -EnableException $EnableException -Cmdlet $PSCmdlet return } $searchBase = Resolve-String -Text $category.SearchBase @parameters if ($category.LdapFilter) { $filter = '(&(objectClass={0})({1}))' -f $category.ObjectClass, (Resolve-String -Text $category.LdapFilter @parameters) if ($Property) { $parameters.Properties = $Property } try { Get-ADObject @parameters -LDAPFilter $filter -SearchBase $searchBase -SearchScope $category.SearchScope -ErrorAction Stop } catch { Stop-PSFFunction -String 'Find-DMObjectCategoryItem.ADError' -StringValues $Name -EnableException $EnableException -Cmdlet $PSCmdlet return } } else { if ($Property) { $parameters.Properties = $Property } try { Get-ADObject @parameters -Filter $category.Filter -SearchBase $searchBase -SearchScope $category.SearchScope -ErrorAction Stop } catch { Stop-PSFFunction -String 'Find-DMObjectCategoryItem.ADError' -StringValues $Name -EnableException $EnableException -Cmdlet $PSCmdlet return } } } } |