Compare ResourcePropertyState

Compare-ResourcePropertyState

SYNOPSIS

Compare current and desired property values for any DSC resource and return a hashtable with the metadata from the comparison.

SYNTAX

Compare-ResourcePropertyState [-CurrentValues] <Hashtable> [-DesiredValues] <Hashtable>
 [[-Properties] <String[]>] [[-IgnoreProperties] <String[]>] [[-CimInstanceKeyProperties] <Hashtable>]
 [<CommonParameters>]

DESCRIPTION

This function is used to compare current and desired property values for any DSC resource, and return a hashtable with the metadata from the comparison.

This introduces another design pattern that is used to evaluate current and desired state in a DSC resource. This command is meant to be used in a DSC resource from both Test and Set. The evaluation is made in Set to make sure to only change the properties that are not in the desired state. Properties that are in the desired state should not be changed again. This design pattern also handles when the command Invoke-DscResource is called with the method Set, which with this design pattern will evaluate the properties correctly.

Note

This design pattern is not widely used in the DSC resource modules in the DSC Community, the only known use is in SqlServerDsc. This design pattern can be viewed as deprecated, and should be replaced with the design pattern that uses the command Compare-DscParameterState.

See the other design patterns that uses the command Compare-DscParameterState or Test-DscParameterState.

EXAMPLES

EXAMPLE 1

$compareTargetResourceStateParameters = @{
    CurrentValues = (Get-TargetResource $PSBoundParameters)
    DesiredValues = $PSBoundParameters
}
$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters
$propertiesNotInDesiredState = $propertyState.Where({ -not $_.InDesiredState })

This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array of all the properties that was evaluated based on the properties pass in the parameter DesiredValues. Finally it sets a parameter $propertiesNotInDesiredState that contain an array with all properties not in desired state.

EXAMPLE 2

$compareTargetResourceStateParameters = @{
    CurrentValues = (Get-TargetResource $PSBoundParameters)
    DesiredValues = $PSBoundParameters
    Properties    = @(
        'Property1'
    )
}
$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters
$false -in $propertyState.InDesiredState

This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array with just the property Property1 as that was the only property that was to be evaluated. Finally it checks if $false is present in the array property InDesiredState.

EXAMPLE 3

$compareTargetResourceStateParameters = @{
    CurrentValues    = (Get-TargetResource $PSBoundParameters)
    DesiredValues    = $PSBoundParameters
    IgnoreProperties = @(
        'Property1'
    )
}
$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters

This example calls Compare-ResourcePropertyState with the current state and the desired state and returns a hashtable array of all the properties except the property Property1.

EXAMPLE 4

$compareTargetResourceStateParameters = @{
    CurrentValues    = (Get-TargetResource $PSBoundParameters)
    DesiredValues    = $PSBoundParameters
    CimInstanceKeyProperties = @{
        ResourceProperty1 = @(
            'CimProperty1'
        )
    }
}
$propertyState = Compare-ResourcePropertyState @compareTargetResourceStateParameters

This example calls Compare-ResourcePropertyState with the current state and the desired state and have a property ResourceProperty1 who's value is an array of embedded CIM instances. The key property for the CIM instances are CimProperty1. The CIM instance key property CimProperty1 is used to get the unique CIM instance object to compare against from both the current state and the desired state.

PARAMETERS

-CimInstanceKeyProperties

A hashtable containing a key for each property that contain a collection of CimInstances and the value is an array of strings of the CimInstance key properties. @{ Permission = @('State') }

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: @{}
Accept pipeline input: False
Accept wildcard characters: False

-CurrentValues

The current values that should be compared to to desired values. Normally the values returned from Get-TargetResource.

Type: Hashtable
Parameter Sets: (All)
Aliases:

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

-DesiredValues

The values set in the configuration and is provided in the call to the functions *-TargetResource, and that will be compared against current values. Normally set to $PSBoundParameters.

Type: Hashtable
Parameter Sets: (All)
Aliases:

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

-IgnoreProperties

An array of property names, from the keys provided in DesiredValues, that will be ignored in the comparison. If this parameter is left out, all the keys in the DesiredValues will be compared.

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

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

-Properties

An array of property names, from the keys provided in DesiredValues, that will be compared. If this parameter is left out, all the keys in the DesiredValues will be compared.

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

Required: False
Position: 3
Default value: None
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.Collections.Hashtable[]

NOTES

Returns an array containing a hashtable with metadata for each property that was evaluated.

Metadata Name	Type	Description
ParameterName	[System.String]	The name of the property that was evaluated
Expected	The type of the property	The desired value for the property
Actual	The type of the property	The actual current value for the property
InDesiredState	[System.Boolean]	Returns $true if the expected and actual value was equal.

RELATED LINKS