Functions/New-MergedObjectHashTable.ps1

<#
.SYNOPSIS
    This function merges two lists of objects into a combined hash table to help with syncing.
.DESCRIPTION
    This function merges two lists of objects into a combined hash table to help with syncing.
.PARAMETER currentObjects
    The objects which are currently present.
.PARAMETER expectedObjects
    The objects which are expected to be present.
.PARAMETER keyProperty
    The name of the object property used as the hash table key.
#>

function New-MergedObjectHashTable {
    [CmdletBinding(PositionalBinding=$false)]
    [OutputType([HashTable])]
    param (
        # The objects which are currently present.
        [Parameter(Mandatory=$true)]
        [AllowEmptyCollection()]
        [PSObject[]]$currentObjects,

        # The objects which are expected to be present.
        [Parameter(Mandatory=$true)]
        [AllowEmptyCollection()]
        [PSObject[]]$expectedObjects,

        # The name of the object property used as the hash table key.
        [Parameter(Mandatory=$true)]
        [String]$keyProperty
    )

    # Create hash table
    $hashTable = @{}

    # Add current objects to hash table
    foreach ($object in $currentObjects) {
        # Ensure that all key properties are not null
        if ($null -eq $object.$keyProperty) {
            return $null
        }

        # Add to the hash table
        $hashTable.Add(
            $object.$keyProperty,
            @{
                Current     = $object
                Expected    = $null
            }
        )
    }

    # Update hash table with expected objects
    foreach ($object in $expectedObjects) {
        # Ensure that all key properties are not null
        if ($null -eq $object.$keyProperty) {
            return $null
        }

        # Object is already in the hash table
        if ($hashTable.ContainsKey($object.$keyProperty)) {
            $hashTable.($object.$keyProperty).Expected = $object
        }

        # Add object to the hash table
        else {
            $hashTable.Add(
                $object.$keyProperty,
                @{
                    Current     = $null
                    Expected    = $object
                }
            )
        }
    }

    # Return the hash table
    return $hashTable
}