| | | 1 | | <# |
| | | 2 | | .SYNOPSIS |
| | | 3 | | Configures a custom PowerShell scriptblock to build error responses for route execution failures. |
| | | 4 | | .DESCRIPTION |
| | | 5 | | Sets or clears a host-level custom PowerShell error response script. When configured, PowerShell |
| | | 6 | | route execution error paths invoke this scriptblock instead of the default WriteErrorResponseAsync |
| | | 7 | | behavior. If the custom script is not configured or fails, Kestrun falls back to the default behavior. |
| | | 8 | | .PARAMETER Server |
| | | 9 | | The Kestrun server instance. If omitted, the current server is resolved. |
| | | 10 | | .PARAMETER ScriptBlock |
| | | 11 | | Scriptblock invoked during PowerShell route error handling. The script runs in the request runspace |
| | | 12 | | and can use variables: $Context, $KrContext, $StatusCode, $ErrorMessage, and $Exception. |
| | | 13 | | .PARAMETER Clear |
| | | 14 | | Clears the currently configured custom PowerShell error response script. |
| | | 15 | | .PARAMETER WhatIf |
| | | 16 | | Shows what would happen if the cmdlet runs. The cmdlet is not run. |
| | | 17 | | .PARAMETER Confirm |
| | | 18 | | Prompts for confirmation before running the cmdlet. |
| | | 19 | | .EXAMPLE |
| | | 20 | | Set-KrPowerShellErrorResponse -ScriptBlock { |
| | | 21 | | Write-KrJsonResponse @{ error = $ErrorMessage; status = $StatusCode } -StatusCode $StatusCode |
| | | 22 | | } |
| | | 23 | | |
| | | 24 | | Configures a custom JSON error payload for PowerShell route execution errors. |
| | | 25 | | .EXAMPLE |
| | | 26 | | Set-KrPowerShellErrorResponse -Clear |
| | | 27 | | |
| | | 28 | | Clears the custom PowerShell error response script and restores default error handling. |
| | | 29 | | .NOTES |
| | | 30 | | Configure this before Enable-KrConfiguration. |
| | | 31 | | #> |
| | | 32 | | function Set-KrPowerShellErrorResponse { |
| | | 33 | | [KestrunRuntimeApi('Definition')] |
| | | 34 | | [CmdletBinding(DefaultParameterSetName = 'Set', SupportsShouldProcess = $true, ConfirmImpact = 'Low')] |
| | | 35 | | param( |
| | | 36 | | [Parameter(Mandatory = $false, ValueFromPipeline = $true)] |
| | | 37 | | [Kestrun.Hosting.KestrunHost]$Server, |
| | | 38 | | |
| | | 39 | | [Parameter(Mandatory = $true, ParameterSetName = 'Set')] |
| | | 40 | | [scriptblock]$ScriptBlock, |
| | | 41 | | |
| | | 42 | | [Parameter(Mandatory = $true, ParameterSetName = 'Clear')] |
| | | 43 | | [switch]$Clear |
| | | 44 | | ) |
| | | 45 | | |
| | | 46 | | process { |
| | 0 | 47 | | $Server = Resolve-KestrunServer -Server $Server |
| | | 48 | | |
| | 0 | 49 | | if ($Clear.IsPresent) { |
| | 0 | 50 | | if ($PSCmdlet.ShouldProcess("Kestrun server '$($Server.ApplicationName)'", 'Clear custom PowerShell error re |
| | 0 | 51 | | $Server.PowerShellErrorResponseScript = $null |
| | | 52 | | } |
| | | 53 | | return |
| | | 54 | | } |
| | | 55 | | |
| | 0 | 56 | | if ($PSCmdlet.ShouldProcess("Kestrun server '$($Server.ApplicationName)'", 'Set custom PowerShell error response |
| | 0 | 57 | | $Server.PowerShellErrorResponseScript = $ScriptBlock.ToString() |
| | | 58 | | } |
| | | 59 | | } |
| | | 60 | | } |