Add correct support for Reasons (#10)

johlju · web-flow · commit d97d1e16ed3c · 2023-02-26T13:25:10.000+01:00
- DscResource.Base - A new private function `ConvertFrom-Reason` was added which takes an array of `[Reason]` and coverts it to an array of `[System.Collections.Hashtable]`. - The private function `ConvertTo-Reason` was renamed `Resolve-Reason`. - `ResourceBase` - The property `Reasons` in derived class-based resources is now expected to use the type `[System.Collections.Hashtable[]]` (issue #4).
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -16,10 +16,10 @@
 
 #### This Pull Request (PR) fixes the following issues
 <!--
-    Replace this comment block with the list of issues or n/a.
-    Use format:
-    - Fixes #123
-    - Fixes #124
+Replace this comment block with the list of issues or n/a.
+Use format:
+- Fixes #123
+- Fixes #124
 -->
 
 #### Task list
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -25,6 +25,8 @@
         "powershell"
     ],
     "cSpell.words": [
+        "Hashtable",
+        "notin"
     ],
     "cSpell.ignorePaths": [
         ".git"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,10 +5,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- DscResource.Base
+  - A new private function `ConvertFrom-Reason` was added which takes an
+    array of `[Reason]` and coverts it to an array of `[System.Collections.Hashtable]`.
+
 ### Changed
 
 - DscResource.Base
   - Enable Pester's new code coverage method.
+  - The private function `ConvertTo-Reason` was renamed `Resolve-Reason`.
+- `ResourceBase`
+  - The property `Reasons` in derived class-based resources is now expected
+    to use the type `[System.Collections.Hashtable[]]` ([issue #4](https://github.com/dsccommunity/DscResource.Base/issues/4)).
 
 ### Fixed
 
diff --git a/source/Classes/010.ResourceBase.ps1 b/source/Classes/010.ResourceBase.ps1
@@ -122,7 +122,8 @@ class ResourceBase
         {
             # Always return an empty array if all properties are in desired state.
             $dscResourceObject.Reasons = $propertiesNotInDesiredState |
-                ConvertTo-Reason -ResourceName $this.GetType().Name
+                Resolve-Reason -ResourceName $this.GetType().Name |
+                ConvertFrom-Reason
         }
 
         # Return properties.
diff --git a/source/Private/ConvertFrom-Reason.ps1 b/source/Private/ConvertFrom-Reason.ps1
@@ -0,0 +1,58 @@
+<#
+    .SYNOPSIS
+        Returns a array of the type `System.Collections.Hashtable`.
+
+    .DESCRIPTION
+        This command converts an array of [Reason] that is returned by the command
+        `Resolve-Reason`. The result is an array of the type `[System.Collections.Hashtable]`
+        that can be returned as the value of a DSC resource's property **Reasons**.
+
+    .PARAMETER Reason
+       Specifies an array of `[Reason]`. Normally the result from the command `Resolve-Reason`.
+
+    .EXAMPLE
+        Resolve-Reason -Reason (Resolve-Reason) -ResourceName 'MyResource'
+
+        Returns an array of `[System.Collections.Hashtable]` with the converted
+        `[Reason[]]`.
+
+    .OUTPUTS
+        [System.Collections.Hashtable[]]
+#>
+function ConvertFrom-Reason
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseOutputTypeCorrectly', '', Justification = 'Because the rule does not understands that the command returns [System.Collections.Hashtable[]] when using , (comma) in the return statement')]
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when the output type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable[]])]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [AllowEmptyCollection()]
+        [AllowNull()]
+        [Reason[]]
+        $Reason
+    )
+
+    begin
+    {
+        # Always return an empty array if there are nothing to convert.
+        $reasonsAsHashtable = [System.Collections.Hashtable[]] @()
+    }
+
+    process
+    {
+        foreach ($currentReason in $Reason)
+        {
+            $reasonsAsHashtable += [System.Collections.Hashtable] @{
+                Code   = $currentReason.Code
+                Phrase = $currentReason.Phrase
+            }
+        }
+    }
+
+    end
+    {
+        return , [System.Collections.Hashtable[]] $reasonsAsHashtable
+    }
+}
diff --git a/source/Private/Resolve-Reason.ps1 b/source/Private/Resolve-Reason.ps1
@@ -3,9 +3,8 @@
         Returns a array of the type `[Reason]`.
 
     .DESCRIPTION
-        This command converts the array of properties that is returned by the command
-        `Compare-DscParameterState`. The result is an array of the type `[Reason]` that
-        can be returned in a DSC resource's property **Reasons**.
+        This command builds an array from the properties that is returned by the command
+        `Compare-DscParameterState`. The result is an array of the type `[Reason]`.
 
     .PARAMETER Property
        The result from the command Compare-DscParameterState.
@@ -15,15 +14,15 @@
        the correct value.
 
     .EXAMPLE
-        ConvertTo-Reason -Property (Compare-DscParameterState) -ResourceName 'MyResource'
+        Resolve-Reason -Property (Compare-DscParameterState) -ResourceName 'MyResource'
 
         Returns an array of `[Reason]` that contain all the properties not in desired
         state and why a specific property is not in desired state.
 
     .OUTPUTS
         [Reason[]]
 #>
