Modules/M365DSCCompare.psm1
|
<#
.SYNOPSIS This module contains the comparison logic for M365DSC. Delegates to the C# ResourceComparer for all type normalization, primary-key alignment, and drift detection. #> <# .SYNOPSIS Compares the current state of a resource with the desired state and returns whether they match. .DESCRIPTION This function compares the current state of a resource with the desired state and returns whether they match. It also populates a global variable with detailed information about any drifts detected during the comparison. .PARAMETER ResourceName Specifies the name of the resource to compare. .PARAMETER DesiredValues Specifies a hashtable containing the desired values for the resource. .PARAMETER CurrentValues Specifies a hashtable containing the current values of the resource. .PARAMETER ExcludedProperties Specifies an array of property names to exclude from the comparison. .PARAMETER IncludedProperties Specifies an array of property names to include in the comparison. If specified, only these properties will be compared. .PARAMETER PostProcessing Specifies a script block or function that will be invoked after the initial comparison to allow for custom post-processing of the current and desired values. The script block should accept three parameters: DesiredValues, CurrentValues, and ValuesToCheck, and return a tuple containing the modified DesiredValues, CurrentValues, and ValuesToCheck. The comparison throws when the script block fails or does not return a tuple of three hashtables. .PARAMETER PostProcessingArgs Specifies an array of additional arguments to pass to the PostProcessing script block or function. .PARAMETER CompareRules Specifies the declarative compare rules applied before PostProcessing. .OUTPUTS Returns a boolean indicating whether the current state matches the desired state. #> function Compare-M365DSCResourceState { [CmdletBinding()] [OutputType([System.Boolean])] param ( [Parameter(Mandatory = $true)] [System.String] $ResourceName, [Parameter(Mandatory = $true)] [System.Collections.Hashtable] $DesiredValues, [Parameter(Mandatory = $true)] [System.Collections.Hashtable] $CurrentValues, [Parameter()] [System.String[]] $ExcludedProperties, [Parameter()] [System.String[]] $IncludedProperties, [Parameter()] [System.Func[System.Collections.Hashtable, System.Collections.Hashtable, System.Collections.Hashtable, [System.Object[]], System.Tuple[System.Collections.Hashtable, System.Collections.Hashtable, System.Collections.Hashtable]]] $PostProcessing, [Parameter()] [System.Object[]] $PostProcessingArgs = @(), [Parameter()] [System.Object[]] $CompareRules ) Initialize-M365DSCSchemaCache -ErrorAction Stop $Global:AllDrifts = @{ DriftInfo = @() CurrentValues = @{} DesiredValues = @{} } $Global:PotentialDrifts = @() $ValuesToCheck = $DesiredValues.Clone() if ($null -ne $CompareRules -and $CompareRules.Count -gt 0) { $logDrift = [System.Action[System.String]] { param($Message) Add-M365DSCEvent -Message $Message -EntryType 'Warning' -EventID 1 -Source $ResourceName } $rewritten = [Microsoft365DSC.Compare.CompareRule]::ApplyAll( [Microsoft365DSC.Compare.CompareRule]::ParseAll($CompareRules), $DesiredValues, $CurrentValues, $ValuesToCheck, [Microsoft365DSC.Cache.CacheManager]::Schema, $ResourceName, $logDrift) $DesiredValues = $rewritten.Item1 $CurrentValues = $rewritten.Item2 $ValuesToCheck = $rewritten.Item3 } # Apply custom post-processing callback if specified. # PostProcessing is a PowerShell Func delegate, so it must be called here (before entering C#). if ($null -ne $PostProcessing) { Write-Verbose -Message "Applying custom post-processing to CurrentValues and ValuesToCheck for resource $ResourceName" try { $result = $PostProcessing.Invoke($DesiredValues, $CurrentValues, $ValuesToCheck, $PostProcessingArgs) } catch { throw [System.InvalidOperationException]::new("PostProcessing failed for resource $($ResourceName): $($_.Exception.Message)", $_.Exception) } if ($null -eq $result -or $result.Item1 -isnot [System.Collections.Hashtable] -or $result.Item2 -isnot [System.Collections.Hashtable] -or $result.Item3 -isnot [System.Collections.Hashtable]) { throw [System.InvalidOperationException]::new("PostProcessing did not return a tuple of three hashtables for resource $ResourceName.") } $DesiredValues = $result.Item1 $CurrentValues = $result.Item2 $ValuesToCheck = $result.Item3 } if ($VerbosePreference -ne 'SilentlyContinue') { Write-Verbose -Message "Current Values: $(Convert-M365DscHashtableToString -Hashtable $CurrentValues)" Write-Verbose -Message "Target Values: $(Convert-M365DscHashtableToString -Hashtable $DesiredValues)" } # Delegate the entire comparison to C#. # ResourceComparer handles: schema lookup, key/credential exclusion, Ensure handling, # CimInstance/PSObject normalization (via ObjectNormalizer), primary-key alignment, # complex object comparison, and simple property comparison. $compareResult = [Microsoft365DSC.Compare.ResourceComparer]::Compare( $DesiredValues, $CurrentValues, $ValuesToCheck, [Microsoft365DSC.Cache.CacheManager]::Schema, $ResourceName, $ExcludedProperties, $IncludedProperties ) # Populate the global drift state from the C# result for downstream consumers # (event logging, telemetry, drift reporting). $testTargetResource = $compareResult.TestResult foreach ($drift in $compareResult.DriftInfo) { $Global:AllDrifts.DriftInfo += @{ PropertyName = $drift['PropertyName'] CurrentValue = $drift['CurrentValue'] DesiredValue = $drift['DesiredValue'] } if ($drift.ContainsKey('DeltaValue')) { $Global:AllDrifts.DriftInfo[-1]['DeltaValue'] = $drift['DeltaValue'] } } return $testTargetResource } Export-ModuleMember -Function Compare-M365DSCResourceState |