Private/Utilities/ConvertTo-DistinguishedName.ps1

function ConvertTo-DistinguishedName {
    <#
    .SYNOPSIS
        Turns whatever a command received as a distinguished name into DN strings.
 
    .DESCRIPTION
        The public commands take their search base or restore target from the command line or the
        pipeline, and an operator pipes whatever they have: DN strings, objects from
        Get-ADOrganizationalUnit or Get-ADObject, rows from Import-Csv, or hashtables.
 
        Binding those to a [string[]] parameter by property name does not work for Active Directory
        objects. PowerShell asks for the parameter's own name before its DistinguishedName alias,
        and the AD module's adapter answers any property name with an empty collection, so the
        parameter bound as empty and the command fell back to the domain root. The parameters are
        therefore [object[]], and this function reads each item:
 
        - A string is trimmed and used as the DN.
        - An object or dictionary with a DistinguishedName property or key contributes its value.
        - Blank values are dropped.
        - Anything else is reported with a non-terminating error naming its type, and skipped.
 
    .PARAMETER InputObject
        The items bound to the command's DN parameter, as one array or one item at a time.
 
    .OUTPUTS
        [string] One trimmed distinguished name per usable item.
 
    .EXAMPLE
        PS> Get-ADOrganizationalUnit -Filter * -SearchScope OneLevel | ForEach-Object { ConvertTo-DistinguishedName -InputObject $_ }
 
        DESCRIPTION: Reads the DN of each AD object
        OUTPUT: 'OU=Servers,DC=contoso,DC=com', ...
        USE CASE: Normalising a command's -SearchBase input in its process block
 
    .EXAMPLE
        PS> ConvertTo-DistinguishedName -InputObject ' OU=A,DC=contoso,DC=com ', '', [pscustomobject]@{ DistinguishedName = 'OU=B,DC=contoso,DC=com' }
 
        DESCRIPTION: Mixed input from the command line and from an Import-Csv row
        OUTPUT: 'OU=A,DC=contoso,DC=com', 'OU=B,DC=contoso,DC=com'
 
    .NOTES
        Author: Jeffrey Stuhr
        Blog: https://www.techbyjeff.net
        LinkedIn: https://www.linkedin.com/in/jeffrey-stuhr-034214aa/
    #>

    [CmdletBinding()]
    [OutputType([string])]
    param(
        [Parameter()]
        [AllowNull()]
        [AllowEmptyCollection()]
        [object[]]$InputObject
    )

    foreach ($item in $InputObject) {
        if ($null -eq $item) {
            continue
        }

        $value = $null
        if ($item -is [string]) {
            $value = $item
        } elseif ($item -is [System.Collections.IDictionary]) {
            if ($item.Contains('DistinguishedName')) {
                $value = $item['DistinguishedName']
            }
        } else {
            $property = $item.PSObject.Properties['DistinguishedName']
            if ($property) {
                $value = $property.Value
            }
        }

        # An AD object can hand back its value wrapped in a one-element collection
        if ($null -ne $value -and $value -isnot [string] -and $value -is [System.Collections.IEnumerable]) {
            $value = @($value | Where-Object { $_ }) | Select-Object -First 1
        }

        if ($null -eq $value) {
            $typeName = $item.GetType().FullName
            $message = "Cannot use an object of type $typeName as a distinguished name: it is not a string and has no DistinguishedName property"
            Write-Error -Message $message -TargetObject $item -Category InvalidArgument -ErrorId 'NotADistinguishedName'
            continue
        }

        $dn = ([string]$value).Trim()
        if ($dn) {
            $dn
        }
    }
}