|
| 1 | +<# |
| 2 | + .SYNOPSIS |
| 3 | + The `DebugDscEngine` DSC resource is used for debugging and testing |
| 4 | + purposes to demonstrate DSC resource patterns and behaviors. |
| 5 | +
|
| 6 | + .DESCRIPTION |
| 7 | + The `DebugDscEngine` DSC resource is used for debugging and testing |
| 8 | + purposes to demonstrate DSC resource patterns and behaviors. This |
| 9 | + resource does not perform any actual configuration changes but instead |
| 10 | + outputs verbose messages to help understand the DSC resource lifecycle |
| 11 | + and method execution flow. |
| 12 | +
|
| 13 | + The built-in parameter **PSDscRunAsCredential** can be used to run the resource |
| 14 | + as another user. |
| 15 | +
|
| 16 | + ## Requirements |
| 17 | +
|
| 18 | + * No specific requirements - this is a debug resource for testing purposes. |
| 19 | +
|
| 20 | + ## Known issues |
| 21 | +
|
| 22 | + All issues are not listed here, see [here for all open issues](https://github.com/dsccommunity/SqlServerDsc/issues?q=is%3Aissue+is%3Aopen+in%3Atitle+DebugDscEngine). |
| 23 | +
|
| 24 | + .PARAMETER KeyProperty |
| 25 | + Specifies the key property for the resource. This is a required property |
| 26 | + that uniquely identifies the resource instance. |
| 27 | +
|
| 28 | + .PARAMETER MandatoryProperty |
| 29 | + Specifies a mandatory property that must be provided when using the resource. |
| 30 | + This demonstrates how mandatory properties work in DSC resources. |
| 31 | +
|
| 32 | + .PARAMETER WriteProperty |
| 33 | + Specifies an optional write property that can be configured by the resource. |
| 34 | + This property can be enforced and will be compared during Test() operations. |
| 35 | +
|
| 36 | + .PARAMETER ReadProperty |
| 37 | + Specifies a read-only property that is returned by the resource but cannot |
| 38 | + be configured. This property is populated during Get() operations to show |
| 39 | + the current state. |
| 40 | +
|
| 41 | + .NOTES |
| 42 | + This resource is designed for debugging and testing purposes only. |
| 43 | + It demonstrates the proper patterns for creating DSC class-based resources |
| 44 | + following the SqlServerDsc module conventions. |
| 45 | +
|
| 46 | + .EXAMPLE |
| 47 | + Configuration Example |
| 48 | + { |
| 49 | + Import-DscResource -ModuleName SqlServerDsc |
| 50 | +
|
| 51 | + Node localhost |
| 52 | + { |
| 53 | + DebugDscEngine 'TestResource' |
| 54 | + { |
| 55 | + KeyProperty = 'UniqueIdentifier' |
| 56 | + MandatoryProperty = 'RequiredValue' |
| 57 | + WriteProperty = 'ConfigurableValue' |
| 58 | + } |
| 59 | + } |
| 60 | + } |
| 61 | +
|
| 62 | + This example shows how to use the DebugDscEngine resource for testing. |
| 63 | +#> |
| 64 | +[DscResource(RunAsCredential = 'Optional')] |
| 65 | +class DebugDscEngine : ResourceBase |
| 66 | +{ |
| 67 | + [DscProperty(Key)] |
| 68 | + [System.String] |
| 69 | + $KeyProperty |
| 70 | + |
| 71 | + [DscProperty(Mandatory)] |
| 72 | + [System.String] |
| 73 | + $MandatoryProperty |
| 74 | + |
| 75 | + [DscProperty()] |
| 76 | + [System.String] |
| 77 | + $WriteProperty |
| 78 | + |
| 79 | + [DscProperty(NotConfigurable)] |
| 80 | + [System.String] |
| 81 | + $ReadProperty |
| 82 | + |
| 83 | + DebugDscEngine () : base ($PSScriptRoot) |
| 84 | + { |
| 85 | + # These properties will not be enforced. |
| 86 | + $this.ExcludeDscProperties = @( |
| 87 | + 'MandatoryProperty' |
| 88 | + ) |
| 89 | + } |
| 90 | + |
| 91 | + [DebugDscEngine] Get() |
| 92 | + { |
| 93 | + # Call the base method to return the properties. |
| 94 | + return ([ResourceBase] $this).Get() |
| 95 | + } |
| 96 | + |
| 97 | + [System.Boolean] Test() |
| 98 | + { |
| 99 | + # Call the base method to test all of the properties that should be enforced. |
| 100 | + return ([ResourceBase] $this).Test() |
| 101 | + } |
| 102 | + |
| 103 | + [void] Set() |
| 104 | + { |
| 105 | + # Call the base method to enforce the properties. |
| 106 | + ([ResourceBase] $this).Set() |
| 107 | + } |
| 108 | + |
| 109 | + <# |
| 110 | + Base method Get() call this method to get the current state as a hashtable. |
| 111 | + The parameter properties will contain the key properties. |
| 112 | + #> |
| 113 | + hidden [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties) |
| 114 | + { |
| 115 | + Write-Verbose -Message ( |
| 116 | + $this.localizedData.Getting_CurrentState -f @( |
| 117 | + $properties.KeyProperty |
| 118 | + ) |
| 119 | + ) |
| 120 | + |
| 121 | + Write-Verbose -Message ( |
| 122 | + $this.localizedData.Debug_GetCurrentState_Called -f @( |
| 123 | + $properties.KeyProperty, |
| 124 | + ($properties.Keys -join ', ') |
| 125 | + ) |
| 126 | + ) |
| 127 | + |
| 128 | + $currentState = @{ |
| 129 | + KeyProperty = $properties.KeyProperty |
| 130 | + MandatoryProperty = 'CurrentMandatoryStateValue' |
| 131 | + WriteProperty = 'CurrentStateValue' |
| 132 | + ReadProperty = 'ReadOnlyValue_' + (Get-Date -Format 'yyyyMMdd_HHmmss') |
| 133 | + } |
| 134 | + |
| 135 | + Write-Verbose -Message ( |
| 136 | + $this.localizedData.Debug_GetCurrentState_Returning -f @( |
| 137 | + ($currentState.Keys -join ', ') |
| 138 | + ) |
| 139 | + ) |
| 140 | + |
| 141 | + return $currentState |
| 142 | + } |
| 143 | + |
| 144 | + <# |
| 145 | + Base method Set() call this method with the properties that are not in |
| 146 | + desired state and should be enforced. It is not called if all properties |
| 147 | + are in desired state. The variable $properties contains only the properties |
| 148 | + that are not in desired state. |
| 149 | + #> |
| 150 | + hidden [void] Modify([System.Collections.Hashtable] $properties) |
| 151 | + { |
| 152 | + Write-Verbose -Message ( |
| 153 | + $this.localizedData.Debug_Modify_Called -f @( |
| 154 | + $this.KeyProperty, |
| 155 | + ($properties.Keys -join ', ') |
| 156 | + ) |
| 157 | + ) |
| 158 | + |
| 159 | + foreach ($propertyName in $properties.Keys) |
| 160 | + { |
| 161 | + $propertyValue = $properties[$propertyName] |
| 162 | + |
| 163 | + Write-Verbose -Message ( |
| 164 | + $this.localizedData.Debug_Modify_Property -f @( |
| 165 | + $propertyName, |
| 166 | + $propertyValue |
| 167 | + ) |
| 168 | + ) |
| 169 | + |
| 170 | + # Simulate setting the property |
| 171 | + Start-Sleep -Milliseconds 100 |
| 172 | + } |
| 173 | + |
| 174 | + Write-Verbose -Message ( |
| 175 | + $this.localizedData.Debug_Modify_Completed -f $this.KeyProperty |
| 176 | + ) |
| 177 | + } |
| 178 | + |
| 179 | + <# |
| 180 | + Base method Assert() call this method with the properties that was assigned |
| 181 | + a value. |
| 182 | + #> |
| 183 | + hidden [void] AssertProperties([System.Collections.Hashtable] $properties) |
| 184 | + { |
| 185 | + Write-Verbose -Message ( |
| 186 | + $this.localizedData.Debug_AssertProperties_Called -f @( |
| 187 | + $this.KeyProperty, |
| 188 | + ($properties.Keys -join ', ') |
| 189 | + ) |
| 190 | + ) |
| 191 | + |
| 192 | + # Validate that KeyProperty is not null or empty |
| 193 | + if ([System.String]::IsNullOrEmpty($properties.KeyProperty)) |
| 194 | + { |
| 195 | + New-ArgumentException -ArgumentName 'KeyProperty' -Message $this.localizedData.KeyProperty_Invalid |
| 196 | + } |
| 197 | + |
| 198 | + # Validate that MandatoryProperty is not null or empty |
| 199 | + if ([System.String]::IsNullOrEmpty($properties.MandatoryProperty)) |
| 200 | + { |
| 201 | + New-ArgumentException -ArgumentName 'MandatoryProperty' -Message $this.localizedData.MandatoryProperty_Invalid |
| 202 | + } |
| 203 | + |
| 204 | + Write-Verbose -Message ( |
| 205 | + $this.localizedData.Debug_AssertProperties_Completed -f $this.KeyProperty |
| 206 | + ) |
| 207 | + } |
| 208 | + |
| 209 | + <# |
| 210 | + Base method Normalize() call this method with the properties that was assigned |
| 211 | + a value. |
| 212 | + #> |
| 213 | + hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties) |
| 214 | + { |
| 215 | + Write-Verbose -Message ( |
| 216 | + $this.localizedData.Debug_NormalizeProperties_Called -f @( |
| 217 | + $this.KeyProperty, |
| 218 | + ($properties.Keys -join ', ') |
| 219 | + ) |
| 220 | + ) |
| 221 | + |
| 222 | + # Normalize KeyProperty to uppercase |
| 223 | + if ($properties.ContainsKey('KeyProperty')) |
| 224 | + { |
| 225 | + $this.KeyProperty = $properties.KeyProperty.ToUpper() |
| 226 | + |
| 227 | + Write-Verbose -Message ( |
| 228 | + $this.localizedData.Debug_NormalizeProperties_Property -f @( |
| 229 | + 'KeyProperty', |
| 230 | + $this.KeyProperty |
| 231 | + ) |
| 232 | + ) |
| 233 | + } |
| 234 | + |
| 235 | + # Normalize WriteProperty to trim whitespace |
| 236 | + if ($properties.ContainsKey('WriteProperty')) |
| 237 | + { |
| 238 | + $this.WriteProperty = $properties.WriteProperty.Trim() |
| 239 | + |
| 240 | + Write-Verbose -Message ( |
| 241 | + $this.localizedData.Debug_NormalizeProperties_Property -f @( |
| 242 | + 'WriteProperty', |
| 243 | + $this.WriteProperty |
| 244 | + ) |
| 245 | + ) |
| 246 | + } |
| 247 | + |
| 248 | + Write-Verbose -Message ( |
| 249 | + $this.localizedData.Debug_NormalizeProperties_Completed -f $this.KeyProperty |
| 250 | + ) |
| 251 | + } |
| 252 | +} |
0 commit comments