Assert‑BoundParameter - dsccommunity/DscResource.Common GitHub Wiki

Asserts that bound parameters meet specified validation rules.

Assert-BoundParameter -BoundParameterList <Hashtable> -MutuallyExclusiveList1 <String[]>
 -MutuallyExclusiveList2 <String[]> [-IfParameterPresent <Object>] 
 [<CommonParameters>]

Assert-BoundParameter -BoundParameterList <Hashtable> -RequiredParameter <String[]>
 [-RequiredBehavior <BoundParameterBehavior>] [-IfParameterPresent <Object>]
 [<CommonParameters>]

Assert-BoundParameter -BoundParameterList <Hashtable> [-IfParameterPresent <Object>] -NotAllowedList <String[]>
 [<CommonParameters>]

Assert-BoundParameter -BoundParameterList <Hashtable> [-IfParameterPresent <Object>] -AtLeastOneList <String[]>
 [<CommonParameters>]

This command asserts passed parameters. It takes a hashtable, normally $PSBoundParameters.

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 the configuration.

Parameter sets:

MutuallyExclusiveParameters

This parameter set takes two mutually exclusive lists of parameters. If any of the parameters in the first list are specified, none of the parameters in the second list can be specified.

RequiredParameter

Assert that required parameters has been specified, and throws an exception 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.

NotAllowed

Assert that none of the parameters from the specified list have been bound, and throws an exception if any are present.

$assertBoundParameterParameters = @{
    BoundParameterList = $PSBoundParameters
    MutuallyExclusiveList1 = @(
        'Parameter1'
    )
    MutuallyExclusiveList2 = @(
        'Parameter2'
    )
}
Assert-BoundParameter @assertBoundParameterParameters

This example throws an exception if $PSBoundParameters contains both the parameters Parameter1 and Parameter2.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange')

Throws an exception if either of the two parameters are not specified.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfParameterPresent @('Property1')

Throws an exception if the parameter 'Property1' is specified and either of the required parameters are not.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -RequiredBehavior 'Any'

Throws an exception if any of the two parameters are not present.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('PBStartPortRange', 'PBEndPortRange') -RequiredBehavior 'All'

Throws an exception if all of the specified parameters are not present.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -AtLeastOneList @('Severity', 'MessageId')

Throws an exception if none of the parameters 'Severity' or 'MessageId' are specified.

$assertBoundParameterParameters = @{
    BoundParameterList = $PSBoundParameters
    MutuallyExclusiveList1 = @(
        'Severity'
    )
    MutuallyExclusiveList2 = @(
        'MessageId'
    )
    IfParameterPresent = @{
        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.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -RequiredParameter @('Property2', 'Property3') -IfParameterPresent @{ Property1 = 'SpecificValue' }

Throws an exception if the parameter 'Property1' has the value 'SpecificValue' and either of the required parameters are not specified.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -AtLeastOneList @('Severity', 'MessageId') -IfParameterPresent @{ Ensure = 'Present' }

Throws an exception if the parameter 'Ensure' has the value 'Present' and none of the parameters 'Severity' or 'MessageId' are specified.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -NotAllowedList @('Parameter1', 'Parameter2')

Throws an exception if any of the parameters 'Parameter1' or 'Parameter2' are specified.

Assert-BoundParameter -BoundParameterList $PSBoundParameters -NotAllowedList @('Parameter1', 'Parameter2') -IfParameterPresent @{ Ensure = 'Absent' }

Throws an exception if the parameter 'Ensure' has the value 'Absent' and any of the parameters 'Parameter1' or 'Parameter2' are specified.

An array of parameter names where at least one must be bound.

Type: String[]
Parameter Sets: AtLeastOne
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

The parameters that should be evaluated against the mutually exclusive lists MutuallyExclusiveList1 and MutuallyExclusiveList2. This parameter is normally set to the $PSBoundParameters variable.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

One or more parameter names that if specified will trigger the evaluation. If neither of the parameter names has been specified the evaluation of required parameters are not made.

This parameter can also accept 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.

Type: Object
Parameter Sets: (All)
Aliases: IfEqualParameterList

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList2.

Type: String[]
Parameter Sets: MutuallyExclusiveParameters
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

An array of parameter names that are not allowed to be bound at the same time as those in MutuallyExclusiveList1.

Type: String[]
Parameter Sets: MutuallyExclusiveParameters
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

An array of parameter names that are not allowed to be bound.

Type: String[]
Parameter Sets: NotAllowed
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Whether RequiredParameter requires all or at least one parameter to be present.

Type: BoundParameterBehavior
Parameter Sets: RequiredParameter
Aliases:
Accepted values: All, Any

Required: False
Position: Named
Default value: All
Accept pipeline input: False
Accept wildcard characters: False

One or more parameter names that is required to have been specified.

Type: String[]
Parameter Sets: RequiredParameter
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.