content/examples/sdk/powershell/14-diagnostics.ps1
|
# 14-diagnostics.ps1 - an "About / Support" window: capabilities, counters, support bundle. # # Teaches: Get-NativeHTMLKitCapabilities (feature detection), Get-NativeHTMLKitPreferences, # Get-NativeHTMLKitDiagnosticReport -Application (loss and failure counters), # Get-NativeHTMLKitDiagnostics (document CSS/resource notes), and # Export-NativeHTMLKitSupportBundle (a local, redacted ZIP - nothing is uploaded). # # Run: pwsh -File ./14-diagnostics.ps1 [-OutputFolder C:\Temp] # powershell.exe -NoProfile -File .\14-diagnostics.ps1 # Tip: start with -Diagnostics Trace on Start-NativeHTMLKitScript (or set # NATIVEHTMLKIT_DIAGNOSTICS=trace) to record callback and request timing in the bundle. # -SelfTest exports a bundle to a temporary folder, inspects it, and quits. param([string]$OutputFolder, [switch]$SelfTest) $ErrorActionPreference = 'Stop' Import-Module NativeHTMLKit $app = Start-NativeHTMLKitScript -Name 'Diagnostics' try { if ($SelfTest) { $OutputFolder = Join-Path ([IO.Path]::GetTempPath()) ('nhk-diag-' + [guid]::NewGuid().ToString('N')) $null = New-Item -ItemType Directory -Path $OutputFolder } if (-not $OutputFolder) { $OutputFolder = [IO.Path]::GetTempPath() } $window = New-NativeHTMLKitWindow -Application $app -Title 'About and support' -Width 760 -Height 640 $doc = Open-NativeHTMLKitHtml -Window $window -Html @' <!doctype html> <html><head><style> body { font-family: system-ui, sans-serif; margin: 18px; font-size: 14px; } h2 { font-size: 16px; margin: 18px 0 6px; } table { border-collapse: collapse; } td, th { text-align: left; padding: 2px 12px 2px 0; vertical-align: top; } td.yes { color: #2e7d32; } td.no { color: #8a1c1c; } #bundle { font-family: monospace; font-size: 12px; } </style></head> <body> <h2>Host</h2><table id="host"></table> <h2>Features</h2><table id="features"></table> <h2>Desktop preferences</h2><table id="prefs"></table> <h2>Connection counters</h2><table id="counters"></table> <h2>Support</h2> <p><button id="refresh">Refresh</button> <button id="export">Save support bundle</button></p> <p id="bundle" role="status"></p> </body></html> '@ # Top-level capability flag -> its entry in $caps.features (the host names drops differently). $script:featureKeys = [ordered]@{ clipboard_text = 'clipboard_text'; file_dialogs = 'file_dialogs'; external_open = 'external_open' drag_drop = 'incoming_drop'; ime = 'ime'; accessibility = 'accessibility' } function Get-FeatureState($Caps, [string]$Flag) { # The top-level flag says whether the host offers the API in this session. The feature # entry's 'available' is $true/$false when the host has observed the native service and # $null ("not observed") otherwise; on a native desktop Core 1.0.3 reports $null here. # $null is not $false. if (-not $Caps.$Flag) { return @{ Text = 'not available'; Usable = $false } } $entry = $null if ($null -ne $Caps.features) { $entry = $Caps.features.($script:featureKeys[$Flag]) } $available = $null if ($null -ne $entry) { $available = $entry.available } if ($null -eq $available) { return @{ Text = 'enabled (not observed)'; Usable = $true } } if ($available) { return @{ Text = 'available'; Usable = $true } } return @{ Text = 'unavailable'; Usable = $false } } function ConvertTo-Rows($Pairs) { # Values from the host are data: always encoded, never trusted as markup. $html = New-Object System.Text.StringBuilder foreach ($pair in $Pairs) { $value = $pair.Value $class = '' if ($value -is [bool]) { $class = ' class="no"'; if ($value) { $class = ' class="yes"' } } if ($null -eq $value) { $value = 'unknown' } [void]$html.Append('<tr><th>' + [Net.WebUtility]::HtmlEncode([string]$pair.Name) + "</th><td$class>" + [Net.WebUtility]::HtmlEncode([string]$value) + '</td></tr>') } return $html.ToString() } function Update-Diagnostics { $caps = Get-NativeHTMLKitCapabilities -Application $app $hostInfo = @( @{ Name = 'Platform'; Value = $caps.platform }, @{ Name = 'Native session'; Value = $caps.native }, @{ Name = 'Headless'; Value = $caps.headless }, @{ Name = 'Renderer'; Value = $caps.renderer }, @{ Name = 'CSS profile'; Value = $caps.css_profile }, @{ Name = 'Max windows'; Value = $caps.max_windows }, @{ Name = 'PowerShell'; Value = "$($PSVersionTable.PSEdition) $($PSVersionTable.PSVersion)" }, @{ Name = 'Module'; Value = [string](Get-Module NativeHTMLKit).Version }) Set-NativeHTMLKitDocumentHtml -Document $doc -Element host -Html (ConvertTo-Rows $hostInfo) $featureHtml = New-Object System.Text.StringBuilder foreach ($flag in $script:featureKeys.Keys) { $state = Get-FeatureState $caps $flag $class = 'no' if ($state.Usable) { $class = 'yes' } [void]$featureHtml.Append('<tr><th>' + [Net.WebUtility]::HtmlEncode($flag) + "</th><td class=`"$class`">" + [Net.WebUtility]::HtmlEncode($state.Text) + '</td></tr>') } Set-NativeHTMLKitDocumentHtml -Document $doc -Element features -Html $featureHtml.ToString() $prefs = Get-NativeHTMLKitPreferences -Application $app Set-NativeHTMLKitDocumentHtml -Document $doc -Element prefs -Html (ConvertTo-Rows @( @{ Name = 'Source'; Value = $prefs.source }, @{ Name = 'Colour scheme'; Value = $prefs.color_scheme }, @{ Name = 'Reduced motion'; Value = $prefs.reduced_motion }, @{ Name = 'High contrast'; Value = $prefs.high_contrast })) $report = Get-NativeHTMLKitDiagnosticReport -Application $app $counters = @(foreach ($p in $report.Connection.GetEnumerator()) { @{ Name = $p.Key; Value = $p.Value } }) $counters += @{ Name = 'SDK records (dropped)'; Value = "$($report.RecordCount) ($($report.DroppedRecords))" } $notes = @((Get-NativeHTMLKitDiagnostics -Document $doc).diagnostics).Count $counters += @{ Name = 'Document diagnostics'; Value = $notes } Set-NativeHTMLKitDocumentHtml -Document $doc -Element counters -Html (ConvertTo-Rows $counters) return $report } function Export-Bundle { $file = Join-Path $OutputFolder ('nativehtmlkit-support-' + (Get-Date).ToString('yyyyMMdd-HHmmss') + '.zip') try { $item = Export-NativeHTMLKitSupportBundle -Path $file -Application $app Set-NativeHTMLKitDocumentText -Document $doc -Element bundle -Text ('Saved ' + $item.FullName + ' (' + $item.Length + ' bytes). Attach it to a bug report.') return $item } catch { Set-NativeHTMLKitDocumentText -Document $doc -Element bundle -Text ('Could not save the bundle: ' + $_.Exception.Message) } } $null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element refresh -Callback { $null = Update-Diagnostics } $null = Register-NativeHTMLKitDocumentEvent -Document $doc -Type click -Element export -Callback { $null = Export-Bundle } $null = Update-Diagnostics Set-NativeHTMLKitReady -Application $app if ($SelfTest) { $report = Update-Diagnostics if ($report.Connection.CallbackFailures -ne 0) { throw 'no callback should have failed' } if ((Find-NativeHTMLKitElement -Document $doc -Selector '#features tr').matched_nodes -ne 6) { throw 'feature table incomplete' } # The shape a native desktop reports (Core 1.0.3): top-level flags true, availability null. $native = [pscustomobject]@{ clipboard_text = $true; file_dialogs = $true; external_open = $true; drag_drop = $true; ime = $true; accessibility = $true features = [pscustomobject]@{ clipboard_text = [pscustomobject]@{ available = $null }; file_dialogs = [pscustomobject]@{ available = $null } external_open = [pscustomobject]@{ available = $null }; incoming_drop = [pscustomobject]@{ available = $false } ime = [pscustomobject]@{ available = $null }; accessibility = [pscustomobject]@{ available = $null } } } if ((Get-FeatureState $native 'file_dialogs').Text -ne 'enabled (not observed)') { throw 'null availability must not be reported as unavailable' } if ((Get-FeatureState $native 'drag_drop').Text -ne 'unavailable') { throw 'drag_drop must read features.incoming_drop' } $caps = Get-NativeHTMLKitCapabilities -Application $app $expected = (@($script:featureKeys.Keys | ForEach-Object { $_ + (Get-FeatureState $caps $_).Text }) -join '') if ((Get-NativeHTMLKitDocumentText -Document $doc -Element features) -ne $expected) { throw 'feature rows do not match the capabilities' } $item = Export-Bundle if ($null -eq $item -or -not (Test-Path -LiteralPath $item.FullName)) { throw 'bundle not written' } Add-Type -AssemblyName System.IO.Compression.FileSystem $zip = [IO.Compression.ZipFile]::OpenRead($item.FullName) try { $names = @($zip.Entries | ForEach-Object { $_.FullName } | Sort-Object) } finally { $zip.Dispose() } if (($names -join ',') -ne 'manifest.json,timeline.jsonl') { throw "unexpected bundle entries: $($names -join ',')" } Remove-Item -LiteralPath $OutputFolder -Recurse -Force [Console]::Out.WriteLine('SELFTEST PASS 14-diagnostics') $null = Request-NativeHTMLKitQuit -Application $app } Wait-NativeHTMLKit -Application $app -UntilShutdown } finally { Close-NativeHTMLKit -Application $app } |