Assert-BoundParameter: Add parameters AtLeastOneList and IfEqualParameterList

.vscode/settings.json

@@ -32,7 +32,10 @@
         "keepachangelog",
         "notin",
         "pscmdlet",
-        "steppable"
+        "steppable",
+        "hashtables",
+        "HQRM",
+        "LCID"
     ],
     "[markdown]": {
         "files.trimTrailingWhitespace": true,

.vscode/tasks.json

@@ -41,7 +41,7 @@
             "label": "build",
             "type": "shell",
             "command": "&${cwd}/build.ps1",
-            "args": [],
+            "args": ["-AutoRestore", "-UseModuleFast", "-Tasks", "build"],
             "presentation": {
                 "echo": true,
                 "reveal": "always",
@@ -84,7 +84,64 @@
             "label": "test",
             "type": "shell",
             "command": "&${cwd}/build.ps1",
-            "args": ["-AutoRestore","-Tasks","test"],
+            "args": [
+                "-AutoRestore",
+                "-UseModuleFast",
+                "-Tasks",
+                "test",
+                "-PesterPath",
+                "./tests/Unit/Classes,./tests/Unit/Private,./tests/Unit/Public,./tests/QA",
+                "-CodeCoverageThreshold",
+                "0"
+            ],
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": true,
+                "panel": "dedicated",
+                "showReuseMessage": true,
+                "clear": false
+            },
+            "problemMatcher": [
+                {
+                    "owner": "powershell",
+                    "fileLocation": [
+                        "absolute"
+                    ],
+                    "severity": "error",
+                    "pattern": [
+                        {
+                            "regexp": "^\\s*(\\[-\\]\\s*.*?)(\\d+)ms\\s*$",
+                            "message": 1
+                        },
+                        {
+                            "regexp": "(.*)",
+                            "code": 1
+                        },
+                        {
+                            "regexp": ""
+                        },
+                        {
+                            "regexp": "^.*,\\s*(.*):\\s*line\\s*(\\d+).*",
+                            "file": 1,
+                            "line": 2
+                        }
+                    ]
+                }
+            ]
+        },
+        {
+            "label": "hqrmtest",
+            "type": "shell",
+            "command": "&${cwd}/build.ps1",
+            "args": [
+                "-AutoRestore",
+                "-UseModuleFast",
+                "-Tasks",
+                "hqrmtest",
+                "-CodeCoverageThreshold",
+                "0"
+            ],
             "presentation": {
                 "echo": true,
                 "reveal": "always",

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `Assert-BoundParameter`
+  - Added parameter set `AtLeastOne` with parameter `AtLeastOneList` to
+    validate that at least one parameter from a specified list is bound
+    [#161](https://github.com/dsccommunity/DscResource.Common/issues/161).
+  - Added parameter `IfEqualParameterList` to conditionally perform assertions
+    only when specified parameters have exact values [#160](https://github.com/dsccommunity/DscResource.Common/issues/160).
 - `Format-Path`
   - Added parameter `ExpandEnvironmentVariable` fixes [#147](https://github.com/dsccommunity/DscResource.Common/issues/147).
   - Added support to `Compare-DscParameterState` for comparing large hashtables
@@ -322,8 +328,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - DscResource.Common
-  - updating the Get-LocalizedData to bypass Import-LocalizedData when in Globalization-Invariant mode.
-    The command throws when running on an Invariant culture on Linux in the latest PS versions.
+  - updating the Get-LocalizedData to bypass Import-LocalizedData when in
+    Globalization-Invariant mode.
+    The command throws when running on an Invariant culture on Linux in
+    the latest PS versions.
 
 ## [0.11.0] - 2022-08-01
 
@@ -337,9 +345,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - Correction to `Compare-DscParameterState` returning false positive when parameter
-  with an empty hashtable or CimInstance property is passed in `DesriedValues` - fixes
-  [issue #65](https://github.com/dsccommunity/DscResource.Common/issues/65).
-- Correction somes problems in `Compare-DscParameterState` - see [issue #70](https://github.com/dsccommunity/DscResource.Common/issues/70) :
+  with an empty hashtable or CimInstance property is passed in `DesiredValues`,
+  fixes [issue #65](https://github.com/dsccommunity/DscResource.Common/issues/65).
+- Correction some problems in `Compare-DscParameterState`, see
+  [issue #70](https://github.com/dsccommunity/DscResource.Common/issues/70).
   - When you use `-ReverseCheck`, this value is used in recursive call of
   `Test-DscParameterState` and `Compare-DscParameterState`, and that called
   another time the function.
@@ -398,15 +407,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Get-TargetResource function or Get() method in Class based Resources.
   It is based on the code of Test-DscParameterState function to get compliance
   between current and desired state of resources.
-  The OutPut of Compare-DscParameterState is a collection psobject.
-  The properties of psobject are Property,InDesiredState,ExpectedType,ActualType,
-  ExpectedValue and ActualValue. The IncludeInDesiredState parameter must be use to
-  add ExeptedValue and ActualValue.
-- Added pester test to test the pscredential object with `Compare-DscParameterState`.
+  The OutPut of Compare-DscParameterState is a collection of PSObject.
+  The properties of each PSObject are Property, InDesiredState, ExpectedType, ActualType,
+  ExpectedValue, and ActualValue. The IncludeInDesiredState parameter must
+  be used to add ExpectedValue and ActualValue.
+- Added pester test to test the PSCredential object with `Compare-DscParameterState`.
 
 ### Changed
 
-- Cmdlet Test-DscResourceState is now calling Compare-DscParameterState. Possible breaking change.
+- Cmdlet Test-DscResourceState is now calling Compare-DscParameterState.
+  Possible breaking change.
 - IncludeInDesiredState and IncludeValue parameters of Compare-DscParameterState
   are removed in splatting when Test-DscCompareState is called.
 
@@ -419,15 +429,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Fixed
 
 - Correction to `Test-DscParameterState` returning false positive when parameter
-  with an empty array is passed in `DesriedValues` or `CurrentValues` - fixes
+  with an empty array is passed in `DesiredValues` or `CurrentValues` - fixes
   [issue #53](https://github.com/dsccommunity/DscResource.Common/issues/53).
 
 ## [0.9.2] - 2020-07-22
 
 ### Added
 
-- `Test-DscParameterState` can now handle scriptblocks. The parameter 'ValuesToCheck' was renamed to 'Properties' but an alias
-  was added so it is not a braking change. The parameter 'ExcludeProperties' was added.
+- `Test-DscParameterState` can now handle script blocks. The parameter
+  'ValuesToCheck' was renamed to 'Properties' but an alias
+  was added so it is not a braking change. The parameter 'ExcludeProperties'
+  was added.
 - Added a new test for the alias 'ValuesToCheck' pointing to 'Properties'.
 - Added cmdlet `Compare-ResourcePropertyState` that also introduces a new
   design pattern to evaluate properties in both _Test_ and _Set_ - fixes
@@ -458,8 +470,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.8.0] - 2020-05-11
 
-- Added a default value of `en-US` to the `DefaultUICulture` parameter of the `Get-LocalizedData` function
-  [Issue #33](https://github.com/dsccommunity/DscResource.Common/issues/33).
+- Added a default value of `en-US` to the `DefaultUICulture` parameter of
+  the `Get-LocalizedData` function [Issue #33](https://github.com/dsccommunity/DscResource.Common/issues/33).
 - Fixing a problem with the latest ModuleBuild 1.7.0 that breaks the CI pipeline.
 
 ## [0.7.1] - 2020-05-02
@@ -524,7 +536,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Fixed the New-*Exception function unit tests to work correctly on PowerShell version 5, 6 and 7.
+- Fixed the New-*Exception function unit tests to work correctly on PowerShell
+  version 5, 6 and 7.
 
 ## [0.4.0] - 2020-03-09
 

source/Public/Assert-BoundParameter.ps1

@@ -5,7 +5,7 @@
 
     .DESCRIPTION
         This command asserts passed parameters. It takes a hashtable, normally
-        `$PSBoundParameters`. There are two parameter sets for this command.
+        `$PSBoundParameters`. There are three parameter sets for this command.
 
         >There is no built in logic to validate against parameters sets for DSC
         >so this can be used instead to validate the parameters that were set in
@@ -23,6 +23,11 @@
         if not. Optionally it can be specified that parameters are only required
         if a specific parameter has been passed.
 
+        **AtLeastOne**
+
+        Assert that at least one parameter from the specified list has been bound,
+        and throws an exception if none are present.
+
     .PARAMETER BoundParameterList
         The parameters that should be evaluated against the mutually exclusive
         lists MutuallyExclusiveList1 and MutuallyExclusiveList2. This parameter is
@@ -47,6 +52,14 @@
        If neither of the parameter names has been specified the evaluation of required
        parameters are not made.
 
+    .PARAMETER IfEqualParameterList
+       A hashtable of parameter names and their expected values. The assertion will
+       only be performed if all the specified parameters in the BoundParameterList
+       have the exact values specified in this hashtable.
+
+    .PARAMETER AtLeastOneList
+       An array of parameter names where at least one must be bound.
+
     .EXAMPLE
         $assertBoundParameterParameters = @{
             BoundParameterList = $PSBoundParameters
@@ -74,9 +87,50 @@
         of the required parameters are not.
 
     .EXAMPLE
-        Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -RequiredBehavior 'AtLeastOnce'
+        Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -RequiredBehavior 'Any'
+
+        Throws an exception if any of the two parameters are not present.
+
+    .EXAMPLE
+        Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -RequiredBehavior 'All'
+
+        Throws an exception if all of the specified parameters are not present.
+
+    .EXAMPLE
+        Assert-BoundParameter -BoundParameterList $PSBoundParameters -AtLeastOneList @('Severity', 'MessageId')
+
+        Throws an exception if none of the parameters 'Severity' or 'MessageId' are specified.
+
+    .EXAMPLE
+        $assertBoundParameterParameters = @{
+            BoundParameterList = $PSBoundParameters
+            MutuallyExclusiveList1 = @(
+                'Severity'
+            )
+            MutuallyExclusiveList2 = @(
+                'MessageId'
+            )
+            IfEqualParameterList = @{
+                Ensure = 'Present'
+            }
+        }
+        Assert-BoundParameter @assertBoundParameterParameters
+
+        This example throws an exception if `$PSBoundParameters` contains both
+        the parameters `Severity` and `MessageId` and the parameter `Ensure` has
+        the value `Present`.
+
+    .EXAMPLE
+        Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfEqualParameterList @{ Property1 = 'SpecificValue' }
+
+        Throws an exception if the parameter 'Property1' has the value 'SpecificValue'
+        and either of the required parameters are not specified.
 
-        Throws an exception if at least one of the two parameters are not specified.
+    .EXAMPLE
+        Assert-BoundParameter -BoundParameterList $PSBoundParameters -AtLeastOneList @('Severity', 'MessageId') -IfEqualParameterList @{ Ensure = 'Present' }
+
+        Throws an exception if the parameter 'Ensure' has the value 'Present' and
+        none of the parameters 'Severity' or 'MessageId' are specified.
 #>
 function Assert-BoundParameter
 {
@@ -106,9 +160,31 @@ function Assert-BoundParameter
 
         [Parameter(ParameterSetName = 'RequiredParameter')]
         [System.String[]]
-        $IfParameterPresent
+        $IfParameterPresent,
+
+        [Parameter(ParameterSetName = 'MutuallyExclusiveParameters')]
+        [Parameter(ParameterSetName = 'RequiredParameter')]
+        [Parameter(ParameterSetName = 'AtLeastOne')]
+        [System.Collections.Hashtable]
+        $IfEqualParameterList,
+
+        [Parameter(ParameterSetName = 'AtLeastOne', Mandatory = $true)]
+        [System.String[]]
+        $AtLeastOneList
     )
 
+    # Early return if IfEqualParameterList conditions are not met
+    if ($PSBoundParameters.ContainsKey('IfEqualParameterList'))
+    {
+        foreach ($parameterName in $IfEqualParameterList.Keys)
+        {
+            if (-not $BoundParameterList.ContainsKey($parameterName) -or $BoundParameterList[$parameterName] -ne $IfEqualParameterList[$parameterName])
+            {
+                return
+            }
+        }
+    }
+
     switch ($PSCmdlet.ParameterSetName)
     {
         'MutuallyExclusiveParameters'
@@ -118,18 +194,24 @@ function Assert-BoundParameter
 
             if ($itemFoundFromList1.Count -gt 0 -and $itemFoundFromList2.Count -gt 0)
             {
-                $errorMessage = `
-                    $script:localizedData.ParameterUsageWrong `
-                    -f ($MutuallyExclusiveList1 -join "','"), ($MutuallyExclusiveList2 -join "','")
+                $errorMessage = $script:localizedData.ParameterUsageWrong -f (
+                    ($MutuallyExclusiveList1 -join "','"),
+                    ($MutuallyExclusiveList2 -join "','")
+                )
 
-                New-InvalidArgumentException -ArgumentName 'Parameters' -Message $errorMessage
+                New-ArgumentException -ArgumentName 'Parameters' -Message $errorMessage
             }
 
             break
         }
 
         'RequiredParameter'
         {
+            if ($PSBoundParameters.ContainsKey('IfEqualParameterList'))
+            {
+                $PSBoundParameters.Remove('IfEqualParameterList')
+            }
+
             if (-not $PSBoundParameters.ContainsKey('RequiredBehavior'))
             {
                 $PSBoundParameters.RequiredBehavior = $RequiredBehavior
@@ -138,5 +220,19 @@ function Assert-BoundParameter
             Assert-RequiredCommandParameter @PSBoundParameters
             break
         }
+
+        'AtLeastOne'
+        {
+            $boundParametersFromList = $BoundParameterList.Keys.Where({ $_ -in $AtLeastOneList })
+
+            if ($boundParametersFromList.Count -eq 0)
+            {
+                $errorMessage = $script:localizedData.Assert_BoundParameter_AtLeastOneParameterMustBeSet -f ($AtLeastOneList -join "','")
+
+                New-ArgumentException -ArgumentName 'Parameters' -Message $errorMessage
+            }
+
+            break
+        }
     }
 }

source/Public/Assert-IPAddress.ps1

@@ -53,7 +53,7 @@ function Assert-IPAddress
 
     if (-not ([System.Net.IPAddress]::TryParse($Address, [ref] $ipAddress)))
     {
-        New-InvalidArgumentException `
+        New-ArgumentException `
             -Message ($script:localizedData.AddressFormatError -f $Address) `
             -ArgumentName 'Address'
     }
@@ -66,7 +66,7 @@ function Assert-IPAddress
             {
                 if ($ipAddress.AddressFamily -ne [System.Net.Sockets.AddressFamily]::InterNetwork.ToString())
                 {
-                    New-InvalidArgumentException `
+                    New-ArgumentException `
                         -Message ($script:localizedData.AddressIPv6MismatchError -f $Address, $AddressFamily) `
                         -ArgumentName 'AddressFamily'
                 }
@@ -76,7 +76,7 @@ function Assert-IPAddress
             {
                 if ($ipAddress.AddressFamily -ne [System.Net.Sockets.AddressFamily]::InterNetworkV6.ToString())
                 {
-                    New-InvalidArgumentException `
+                    New-ArgumentException `
                         -Message ($script:localizedData.AddressIPv4MismatchError -f $Address, $AddressFamily) `
                         -ArgumentName 'AddressFamily'
                 }