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