SharedResources/Src/InstallPrimaryHeadNode/xPSDesiredStateConfiguration/DSCResources/MSFT_xRegistryResource/MSFT_xRegistryResource.psm1

<#
    This PS module contains functions for Desired State Configuration (DSC) Registry provider.
    It enables querying, creation, removal and update of Windows registry keys through
    Get, Set and Test operations on DSC managed nodes.
#>

# Fallback message strings in en-US
data localizedData
{
    # culture = "en-US"
    ConvertFrom-StringData @'
        ParameterValueInvalid = (ERROR) Parameter '{0}' has an invalid value '{1}' for type '{2}'
        InvalidPSDriveSpecified = (ERROR) Invalid PSDrive '{0}' specified in registry key '{1}'
        InvalidRegistryHiveSpecified = (ERROR) Invalid registry hive was specified in registry key '{0}'
        SetRegValueFailed = (ERROR) Failed to set registry key value '{0}' to value '{1}' of type '{2}'
        SetRegValueUnchanged = (UNCHANGED) No change to registry key value '{0}' containing '{1}'
        SetRegKeyUnchanged = (UNCHANGED) No change to registry key '{0}'
        SetRegValueSucceeded = (SET) Set registry key value '{0}' to '{1}' of type '{2}'
        SetRegKeySucceeded = (SET) Create registry key '{0}'
        SetRegKeyFailed = (ERROR) Failed to created registry key '{0}'
        RemoveRegKeyTreeFailed = (ERROR) Registry Key '{0}' has subkeys, cannot remove without Force flag
        RemoveRegKeySucceeded = (REMOVAL) Registry key '{0}' removed
        RemoveRegKeyFailed = (ERROR) Failed to remove registry key '{0}'
        RemoveRegValueSucceeded = (REMOVAL) Registry key value '{0}' removed
        RemoveRegValueFailed = (ERROR) Failed to remove registry key value '{0}'
        RegKeyDoesNotExist = Registry key '{0}' does not exist
        RegKeyExists = Registry key '{0}' exists
        RegValueExists = Found registry key value '{0}' with type '{1}' and data '{2}'
        RegValueDoesNotExist = Registry key value '{0}' does not exist
        RegValueTypeMismatch = Registry key value '{0}' of type '{1}' does not exist
        RegValueDataMismatch = Registry key value '{0}' of type '{1}' does not contain data '{2}'
        DefaultValueDisplayName = (Default)
        GetTargetResourceStartMessage = Begin executing Get functionality on the Registry key {0}.
        GetTargetResourceEndMessage = End executing Get functionality on the Registry key {0}.
        SetTargetResourceStartMessage = Begin executing Set functionality on the Registry key {0}.
        SetTargetResourceEndMessage = End executing Set functionality on the Registry key {0}.
        TestTargetResourceStartMessage = Begin executing Test functionality on the Registry key {0}.
        TestTargetResourceEndMessage = End executing Test functionality on the Registry key {0}.
'@
}

# Commented-out until more languages are supported
# Import-LocalizedData LocalizedData -FileName MSFT_xRegistryResource.strings.psd1

<#
    .SYNOPSIS
        Gets the current state of the Registry item being managed.

    .PARAMETER Key
        Indicates the path of the registry key for which you want to ensure a specific state.
        This path must include the hive.

    .PARAMETER ValueName
        Indicates the name of the registry value.
#>
function Get-TargetResourceInternal
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key,

        # Default is [String]::Empty to cater for the (Default) RegValue
        [System.String]
        $ValueName = [System.String]::Empty
    )

    # Perform any required setup steps for the provider
    Invoke-RegistryProviderSetup -KeyName ([ref] $Key)

    $valueNameSpecified = $PSBoundParameters.ContainsKey('ValueName')

    # First check if the specified key exists
    $keyInfo = Get-RegistryKeyInternal -Path $Key -ErrorAction SilentlyContinue

    # If $keyInfo is $null, the registry key doesn't exist
    if ($null -eq $keyInfo)
    {
        Write-Verbose ($localizedData.RegKeyDoesNotExist -f $Key)

        $retVal = @{
            Ensure = 'Absent'
            Key = $Key
        }

        return $retVal
    }

    # If the control reaches here, the key has been found at least
    $retVal = @{
        Ensure = 'Present'
        Key = $Key
        Data = $keyInfo
    }

    <#
        If $ValueName parameter has not been specified
        then we simply report success on finding the $Key
    #>
    if (!$valueNameSpecified)
    {
        Write-Verbose ($localizedData.RegKeyExists -f $Key)

        return $retVal
    }

    <#
        If the control reaches here, the $ValueName has been specified as a parameter
        and we should query it now
    #>
    $registryValueOptions = [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames
    $valData = $keyInfo.GetValue($ValueName, $null, $registryValueOptions)

    # If $ValueName is not found in the specified $Key
    if ($null -eq $valData)
    {
        Write-Verbose ($localizedData.RegValueDoesNotExist -f "$Key\$ValueName")

        $retVal = @{
            Ensure = 'Absent'
            Key = $Key
            ValueName = (Get-ValueDisplayName -ValueName $ValueName)
        }

        return $retVal
    }

    # Finalize name, type and data to be returned
    $finalName = Get-ValueDisplayName -ValueName $ValueName
    $finalType = $keyInfo.GetValueKind($ValueName)
    $finalData = $valData

    # Special case: For Binary type data we convert the received bytes back to a readable hex-string
    if ($finalType -ieq 'Binary')
    {
        $finalData = Convert-ByteArrayToHexString -Data $valData
    }

    # Populate all config in the return object
    $retVal.ValueName = $finalName
    $retVal.ValueType = $finalType
    $retVal.Data =  $finalData

    <#
        If the control reaches here, both the $Key and the $ValueName have been found,
        query is fully successful
    #>
    Write-Verbose ($localizedData.RegValueExists -f "$Key\$ValueName", $retVal.ValueType,
        (Convert-ArrayToString $retVal.Data))

    return $retVal
}

