|
| 1 | +<# |
| 2 | + .SYNOPSIS |
| 3 | + A class with methods that are equal for all class-based resources. |
| 4 | +
|
| 5 | + .DESCRIPTION |
| 6 | + A class with methods that are equal for all class-based resources. |
| 7 | +
|
| 8 | + .NOTES |
| 9 | + This class should be able to be inherited by all DSC resources. This class |
| 10 | + shall not contain any DSC properties, neither shall it contain anything |
| 11 | + specific to only a single resource. |
| 12 | +#> |
| 13 | + |
| 14 | +class ResourceBase |
| 15 | +{ |
| 16 | + # Property for holding localization strings |
| 17 | + hidden [System.Collections.Hashtable] $localizedData = @{} |
| 18 | + |
| 19 | + # Property for derived class to set properties that should not be enforced. |
| 20 | + hidden [System.String[]] $ExcludeDscProperties = @() |
| 21 | + |
| 22 | + # Default constructor |
| 23 | + ResourceBase() |
| 24 | + { |
| 25 | + <# |
| 26 | + TODO: When this fails, for example when the localized string file is missing |
| 27 | + the LCM returns the error 'Failed to create an object of PowerShell |
| 28 | + class SqlDatabasePermission' instead of the actual error that occurred. |
| 29 | + #> |
| 30 | + $this.localizedData = Get-LocalizedDataRecursive -ClassName ($this | Get-ClassName -Recurse) |
| 31 | + } |
| 32 | + |
| 33 | + [ResourceBase] Get() |
| 34 | + { |
| 35 | + $this.Assert() |
| 36 | + |
| 37 | + # Get all key properties. |
| 38 | + $keyProperty = $this | Get-DscProperty -Type 'Key' |
| 39 | + |
| 40 | + Write-Verbose -Message ($this.localizedData.GetCurrentState -f $this.GetType().Name, ($keyProperty | ConvertTo-Json -Compress)) |
| 41 | + |
| 42 | + $getCurrentStateResult = $this.GetCurrentState($keyProperty) |
| 43 | + |
| 44 | + $dscResourceObject = [System.Activator]::CreateInstance($this.GetType()) |
| 45 | + |
| 46 | + # Set values returned from the derived class' GetCurrentState(). |
| 47 | + foreach ($propertyName in $this.PSObject.Properties.Name) |
| 48 | + { |
| 49 | + if ($propertyName -in @($getCurrentStateResult.Keys)) |
| 50 | + { |
| 51 | + $dscResourceObject.$propertyName = $getCurrentStateResult.$propertyName |
| 52 | + } |
| 53 | + } |
| 54 | + |
| 55 | + $keyPropertyAddedToCurrentState = $false |
| 56 | + |
| 57 | + # Set key property values unless it was returned from the derived class' GetCurrentState(). |
| 58 | + foreach ($propertyName in $keyProperty.Keys) |
| 59 | + { |
| 60 | + if ($propertyName -notin @($getCurrentStateResult.Keys)) |
| 61 | + { |
| 62 | + # Add the key value to the instance to be returned. |
| 63 | + $dscResourceObject.$propertyName = $this.$propertyName |
| 64 | + |
| 65 | + $keyPropertyAddedToCurrentState = $true |
| 66 | + } |
| 67 | + } |
| 68 | + |
| 69 | + if (($this | Test-ResourceHasDscProperty -Name 'Ensure') -and -not $getCurrentStateResult.ContainsKey('Ensure')) |
| 70 | + { |
| 71 | + # Evaluate if we should set Ensure property. |
| 72 | + if ($keyPropertyAddedToCurrentState) |
| 73 | + { |
| 74 | + <# |
| 75 | + A key property was added to the current state, assume its because |
| 76 | + the object did not exist in the current state. Set Ensure to Absent. |
| 77 | + #> |
| 78 | + $dscResourceObject.Ensure = [Ensure]::Absent |
| 79 | + $getCurrentStateResult.Ensure = [Ensure]::Absent |
| 80 | + } |
| 81 | + else |
| 82 | + { |
| 83 | + $dscResourceObject.Ensure = [Ensure]::Present |
| 84 | + $getCurrentStateResult.Ensure = [Ensure]::Present |
| 85 | + } |
| 86 | + } |
| 87 | + |
| 88 | + <# |
| 89 | + Returns all enforced properties not in desires state, or $null if |
| 90 | + all enforced properties are in desired state. |
| 91 | + #> |
| 92 | + $propertiesNotInDesiredState = $this.Compare($getCurrentStateResult, @()) |
| 93 | + |
| 94 | + <# |
| 95 | + Return the correct values for Reasons property if the derived DSC resource |
| 96 | + has such property and it hasn't been already set by GetCurrentState(). |
| 97 | + #> |
| 98 | + if (($this | Test-ResourceHasDscProperty -Name 'Reasons') -and -not $getCurrentStateResult.ContainsKey('Reasons')) |
| 99 | + { |
| 100 | + # Always return an empty array if all properties are in desired state. |
| 101 | + $dscResourceObject.Reasons = $propertiesNotInDesiredState | |
| 102 | + ConvertTo-Reason -ResourceName $this.GetType().Name |
| 103 | + } |
| 104 | + |
| 105 | + # Return properties. |
| 106 | + return $dscResourceObject |
| 107 | + } |
| 108 | + |
| 109 | + [void] Set() |
| 110 | + { |
| 111 | + # Get all key properties. |
| 112 | + $keyProperty = $this | Get-DscProperty -Type 'Key' |
| 113 | + |
| 114 | + Write-Verbose -Message ($this.localizedData.SetDesiredState -f $this.GetType().Name, ($keyProperty | ConvertTo-Json -Compress)) |
| 115 | + |
| 116 | + $this.Assert() |
| 117 | + |
| 118 | + <# |
| 119 | + Returns all enforced properties not in desires state, or $null if |
| 120 | + all enforced properties are in desired state. |
| 121 | + #> |
| 122 | + $propertiesNotInDesiredState = $this.Compare() |
| 123 | + |
| 124 | + if ($propertiesNotInDesiredState) |
| 125 | + { |
| 126 | + $propertiesToModify = $propertiesNotInDesiredState | ConvertFrom-CompareResult |
| 127 | + |
| 128 | + $propertiesToModify.Keys | |
| 129 | + ForEach-Object -Process { |
| 130 | + Write-Verbose -Message ($this.localizedData.SetProperty -f $_, $propertiesToModify.$_) |
| 131 | + } |
| 132 | + |
| 133 | + <# |
| 134 | + Call the Modify() method with the properties that should be enforced |
| 135 | + and was not in desired state. |
| 136 | + #> |
| 137 | + $this.Modify($propertiesToModify) |
| 138 | + } |
| 139 | + else |
| 140 | + { |
| 141 | + Write-Verbose -Message $this.localizedData.NoPropertiesToSet |
| 142 | + } |
| 143 | + } |
| 144 | + |
| 145 | + [System.Boolean] Test() |
| 146 | + { |
| 147 | + # Get all key properties. |
| 148 | + $keyProperty = $this | Get-DscProperty -Type 'Key' |
| 149 | + |
| 150 | + Write-Verbose -Message ($this.localizedData.TestDesiredState -f $this.GetType().Name, ($keyProperty | ConvertTo-Json -Compress)) |
| 151 | + |
| 152 | + $this.Assert() |
| 153 | + |
| 154 | + $isInDesiredState = $true |
| 155 | + |
| 156 | + <# |
| 157 | + Returns all enforced properties not in desires state, or $null if |
| 158 | + all enforced properties are in desired state. |
| 159 | + #> |
| 160 | + $propertiesNotInDesiredState = $this.Compare() |
| 161 | + |
| 162 | + if ($propertiesNotInDesiredState) |
| 163 | + { |
| 164 | + $isInDesiredState = $false |
| 165 | + } |
| 166 | + |
| 167 | + if ($isInDesiredState) |
| 168 | + { |
| 169 | + Write-Verbose $this.localizedData.InDesiredState |
| 170 | + } |
| 171 | + else |
| 172 | + { |
| 173 | + Write-Verbose $this.localizedData.NotInDesiredState |
| 174 | + } |
| 175 | + |
| 176 | + return $isInDesiredState |
| 177 | + } |
| 178 | + |
| 179 | + <# |
| 180 | + Returns a hashtable containing all properties that should be enforced and |
| 181 | + are not in desired state, or $null if all enforced properties are in |
| 182 | + desired state. |
| 183 | +
|
| 184 | + This method should normally not be overridden. |
| 185 | + #> |
| 186 | + hidden [System.Collections.Hashtable[]] Compare() |
| 187 | + { |
| 188 | + # Get the current state, all properties except Read properties . |
| 189 | + $currentState = $this.Get() | Get-DscProperty -Type @('Key', 'Mandatory', 'Optional') |
| 190 | + |
| 191 | + return $this.Compare($currentState, @()) |
| 192 | + } |
| 193 | + |
| 194 | + <# |
| 195 | + Returns a hashtable containing all properties that should be enforced and |
| 196 | + are not in desired state, or $null if all enforced properties are in |
| 197 | + desired state. |
| 198 | +
|
| 199 | + This method should normally not be overridden. |
| 200 | + #> |
| 201 | + hidden [System.Collections.Hashtable[]] Compare([System.Collections.Hashtable] $currentState, [System.String[]] $excludeProperties) |
| 202 | + { |
| 203 | + # Get the desired state, all assigned properties that has an non-null value. |
| 204 | + $desiredState = $this | Get-DscProperty -Type @('Key', 'Mandatory', 'Optional') -HasValue |
| 205 | + |
| 206 | + $CompareDscParameterState = @{ |
| 207 | + CurrentValues = $currentState |
| 208 | + DesiredValues = $desiredState |
| 209 | + Properties = $desiredState.Keys |
| 210 | + ExcludeProperties = ($excludeProperties + $this.ExcludeDscProperties) | Select-Object -Unique |
| 211 | + IncludeValue = $true |
| 212 | + # This is needed to sort complex types. |
| 213 | + SortArrayValues = $true |
| 214 | + } |
| 215 | + |
| 216 | + <# |
| 217 | + Returns all enforced properties not in desires state, or $null if |
| 218 | + all enforced properties are in desired state. |
| 219 | + #> |
| 220 | + return (Compare-DscParameterState @CompareDscParameterState) |
| 221 | + } |
| 222 | + |
| 223 | + # This method should normally not be overridden. |
| 224 | + hidden [void] Assert() |
| 225 | + { |
| 226 | + # Get the properties that has a non-null value and is not of type Read. |
| 227 | + $desiredState = $this | Get-DscProperty -Type @('Key', 'Mandatory', 'Optional') -HasValue |
| 228 | + |
| 229 | + $this.AssertProperties($desiredState) |
| 230 | + } |
| 231 | + |
| 232 | + <# |
| 233 | + This method can be overridden if resource specific property asserts are |
| 234 | + needed. The parameter properties will contain the properties that was |
| 235 | + assigned a value. |
| 236 | + #> |
| 237 | + [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidEmptyNamedBlocks', '')] |
| 238 | + hidden [void] AssertProperties([System.Collections.Hashtable] $properties) |
| 239 | + { |
| 240 | + } |
| 241 | + |
| 242 | + <# |
| 243 | + This method must be overridden by a resource. The parameter properties will |
| 244 | + contain the properties that should be enforced and that are not in desired |
| 245 | + state. |
| 246 | + #> |
| 247 | + hidden [void] Modify([System.Collections.Hashtable] $properties) |
| 248 | + { |
| 249 | + throw $this.localizedData.ModifyMethodNotImplemented |
| 250 | + } |
| 251 | + |
| 252 | + <# |
| 253 | + This method must be overridden by a resource. The parameter properties will |
| 254 | + contain the key properties. |
| 255 | + #> |
| 256 | + hidden [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties) |
| 257 | + { |
| 258 | + throw $this.localizedData.GetCurrentStateMethodNotImplemented |
| 259 | + } |
| 260 | +} |
0 commit comments