Private/ConvertTo-WinClatTestSummary.ps1
|
Function ConvertTo-WinClatTestSummary { <# .SYNOPSIS Summarizes the WinClat.TestResult rows of one computer. .DESCRIPTION Builds the WinClat.TestSummary object that Test-WinClat returns by default (DESIGN.md, sections 6 and 8.6): - Status: the first non-Success Status among the rows, or Success. - Overall, in order of precedence: NotApplicable when Status is NotSupported (Windows Server); Fail when any row failed; Warning when any row warned; Incomplete when the interface checks were skipped for lack of elevation; Pass when CLAT is translating; Ready when CLAT permitted, Prefix discovery valid, and Mode sanity all passed; otherwise Inactive. - Passed, Warnings, Failures: the number of rows with each Result. Info and Skipped rows are not counted. - Translating: $true when an 'Instance active' check passed, $false when it ran on at least one interface without passing, and $null when it did not run. - Issues: the checks with Result Fail or Warning, in row order and each once, as 'Check (InterfaceAlias)' or 'Check' for checks without an interface, joined with '; ', for example 'CLAT address (Internal); Functional test'. $null when there are none. - Note: why Overall is Incomplete, Ready, or Inactive, and the elevation note whenever the interface checks were skipped for elevation. $null otherwise. Runs on the calling computer only. .PARAMETER ComputerName The computer name as supplied by the caller. .PARAMETER InputObject The WinClat.TestResult rows for that computer. .INPUTS None. This function does not accept pipeline input. .OUTPUTS WinClat.TestSummary. .EXAMPLE ConvertTo-WinClatTestSummary -ComputerName 'CLIENT4' -InputObject $Rows Returns one summary object for CLIENT4. .LINK https://learn.microsoft.com/powershell/scripting/learn/deep-dives/everything-about-pscustomobject .NOTES Version: 1.1.0 Creation Date: October 28, 2026 Last Updated: November 12, 2026 Author: Richard Hicks Organization: Richard M. Hicks Consulting, Inc. Contact: rich@richardhicks.com Website: https://www.richardhicks.com/ #> [CmdletBinding()] [OutputType('WinClat.TestSummary')] Param ( [Parameter(Mandatory)] [string]$ComputerName, [Parameter(Mandatory)] [AllowEmptyCollection()] [object[]]$InputObject ) $Status = 'Success' $NonSuccess = @($InputObject | Where-Object -FilterScript { $_.Status -and $_.Status -ne 'Success' }) If ($NonSuccess.Count -gt 0) { $Status = $NonSuccess[0].Status } $Passed = @($InputObject | Where-Object -FilterScript { $_.Result -eq 'Pass' }).Count $Warnings = @($InputObject | Where-Object -FilterScript { $_.Result -eq 'Warning' }).Count $Failures = @($InputObject | Where-Object -FilterScript { $_.Result -eq 'Fail' }).Count $Translating = $null $InstanceRows = @($InputObject | Where-Object -FilterScript { $_.Check -eq 'Instance active' -and $_.Result -ne 'Skipped' }) If ($InstanceRows.Count -gt 0) { $Translating = @($InstanceRows | Where-Object -FilterScript { $_.Result -eq 'Pass' }).Count -gt 0 } # The test script skips every interface check with this Detail when the session is not elevated (DESIGN.md, section 8.6). $NotElevated = @($InputObject | Where-Object -FilterScript { $_.Result -eq 'Skipped' -and "$($_.Detail)" -like 'Interface checks require an elevated session*' }).Count -gt 0 # The configuration checks that must pass for CLAT to start on its own on an IPv6-only network. $ReadyChecks = @('CLAT permitted', 'Prefix discovery valid', 'Mode sanity') $NotReady = @(ForEach ($Check in $ReadyChecks) { If (@($InputObject | Where-Object -FilterScript { $_.Check -eq $Check -and $_.Result -eq 'Pass' }).Count -eq 0) { $Check } }) $Note = $null # Windows Server never receives WinCLAT, so its checks are not applicable rather than passed. If ($Status -eq 'NotSupported') { $Overall = 'NotApplicable' } ElseIf ($Failures -gt 0) { $Overall = 'Fail' } ElseIf ($Warnings -gt 0) { $Overall = 'Warning' } ElseIf ($NotElevated) { $Overall = 'Incomplete' } ElseIf ($Translating -eq $true) { $Overall = 'Pass' } ElseIf ($NotReady.Count -eq 0) { $Overall = 'Ready' $Note = 'CLAT is not active. It would start automatically on an IPv6-only network.' } Else { $Overall = 'Inactive' $Note = "CLAT is not active and would not start automatically on an IPv6-only network. Checks that did not pass: $($NotReady -join ', ')." } # Without elevation the result is incomplete whatever Overall is, so the reason is always given. If ($NotElevated -and $Status -ne 'NotSupported') { $Note = 'Interface checks require an elevated session, so whether CLAT is active or ready is not known. Run Test-WinClat elevated.' } # The failed and warning checks in row order, with the interface when there is one, as one string so the summary # stays flat for Export-Csv (DESIGN.md, section 8.6). $Issues = New-Object -TypeName 'System.Collections.Generic.List[string]' ForEach ($Row in @($InputObject | Where-Object -FilterScript { $_.Result -eq 'Fail' -or $_.Result -eq 'Warning' })) { $Name = [string]$Row.Check If ($Row.InterfaceAlias) { $Name = "$($Row.Check) ($($Row.InterfaceAlias))" } If (-not $Issues.Contains($Name)) { $Issues.Add($Name) } } $IssueText = $null If ($Issues.Count -gt 0) { $IssueText = $Issues.ToArray() -join '; ' } [PSCustomObject]@{ PSTypeName = 'WinClat.TestSummary' ComputerName = $ComputerName Status = $Status Overall = $Overall Passed = $Passed Warnings = $Warnings Failures = $Failures Translating = $Translating Issues = $IssueText Note = $Note } } |