<#
    .SYNOPSIS
        Returns the current state of the Registry item being managed.

    .PARAMETER Key
        Indicates the path of the registry key for which you want to ensure a specific state.
        This path must include the hive.

    .PARAMETER ValueName
        Indicates the name of the registry value.

    .PARAMETER ValueData
        The data for the registry value.

    .PARAMETER ValueType
        Indicates the type of the value. The supported types are:
            String (REG_SZ)
            Binary (REG-BINARY)
            Dword 32-bit (REG_DWORD)
            Qword 64-bit (REG_QWORD)
            Multi-string (REG_MULTI_SZ)
            Expandable string (REG_EXPAND_SZ)
#>
function Get-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Collections.Hashtable])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key,

        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [AllowEmptyString()]
        [System.String]
        $ValueName,

        <#
            Special-case: Used only as a boolean flag (along with ValueType) to determine
            if the target entity is the Default Value or the key itself.
        #>
        [System.String[]]
        $ValueData,

        <#
            Special-case: Used only as a boolean flag (along with ValueData) to determine
            if the target entity is the Default Value or the key itself.
        #>
        [ValidateSet('String', 'Binary', 'DWord', 'QWord', 'MultiString', 'ExpandString')]
        [System.String]
        $ValueType
    )

    Write-Verbose ($localizedData.GetTargetResourceStartMessage -f $Key)

    <#
        If $ValueName is "" and ValueType and ValueData are both not specified,
        then we target the key itself (not Default Value)
    #>
    if ($ValueName -eq '' -and !$PSBoundParameters.ContainsKey('ValueType') -and
        !$PSBoundParameters.ContainsKey('ValueData'))
    {
        $retVal = Get-TargetResourceInternal -Key $Key
    }
    else
    {
        $retVal = Get-TargetResourceInternal -Key $Key -ValueName $ValueName

        if ($retVal.Ensure -eq 'Present')
        {
            $retVal.ValueData = [System.String[]]@()
            $retVal.ValueData += $retVal.Data

            if ($retVal.ValueType -ieq 'MultiString')
            {
                $retVal.ValueData = $retVal.Data
            }
        }
    }

    $retVal.Remove('Data')

    Write-Verbose ($localizedData.GetTargetResourceEndMessage -f $Key)

    return $retVal
}

<#
    .SYNOPSIS
        Ensures the specified state of the Registry item being managed

    .PARAMETER Key
        Indicates the path of the registry key for which you want to ensure a specific state.
        This path must include the hive.

    .PARAMETER ValueName
        Indicates the name of the registry value.

    .PARAMETER Ensure
        Indicates if the key and value should exist.
        To ensure that they do, set this property to "Present".
        To ensure that they do not exist, set the property to "Absent".
        The default value is "Present".

    .PARAMETER ValueData
        The data for the registry value.

    .PARAMETER ValueType
        Indicates the type of the value. The supported types are:
            String (REG_SZ)
            Binary (REG-BINARY)
            Dword 32-bit (REG_DWORD)
            Qword 64-bit (REG_QWORD)
            Multi-string (REG_MULTI_SZ)
            Expandable string (REG_EXPAND_SZ)

    .PARAMETER Hex
        Indicates if data will be expressed in hexadecimal format.
        If specified, the DWORD/QWORD value data is presented in hexadecimal format.
        Not valid for other types. The default value is $false.

    .PARAMETER Force
        If the specified registry key is present, Force overwrites it with the new value.
