Public/Show-ApiContext.ps1
|
function Show-ApiContext { <# .SYNOPSIS Generates an interactive, 100% offline browser-based API & Object Graph Explorer for PowerShell and VMware PowerCLI objects. .DESCRIPTION Part of the xDPsApiExplorer module by xDlabs (https://xdlabs.info). Show-ApiContext (aliases: Show-ApiGraph, sac) accepts any PowerShell or .NET object from the pipeline (such as VMware PowerCLI Get-View objects, ExtensionData, or standard .NET / PowerShell objects), inspects both its live runtime values and its .NET Reflection schema (even for $null properties) up to -MaxDepth (1..10), and opens a self-contained, zero-dependency interactive HTML explorer. Key Features: - 100% Offline Execution: No external CDNs or internet access required; safe for air-gapped datacenter/vSphere environments. - Live Instance + Reflected $null Schema: Displays live property values and reflects full .NET schemas for $null properties. - Embedded Broadcom vSphere SDK Documentation: Built-in descriptions for 4,880+ vSphere API types, properties, and methods. - Interactive Where-Object (?{ }) Filter Builder: Click '?' next to any property to build multi-condition PowerShell filters. - ManagedObjectReference (MoRef) Detection: Automatically highlights MoRef pointers and generates ready-to-run Get-View commands. - Pinned Boxes Dock: Pin up to 5 objects to the bottom-left dock for instant navigation across large object graphs. .PARAMETER InputObject The PowerShell or .NET object to inspect. Accepts pipeline input (e.g., $vm | Show-ApiContext). .PARAMETER MaxDepth Maximum traversal depth for nested complex objects (valid range: 1 to 10; default: 4). Array/collection indexing ([0], [1], ...) does not consume an extra depth level. .PARAMETER MaxCollectionItems Maximum number of elements sampled from each array or collection property (valid range: 1 to 50; default: 5). .PARAMETER RootName Optional root variable name displayed in generated PowerShell paths (e.g., '$vm'). When omitted, Show-ApiContext automatically infers the variable expression from the pipeline invocation. .PARAMETER ExcludeMethods If specified, skips collecting .NET and PSObject method signatures on inspected objects. .PARAMETER OutputPath Optional file path for the generated HTML report. Defaults to a timestamped file in the system temporary folder. .PARAMETER NoBrowser If specified, generates the HTML file without automatically launching the default web browser. .PARAMETER PassThru If specified, returns a summary object containing HtmlPath, RootName, RootType, MaxDepth, and the inspected NodeTree. .INPUTS System.Object You can pipe any PowerShell or .NET object to Show-ApiContext. .OUTPUTS None by default, or PSCustomObject when -PassThru is specified. .EXAMPLE $vm = Get-View -ViewType VirtualMachine -Filter @{ Name = 'prod-db-01' } $vm | Show-ApiContext -MaxDepth 6 Inspects a VMware vSphere VirtualMachine View object up to 6 levels deep and opens the interactive API Explorer in the default browser. .EXAMPLE (Get-VM 'prod-db-01').ExtensionData | sac -MaxDepth 5 Uses the 'sac' alias to inspect the ExtensionData property of a PowerCLI virtual machine. .EXAMPLE Get-Process -Id $PID | Show-ApiGraph -MaxDepth 3 Inspects the current PowerShell process object up to 3 levels deep. .EXAMPLE $report = $vm | Show-ApiContext -MaxDepth 4 -OutputPath 'C:\Reports\vm-api.html' -NoBrowser -PassThru Generates the offline HTML file at a custom path without opening a browser and returns the inspection metadata object. .LINK https://xdlabs.info #> [CmdletBinding()] [Alias('Show-ApiGraph', 'sac')] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)] [AllowNull()] [object]$InputObject, [Parameter(Mandatory = $false)] [ValidateRange(1, 10)] [int]$MaxDepth = 4, [Parameter(Mandatory = $false)] [ValidateRange(1, 50)] [int]$MaxCollectionItems = 5, [Parameter(Mandatory = $false)] [string]$RootName, [Parameter(Mandatory = $false)] [switch]$ExcludeMethods, [Parameter(Mandatory = $false)] [string]$OutputPath, [Parameter(Mandatory = $false)] [switch]$NoBrowser, [Parameter(Mandatory = $false)] [switch]$PassThru ) begin { $collectedItems = New-Object System.Collections.Generic.List[object] # Try to infer variable expression from pipeline invocation $inferredRootName = '$obj' try { $invLine = $MyInvocation.Line if ([string]::IsNullOrWhiteSpace($invLine)) { $lastHist = Get-History -Count 1 -ErrorAction SilentlyContinue if ($null -ne $lastHist) { $invLine = $lastHist.CommandLine } } if (-not [string]::IsNullOrWhiteSpace($invLine)) { # Match expression immediately before '| Show-ApiContext' / '| Show-ApiGraph' / '| sac' if ($invLine -match '(?:^|[=;])\s*(?<expr>\$[a-zA-Z0-9_:\.\[\]''"]+)\s*\|\s*(?:Show-ApiContext|Show-ApiGraph|sac)\b') { $inferredRootName = $Matches['expr'].Trim() } elseif ($invLine -match '(?<expr>\$[a-zA-Z0-9_:\.\[\]]+)\s*\|') { $inferredRootName = $Matches['expr'].Trim() } } } catch {} } process { $collectedItems.Add($InputObject) } end { if ($collectedItems.Count -eq 0) { Write-Warning "No input object provided to Show-ApiContext." return } $targetObj = if ($collectedItems.Count -eq 1) { $collectedItems[0] } else { $collectedItems.ToArray() } $effectiveRootName = if (-not [string]::IsNullOrWhiteSpace($RootName)) { if ($RootName.StartsWith('$')) { $RootName } else { "`$$RootName" } } else { $inferredRootName } $includeMethodsBool = -not $ExcludeMethods.IsPresent $nodeTree = ConvertTo-ApiNodeTree ` -InputObject $targetObj ` -Name $effectiveRootName ` -PsPath $effectiveRootName ` -MaxDepth $MaxDepth ` -CurrentDepth 0 ` -MaxCollectionItems $MaxCollectionItems ` -IncludeMethods $includeMethodsBool if ([string]::IsNullOrWhiteSpace($OutputPath)) { $outDir = Join-Path ([System.IO.Path]::GetTempPath()) 'xDPsApiExplorer' if (-not (Test-Path -LiteralPath $outDir)) { New-Item -ItemType Directory -Path $outDir -Force | Out-Null } $safeName = ($effectiveRootName -replace '[^a-zA-Z0-9_-]', '') if ([string]::IsNullOrWhiteSpace($safeName)) { $safeName = 'object' } $timestamp = Get-Date -Format 'yyyyMMdd_HHmmss' $OutputPath = Join-Path $outDir "ApiContext_${safeName}_${timestamp}.html" } else { $parentDir = Split-Path -Path $OutputPath -Parent if (-not [string]::IsNullOrWhiteSpace($parentDir) -and -not (Test-Path -LiteralPath $parentDir)) { New-Item -ItemType Directory -Path $parentDir -Force | Out-Null } } $htmlContent = New-ApiExplorerHtml -NodeTree $nodeTree -MaxDepth $MaxDepth -RootName $effectiveRootName [System.IO.File]::WriteAllText($OutputPath, $htmlContent, [System.Text.Encoding]::UTF8) if (-not $NoBrowser.IsPresent) { Start-Process -FilePath $OutputPath } if ($PassThru.IsPresent) { return [PSCustomObject]@{ HtmlPath = (Resolve-Path -LiteralPath $OutputPath).Path RootName = $effectiveRootName RootType = $nodeTree.FullTypeName MaxDepth = $MaxDepth NodeTree = $nodeTree } } } } |