Merge pull request #2 from webmd-health-services/feature/mirate-from-…

…carbon

Migrating from Carbon

CHANGELOG.md

@@ -0,0 +1,40 @@
+
+# Carbon.Registry Changelog
+
+## 1.0.0
+
+> Released 16 Aug 2023
+
+Migrated Carbon registry functions.
+
+### Upgrade Instructions
+
+All functions now require using the `C` prefix.
+
+* Replace usages of `Get-RegistryKeyValue` with `Get-CRegistryKeyValue`.
+* Replace usages of `Remove-RegistryKeyValue` with `Remove-CRegistryKeyValue`.
+* Replace usages of `Set-RegistryKeyValue` with `Set-CRegistryKeyValue`.
+* Replace usages of `Test-RegistryKeyValue` with `Test-CRegistryKeyValue`.
+* Replace usages of `Install-RegistryKey` with `Install-CRegistryKey`.
+
+Remove usages of the `Quiet` switch from usages of `Set-CRegistryKeyValue`. That switch was removed.
+
+### Changed
+
+* Replaced verbose-level messages with information-level messages in `Install-CRegistryKey`, `Remove-CRegistryKeyValue`,
+and `Set-CRegistryKeyValue` when saving changes.
+* `Set-CRegistryKeyValue` accepts `$null` as the value of a multi-line string, which sets the value to an empty list.
+
+### Fixed
+
+* `Set-CRegistryKeyValue` fails to set multiline string values to an empty list.
+* `Set-CRegistryKeyValue` sets the value of a multiline string even if the value hasn't changed.
+
+### Removed
+
+* `Get-RegistryKeyValue` (use `Get-CRegistryKeyValue` instead).
+* `Remove-RegistryKeyValue` (use `Remove-CRegistryKeyValue` instead).
+* `Set-RegistryKeyValue` (use `Set-CRegistryKeyValue` instead).
+* `Test-RegistryKeyValue` (use `Test-CRegistryKeyValue` instead).
+* `Install-RegistryKey` (use `Install-CRegistryKey` instead).
+* Parameter `Quiet` from `Set-CRegistryKeyValue`.

Carbon.Registry/Carbon.Registry.psd1

@@ -18,7 +18,7 @@
     RootModule = 'Carbon.Registry.psm1'
 
     # Version number of this module.
-    ModuleVersion = '0.0.0'
+    ModuleVersion = '1.0.0'
 
     # ID used to uniquely identify this module
     GUID = '9772fb52-add8-47bf-83dc-0294ca8d9c64'
@@ -36,7 +36,7 @@
     Copyright = '(c) WebMD Health Services.'
 
     # Description of the functionality provided by this module
-    Description = ''
+    Description = 'Functions for working with the Windows registry to get, remove, set, and test registry key values and install registry keys.'
 
     # Minimum version of the Windows PowerShell engine required by this module
     PowerShellVersion = '5.1'
@@ -76,6 +76,11 @@
 
     # Functions to export from this module. Only list public function here.
     FunctionsToExport = @(
+        'Get-CRegistryKeyValue',
+        'Install-CRegistryKey',
+        'Remove-CRegistryKeyValue',
+        'Set-CRegistryKeyValue',
+        'Test-CRegistryKeyValue'
     )
 
     # Cmdlets to export from this module. By default, you get a script module, so there are no cmdlets.