#>
function Set-TargetResource
{
    [CmdletBinding(SupportsShouldProcess = $true)]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key,

        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [AllowEmptyString()]
        [System.String]
        $ValueName,

        [ValidateSet('Present', 'Absent')]
        [System.String]
        $Ensure = 'Present',

        [ValidateNotNull()]
        [System.String[]]
        $ValueData = @(),

        [ValidateSet('String', 'Binary', 'DWord', 'QWord', 'MultiString', 'ExpandString')]
        [System.String]
        $ValueType = 'String',

        [System.Boolean]
        $Hex = $false,

        [System.Boolean]
        $Force = $false
    )

    Write-Verbose ($localizedData.SetTargetResourceStartMessage -f $Key)

    # Perform any required setup steps for the provider
    Invoke-RegistryProviderSetup -KeyName ([ref] $Key)

    # Query if the RegVal related parameters have been specified
    $valueNameSpecified = $PSBoundParameters.ContainsKey('ValueName')
    $valueTypeSpecified = $PSBoundParameters.ContainsKey('ValueType')
    $valueDataSpecified = $PSBoundParameters.ContainsKey('ValueData')
    $keyCreated = $false

    <#
        If an empty string ValueName has been specified and no ValueType and no ValueData
        has been specified, treat this case as if ValueName was not specified and target
        the Key itself. This is to cater the limitation that both Key and ValueName
        are mandatory now and we must special-case like this to target the Key only.
    #>
    if ($ValueName -eq '' -and !$valueTypeSpecified -and !$valueDataSpecified)
    {
        $valueNameSpecified = $false
    }

    # Now, query the specified key
    $keyInfo = Get-TargetResourceInternal -Key $Key -Verbose:$false

    <#
        ----------------
        ENSURE = PRESENT
    #>
    if ($Ensure -ieq 'Present')
    {
        # If key doesn't exist, attempt to create it
        if ($keyInfo.Ensure -ieq 'Absent')
        {
            if ($PSCmdlet.ShouldProcess(($localizedData.SetRegKeySucceeded -f "$Key"), $null, $null))
            {
                try
                {
                    $keyInfo = New-RegistryKeyInternal -Key $Key
                    $keyCreated = $true
                }
                catch [System.Exception]
                {
                    Write-Verbose ($localizedData.SetRegKeyFailed -f "$Key")

                    throw
                }
            }
        }

        <#
            If $ValueName, $ValueType and $ValueData are not specified, the simple existence/creation
            of the Regkey satisfies the Ensure=Present condition, just return
        #>
        if (!$valueNameSpecified -and !$valueDataSpecified -and !$valueTypeSpecified)
        {
            if (!$keyCreated)
            {
                Write-Log ($localizedData.SetRegKeyUnchanged -f "$Key")
            }

            return
        }

        <#
            If $ValueType and $ValueData are both not specified, but $ValueName is specified, check
            if the Value exists, if yes return with status unchanged, otherwise report input error
        #>
        if (!$ValueTypeSpecified -and !$valueDataSpecified -and $valueNameSpecified)
        {
            $valData = $keyInfo.Data.GetValue($ValueName)

            if ($null -ne $valData)
            {
                Write-Log ($localizedData.SetRegValueUnchanged -f "$Key\$ValueName",
                    (Convert-ArrayToString -Value $valData))

                return
            }
        }

        # Create a strongly-typed object (in accordance with the specified $ValueType)
        $setVal = $null
        Get-TypedObject -Type $ValueType -Data $ValueData -Hex $Hex -ReturnValue ([ref] $setVal)

        <#
            Get the appropriate display name for the specified ValueName
            (to handle the Default RegValue case)
        #>
        $valDisplayName = Get-ValueDisplayName -ValueName $ValueName

        if ($PSCmdlet.ShouldProcess(($localizedData.SetRegValueSucceeded -f "$Key\$valDisplayName",
            (Convert-ArrayToString -Value $setVal), $ValueType), $null, $null))
        {
            try
            {
                # Finally set the $ValueName here
                $keyName = $keyInfo.Data.Name
                [Microsoft.Win32.Registry]::SetValue($keyName, $ValueName, $setVal, $ValueType)
            }
            catch [System.Exception]
            {
                Write-Verbose ($localizedData.SetRegValueFailed -f "$Key\$valDisplayName",
                    (Convert-ArrayToString -Value $setVal), $ValueType)

                throw
            }
        }
    }

    <#
        ---------------
        ENSURE = ABSENT
    #>
    elseif ($Ensure -ieq 'Absent')
    {
        # If key doesn't exist, no action is required
        if ($keyInfo.Ensure -ieq 'Absent')
        {
            Write-Log ($localizedData.RegKeyDoesNotExist -f "$Key")

            return
        }

        # If the code reaches here, the key exists

        <#
            If ValueName is "" and ValueType and ValueData have not been specified,
            target the key for removal
        #>
        if (!$valueNameSpecified -and !$ValueTypeSpecified -and !$valueDataSpecified)
        {
            <#
                If this is not a Force removal and the Key contains subkeys,
                report no change and return
            #>
            if (!$Force -and ($keyInfo.Data.SubKeyCount -gt 0))
            {
                $errorMessage = $localizedData.RemoveRegKeyTreeFailed -f "$Key"

                Write-Log $errorMessage

                $invokeThrowErrorHelperParams = @{
                    ExceptionName = 'System.InvalidOperationException'
                    ExceptionMessage = $errorMessage
                    ExceptionObject = $Force
                    ErrorId = 'CannotRemoveKeyTreeWithoutForceFlag'
                    ErrorCategory = 'NotSpecified'
                }
                Invoke-ThrowErrorHelper @invokeThrowErrorHelperParams
            }

            <#
                If the control reaches here, either the $Force flag was specified
                or the Regkey has no subkeys. In either case we simply remove it.
            #>
            if ($PSCmdlet.ShouldProcess(($localizedData.RemoveRegKeySucceeded -f $Key), $null, $null))
            {
                try
                {
                    $null = Remove-Item -Path $Key -Recurse -Force
                }
                catch [System.Exception]
                {
                    Write-Verbose ($localizedData.RemoveRegKeyFailed -f "$Key")

                    throw
                }
            }

            return
        }

        <#
            If the control reaches here, ValueName has been specified so a RegValue
            needs be removed (if found)
        #>

        <#
            Get the appropriate display name for the specified ValueName
            (to handle the Default RegValue case)
        #>
        $valDisplayName = Get-ValueDisplayName -ValueName $ValueName

        # Query the specified $ValueName
        $valData = $keyInfo.Data.GetValue($ValueName)

        # If $ValueName is not found in the specified $Key
        if ($null -eq $valData)
        {
            Write-Log ($localizedData.RegValueDoesNotExist -f "$Key\$valDisplayName")

            return
        }

        # If the control reaches here, the specified Value has been found and should be removed.

        if ($PSCmdlet.ShouldProcess(
            ($localizedData.RemoveRegValueSucceeded -f "$Key\$valDisplayName"), $null, $null))
        {
            try
            {
                $null = Remove-ItemProperty -Path $Key -Name $ValueName -Force

            }
            catch [System.Exception]
            {
                Write-Verbose ($localizedData.RemoveRegValueFailed -f "$Key\$valDisplayName")

                throw
            }
        }
    }

    Write-Verbose ($localizedData.SetTargetResourceEndMessage -f $Key)
}