-function ConvertTo-Reason
+function Resolve-Reason
 {
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when the output type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
     [CmdletBinding()]
diff --git a/tests/Unit/Classes/ResourceBase.Tests.ps1 b/tests/Unit/Classes/ResourceBase.Tests.ps1
@@ -162,7 +162,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     <#
@@ -213,6 +213,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                     $getResult.MyResourceKeyProperty1 | Should -Be 'MyValue1'
                     $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                     $getResult.Ensure | Should -Be ([Ensure]::Present)
+
+                    Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
                     $getResult.Reasons | Should -BeNullOrEmpty
                 }
             }
@@ -248,7 +250,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     <#
@@ -292,6 +294,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                     $getResult.MyResourceKeyProperty1 | Should -Be 'MyValue1'
                     $getResult.MyResourceProperty2 | Should -BeNullOrEmpty
                     $getResult.Ensure | Should -Be ([Ensure]::Absent)
+
+                    Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
                     $getResult.Reasons | Should -BeNullOrEmpty
                 }
             }
@@ -328,7 +332,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
@@ -364,6 +368,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceKeyProperty1 | Should -Be 'MyValue1'
                         $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                         $getResult.Ensure | Should -Be ([Ensure]::Present)
+
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
                         $getResult.Reasons | Should -BeNullOrEmpty
                     }
                 }
@@ -399,7 +405,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
@@ -435,6 +441,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceKeyProperty1 | Should -Be 'MyValue1'
                         $getResult.MyResourceProperty2 | Should -BeNullOrEmpty
                         $getResult.Ensure | Should -Be ([Ensure]::Absent)
+
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
                         $getResult.Reasons | Should -BeNullOrEmpty
                     }
                 }
@@ -476,7 +484,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     MyMockResource() : base ()
@@ -518,6 +526,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                         $getResult.Ensure | Should -Be ([Ensure]::Present)
 
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
+
                         $getResult.Reasons | Should -HaveCount 1
                         $getResult.Reasons[0].Code | Should -Be 'MyMockResource:MyMockResource:MyResourceProperty2'
                         $getResult.Reasons[0].Phrase | Should -Be 'The property MyResourceProperty2 should be "NewValue2", but was "MyValue2"'
@@ -550,7 +560,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     MyMockResource() : base ()
@@ -588,6 +598,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceKeyProperty1 | Should -Be 'MyValue1'
                         $getResult.Ensure | Should -Be ([Ensure]::Absent)
 
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
+
                         $getResult.Reasons | Should -HaveCount 1
                         $getResult.Reasons[0].Code | Should -Be 'MyMockResource:MyMockResource:Ensure'
                         $getResult.Reasons[0].Phrase | Should -Be 'The property Ensure should be "Present", but was "Absent"'
@@ -626,7 +638,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     MyMockResource() : base ()
@@ -668,6 +680,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                     $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                     $getResult.Ensure | Should -Be ([Ensure]::Present)
 
+                    Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
+
                     $getResult.Reasons | Should -HaveCount 1
                     $getResult.Reasons[0].Code | Should -Be 'MyMockResource:MyMockResource:Ensure'
                     $getResult.Reasons[0].Phrase | Should -Be 'The property Ensure should be "Absent", but was "Present"'
@@ -701,7 +715,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
@@ -738,6 +752,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                         $getResult.Ensure | Should -Be ([Ensure]::Absent)
 
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
+
                         $getResult.Reasons | Should -HaveCount 2
 
                         # The order in the array was sometimes different so could not use array index ($getResult.Reasons[0]).
@@ -779,7 +795,7 @@ class MyMockResource : ResourceBase
     $MyResourceProperty2
 
     [DscProperty(NotConfigurable)]
-    [Reason[]]
+    [System.Collections.Hashtable[]]
     $Reasons
 
     [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
@@ -816,6 +832,8 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
                         $getResult.MyResourceProperty2 | Should -Be 'MyValue2'
                         $getResult.Ensure | Should -Be ([Ensure]::Present)
 
+                        Should -ActualValue $getResult.Reasons -HaveType [System.Collections.Hashtable[]]
+
                         $getResult.Reasons | Should -HaveCount 1
 
                         $getResult.Reasons[0].Code | Should -Be 'MyMockResource:MyMockResource:Ensure'
diff --git a/tests/Unit/Private/ConvertFrom-Reason.Tests.ps1 b/tests/Unit/Private/ConvertFrom-Reason.Tests.ps1
diff --git a/tests/Unit/Private/Resolve-Reason.Tests.ps1 b/tests/Unit/Private/Resolve-Reason.Tests.ps1

Original file line number	Diff line number	Diff line change
`@@ -122,7 +122,8 @@ class ResourceBase`
`122`	`122`	`{`
`123`	`123`	`# Always return an empty array if all properties are in desired state.`
`124`	`124`	`$dscResourceObject.Reasons = $propertiesNotInDesiredState \|`
`125`		`- ConvertTo-Reason -ResourceName $this.GetType().Name`
	`125`	`+ Resolve-Reason -ResourceName $this.GetType().Name \|`
	`126`	`+ ConvertFrom-Reason`
`126`	`127`	`}`
`127`	`128`
`128`	`129`	`# Return properties.`