Public/New-specRegistryObject.ps1
|
function New-specRegistryObject { <# .SYNOPSIS The New-specRegistryObject function creates a new Registry object for interacting with the Windows Registry. .DESCRIPTION This function initialises a Registry object with the provided registry hive, key path, value name, value data, and value type. The Registry object can be used to perform various registry operations such as retrieving, adding, modifying, and deleting registry keys and values. .PARAMETER Hive The root registry hive (e.g., 'HKCU:', 'HKLM:'). This parameter accepts one of the following valid registry hives: - 'HKCU:' (HKEY_CURRENT_USER) - 'HKLM:' (HKEY_LOCAL_MACHINE) The value must end with a colon (e.g., 'HKCU:'). .PARAMETER KeyPath The relative path to the registry key within the specified hive (e.g., 'Software\MyApp'). .PARAMETER ValueName The name of the registry value to interact with (e.g., 'AppVersion'). .PARAMETER ValueData The data associated with the registry value. This parameter is optional and only used when adding or modifying a registry value. .PARAMETER ValueType The type of the registry value. This can be one of the following: - 'String' (REG_SZ) - 'ExpandString' (REG_EXPAND_SZ) - 'Binary' (REG_BINARY) - 'DWord' (REG_DWORD) - 'MultiString' (REG_MULTI_SZ) - 'QWord' (REG_QWORD) The default value is 'String'. .OUTPUTS Returns a Registry object that can be used for further registry operations, such as retrieving, adding, or modifying registry values. .EXAMPLE # Example 1: Create a Registry object for retrieving a registry value $reg = New-specRegistryObject -Hive "HKCU:" -KeyPath "Software\MyApp" -ValueName "AppVersion" Write-Output $reg This example creates a new Registry object to interact with the registry path "HKCU:\Software\MyApp" and the value "AppVersion". .EXAMPLE # Example 2: Create a Registry object to add a new registry value $reg = New-specRegistryObject -Hive "HKCU:" -KeyPath "Software\MyApp" -ValueName "AppVersion" -ValueData "1.0" -ValueType "String" Write-Output $reg This example creates a new Registry object and initialises it with the value "AppVersion" of type 'String' and data "1.0" at the specified registry path. .EXAMPLE # Example 3: Create a Registry object with a QWord type value $reg = New-specRegistryObject -Hive "HKLM:" -KeyPath "Software\MyApp" -ValueName "MaxLimit" -ValueData "5000" -ValueType "QWord" Write-Output $reg This example creates a new `Registry` object and initialises it with a value "MaxLimit" of type 'QWord' and data "5000" at the specified registry path. .EXAMPLE # Example 4: Attempting to use an invalid Hive value # This will throw an error since 'INVALID_HIVE:' is not a valid registry hive. $reg = New-specRegistryObject -Hive "INVALID_HIVE:" -KeyPath "Software\MyApp" -ValueName "AppVersion" -ValueData "1.0" -ValueType "String" This example will throw an error because the Hive parameter is set to an invalid value. .NOTES - This function does not directly interact with the registry. It only creates an instance of the `Registry` class with the specified parameters. - Use the methods available in the Registry class to perform actual registry operations. Author: owen.heaume Version: 1.0 #> param ( [Parameter(Mandatory = $true)] [ValidateSet('HKCU:', 'HKLM:')] [string]$Hive, [Parameter(Mandatory = $true)] [string]$KeyPath, [Parameter(Mandatory = $true)] [string]$ValueName, [string]$ValueData = $null, [ValidateSet('String', 'ExpandString', 'Binary', 'DWord', 'MultiString', 'QWord')] [string]$ValueType = 'String' ) # Convert string value type to RegistryType enum $RegistryType = [RegistryType]::$ValueType # Instantiate and return the Registry object return [specRegistry]::new($Hive, $KeyPath, $ValueName, $ValueData, $RegistryType) } |