<#
    .SYNOPSIS
        Tests if the Registry item being managed is in the desired state

    .PARAMETER Key
        Indicates the path of the registry key for which you want to ensure a specific state.
        This path must include the hive.

    .PARAMETER ValueName
        Indicates the name of the registry value.

    .PARAMETER Ensure
        Indicates if the key and value should exist.
        To test that they exist, set this property to "Present".
        To test that they do not exist, set the property to "Absent".
        The default value is "Present".

    .PARAMETER ValueData
        The data for the registry value.

    .PARAMETER ValueType
        Indicates the type of the value. The supported types are:
            String (REG_SZ)
            Binary (REG-BINARY)
            Dword 32-bit (REG_DWORD)
            Qword 64-bit (REG_QWORD)
            Multi-string (REG_MULTI_SZ)
            Expandable string (REG_EXPAND_SZ)

    .PARAMETER Hex
        Indicates if data will be expressed in hexadecimal format.
        If specified, the DWORD/QWORD value data is presented in hexadecimal format.
        Not valid for other types. The default value is $false.

    .PARAMETER Force
        If the specified registry key is present, Force overwrites it with the new value.
#>
function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key,

        [Parameter(Mandatory = $true)]
        [AllowEmptyString()]
        [ValidateNotNull()]
        [System.String]
        $ValueName,

        [ValidateSet('Present', 'Absent')]
        [System.String]
        $Ensure = 'Present',

        [ValidateNotNull()]
        [System.String[]]
        $ValueData = @(),

        [ValidateSet('String', 'Binary', 'DWord', 'QWord', 'MultiString', 'ExpandString')]
        [System.String]
        $ValueType = 'String',

        [System.Boolean]
        $Hex = $false,

        <#
            Force is not used in Test-TargetResource but is required by DSC engine
            to keep parameter-sets in parity for both SET and TEST
        #>
        [System.Boolean]
        $Force = $false
    )

    Write-Verbose ($localizedData.TestTargetResourceStartMessage -f $Key)

    # Perform any required setup steps for the provider
    Invoke-RegistryProviderSetup -KeyName ([ref] $Key)

    # Query if the RegVal related parameters have been specified
    $valueNameSpecified = $PSBoundParameters.ContainsKey('ValueName')
    $ValueTypeSpecified = $PSBoundParameters.ContainsKey('ValueType')
    $valueDataSpecified = $PSBoundParameters.ContainsKey('ValueData')

    <#
        If an empty string ValueName has been specified and no ValueType and no ValueData
        has been specified, treat this case as if ValueName was not specified and target
        the Key itself.

        This is to cater the limitation that both Key and ValueName are mandatory now and
        we must special-case like this to target the Key only.
    #>
    if (($ValueName -eq '') -and !$ValueTypeSpecified -and !$valueDataSpecified)
    {
        $valueNameSpecified = $false
    }

    # Now, query the specified key
    $keyInfo = Get-TargetResourceInternal -Key $Key -Verbose:$false

    <#
        ----------------
        ENSURE = PRESENT
    #>
    if ($Ensure -ieq 'Present')
    {
        # If key doesn't exist, the test fails
        if ($keyInfo.Ensure -ieq 'Absent')
        {
            Write-Verbose ($localizedData.RegKeyDoesNotExist -f $Key)

            return $false
        }

        <#
            If $ValueName, $ValueType and $ValueData are not specified, the simple existence
            of the Regkey satisfies the Ensure=Present condition, test is successful
        #>
        if (!$valueNameSpecified -and !$valueDataSpecified -and !$ValueTypeSpecified)
        {
            Write-Verbose ($localizedData.RegKeyExists -f $Key)

            return $true
        }

        # IF THE CONTROL REACHED HERE, THE KEY EXISTS AND A REGVALUE ATTRIBUTE HAS BEEN SPECIFIED

        <#
            Get the appropriate display name for the specified ValueName
            (to handle the Default RegValue case)
        #>
        $valDisplayName = Get-ValueDisplayName -ValueName $ValueName

        # Now query the specified Reg Value
        $valData = Get-TargetResourceInternal -Key $Key -ValueName $ValueName -Verbose:$false

        # If the Value doesn't exist, the test has failed
        if ($valData.Ensure -ieq 'Absent')
        {
            Write-Verbose ($localizedData.RegValueDoesNotExist -f "$Key\$valDisplayName")

            return $false
        }

        # IF THE CONTROL REACHED HERE, THE KEY EXISTS AND THE SPECIFIED (or Default) VALUE EXISTS

        <#
            If the $ValueType has been specified and
            it doesn't match the type of the found RegValue, test fails
        #>
        if ($ValueTypeSpecified -and ($ValueType -ine $valData.ValueType))
        {
            Write-Verbose ($localizedData.RegValueTypeMismatch -f "$Key\$valDisplayName", $ValueType)

            return $false
        }

        <#
            If an explicit ValueType has not been specified, given the Value already exists
            in Registry, assume the ValueType to be of the existing Value
        #>
        if (!$ValueTypeSpecified)
        {
            $ValueType = $valData.ValueType
        }

        # If $ValueData has been specified, match the data of the found Regvalue.
        if ($valueDataSpecified -and
            !(Compare-ValueData -RetrievedValue $valData -ValueType $ValueType -ValueData $ValueData))
        {
            # Since the $ValueData specified didn't match the data of the found RegValue, test failed
            Write-Verbose ($localizedData.RegValueDataMismatch -f "$Key\$valDisplayName",
                $ValueType, (Convert-ArrayToString -Value $ValueData))

            return $false
        }

        <#
            IF THE CONTROL REACHED HERE, ALL TESTS HAVE PASSED FOR THE SPECIFIED REGISTRY VALUE AND
            IT COMPLETELY MATCHES, REPORT SUCCESS
        #>

        Write-Verbose ($localizedData.RegValueExists -f "$Key\$valDisplayName", $valData.ValueType,
            (Convert-ArrayToString -Value $valData.Data))

        return $true
    }

    <#
        ---------------
        ENSURE = ABSENT
    #>
    elseif ($Ensure -ieq 'Absent')
    {
        # If key doesn't exist, test is successful
        if ($keyInfo.Ensure -ieq 'Absent')
        {
            Write-Log ($localizedData.RegKeyDoesNotExist -f "$Key")

            return $true
        }

        # IF CONTROL REACHED HERE, THE SPECIFIED KEY EXISTS

        <#
            If $ValueName, $ValueType and $ValueData are not specified, the simple existence of
            the Regkey fails the test
        #>
        if (!$valueNameSpecified -and !$valueDataSpecified -and !$ValueTypeSpecified)
        {
            Write-Verbose ($localizedData.RegKeyExists -f $Key)

            return $false
        }

        # IF THE CONTROL REACHED HERE, THE KEY EXISTS AND A REGVALUE ATTRIBUTE HAS BEEN SPECIFIED

        <#
            Get the appropriate display name for the specified ValueName
            (to handle the Default RegValue case)
        #>
        $valDisplayName = Get-ValueDisplayName -ValueName $ValueName

        # Now query the specified RegValue
        $valData = Get-TargetResourceInternal -Key $Key -ValueName $ValueName -Verbose:$false

        # If the Value doesn't exist, the test has passed
        if ($valData.Ensure -ieq 'Absent')
        {
            Write-Verbose ($localizedData.RegValueDoesNotExist -f "$Key\$valDisplayName")

            return $true
        }

        <#
            IF THE CONTROL REACHED HERE, THE KEY EXISTS AND THE SPECIFIED (or Default) VALUE EXISTS,
            THUS REPORT FAILURE
        #>

        Write-Verbose ($localizedData.RegValueExists -f "$Key\$valDisplayName", $valData.ValueType,
            (Convert-ArrayToString -Value $valData.Data))

        return $false
    }

    Write-Verbose ($localizedData.TestTargetResourceEndMessage -f $Key)
}

