#Requires -version 2.0

# Jeffery Hicks
# http://jdhitsolutions.com/blog
# follow on Twitter: http://twitter.com/JeffHicks
#
# 
# "Those who neglect to script are doomed to repeat their work."

#  ****************************************************************
#  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
#  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
#  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
#  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
#  ****************************************************************

Function Test-RegistryItem {

<#
.SYNOPSIS
	Test the the existence of a registry item and value.

.DESCRIPTION
	This command will determine if a given registry key exists. You must specify a registry path
	and the name of the key. You can also verify if the value is what you are expecting.

.PARAMETER Path
	The registry path using the registry PSDrive format, ie HKLM:

.PARAMETER Property
	The property name to check. The parameter as an alias of Name.
    
.PARAMETER TargetValue
	The value you expect to find for the specified property.
    
.PARAMETER UseTransaction
	Use an active transaction. This parameter is valid only when a transaction is in progress.
 	For more information, see about_Transactions.

.EXAMPLE
PS C:\> test-RegistryItem -Path "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon" -Property "Shell"
	
Property Path                                                        Exists
-------- ----                                                        ------
Shell    HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon   True

.EXAMPLE
PS C:\> Test-RegistryItem -path "HKLM:\Software\Microsoft\Windows NT\CurrentVersion\WinLogon" -Property "AutoAdminLogon" -TargetValue 1


Property      : AutoAdminLogon
Path          : HKLM:\Software\Microsoft\Windows NT\CurrentVersion\WinLogon
Exists        : True
PropertyMatch : False
TargetValue   : 1
ActualValue   : 0

.EXAMPLE
PS C:\> import-csv winlogon.csv | test-registryitem | Where {-Not $_.Exists} 

Property         Path                                                        Exists
--------         ----                                                        ------
FOODisableCAD    HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon  False
FOOShutdownFlags HKLM:\Software\Microsoft\Windows NT\CurrentVersion\Winlogon  False

.INPUTS
	[String]

.OUTPUTS
	[object]

.NOTES
  NAME:     Test-RegistryItem
  AUTHOR:   Jeffery Hicks
  VERSION:  2.0
  LASTEDIT: 10/14/2010

 Learn more with a copy of Windows PowerShell 2.0: TFM (SAPIEN Press 2010)

.LINK
	Get-ItemProperty
.LINK
	http://jdhitsolutions.com/blog

#>
	
[cmdletbinding()]
	
Param (
	[Parameter(Position=0,Mandatory=$True,
    ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True,
    HelpMessage="Enter a registry path using the PSDrive format.")]
	[ValidateNotNullOrEmpty()]
    [Alias("PSPath")]
    [string]$Path,
    
	[Parameter(Position=1,Mandatory=$True,
    ValueFromPipeline=$True,ValueFromPipelineByPropertyName=$True,
    HelpMessage="Enter a registry key name.")]
	[ValidateNotNullOrEmpty()]
	[Alias("name","item")]
    [string]$Property,

    [Parameter()]
    [Alias("value")]
	[string]$TargetValue,
    
    [Switch]$UseTransaction
)

Process {
 	Write-Verbose ("Looking for {0} in {1}" -f $Property,$Path)
    if (Test-Path $path) 
    {
    	if ($UseTransaction) 
    	{
    		$item=Get-ItemProperty -Path $path -Name $property -ErrorAction "SilentlyContinue" -UseTransaction
    	} else
    	{
    		$item=Get-ItemProperty -Path $path -Name $property -ErrorAction "SilentlyContinue" 
    	}
    	
        if ($item ) 
        {
            #display the item if using -Verbose
        	Write-Verbose ($item | select * | Out-String)
            $Exists=$True
            if ($TargetValue)
            {
                $ActualValue=$item.$Property
                Write-Verbose "Retrieving value for $Property"
                if ($ActualValue -eq $TargetValue) 
                {
                    $PropertyMatch=$True
                }
                else
                {
                    $PropertyMatch=$False
                }
            } #if $value
        } #if $item
        else 
        {
        	Write-Verbose "Not found"
            $Exists=$False
            $PropertyMatch=$False
        }
    } #if test-path
    else 
    {
        Write-Warning "Failed to find $path"
        $Exists=$False
    }
    
    #create a custom object
    $obj=New-Object -TypeName PSObject -Property @{
        "Path"=$path
        "Property"=$Property
        "Exists"=$Exists
     }
     #add additional properties if looking for a property match
     if ($TargetValue) 
     {
        Write-Verbose "Adding TargetValue Properties"
        $obj | Add-Member -MemberType NoteProperty -Name "PropertyMatch" -Value $PropertyMatch
        $obj | Add-Member -MemberType NoteProperty -Name "TargetValue" -Value $TargetValue
        $obj | Add-Member -MemberType NoteProperty -Name "ActualValue" -Value $ActualValue
     }
     #write the result to the pipeline
     write $obj
     
 } #end Process

} #end function