Private/ConvertTo-ECMA2LocalDateTime.ps1

function ConvertTo-ECMA2LocalDateTime {
    <#
    .SYNOPSIS
        Converts a Microsoft Graph timestamp to a DateTime in the system's local time zone.

    .DESCRIPTION
        Internal function. Microsoft Graph returns timestamps as ISO 8601 UTC strings.
        PowerShell 7 deserializes them to a UTC DateTime, while Windows PowerShell 5.1
        leaves them as strings. This accepts either form (or a DateTimeOffset) and
        returns a DateTime of Kind Local, or $null when no value is supplied.

        Local DateTime values are for display. Don't compare them to order two
        timestamps: during the daylight-saving fall-back hour a later instant can have
        an earlier local clock time. Use -AsUtc to get the instant for comparisons.

    .PARAMETER Value
        The timestamp to convert: an ISO 8601 string, a DateTime, or a DateTimeOffset.

    .PARAMETER AsUtc
        Return the timestamp as a DateTime of Kind Utc instead of local time.

    .EXAMPLE
        ConvertTo-ECMA2LocalDateTime -Value '2026-01-01T00:00:00Z'

    .EXAMPLE
        ConvertTo-ECMA2LocalDateTime -Value '2026-01-01T00:00:00Z' -AsUtc
    #>

    [CmdletBinding()]
    [OutputType([datetime])]
    param(
        [Parameter()]
        [AllowNull()]
        [AllowEmptyString()]
        [object]$Value,

        [Parameter()]
        [switch]$AsUtc
    )

    if ($null -eq $Value) {
        return $null
    }

    # Normalize every accepted form to a UTC DateTime first
    $utc = $null

    if ($Value -is [datetime]) {
        # A timestamp with no kind came from Graph, which is always UTC
        if ($Value.Kind -eq [System.DateTimeKind]::Unspecified) {
            $utc = [datetime]::SpecifyKind($Value, [System.DateTimeKind]::Utc)
        }
        else {
            $utc = $Value.ToUniversalTime()
        }
    }
    elseif ($Value -is [System.DateTimeOffset]) {
        $utc = $Value.UtcDateTime
    }
    else {
        $text = [string]$Value
        if ([string]::IsNullOrWhiteSpace($text)) {
            return $null
        }

        $parsed = [System.DateTimeOffset]::MinValue
        $styles = [System.Globalization.DateTimeStyles]::AssumeUniversal
        if (-not [System.DateTimeOffset]::TryParse($text, [System.Globalization.CultureInfo]::InvariantCulture, $styles, [ref]$parsed)) {
            Write-Verbose "Could not parse '$text' as a timestamp"
            return $null
        }
        $utc = $parsed.UtcDateTime
    }

    # Graph reports "no value yet" (e.g. the end time of a run still in progress) as
    # 0001-01-01T00:00:00Z rather than null; treat that sentinel as no value
    if ($utc.Year -le 1) {
        return $null
    }

    if ($AsUtc) {
        return $utc
    }
    return $utc.ToLocalTime()
}