<#
    .SYNOPSIS
        Helper function to open a registry key

    .PARAMETER Path
        Indicates the path to the Registry key to be opened. This path must include the hive.

#>
function Get-RegistryKeyInternal
{
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [System.String] $Path
    )

    <#
        By the time we get here, the Invoke-RegistryProviderSetup function has already
        set up our path to start with a PSDrive,and validated that it exists, is a Registry drive,
        has a valid root.

        We're using this method instead of Get-Item so there is no ambiguity between
        forward slashes being treated as a path separator vs a literal character in a key name
        (which is legal in the registry.)
    #>

    $driveName = $Path -replace ':.*'
    $subKey = $Path -replace '^[^:]+:\\*'

    $drive = Get-Item -literalPath "${driveName}:\"
    return $drive.OpenSubKey($subKey, $true)
}

<#
    .SYNOPSIS
        Helper function to create an arbitrary registry key

    .PARAMETER Key
        Indicates the path to the Registry key to be created. This path must include the hive.
#>
function New-RegistryKeyInternal
{
    [CmdletBinding(SupportsShouldProcess = $true)]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key
    )

    # Trim any "\" back-slash(es) at the end of the specified RegKey
    $Key = ([System.String] $Key).TrimEnd('\')

    # Extract the parent-key
    $slashIndex = $Key.LastIndexOf('\')
    $parentKey = $Key.Substring(0, $slashIndex)
    $childKey = $Key.Substring($slashIndex + 1)

    # Check if the parent-key exists, if not first create that (recurse).
    if ((Get-TargetResourceInternal -Key $parentKey -Verbose:$false).Ensure -eq 'Absent')
    {
        New-RegistryKeyInternal -Key $parentKey | Out-Null
    }

    $parentKeyObject = Get-RegistryKeyInternal -Path $parentKey

    # Create the Regkey
    try
    {
        if ($PSCmdlet.ShouldProcess($childKey, 'Create'))
        {
            $null = $parentKeyObject.CreateSubKey($childKey)
        }
    }
    catch
    {
        throw
    }

    # If the control reaches here, the key was created successfully
    return (Get-TargetResourceInternal -Key $Key -Verbose:$false)
}

<#
    .SYNOPSIS
        Assert if the PSDrive specified in Registry Key is valid.

    .PARAMETER Key
        Indicates the path to the Registry key to be validated. This path must include the hive.
#>
function Assert-PSDriveValid
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Key
    )

    # Extract the PSDriveName from the specified Key
    $psDriveName = $Key.Substring(0, $Key.IndexOf(':'))

    # Query the specified PSDrive
    $psDrive = Get-PSDrive $psDriveName -ErrorAction SilentlyContinue

    # Validate that the specified psdrive is a valid
    if (($null -eq $psDrive) -or ($null -eq $psDrive.Provider) -or
        ($psDrive.Provider.Name -ine 'Registry') -or
        !(Test-IsValidRegistryRoot -PSDriveRoot $psDrive.Root))
    {
        $errorMessage = $localizedData.InvalidPSDriveSpecified -f $psDriveName, $Key
        $invokeThrowErrorHelperParams = @{
            ExceptionName = 'System.ArgumentException'
            ExceptionMessage = $errorMessage
            ExceptionObject = $Key
            ErrorId = 'InvalidPSDrive'
            ErrorCategory = 'InvalidArgument'
        }
        Invoke-ThrowErrorHelper @invokeThrowErrorHelperParams
    }
}

