Compare DscParameterState

Compare-DscParameterState

SYNOPSIS

This method is used to compare current and desired values for any DSC resource.

SYNTAX

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

DESCRIPTION

This function compare the parameter status of DSC resource parameters against the current values present on the system, and return a hashtable with the metadata from the comparison.

Note

The content of the function Test-DscParameterState has been extracted and now Test-DscParameterState is just calling Compare-DscParameterState. This function can be used in a DSC resource from the Get function/method.

EXAMPLES

EXAMPLE 1

$currentValues = @{
    String = 'This is a string'
    Int = 1
    Bool = $true
}
$desiredValues = @{
    String = 'This is a string'
    Int = 99
}
Compare-DscParameterState -CurrentValues $currentValues -DesiredValues $desiredValues

The function Compare-DscParameterState compare the value of each hashtable based on the keys present in $desiredValues hashtable. The result indicates that Int property is not in the desired state. No information about Bool property, because it is not in $desiredValues hashtable.

EXAMPLE 2

$currentValues = @{
    String = 'This is a string'
    Int = 1
    Bool = $true
}
$desiredValues = @{
    String = 'This is a string'
    Int = 99
    Bool = $false
}
$excludeProperties = @('Bool')
Compare-DscParameterState `
    -CurrentValues $currentValues `
    -DesiredValues $desiredValues `
    -ExcludeProperties $ExcludeProperties

The function Compare-DscParameterState compare the value of each hashtable based on the keys present in $desiredValues hashtable and without those in $excludeProperties. The result indicates that Int property is not in the desired state. No information about Bool property, because it is in $excludeProperties.

EXAMPLE 3

$serviceParameters = @{
    Name     = $Name
}
$returnValue = Compare-DscParameterState `
    -CurrentValues (Get-Service @serviceParameters) `
    -DesiredValues $PSBoundParameters `
    -Properties @(
        'Name'
        'Status'
        'StartType'
    )

This compares the values in the current state against the desires state. The command Get-Service is called using just the required parameters to get the values in the current state. The parameter 'Properties' is used to specify the properties 'Name','Status' and 'StartType' for the comparison.

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

-IncludeInDesiredState

Indicates that result adds the properties in the desired state. By default, this command returns only the properties not in desired state.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-IncludeValue

Indicates that result contains the ActualValue and ExpectedValue properties.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
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.Object[]

NOTES

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

Metadata Name	Type	Description
Property	[System.String]	The name of the property that was evaluated
InDesiredState	[System.Boolean]	Returns $true if the expected and actual value was equal.
ExpectedType	[System.String]	Return the type of desired object.
ActualType	[System.String]	Return the type of current object.
ExpectedValue	[System.PsObject]	Return the value of expected object.
ActualValue	[System.PsObject]	Return the value of current object.

RELATED LINKS