Private/ActiveDirectory/Get-ADObjectFromSearchBase.ps1

function Get-ADObjectFromSearchBase {
    <#
    .SYNOPSIS
        Retrieves Active Directory objects from a single search base
 
    .DESCRIPTION
        Performs AD object retrieval from a specified search base, including each object's
        security descriptor. A transient failure is retried through Invoke-ADOperationWithRetry;
        a failure that persists is thrown. Designed for pipeline efficiency.
 
    .PARAMETER SearchBase
        The distinguished name of the search base
 
    .PARAMETER IncludeInherited
        Whether to include inherited permissions in security descriptors
 
    .PARAMETER Properties
        Additional properties to retrieve (nTSecurityDescriptor always included)
 
    .PARAMETER MaxRetries
        Retries after the first attempt when the read fails with an error that looks transient
        (0-10, default 3). A read that still fails is thrown to the caller.
 
    .EXAMPLE
        PS> Get-ADObjectFromSearchBase -SearchBase "OU=Users,DC=contoso,DC=com"
 
        DESCRIPTION: Retrieves all AD objects from the Users OU
        OUTPUT: Collection of AD objects with security descriptors
        USE CASE: Scanning specific organizational units for security analysis
 
    .EXAMPLE
        PS> @("OU=Users,DC=contoso,DC=com", "OU=Groups,DC=contoso,DC=com") | Get-ADObjectFromSearchBase
 
        DESCRIPTION: Pipeline processing of multiple search bases
        OUTPUT: Combined collection from all search bases
        USE CASE: Bulk processing of multiple organizational units
 
    .NOTES
        Author: Jeffrey Stuhr
        Blog: https://www.techbyjeff.net
        LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/
 
        TROUBLESHOOTING:
        - For search base issues: .\Troubleshooting\Common\Common-Issues.md
    #>


    [CmdletBinding()]
    [OutputType('Microsoft.ActiveDirectory.Management.ADObject')]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'IncludeInherited',
        Justification = 'Accepted for call-site parity; inheritance is filtered when the ACL is examined')]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$SearchBase,

        [Parameter()]
        [switch]$IncludeInherited,

        [Parameter()]
        [string[]]$Properties = @('nTSecurityDescriptor'),

        [Parameter()]
        [ValidateRange(0, 10)]
        [int]$MaxRetries = 3,

        [Parameter()]
        [string]$CorrelationId = [System.Guid]::NewGuid().ToString()
    )

    process {
        Write-Verbose "Retrieving AD objects from search base: $SearchBase - CorrelationId: $CorrelationId"

        # Ensure nTSecurityDescriptor is always included
        $allProperties = @($Properties) + @('nTSecurityDescriptor') | Sort-Object -Unique

        # A transient failure is retried; one that persists is thrown, so Get-ADObjectsSequential
        # counts the search base as failed, warns, and records it in the security log. Swallowing it
        # here once made an unreadable search base count as a successful one with no objects.
        $objects = Invoke-ADOperationWithRetry -ScriptBlock {
            Get-ADObject -SearchBase $SearchBase -Filter * -Properties $allProperties -ErrorAction Stop
        } -MaxRetries ($MaxRetries + 1) -OperationName 'Get-ADObject-SearchBase' -ObjectContext $SearchBase -CorrelationId $CorrelationId

        # Output to pipeline for efficiency
        if ($objects) {
            foreach ($obj in @($objects)) {
                Write-Output $obj
            }
        }

        Write-Verbose "Retrieved $(@($objects).Count) objects from search base: $SearchBase"
    }
}