<#
    .SYNOPSIS
        Helper function to test if the PSDriveRoot is a valid registry root

    .PARAMETER PSDriveRoot
        Indicates the PSDriveRoot to be tested.
#>
function Test-IsValidRegistryRoot
{
    param
    (
        [System.String]
        $PSDriveRoot
    )

    # List of valid registry roots
    $validRegistryRoots = @('HKEY_CLASSES_ROOT', 'HKEY_CURRENT_USER', 'HKEY_LOCAL_MACHINE',
        'HKEY_USERS', 'HKEY_CURRENT_CONFIG')

    # Extract the base of the PSDrive root
    if ($PSDriveRoot.Contains('\'))
    {
        $PSDriveRoot = $PSDriveRoot.Substring(0, $PSDriveRoot.IndexOf('\'))
    }

    return ($validRegistryRoots -icontains $PSDriveRoot)
}

<#
    .SYNOPSIS
        Helper function to write WhatIf or Verbose logs

    .PARAMETER Message
        Specifies the message text to write.
#>
function Write-Log
{
    [CmdletBinding(SupportsShouldProcess = $true)]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Message
    )

    if ($PSCmdlet.ShouldProcess($Message, $null, $null))
    {
        Write-Verbose $Message
    }
}

<#
    .SYNOPSIS
        Helper function to throw an error/exception

    .PARAMETER ExceptionName
        Specifies the name of the exception class to be instantiated.

    .PARAMETER ExceptionMessage
        Specifies the message that describes the error.

    .PARAMETER ExceptionObject
        Specifies the object that was being operated on when the error occurred.

    .PARAMETER ErrorId
        Specifies a developer-defined identifier of the error.
        This identifier must be a non-localized string for a specific error type.

    .PARAMETER ErrorCategory
        Specifies the category of the error.
#>
function Invoke-ThrowErrorHelper
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ExceptionName,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ExceptionMessage,

         [System.Object]
        $ExceptionObject,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ErrorId,

        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [System.Management.Automation.ErrorCategory]
        $ErrorCategory
    )

    $exception = New-Object $ExceptionName $ExceptionMessage;
    $errorRecord = New-Object System.Management.Automation.ErrorRecord $exception, $ErrorId,
        $ErrorCategory, $ExceptionObject
    throw $errorRecord
}

<#
    .SYNOPSIS
        Helper function to construct a strongly-typed object based on specified $Type

    .PARAMETER Type
        Specifies the type of the object to be constructed.

    .PARAMETER Data
        Specifies the data to be assigned to the constructed object.

    .PARAMETER Hex
        Specifies if the data is hexadecimal.

    .PARAMETER ReturnValue
        Returns a reference to the constructed object.
#>
function Get-TypedObject
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Type,

        [System.String[]]
        $Data,

        [ValidateNotNull()]
        [Boolean]
        $Hex,

        [ref]
        $ReturnValue
    )

    $ArgumentExceptionScriptBlock =
    {
        Param($ErrorId)

        $errorMessage = $localizedData.ParameterValueInvalid -f 'ValueData',
            (Convert-ArrayToString -Value $Data), $Type
        Write-Verbose $errorMessage
        $invokeThrowErrorHelperParams = @{
            ExceptionName = 'System.ArgumentException'
            ExceptionMessage = $errorMessage
            ExceptionObject = $Data
            ErrorId = $ErrorId
            ErrorCategory = 'InvalidArgument'
        }
        Invoke-ThrowErrorHelper @invokeThrowErrorHelperParams
    }

    <#
        The the $Type specified is not a multistring then we always expect a non-array $Data.
        If this is not the case, throw an error and let the user know.
    #>
    if (($Type -ine 'Multistring') -and ($null -ne $Data) -and ($Data.Count -gt 1))
    {
        $invokeCommandParams = @{
            ScriptBlock = $ArgumentExceptionScriptBlock
            ArgumentList = 'ArrayNotExpectedForType{0}' -f $Type
        }
        Invoke-Command @invokeCommandParams
    }

    Switch($Type)
    {
        # Case: String
        'String'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.String]::Empty

                return
            }

            $ReturnValue.Value = [System.String] $Data[0]
        }

        # Case: ExpandString
        'ExpandString'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.String]::Empty

                return
            }

            $ReturnValue.Value = [System.String] $Data[0]
        }

        # Case: MultiString
        'MultiString'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.String[]] @()

                return
            }

            $ReturnValue.Value = [System.String[]] $Data
        }

        # Case: DWord
        'DWord'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.Int32] 0
            }
            elseif ($Hex)
            {
                $retVal = $null
                $val = $Data[0].TrimStart('0x')

                $currentCultureInfo = [System.Globalization.CultureInfo]::CurrentCulture
                if ([System.Int32]::TryParse($val, 'HexNumber', $currentCultureInfo, [ref] $retVal))
                {
                    $ReturnValue.Value = $retVal
                }
                else
                {
                    $invokeCommandParams = @{
                        ScriptBlock = $ArgumentExceptionScriptBlock
                        ArgumentList = 'ValueDataNotInHexFormat'
                    }
                    Invoke-Command @invokeCommandParams
                }
            }
            else
            {
                $ReturnValue.Value = [System.Int32]::Parse($Data[0])
            }
        }

        # Case: QWord
        'QWord'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.Int64] 0
            }
            elseif ($Hex)
            {
                $retVal = $null
                $val = $Data[0].TrimStart('0x')

                $currentCultureInfo = [System.Globalization.CultureInfo]::CurrentCulture
                if ([System.Int64]::TryParse($val, 'HexNumber', $currentCultureInfo, [ref] $retVal))
                {
                    $ReturnValue.Value = $retVal
                }
                else
                {
                    $invokeCommandParams = @{
                        ScriptBlock = $ArgumentExceptionScriptBlock
                        ArgumentList = 'ValueDataNotInHexFormat'
                    }
                    Invoke-Command @invokeCommandParams
                }
            }
            else
            {
                $ReturnValue.Value = [System.Int64]::Parse($Data[0])
            }
        }

        # Case: Binary
        'Binary'
        {
            if (($null -eq $Data) -or ($Data.Length -eq 0))
            {
                $ReturnValue.Value = [System.Byte[]] @()

                return
            }

            $val = $Data[0].TrimStart('0x')
            if ($val.Length % 2 -ne 0)
            {
                $val = $val.PadLeft($val.Length+1, '0')
            }

            try
            {
                $byteArray = [System.Byte[]] @()

                for ($i = 0 ; $i -lt ($val.Length-1) ; $i = $i+2)
                {
                    $byteArray += [System.Byte]::Parse($val.Substring($i, 2), 'HexNumber')
                }

                $ReturnValue.Value = [System.Byte[]] $byteArray
            }
            catch [System.Exception]
            {
                $invokeCommandParams = @{
                    ScriptBlock = $ArgumentExceptionScriptBlock
                    ArgumentList = 'ValueDataNotInHexFormat'
                }
                Invoke-Command @invokeCommandParams
            }
        }
    }
}

