functions/configuration/Export-DbatoolsConfig.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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
function Export-DbatoolsConfig
{
<#
    .SYNOPSIS
        Exports configuration items to a Json file.
     
    .DESCRIPTION
        Exports configuration items to a Json file.
     
    .PARAMETER FullName
        Select the configuration objects to export by filtering by their full name.
     
    .PARAMETER Module
        Select the configuration objects to export by filtering by their module name.
     
    .PARAMETER Name
        Select the configuration objects to export by filtering by their name.
     
    .PARAMETER Config
        The configuration object(s) to export.
        Returned by Get-DbatoolsConfig.
     
    .PARAMETER ModuleName
        Exports all configuration pertinent to a module to a predefined path.
        Exported configuration items include all settings marked as 'ModuleExport' that have been changed from the default value.
     
    .PARAMETER ModuleVersion
        The configuration version of the module-settings to write.
     
    .PARAMETER Scope
        Which predefined path to write module specific settings to.
        Only file scopes are considered.
        By default it writes to the suer profile.
     
    .PARAMETER OutPath
        The path (filename included) to export to.
        Will fail if the folder does not exist, will overwrite the file if it exists.
     
    .PARAMETER SkipUnchanged
        If set, configuration objects whose value was not changed from its original value will not be exported.
        (Note: Settings that were updated with the same value as the original default will still be considered changed)
     
    .PARAMETER EnableException
        This parameters disables user-friendly warnings and enables the throwing of exceptions.
        This is less user friendly, but allows catching exceptions in calling scripts.
     
    .EXAMPLE
        PS C:\> Get-DbatoolsConfig | Export-DbatoolsConfig -OutPath '~/export.json'
         
        Exports all current settings to json.
     
    .EXAMPLE
        Export-DbatoolsConfig -Module message -OutPath '~/export.json' -SkipUnchanged
         
        Exports all settings of the module 'message' that are no longer the original default values to json.
#>

    [CmdletBinding(DefaultParameterSetName = 'FullName')]
    Param (
        [Parameter(ParameterSetName = "FullName", Position = 0, Mandatory = $true)]
        [string]
        $FullName,
        
        [Parameter(ParameterSetName = "Module", Position = 0, Mandatory = $true)]
        [string]
        $Module,
        
        [Parameter(ParameterSetName = "Module", Position = 1)]
        [string]
        $Name = "*",
        
        [Parameter(ParameterSetName = "Config", Position = 0, Mandatory = $true, ValueFromPipeline = $true)]
        [Sqlcollaborative.Dbatools.Configuration.Config[]]
        $Config,
        
        [Parameter(ParameterSetName = "ModuleName", Mandatory = $true)]
        [string]
        $ModuleName,
        
        [Parameter(ParameterSetName = "ModuleName")]
        [int]
        $ModuleVersion = 1,
        
        [Parameter(ParameterSetName = "ModuleName")]
        [Sqlcollaborative.Dbatools.Configuration.ConfigScope]
        $Scope = "FileUserShared",
        
        [Parameter(Position = 1, Mandatory = $true, ParameterSetName = 'Config')]
        [Parameter(Position = 1, Mandatory = $true, ParameterSetName = 'FullName')]
        [Parameter(Position = 2, Mandatory = $true, ParameterSetName = 'Module')]
        [string]
        $OutPath,
        
        [switch]
        $SkipUnchanged,
        
        [switch]
        $EnableException
    )
    
    begin
    {
        Write-Message -Level InternalComment -Message "Bound parameters: $($PSBoundParameters.Keys -join ", ")" -Tag 'debug', 'start', 'param'
        
        $items = @()
        
        if (($Scope -band 15) -and ($ModuleName))
        {
            Stop-Function -Message "Cannot export modulecache to registry! Please pick a file scope for your export destination" -EnableException $EnableException -Category InvalidArgument -Tag 'fail', 'scope', 'registry'
            return
        }
    }
    process
    {
        if (Test-FunctionInterrupt) { return }
        
        if (-not $ModuleName)
        {
            foreach ($item in $Config) { $items += $item }
            if ($FullName) { $items = Get-DbatoolsConfig -FullName $FullName }
            if ($Module) { $items = Get-DbatoolsConfig -Module $Module -Name $Name }
        }
    }
    end
    {
        if (Test-FunctionInterrupt) { return }
        
        if (-not $ModuleName)
        {
            try { Write-DbatoolsConfigFile -Config ($items | Where-Object { -not $SkipUnchanged -or -not $_.Unchanged } ) -Path $OutPath -Replace }
            catch
            {
                Stop-Function -Message "Failed to export to file" -EnableException $EnableException -ErrorRecord $_ -Tag 'fail', 'export'
                return
            }
        }
        else
        {
            if ($Scope -band 16)
            {
                Write-DbatoolsConfigFile -Config (Get-DbatoolsConfig -Module $ModuleName -Force | Where-Object ModuleExport | Where-Object Unchanged -NE $true) -Path (Join-Path $script:path_FileUserLocal "$($ModuleName.ToLower())-$($ModuleVersion).json")
            }
            if ($Scope -band 32)
            {
                Write-DbatoolsConfigFile -Config (Get-DbatoolsConfig -Module $ModuleName -Force | Where-Object ModuleExport | Where-Object Unchanged -NE $true)  -Path (Join-Path $script:path_FileUserShared "$($ModuleName.ToLower())-$($ModuleVersion).json")
            }
            if ($Scope -band 64)
            {
                Write-DbatoolsConfigFile -Config (Get-DbatoolsConfig -Module $ModuleName -Force | Where-Object ModuleExport | Where-Object Unchanged -NE $true)  -Path (Join-Path $script:path_FileSystem "$($ModuleName.ToLower())-$($ModuleVersion).json")
            }
        }
    }
}