The commands in OrphanedSid return objects so you can keep going with them in the pipeline. The first post showed it with the same example the README opens its usage section with:

1
2
3
4
Get-ADOrganizationalUnit -Filter * -SearchScope OneLevel |
    Find-OrphanedSid -IncludeInherited |
    Group-Object OrphanedSID |
    Sort-Object Count -Descending

Point it at every top-level OU and see which dead SIDs show up most. On 1.0.0 and 1.0.1, that example dropped every OU you piped in and searched the domain root. Piping the same objects into Remove-OrphanedSid did the same thing, and piping them into Restore-OrphanedSidBackup failed to bind at all. It’s issue #79.

Less than two weeks before 1.0.0 shipped, I’d ended a post about CaOutcome with “A README example is a test case I haven’t written yet.” This was another one.

The right answer from 303 objects

I ran the README’s pipe again on the lab DC on November 19, piping one OU into Find-OrphanedSid from the 1.0.1 and 1.1.0 packages, each in a fresh process:

ModuleSearch base in the logObjects readTimeResults
1.0.1DC=ad,DC=homelabdomain,DC=xyz30378 s2
1.1.0OU=Orphaned,OU=EdgeCases,...36 s2

Both runs returned the same two orphans on the same two groups. In my lab, the only seeded orphans live in that OU, so a domain-wide search finds the same two. The output looked correct. The only signs were a warning and a log line:

1
2
WARNING: No search base specified. Using the current domain root.
[Information] [MainProcessing] Processing search base: DC=ad,DC=homelabdomain,DC=xyz

A real directory has orphans everywhere. When #79 was filed, a -WhatIf preview of Get-ADOrganizationalUnit <one OU> | Remove-OrphanedSid listed 7 objects, and 6 of them were outside the piped OU. Without -WhatIf and with -Force, that’s a removal across the domain from a command that named one OU.

Restore failed in a safer way:

1
Cannot bind argument to parameter 'TargetObjectDN' because it is an empty array.

An object that answers every question

Piping a DN string worked. Piping a [pscustomobject] with a DistinguishedName property worked. Only real AD objects failed, and the AD module explains why. On the DC:

1
2
$ou = Get-ADOrganizationalUnit 'OU=Orphaned,OU=EdgeCases,OU=ZZ-TEST-TestData,DC=ad,DC=homelabdomain,DC=xyz'
foreach ($n in 'SearchBase', 'TargetObjectDN', 'NoSuchPropertyAtAll') { ... }
1
2
3
SearchBase -> Microsoft.ActiveDirectory.Management.ADPropertyValueCollection count 0
TargetObjectDN -> Microsoft.ActiveDirectory.Management.ADPropertyValueCollection count 0
NoSuchPropertyAtAll -> Microsoft.ActiveDirectory.Management.ADPropertyValueCollection count 0

The AD module’s adapter answers any property name you ask for. If the attribute isn’t there, you get an empty collection back, not $null.

Now look at the 1.0.1 parameter:

1
2
3
[Parameter(ValueFromPipeline, ValueFromPipelineByPropertyName)]
[Alias('DistinguishedName')]
[string[]]$SearchBase,

A string was meant to bind by value, and an object by its DistinguishedName through the alias. To see what PowerShell does with an AD object, I put the same parameter on a small test function on the DC and ran Trace-Command -Name ParameterBinding. Trimmed to the pipeline part:

1
2
3
4
5
6
PIPELINE object TYPE = [Microsoft.ActiveDirectory.Management.ADOrganizationalUnit]
Parameter [SearchBase] PIPELINE INPUT ValueFromPipeline NO COERCION
    BIND arg [OU=Orphaned,...] to param [SearchBase] SKIPPED
Parameter [SearchBase] PIPELINE INPUT ValueFromPipelineByPropertyName NO COERCION
    BIND arg [Microsoft.ActiveDirectory.Management.ADPropertyValueCollection] to parameter [SearchBase]
    BIND arg [System.String[]] to param [SearchBase] SUCCESSFUL

By value is tried first without type conversion, and an ADOrganizationalUnit isn’t a string, so it’s skipped. By property name comes next, and PowerShell asks for the parameter’s own name before any alias. It asked the OU for SearchBase, the adapter handed back an empty collection, and that bound as an empty string[]. The binding succeeded, so the DistinguishedName alias was never tried.

The process block saw nothing to add, and end did what it was written to do with an empty list:

1
2
3
4
if ($searchBases.Count -eq 0) {
    Write-Warning 'No search base specified. Using the current domain root.'
    $searchBases.Add((Get-ADDomain).DistinguishedName)
}

Restore-OrphanedSidBackup had the same shape on -TargetObjectDN, but it’s Mandatory, so the empty array failed binding instead of falling back.

The CaOutcome post’s rule applies here too: pipe the shape your real upstream produces. The unit tests piped strings and [pscustomobject]s, and both bind correctly. Only an object whose adapter claims every property shows the failure.

Reading the DN myself

1.1.0 stops asking PowerShell to find the DN. All three parameters are [object[]], bound by value only:

