Add support for method NormalizeProperties (#28)

Author: johlju

CHANGELOG.md

@@ -5,6 +5,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `ResourceBase`
+  - Added a new method `NormalizeProperties` that can be overridden in a
+    derived class to provide custom normalization logic. This method can
+    be used to normalize the properties of a desired state prior to the
+    methods `AssertProperties`, `GetCurrentState`, and `Modify` being called.
+    Default there is no normalization of properties. Fixes [issue #27](https://github.com/dsccommunity/DscResource.Base/issues/27).
+
 ## [1.2.1] - 2025-02-03
 
 ### Changed
@@ -16,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `Resource.Base`
+- `ResourceBase`
   - Add optional feature flag to handle using Enums as optional properties.
     This requires setting the starting value of the Enum to 1 so it is
     initialized as 0. Fixes [Issue #22](https://github.com/dsccommunity/DscResource.Base/issues/22).

source/Classes/010.ResourceBase.ps1

@@ -58,6 +58,8 @@ class ResourceBase
 
     [ResourceBase] Get()
     {
+        $this.Normalize()
+
         $this.Assert()
 
         # Get all key properties.
@@ -135,6 +137,8 @@ class ResourceBase
 
     [void] Set()
     {
+        $this.Normalize()
+
         # Get all key properties.
         $keyProperty = $this | Get-DscProperty -Attribute 'Key'
 
@@ -171,6 +175,8 @@ class ResourceBase
 
     [System.Boolean] Test()
     {
+        $this.Normalize()
+
         # Get all key properties.
         $keyProperty = $this | Get-DscProperty -Attribute 'Key'
 
@@ -227,13 +233,7 @@ class ResourceBase
     #>
     hidden [System.Collections.Hashtable[]] Compare([System.Collections.Hashtable] $currentState, [System.String[]] $excludeProperties)
     {
-        # Get the desired state, all assigned properties that has an non-null value.
-        $desiredState = $this | Get-DscProperty -Attribute @('Key', 'Mandatory', 'Optional') -HasValue
-
-        if ($this.FeatureOptionalEnums)
-        {
-            $desiredState = $desiredState | Clear-ZeroedEnumPropertyValue
-        }
+        $desiredState = $this.GetDesiredState()
 
         $CompareDscParameterState = @{
             CurrentValues     = $currentState
@@ -254,6 +254,18 @@ class ResourceBase
 
     # This method should normally not be overridden.
     hidden [void] Assert()
+    {
+        $this.AssertProperties($this.GetDesiredState())
+    }
+
+    # This method should normally not be overridden.
+    hidden [void] Normalize()
+    {
+        $this.NormalizeProperties($this.GetDesiredState())
+    }
+
+    # This is a private method and should normally not be overridden.
+    hidden [System.Collections.Hashtable] GetDesiredState()
     {
         # Get the properties that has a non-null value and is not of type Read.
         $desiredState = $this | Get-DscProperty -Attribute @('Key', 'Mandatory', 'Optional') -HasValue
@@ -263,7 +275,7 @@ class ResourceBase
             $desiredState = $desiredState | Clear-ZeroedEnumPropertyValue
         }
 
-        $this.AssertProperties($desiredState)
+        return $desiredState
     }
 
     <#
@@ -276,6 +288,16 @@ class ResourceBase
     {
     }
 
+    <#
+        This method can be overridden if resource specific property normalization
+        is needed. The parameter properties will contain the properties that was
+        assigned a value.
+    #>
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidEmptyNamedBlocks', '')]
+    hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
+    {
+    }
+
     <#
         This method must be overridden by a resource. The parameter properties will
         contain the properties that should be enforced and that are not in desired

tests/Unit/Classes/ResourceBase.Tests.ps1

@@ -122,6 +122,22 @@ Describe 'ResourceBase\AssertProperties()' -Tag 'AssertProperties' {
     }
 }
 
+Describe 'ResourceBase\NormalizeProperties()' -Tag 'NormalizeProperties' {
+    BeforeAll {
+        $mockResourceBaseInstance = InModuleScope -ScriptBlock {
+            [ResourceBase]::new()
+        }
+    }
+
+    It 'Should not throw' {
+        $mockDesiredState = @{
+            MyProperty1 = 'MyValue1'
+        }
+
+        { $mockResourceBaseInstance.NormalizeProperties($mockDesiredState) } | Should -Not -Throw
+    }
+}
+
 Describe 'ResourceBase\Assert()' -Tag 'Assert' {
     Context 'When the system is in the desired state' {
         BeforeAll {
@@ -213,6 +229,97 @@ $script:mockResourceBaseInstance = [MyMockResource]::new()
     }
 }
 
+Describe 'ResourceBase\Normalize()' -Tag 'Normalize' {
+    Context 'When the system is in the desired state' {
+        BeforeAll {
+            Mock -CommandName Get-ClassName -MockWith {
+                # Only return localized strings for this class name.
+                @('ResourceBase')
+            }
+
+            Mock -CommandName Get-DscProperty -MockWith {
+                return @{
+                    MyResourceKeyProperty1 = 'SomeString'
+                }
+            }
+
+            Mock -CommandName Clear-ZeroedEnumPropertyValue
+
+            $inModuleScopeScriptBlock = @'
+using module DscResource.Base
+
+enum MyMockEnum {
+Value1 = 1
+Value2
+Value3
+Value4
+}
+
+class MyMockResource : ResourceBase
+{
+[DscProperty(Key)]
+[System.String]
+$MyResourceKeyProperty1
+
+[DscProperty()]
+[System.String]
+$MyResourceProperty2
+
+[DscProperty()]
+[MyMockEnum]
+$MyResourceProperty3
+
+[DscProperty()]
+[MyMockEnum]
+$MyResourceProperty4 = [MyMockEnum]::Value4
+
+[DscProperty(NotConfigurable)]
+[System.String]
+$MyResourceReadProperty
+
+MyMockResource () {
+    $this.FeatureOptionalEnums = $true
+}
+
+[ResourceBase] Get()
+{
+    # Creates a new instance of the mock instance MyMockResource.
+    $currentStateInstance = [System.Activator]::CreateInstance($this.GetType())
+
+    $currentStateInstance.MyResourceProperty2 = 'MyValue1'
+    $currentStateInstance.MyResourceProperty4 = [MyMockEnum]::Value4
+    $currentStateInstance.MyResourceReadProperty = 'MyReadValue1'
+
+    return $currentStateInstance
+}
+}
+
+$script:mockResourceBaseInstance = [MyMockResource]::new()
+'@
+
+            InModuleScope -ScriptBlock ([Scriptblock]::Create($inModuleScopeScriptBlock))
+        }
+
+        It 'Should have correctly instantiated the resource class' {
+            InModuleScope -ScriptBlock {
+                $mockResourceBaseInstance | Should -Not -BeNullOrEmpty
+                $mockResourceBaseInstance.GetType().BaseType.Name | Should -Be 'ResourceBase'
+            }
+        }
+
+        Context 'When no properties are enforced' {
+            It 'Should not return any property to enforce' {
+                InModuleScope -ScriptBlock {
+                    $mockResourceBaseInstance.Normalize()
+                }
+
+                Should -Invoke -CommandName Get-DscProperty -Exactly -Times 1 -Scope It
+                Should -Invoke -CommandName Clear-ZeroedEnumPropertyValue -Exactly -Times 1 -Scope It
+            }
+        }
+    }
+}
+
 Describe 'ResourceBase\Get()' -Tag 'Get' {
     Context 'When the system is in the desired state' {
         BeforeAll {