<#
    .SYNOPSIS
        Helper function to convert an array to a string representation

    .PARAMETER Value
        Specifies the array to be converted.
#>
function Convert-ArrayToString
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [System.Object]
        $Value
    )

    if (!$Value.GetType().IsArray)
    {
        return $Value.ToString()
    }
    if ($Value.Length -eq 1)
    {
        return $Value[0].ToString()
    }

    [System.Text.StringBuilder] $retString = '('

    $Value | ForEach-Object {$retString = ($retString.ToString() + $_.ToString() + ', ')}

    $retString = $retString.ToString().TrimEnd(', ') + ')'

    return $retString.ToString()
}

<#
    .SYNOPSIS
        Helper function to convert a byte array to its hex string representation

    .PARAMETER Data
        Specifies the byte array to be converted.
#>
function Convert-ByteArrayToHexString
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [System.Object]
        $Data
    )

    $retString = ''
    $Data | ForEach-Object { $retString += ('{0:x2}' -f $_) }

    return $retString
}

<#
    .SYNOPSIS
        Helper function to retrieve the display name for the (Default) RegValue

    .PARAMETER ValueName
        Specifies the name of the value to be retrieved.
#>
function Get-ValueDisplayName
{
    param
    (
        [System.String]
        $ValueName
    )

    if ([System.String]::IsNullOrEmpty($ValueName))
    {
        return $localizedData.DefaultValueDisplayName
    }

    return $ValueName
}

<#
    .SYNOPSIS
        Helper function to mount the optional Registry hives as PSDrives

    .PARAMETER KeyName
        Specifies the Registry hive to be mounted.
