Merge pull request #3 from webmd-health-services/feature/uninstall-cr…

…egistrykey

Adding function Uninstall-CRegistryKey.

CHANGELOG.md

@@ -1,6 +1,13 @@
 
 # Carbon.Registry Changelog
 
+## 1.1.0
+
+> Released 26 Jan 2024
+
+Added `Uninstall-CRegistryKey` function for deleting a registry key without errors if it doesn't exist.
+
+
 ## 1.0.0
 
 > Released 16 Aug 2023

Carbon.Registry/Carbon.Registry.psd1

@@ -18,7 +18,7 @@
     RootModule = 'Carbon.Registry.psm1'
 
     # Version number of this module.
-    ModuleVersion = '1.0.0'
+    ModuleVersion = '1.1.0'
 
     # ID used to uniquely identify this module
     GUID = '9772fb52-add8-47bf-83dc-0294ca8d9c64'
@@ -80,7 +80,8 @@
         'Install-CRegistryKey',
         'Remove-CRegistryKeyValue',
         'Set-CRegistryKeyValue',
-        'Test-CRegistryKeyValue'
+        'Test-CRegistryKeyValue',
+        'Uninstall-CRegistryKey'
     )
 
     # Cmdlets to export from this module. By default, you get a script module, so there are no cmdlets.

Carbon.Registry/Functions/Uninstall-CRegistryKey.ps1

@@ -0,0 +1,51 @@
+
+function Uninstall-CRegistryKey
+{
+    <#
+    .SYNOPSIS
+    Deletes a registry key.
+
+    .DESCRIPTION
+    The `Uninstall-CRegistryKey` function deletes a registry key. If the key doesn't exist, nothing happens and no
+    errors are written. Pass the path to the registry key to the `Path` parameter. To delete the key and all subkeys,
+    use the `Recurse` switch.
+
+    .EXAMPLE
+    Uninstall-CRegistryKey -Path 'hklm:\Software\Carbon\Test'
+
+    Demonstrates how to delete a registry key. In this example, the 'hklm:\Software\Carbon\Test' key is deleted if it
+    exists.
+
+    .EXAMPLE
+    Uninstall-CRegistryKey -Path 'hklm:\Software\Carbon\Test' -Recurse
+
+    Demonstrates how to delete a registry key and all its subkeys. In this example, the 'hklm:\Software\Carbon\Test' key
+    is deleted if it exists, along with its subkeys.
+    #>
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        # The path to the registry key to delete.
+        [Parameter(Mandatory)]
+        [String] $Path,
+
+        # Use to delete the key and all its subkeys. This switch is required if the key has any subkeys.
+        [switch] $Recurse
+    )
+
+    Set-StrictMode -Version 'Latest'
+    Use-CallerPreference -Cmdlet $PSCmdlet -Session $ExecutionContext.SessionState
+
+    if (-not (Test-Path -Path $Path))
+    {
+        return
+    }
+
+    $confirmArg = @{}
+    if ($PSBoundParameters.ContainsKey('Confirm'))
+    {
+        $confirmArg['Confirm'] = $PSBoundParameters['Confirm']
+    }
+
+    Write-Information " - ${Path}"
+    Remove-Item -Path $Path -Recurse:$Recurse -Force @confirmArg
+}

Tests/Uninstall-CRegistryKey.Tests.ps1

@@ -0,0 +1,100 @@
+
+#Requires -Version 5.1
+Set-StrictMode -Version 'Latest'
+
+BeforeAll {
+    Set-StrictMode -Version 'Latest'
+
+    & (Join-Path -Path $PSScriptRoot -ChildPath 'Initialize-Test.ps1' -Resolve)
+
+    $script:rootKey = 'hkcu:\Uninstall-CRegistryKey'
+
+    function GivenKey
+    {
+        param(
+            [String] $Named
+        )
+
+        Install-CRegistryKey -Path (Join-Path -Path $script:rootKey -ChildPath $Named)
+    }
+
+    function ThenKey
+    {
+        param(
+            [String] $Named,
+
+            [switch] $Not,
+
+            [switch] $Exists
+        )
+
+        Join-Path -Path $script:rootKey -ChildPath $Named | Should -Not:$Not -Exist
+    }
+
+    function ThenNoError
+    {
+        param(
+        )
+
+        $Global:Error | Should -BeNullOrEmpty
+    }
+
+    function WhenUninstalling
+    {
+        param(
+            [String] $Named,
+
+            [switch] $Recursively,
+
+            [switch] $WithWhatIf
+        )
+
+        $optionalArgs = @{}
+        if ($Recursively)
+        {
+            $optionalArgs['Recurse'] = $true
+        }
+
+        if ($WithWhatIf)
+        {
+            $optionalArgs['WhatIf'] = $true
+        }
+
+        Uninstall-CRegistryKey -Path (Join-Path -Path $script:rootKey -ChildPath $Named) @optionalArgs
+    }
+}
+
+Describe 'Install-CRegistryKey' {
+    BeforeEach {
+        $Global:Error.Clear()
+    }
+
+    It 'deletes key' {
+        GivenKey 'test1'
+        WhenUninstalling 'test1'
+        ThenNoError
+        ThenKey 'test1' -Not -Exists
+    }
+
+    It 'deletes recursively' {
+        GivenKey 'test3/subkey/subkey/subkey'
+        WhenUninstalling 'test3' -Recursively
+        ThenNoError
+        ThenKey 'test3/subkey/subkey/subkey' -Not -Exists
+        ThenKey 'test3/subkey/subkey' -Not -Exists
+        ThenKey 'test3/subkey' -Not -Exists
+        ThenKey 'test3' -Not -Exists
+    }
+
+    It 'supports WhatIf' {
+        GivenKey 'test4'
+        WhenUninstalling 'test4' -WithWhatIf
+        ThenNoError
+        ThenKey 'test4' -Exists
+    }
+
+    It 'writes no errors for non-existent key' {
+        WhenUninstalling 'IDoNotExist'
+        ThenNoError
+    }
+}