#requires -version 2.0

Function Join-Hashtable {

<#
.Synopsis
Combine two hashtables into one.
.Description
This command will combine two hashtables into a single hashtable. Normally this
is as easy as $hash1+$hash2. But if there are duplicate keys, this will fail.
Join-Hashtable will test for duplicate keys. If any of the keys from the first,
or primary hashtable are found in the secondary hashtable, you will be prompted
for which to keep. Or you can use -Force which will always keep the conflicting
key from the first hashtable.

The original hashtables will not be modified.

.Parameter First
The primary hashtable. If there are any duplicate keys and you use -Force, 
values from this hashtable will be kept.
.Parameter Second
The secondary hashtable.
.Parameter Force
Do not prompt for conflicts. Always keep the key from the first hashtable.
.Example
PS C:\> $a=@{Name="Jeff";Count=3;Color="Green"}
PS C:\> $b=@{Computer="HAL";Enabled=$True;Year=2020;Color="Red"}
PS C:\> join-hashtable $a $b
Duplicate key Color
A Green
B Red
Which key do you want to KEEP [AB]?: A

Name                           Value                                                      
----                           -----                                                      
Year                           2020                                                       
Name                           Jeff                                                       
Enabled                        True                                                       
Color                          Green                                                      
Computer                       HAL                                                        
Count                          3       
.Example
PS C:\> $c = join-hashtable $a $b -force
PS C:\> $c

Name                           Value                                                      
----                           -----                                                      
Year                           2020                                                       
Name                           Jeff                                                       
Enabled                        True                                                       
Color                          Green                                                      
Computer                       HAL                                                        
Count                          3     
.NOTES
NAME        :  Join-HashTable
VERSION     :  1.0   
LAST UPDATED:  1/23/2013
AUTHOR      :  Jeffery Hicks (@JeffHicks)

Read PowerShell:
Learn Windows PowerShell 3 in a Month of Lunches
Learn PowerShell Toolmaking in a Month of Lunches
PowerShell in Depth: An Administrator's Guide

!!Do not use in a production environment until you have tested. If you don't!!
!!understand something then you should not run it in production. You accept !!
!!any and all risks.                                                        !!

.Link
About_Hash_Tables
.Inputs
hashtable
.Outputs
hashtable
#>
[cmdletbinding()]
Param (
[hashtable]$First, 
[hashtable]$Second, 
[switch]$Force
)

#create clones of hashtables so originals are not modified
$Primary = $First.Clone()
$Secondary = $Second.Clone()

#check for any duplicate keys
$duplicates = $Primary.keys | where {$Secondary.ContainsKey($_)}
if ($duplicates) {
    foreach ($item in $duplicates) {
        if ($force) {
            #force primary key, so remove secondary conflict
            $Secondary.Remove($item)
        }
        else {
            Write-Host "Duplicate key $item" -ForegroundColor Yellow
            Write-Host "A $($Primary.Item($item))" -ForegroundColor Yellow
            Write-host "B $($Secondary.Item($item))" -ForegroundColor Yellow
            $r = Read-Host "Which key do you want to KEEP [AB]?"
            if ($r -eq "A") {
                $Secondary.Remove($item)
            }
            elseif ($r -eq "B") {
                $Primary.Remove($item)
            }
            Else {
                Write-Warning "Aborting operation"
                Return 
            }
        } #else prompt
   }
}

#join the two hash tables
$Primary+$Secondary

} #end Join-Hashtable