Test DscParameterState

Test-DscParameterState

SYNOPSIS

This command is used to test current and desired values for any DSC resource.

SYNTAX

Test-DscParameterState [-CurrentValues] <Object> [-DesiredValues] <Object> [[-Properties] <String[]>]
 [[-ExcludeProperties] <String[]>] [-TurnOffTypeChecking] [-ReverseCheck] [-SortArrayValues]
 [<CommonParameters>]

DESCRIPTION

This function tests the parameter status of DSC resource parameters against the current values present on the system.

This command was designed to be used in a DSC resource from only Test. The design pattern that uses the command Test-DscParameterState assumes that LCM is used which always calls Test before Set, or that there never is a need to evaluate the state in Set.

EXAMPLES

EXAMPLE 1

$currentState = Get-TargetResource @PSBoundParameters
$returnValue = Test-DscParameterState -CurrentValues $currentState -DesiredValues $PSBoundParameters

The function Get-TargetResource is called first using all bound parameters to get the values in the current state. The result is then compared to the desired state by calling Test-DscParameterState. The result is either $true or $false, $false if one or more properties are not in desired state.

EXAMPLE 2

$getTargetResourceParameters = @{
    ServerName     = $ServerName
    InstanceName   = $InstanceName
    Name           = $Name
}
$returnValue = Test-DscParameterState `
    -CurrentValues (Get-TargetResource @getTargetResourceParameters) `
    -DesiredValues $PSBoundParameters `
    -ExcludeProperties @(
        'FailsafeOperator'
        'NotificationMethod'
    )

This compares the values in the current state against the desires state. The function Get-TargetResource is called using just the required parameters to get the values in the current state. The parameter 'ExcludeProperties' is used to exclude the properties 'FailsafeOperator' and 'NotificationMethod' from the comparison. The result is either $true or $false, $false if one or more properties are not in desired state.

EXAMPLE 3

$getTargetResourceParameters = @{
    ServerName     = $ServerName
    InstanceName   = $InstanceName
    Name           = $Name
}
$returnValue = Test-DscParameterState `
    -CurrentValues (Get-TargetResource @getTargetResourceParameters) `
    -DesiredValues $PSBoundParameters `
    -Properties ServerName, Name

This compares the values in the current state against the desires state. The function Get-TargetResource is called using just the required parameters to get the values in the current state. The 'Properties' parameter is used to to only compare the properties 'ServerName' and 'Name'.

PARAMETERS

-CurrentValues

A hashtable with the current values on the system, obtained by e.g. Get-TargetResource.

Type: Object
Parameter Sets: (All)
Aliases:

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

-DesiredValues

The hashtable of desired values. For example $PSBoundParameters with the desired values.

Type: Object
Parameter Sets: (All)
Aliases:

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

-ExcludeProperties

This is a list of which properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-Properties

This is a list of properties in the desired values list should be checked. If this is empty then all values in DesiredValues are checked.

Type: String[]
Parameter Sets: (All)
Aliases: ValuesToCheck

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

-ReverseCheck

Indicates that a reverse check should be done. The current and desired state are swapped for another test.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-SortArrayValues

If the sorting of array values does not matter, values are sorted internally before doing the comparison.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-TurnOffTypeChecking

Indicates that the type of the parameter should not be checked.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

CommonParameters

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

INPUTS

OUTPUTS

[System.Boolean]

NOTES

RELATED LINKS