1
2
3
4
5
6
# [object[]], not [string[]]: by-property binding asks an AD object for 'SearchBase' before
# the alias, the AD adapter answers with an empty collection, and the run fell back to the
# domain root. Each item is read by ConvertTo-DistinguishedName instead.
[Parameter(ValueFromPipeline)]
[Alias('DistinguishedName')]
[object[]]$SearchBase,

An [object[]] parameter accepts anything by value, so every piped item reaches process as itself. A new private function, ConvertTo-DistinguishedName, reads each one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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
    }
}

Strings, hashtables, Import-Csv rows and AD objects all work. A blank value is dropped. Anything with no DN gets an error naming its type. On the DC, with 1.1.0:

1
Get-Service W32Time | Find-OrphanedSid -ErrorAction Stop
1
Cannot use an object of type System.ServiceProcess.ServiceController as a distinguished name: it is not a string and has no DistinguishedName property

That error alone isn’t the fix. Bad input that still fell through to the domain root would be #79 again. So the commands now tell “no -SearchBase at all” apart from “a -SearchBase that held nothing usable”:

1
2
3
4
5
6
7
8
if ($searchBases.Count -eq 0) {
    if ($searchBaseGiven) {
        # Input that held no usable DN is a mistake to report, not a request for the domain root
        throw 'No usable search base in the input. Pass distinguished names, or objects with a DistinguishedName property; the domain root is used only when -SearchBase is not given at all.'
    }
    Write-Warning 'No search base specified. Using the current domain root.'
    $searchBases.Add((Get-ADDomain).DistinguishedName)
}

$searchBaseGiven is set in process from $PSBoundParameters, so it’s true for piped input too. Restore-OrphanedSidBackup stops with No usable restore target in the input. One behavior change came with this, and it’s in the changelog: -SearchBase ' ' used to search the domain root, and now it stops.

The same OU piped into 1.1.0 is the second row of the table: 3 objects, one search base, no warning.

A test double that answers like AD

The new tests needed something that fails the way an AD object does, on a runner without RSAT. The stand-in carries a DistinguishedName plus the two parameter names as empty collections. That’s the shape the adapter presents:

1
2
3
4
5
6
7
function New-ADLikeObject([string]$DistinguishedName) {
    [PSCustomObject]@{
        DistinguishedName = $DistinguishedName
        SearchBase        = [System.Collections.Generic.List[object]]::new()
        TargetObjectDN    = [System.Collections.Generic.List[object]]::new()
    }
}

The test for Find pipes two of them and checks that the domain was never asked for its root:

1
2
3
4
5
6
7
8
It 'Reads the DN of piped AD objects instead of falling back to the domain root (#79)' {
    (New-ADLikeObject 'OU=A,DC=contoso,DC=com'), (New-ADLikeObject 'OU=B,DC=contoso,DC=com') |
        Find-OrphanedSid -WarningVariable warnings -WarningAction SilentlyContinue | Out-Null

    @($warnings).Count | Should -Be 0
    Should -Invoke -ModuleName OrphanedSid Get-ADDomain -Times 0 -Exactly
    # ...plus a check that both OUs reached the processing step, in order
}

With the three public files reverted to the code before the fix, 9 of the new tests fail, including the domain-root fallback for Find and Remove and Restore’s empty-array error.

A relative path that pointed at the profile

Issue #80 was filed less than a minute after #79, and it’s the same kind of bug: a value that looked fine when it came in and meant something else by the time it was used.

1
2
3
4
Set-Location C:\OrphanedSidTest\run
Remove-OrphanedSid -SearchBase $ou -Force -BackupPath .\bk     # .\bk\<timestamp>\ is created here
Restore-OrphanedSidBackup -TargetObjectDN $dn -BackupPath .\bk\20261111_095840 -Force
# ErrorMessage: Backup directory not found: C:\Users\Administrator\bk\20261111_095840

The parameter’s ValidateScript checked the folder with Test-Path, which resolves against your PowerShell location, so validation passed. Then the restore workflow normalized the path with [System.IO.Path]::GetFullPath, which resolves against the process working directory. Set-Location doesn’t change that, and it’s usually your profile folder. On my machine, after Set-Location C:\Windows\Temp, same result on 5.1 and 7:

1
2
3
4
PowerShell location:  C:\Windows\Temp
Process directory:    C:\Users\fadwe
GetFullPath:          C:\Users\fadwe\bk\20261111_095840
Provider path:        C:\Windows\Temp\bk\20261111_095840

The restore’s own help example, -BackupPath '.\Backup\20260703_104232', didn’t work as written. Remove-OrphanedSid -BackupPath .\bk did, because the backup code wrote its files with cmdlets that resolve against your location, and the backup fix in 1.1.0 had already switched it to the PowerShell-aware call. 1.1.0 uses it in all four places the restore normalizes a path:

1
2
3
# Resolved as PowerShell sees it: [IO.Path]::GetFullPath uses the process directory, not
# the current location, so a relative path pointed at the user profile (#80)
$BackupPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($BackupPath)

New-ACLBackup resolves its folder the same way. That’s how it measures the full path for the 260-character budget in the backup post. The new tests set [Environment]::CurrentDirectory and the PowerShell location to different folders before restoring from a relative path. If the two match, the bug can’t show, so the test makes sure they don’t.