functions/configuration/Remove-PSFConfig.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
function Remove-PSFConfig
{
<#
    .SYNOPSIS
        Removes configuration items from memory.
     
    .DESCRIPTION
        This command removes configuration items from memory.
        However, not all settings can just be deleted!
        A configuration item must be flagged as deletable.
        This can be done using Set-PSFConfig -AllowDelete or Import-PSFConfig -AllowDelete.
        Certain schema versions of configuration json may also support defining this in the file.
     
        Limitations to flagging configuration as deletable:
        > Once a configuration item has been initialized, its deletable status is frozen.
          The last time it is possible to change the deletable status is during initialization.
        > A setting that has been set as mandated by policy cannot be removed.
     
        Reason for this limit:
        The configuration system is designed for multiple scenarios.
        Deleting settings makes sense in some, while in others it is actually detrimental.
        Initialization is especially designed for the module scenario, where the module's configuration is its options menu.
        In this scenario, having a user deleting settings could lead to broken execution and unintended code paths, that might be at odds with policies defined.
     
    .PARAMETER Config
        The configuration object to remove from memory.
        Can be retrieved using Get-PSFConfig.
     
    .PARAMETER FullName
        The full name of the setting to be removed from memory.
     
    .PARAMETER Module
        The name of the module, whose settings should be removed from memory.
     
    .PARAMETER Name
        Default: "*"
        Used in conjunction with the -Module parameter to restrict the number of configuration items deleted from memory.
     
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
     
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
     
    .EXAMPLE
        PS C:\> Remove-PSFConfig -FullName 'Phase1.Step1.Server' -Confirm:$false
     
        Deletes the setting 'Phase1.Step1.Server' from memory, assuming it exists and supports deletion.
#>

    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param (
        [Parameter(ParameterSetName = "Default", Position = 0, ValueFromPipeline = $true)]
        [PSFramework.Configuration.Config[]]
        $Config,
        
        [Parameter(ParameterSetName = "Default", Position = 0, ValueFromPipeline = $true)]
        [string[]]
        $FullName,
        
        [Parameter(Mandatory = $true, ParameterSetName = "Name", Position = 0)]
        [string]
        $Module,
        
        [Parameter(ParameterSetName = "Name", Position = 1)]
        [string]
        $Name = "*"
    )
    
    process
    {
        switch ($PSCmdlet.ParameterSetName)
        {
            "Default"
            {
                #region Try removing all items specified
                foreach ($item in $Config)
                {
                    if (-not (Test-PSFShouldProcess -ActionString 'PSFramework.Configuration.Remove-PSFConfig.ShouldRemove' -Target $item.FullName)) { continue }
                    try { $result = [PSFramework.Configuration.ConfigurationHost]::DeleteConfiguration($item.FullName) }
                    catch { Stop-PSFFunction -String Configuration.Remove-PSFConfig.InvalidConfiguration -StringValues $item.FullName -EnableException ($ErrorActionPreference -eq 'Stop') -Continue -Cmdlet $PSCmdlet -ErrorRecord $_ }
                    
                    if ($result) { Write-PSFMessage -Level InternalComment -String Configuration.Remove-PSFConfig.DeleteSuccessful -StringValues $item.FullName }
                    else { Write-PSFMessage -Level Warning -String Configuration.Remove-PSFConfig.DeleteFailed -StringValues $item.FullName, $item.AllowDelete, $item.PolicyEnforced }
                }
                # Since configuration items will also bind to string, if any were included, break the switch
                if (Test-PSFParameterBinding -ParameterName Config) { break }
                #endregion Try removing all items specified
                
                #region Try removing all full names specified
                foreach ($nameItem in $FullName)
                {
                    if (-not (Test-PSFShouldProcess -ActionString 'PSFramework.Configuration.Remove-PSFConfig.ShouldRemove' -Target $nameItem)) { continue }
                    $item = Get-PSFConfig -FullName $nameItem
                    
                    try { $result = [PSFramework.Configuration.ConfigurationHost]::DeleteConfiguration($nameItem) }
                    catch { Stop-PSFFunction -String Configuration.Remove-PSFConfig.InvalidConfiguration -StringValues $nameItem -EnableException ($ErrorActionPreference -eq 'Stop') -Continue -Cmdlet $PSCmdlet -ErrorRecord $_ }
                    
                    
                    if ($result) { Write-PSFMessage -Level InternalComment -String Configuration.Remove-PSFConfig.DeleteSuccessful -StringValues $item.FullName }
                    else { Write-PSFMessage -Level Warning -String Configuration.Remove-PSFConfig.DeleteFailed -StringValues $item.FullName, $item.AllowDelete, $item.PolicyEnforced }
                }
                #endregion Try removing all full names specified
            }
            "Name"
            {
                #region Try removing by filter
                foreach ($item in (Get-PSFConfig -Module $Module -Name $Name))
                {
                    if (-not (Test-PSFShouldProcess -ActionString 'PSFramework.Configuration.Remove-PSFConfig.ShouldRemove' -Target $item.FullName)) { continue }
                    
                    try { $result = [PSFramework.Configuration.ConfigurationHost]::DeleteConfiguration($item.FullName) }
                    catch { Stop-PSFFunction -String Configuration.Remove-PSFConfig.InvalidConfiguration -StringValues $item.FullName -EnableException ($ErrorActionPreference -eq 'Stop') -Continue -Cmdlet $PSCmdlet -ErrorRecord $_ }
                    
                    if ($result) { Write-PSFMessage -Level InternalComment -String Configuration.Remove-PSFConfig.DeleteSuccessful -StringValues $item.FullName }
                    else { Write-PSFMessage -Level Warning -String Configuration.Remove-PSFConfig.DeleteFailed -StringValues $item.FullName, $item.AllowDelete, $item.PolicyEnforced }
                }
                #endregion Try removing by filter
            }
        }
    }
}