Private/Get-WinClatRpcFailure.ps1
|
Function Get-WinClatRpcFailure { <# .SYNOPSIS Explains a failed 'show instance' that reports the RPC server is unavailable. .DESCRIPTION netsh.exe reads instance state from the IP Translation Configuration Service (IPxlatCfgSvc). The service is trigger-started and stays stopped while CLAT has nothing to translate, and 'show instance' then fails with "The RPC server is unavailable." (DESIGN.md, section 10). 'show global' does not need the service. Returns $null when the netsh output does not contain that message. Otherwise returns an object with: - Idle: $true when IPxlatCfgSvc is stopped and not disabled, which means no CLAT instance exists. $false in every other case. - Message: for an idle service, a message saying there is no active instance and why. For a disabled service, the netsh message followed by a sentence saying the service is disabled. Otherwise, the netsh message. This function must also be available in the remote session. See DESIGN.md, section 4.3. .PARAMETER InputObject The output of the failed 'netsh interface clat show instance' command. .INPUTS None. This function does not accept pipeline input. .OUTPUTS System.Management.Automation.PSCustomObject with Idle and Message properties, or $null. .EXAMPLE Get-WinClatRpcFailure -InputObject $Output Returns Idle $true when $Output is "The RPC server is unavailable." and IPxlatCfgSvc is stopped with a Manual start type. .LINK https://learn.microsoft.com/powershell/module/microsoft.powershell.management/get-service .NOTES Version: 1.2.0 Creation Date: November 13, 2026 Last Updated: November 13, 2026 Author: Richard Hicks Organization: Richard M. Hicks Consulting, Inc. Contact: rich@richardhicks.com Website: https://www.richardhicks.com/ #> [CmdletBinding()] [OutputType([PSCustomObject])] Param ( [Parameter(Mandatory)] [AllowEmptyString()] [AllowEmptyCollection()] [string[]]$InputObject ) $Lines = @($InputObject | ForEach-Object -Process { $_ -split '\r?\n' } | ForEach-Object -Process { $_.Trim() } | Where-Object -FilterScript { $_ -ne '' }) $NetshMessage = $Lines -join ' ' If ($NetshMessage -notmatch 'The RPC server is unavailable') { Return $null } $Idle = $false $Message = $NetshMessage Try { $Service = Get-Service -Name 'IPxlatCfgSvc' -ErrorAction Stop If ("$($Service.StartType)" -eq 'Disabled') { $Message = "$NetshMessage The IP Translation Configuration Service (IPxlatCfgSvc) is disabled, so CLAT cannot start." } ElseIf ("$($Service.Status)" -eq 'Stopped') { $Idle = $true $Message = 'No active CLAT instance. The IP Translation Configuration Service (IPxlatCfgSvc) is not running, which is normal when CLAT has nothing to translate.' } } Catch { Write-Verbose -Message "The IP Translation Configuration Service (IPxlatCfgSvc) could not be read: $($_.Exception.Message)" } [PSCustomObject]@{ Idle = $Idle Message = $Message } } |