#>
function Mount-RequiredRegistryHive
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $KeyName
    )

    $psDriveNames = (Get-PSDrive).Name.ToUpperInvariant()

    $newPSDriveParams = @{
        PSProvider = 'Registry'
        Scope = 'Script'
        WhatIf = $false
    }
    if ($KeyName.StartsWith('HKCR','OrdinalIgnoreCase') -and !$psDriveNames.Contains('HKCR'))
    {
        $null = New-PSDrive @newPSDriveParams -Name HKCR -Root HKEY_CLASSES_ROOT
    }
    elseif ($KeyName.StartsWith('HKUS','OrdinalIgnoreCase') -and !$psDriveNames.Contains('HKUS'))
    {
        $null = New-PSDrive @newPSDriveParams -Name HKUS -Root HKEY_USERS
    }
    elseif ($KeyName.StartsWith('HKCC','OrdinalIgnoreCase') -and !$psDriveNames.Contains('HKCC'))
    {
        $null = New-PSDrive @newPSDriveParams -Name HKCC -Root HKEY_CURRENT_CONFIG
    }
    elseif ($KeyName.StartsWith('HKCU','OrdinalIgnoreCase') -and !$psDriveNames.Contains('HKCU'))
    {
        $null = New-PSDrive @newPSDriveParams -Name HKCU -Root HKEY_CURRENT_USER
    }
    elseif ($KeyName.StartsWith('HKLM','OrdinalIgnoreCase') -and !$psDriveNames.Contains('HKLM'))
    {
        $null = New-PSDrive @newPSDriveParams -Name HKLM -Root HKEY_LOCAL_MACHINE
    }
}

<#
    .SYNOPSIS
        Helper function to mount the optional Registry hives as PSDrives

    .PARAMETER KeyName
        Returns the name of the PSDrive that has been mounted.
#>
function Invoke-RegistryProviderSetup
{
    param
    (
        [ValidateNotNull()]
        [ref]
        $KeyName
    )

    # Fix $KeyName if required
    if (!$KeyName.Value.ToString().Contains(':'))
    {
        if ($KeyName.Value.ToString().StartsWith('hkey_users','OrdinalIgnoreCase'))
        {
            $KeyName.Value =  $KeyName.Value.ToString() -replace 'hkey_users', 'HKUS:'
        }
        elseif ($KeyName.Value.ToString().StartsWith('hkey_current_config','OrdinalIgnoreCase'))
        {
            $KeyName.Value =  $KeyName.Value.ToString() -replace 'hkey_current_config', 'HKCC:'
        }
        elseif ($KeyName.Value.ToString().StartsWith('hkey_classes_root','OrdinalIgnoreCase'))
        {
            $KeyName.Value =  $KeyName.Value.ToString() -replace 'hkey_classes_root', 'HKCR:'
        }
        elseif ($KeyName.Value.ToString().StartsWith('hkey_local_machine','OrdinalIgnoreCase'))
        {
            $KeyName.Value =  $KeyName.Value.ToString() -replace 'hkey_local_machine', 'HKLM:'
        }
        elseif ($KeyName.Value.ToString().StartsWith('hkey_current_user','OrdinalIgnoreCase'))
        {
            $KeyName.Value =  $KeyName.Value.ToString() -replace 'hkey_current_user', 'HKCU:'
        }
        else
        {
            $errorMessage = $localizedData.InvalidRegistryHiveSpecified -f $Key

            $invokeThrowErrorHelperParams = @{
                ExceptionName = 'System.ArgumentException'
                ExceptionMessage = $errorMessage
                ExceptionObject = $KeyName
                ErrorId = 'InvalidRegistryHive'
                ErrorCategory = InvalidArgument
            }
            Invoke-ThrowErrorHelper @invokeThrowErrorHelperParams
        }
    }

    # Mount any required registry hives
    Mount-RequiredRegistryHive -KeyName $KeyName.Value.ToString()

    # Check the target PSDrive to be a valid Registry Hive root
    Assert-PSDriveValid -Key $KeyName.Value.ToString()
}

<#
    .SYNOPSIS
        Refactored helper function to test if the ValueData specified
        matches the ValueData retrieved

    .PARAMETER RetrievedValue
        Specifies the retrieved value data.

    .PARAMETER ValueTye
        Specifies the type of the value data.

    .PARAMETER ValueData
        Specifies the value data.

#>
function Compare-ValueData
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNull()]
        [System.Object]
        $RetrievedValue,

        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.String]
        $ValueType,

        [System.String[]]
        $ValueData
    )

    # Convert the specified $ValueData into strongly-typed data for correct comparsion
    $specifiedData = $null
    $retrievedData = $RetrievedValue.Data

    Get-TypedObject -Type $ValueType -Data $ValueData -Hex $Hex -ReturnValue ([ref] $specifiedData)

    # Special case for binary comparison (do hex-string comparison)
    if ($ValueType -ieq 'Binary')
    {
        $specifiedData = $ValueData[0].PadLeft($retrievedData.Length, '0')
    }

    # If the ValueType is not multistring, do a simple comparison
    if ($ValueType -ine 'Multistring')
    {
        return ($specifiedData -ieq $retrievedData)
    }

    <#
        IF THE CONTROL REACHES HERE, THE ValueType IS A "MultiString" and we need a size-based and
        element-by-element comparsion for it
    #>

    #  Array-size comparison
    if ($specifiedData.Length -ne $retrievedData.Length)
    {
        # Size mismatch
        return $false
    }

    # Element-by-Element comparison
    for ($i = 0 ; $i -lt $specifiedData.Length ; $i++)
    {
        if ($specifiedData[$i] -ine $retrievedData[$i])
        {
            return $false
        }
    }

    # IF THE CONTROL REACHED HERE, THE Multistring COMPARISON WAS SUCCESSFUL
    return $true
}

Export-ModuleMember -Function *-TargetResource