@@ -102,7 +107,36 @@
         PSData = @{
 
             # Tags applied to this module. These help with module discovery in online galleries.
-            Tags = @( 'Desktop', 'Core' )
+            Tags = @(
+                'Desktop',
+                'Core',
+                'dword',
+                'hive',
+                'HKCU',
+                'HKEY_CLASSES_ROOT',
+                'HKEY_CURRENT_CONFIG',
+                'HKEY_CURRENT_USER',
+                'HKEY_LOCAL_MACHINE',
+                'HKEY_USERS',
+                'HKLM',
+                'key',
+                'multistring'
+                'new-itemproperty',
+                'qword',
+                'REG_BINARY',
+                'REG_DWORD',
+                'REG_EXPAND_SZ',
+                'REG_MULTI_SZ',
+                'REG_QWORD',
+                'REG_SZ',
+                'reg',
+                'regedit',
+                'registry',
+                'remove-itemproperty',
+                'set-itemproperty',
+                'udword',
+                'uqword'
+            )
 
             # A URL to the license for this module.
             LicenseUri = 'http://www.apache.org/licenses/LICENSE-2.0'

Carbon.Registry/Functions/Get-CRegistryKeyValue.ps1

@@ -0,0 +1,42 @@
+
+function Get-CRegistryKeyValue
+{
+    <#
+    .SYNOPSIS
+    Gets the value from a registry key.
+
+    .DESCRIPTION
+    PowerShell's `Get-ItemProperty` cmdlet is a pain to use.  It doesn't actually return an object representing a
+    registry key's value, but some other weird object that requires painful gyrations to get values from. This function
+    returns just the value of a key.
+
+    .EXAMPLE
+    Get-CRegistryKeyValue -Path 'hklm:\Software\Carbon\Test' -Name 'Title'
+
+    Returns the value of the 'hklm:\Software\Carbon\Test' key's `Title` value.
+    #>
+    [CmdletBinding()]
+    param(
+        # The path to the registry key where the value should be set.  Will be created if it doesn't exist.
+        [Parameter(Mandatory)]
+        [String] $Path,
+
+        # The name of the value being set.
+        [Parameter(Mandatory)]
+        [String] $Name
+    )
+
+    Set-StrictMode -Version 'Latest'
+    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState
+
+    if (-not (Test-CRegistryKeyValue -Path $Path -Name $Name))
+    {
+        return $null
+    }
+
+    $itemProperties = Get-ItemProperty -Path $Path -Name *
+    $value = $itemProperties.$Name
+    Write-Debug -Message ('[{0}@{1}: {2} -is {3}' -f $Path,$Name,$value,$value.GetType())
+    return $value
+}
+

Carbon.Registry/Functions/Install-CRegistryKey.ps1

@@ -0,0 +1,31 @@
+
+function Install-CRegistryKey
+{
+    <#
+    .SYNOPSIS
+    Creates a registry key.  If it already exists, does nothing.
+
+    .DESCRIPTION
+    Given the path to a registry key, creates the key and all its parents.  If the key already exists, nothing happens.
+
+    .EXAMPLE
+    Install-CRegistryKey -Path 'hklm:\Software\Carbon\Test'
+
+    Creates the `hklm:\Software\Carbon\Temp` registry key if it doesn't already exist.
+    #>
+    [CmdletBinding(SupportsShouldPRocess)]
+    param(
+        # The path to the registry key to create.
+        [Parameter(Mandatory)]
+        [String] $Path
+    )
+
+    Set-StrictMode -Version 'Latest'
+    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState
+
+    if (-not (Test-Path -Path $Path -PathType Container))
+    {
+        Write-Information " + ${Path}"
+        New-Item -Path $Path -ItemType RegistryKey -Force | Out-String | Write-Verbose
+    }
+}

Carbon.Registry/Functions/Remove-CRegistryKeyValue.ps1

@@ -0,0 +1,42 @@
+
+function Remove-CRegistryKeyValue
+{
+    <#
+    .SYNOPSIS
+    Removes a value from a registry key, if it exists.
+
+    .DESCRIPTION
+    If the given key doesn't exist, nothing happens.
+
+    .EXAMPLE
+    Remove-CRegistryKeyValue -Path hklm:\Software\Carbon\Test -Name 'InstallPath'
+
+    Removes the `InstallPath` value from the `hklm:\Software\Carbon\Test` registry key.
+    #>
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        # The path to the registry key where the value should be removed.
+        [Parameter(Mandatory)]
+        [String] $Path,
+
+        # The name of the value to remove.
+        [Parameter(Mandatory)]
+        [String] $Name
+    )
+
+    Set-StrictMode -Version 'Latest'
+    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState
+
+    if (-not (Test-CRegistryKeyValue -Path $Path -Name $Name))
+    {
+        return
+    }
+
+    if (-not $PSCmdlet.ShouldProcess(("Item: ${Path} Property: ${Name}"), 'Remove Property'))
+    {
+        return
+    }
+
+    Write-Information "   ${Path}  - ${Name}"
+    Remove-ItemProperty -Path $Path -Name $Name
+}