Add-Debugger.ps1
|
<#PSScriptInfo
.VERSION 2.3.1 .AUTHOR Roman Kuzmin .COPYRIGHT (c) Roman Kuzmin .TAGS Debug .GUID e187060e-ad39-425c-a6e3-b1e1e92ab59d .LICENSEURI http://www.apache.org/licenses/LICENSE-2.0 .PROJECTURI https://github.com/nightroman/PowerShelf #> <# .Synopsis Debugger for PowerShell hosts with no own debuggers. .Description The script adds or replaces existing debugger in any PowerShell runspace. It is useful for hosts with no own debuggers, e.g. bare runspace host "Default Host", Visual Studio NuGet console "Package Manager Host". Or it may replace existing debuggers, e.g. in "ConsoleHost". The script is called at any moment when debugging is needed. To restore the original debuggers, invoke Restore-Debugger defined by Add-Debugger. For output of debug commands the script uses Out-Host by default. If Out-Host is not suitable then specify Path for an output file. Use the switch ReadHost or ReadGui to specify the input method. By default it is ReadHost in console and ReadGui in other cases. .Parameter Path Specifies the output file used instead of Out-Host. A separate console is opened for watching its tail. Do not let this file to grow too large. Invoke `new` when watching gets slower. .Parameter Context Specifies the default numbers of context source lines to show. One or two integers, line numbers before and after the current. .Parameter Environment Specifies the user environment variable name for keeping the state. It is also used as the input box title. The state includes context line numbers and input box coordinates. .Parameter ReadGui Tells to use GUI input boxes for commands. .Parameter ReadHost Tells to use Read-Host or PSReadLine for commands input. PSReadLine should be imported and configured beforehand. .Example > # How to debug a bare runspace $ps = [PowerShell]::Create() $null = $ps.AddScript({ # add debugger with default options Add-Debugger # use this breakpoint or set custom Wait-Debugger }) $ps.Invoke() # or BeginInvoke() .Link https://github.com/nightroman/PowerShelf #> [CmdletBinding(DefaultParameterSetName='Main')] param( [Parameter(Position=0)] [string]$Path , [ValidateCount(1, 2)] [ValidateRange(0, 9999)] [int[]]$Context = @(0, 0) , [string]$Environment , [Parameter(ParameterSetName='ReadGui', Mandatory=1)] [switch]$ReadGui , [Parameter(ParameterSetName='ReadHost', Mandatory=1)] [switch]$ReadHost ) # All done? if (Test-Path Variable:\_Debugger) { return } # Removes and gets debugger handlers. function global:Remove-Debugger { $debugger = [runspace]::DefaultRunspace.Debugger $type = [System.Management.Automation.Debugger] $e = $type.GetEvent('DebuggerStop') $v = $type.GetField('DebuggerStop', ([System.Reflection.BindingFlags]'NonPublic, Instance')).GetValue($debugger) if ($v) { $handlers = $v.GetInvocationList() foreach($handler in $handlers) { $e.RemoveEventHandler($debugger, $handler) } $handlers } } # Restores original debugger handlers. function global:Restore-Debugger { if (!(Test-Path Variable:\_Debugger)) { return } $null = Remove-Debugger if ($_Debugger.Handlers) { foreach($handler in $_Debugger.Handlers) { [runspace]::DefaultRunspace.Debugger.add_DebuggerStop($handler) } } Remove-Variable _Debugger -Scope Global -Force } function global:Read-DebuggerState { param($Environment, $Context) $n, $m = $Context if ($null -eq $m) { $m = $n } $x = -1 $y = -1 if ($Environment) { if ($string = [Environment]::GetEnvironmentVariable($Environment, 'User')) { try { $b = New-Object System.Data.Common.DbConnectionStringBuilder $b.set_ConnectionString($string) $n = [int]$b['n'] $m = [int]$b['m'] $x = [int]$b['x'] $y = [int]$b['y'] } catch {} } } [PSCustomObject]@{n=$n; m=$m; x=$x; y=$y} } function global:Save-DebuggerState { if ($_Debugger.Environment) { $_ = $_Debugger.State $string = "n=$($_.n);m=$($_.m);x=$($_.x);y=$($_.y)" [Environment]::SetEnvironmentVariable($_Debugger.Environment, $string, 'User') } } ### Set debugger data. if (!$ReadHost -and !$ReadGui -and $Host.Name -eq 'ConsoleHost') { $ReadHost = $true } $null = New-Variable -Name _Debugger -Scope Global -Description Add-Debugger.ps1 -Option ReadOnly -Value @{ Path = $null Environment = $Environment State = Read-DebuggerState $Environment $Context Module = $null Args = $null Watch = $null History = [System.Collections.Generic.List[string]]@() Handlers = Remove-Debugger Action = '?' REIndent1 = [regex]'^(\s*)' REIndent2 = [regex]'^(\s+)(.*)' REContext = [regex]'^\s*(=)?\s*(\d+)\s*(\d+)?\s*$' UseAnsi = $PSVersionTable.PSVersion -ge ([Version]'7.2') PSReadLine = if ($ReadHost -and (Get-Module PSReadLine)) {Get-PSReadLineOption} } ### Define how to write debugger output. if ($Path) { $_Debugger.Path = $PSCmdlet.GetUnresolvedProviderPathFromPSPath($Path) function global:Write-Debugger { param($Data) if ($_Debugger.UseAnsi) { $OutputRendering = $PSStyle.OutputRendering $PSStyle.OutputRendering = 'ANSI' } $Data | Out-File -LiteralPath $_Debugger.Path -Encoding utf8 -ErrorAction 0 -Append if ($_Debugger.UseAnsi) { $PSStyle.OutputRendering = $OutputRendering } Watch-Debugger } } else { function global:Write-Debugger { param($Data) $Data | Out-Host } } ### Define how to read debugger input. if ($ReadHost -and $_Debugger.PSReadLine) { function global:Read-Debugger { param($Prompt, $Default) $_Debugger.q1 = $_Debugger.PSReadLine.HistorySaveStyle $_Debugger.PSReadLine.HistorySaveStyle = 'SaveNothing' Write-Host "${Prompt}: " -NoNewline try { PSConsoleHostReadline } finally { $_Debugger.PSReadLine.HistorySaveStyle = $_Debugger.q1 } } } elseif ($ReadHost) { function global:Read-Debugger { param($Prompt, $Default) Read-Host $Prompt } } else { function global:Read-Debugger { param($Prompt, $Default) $title = if ($_Debugger.Environment) {$_Debugger.Environment} else {'Add-Debugger'} Read-InputBox $Prompt $title $Default Step Continue $_Debugger.State Save-DebuggerState } } # Gets an input string from a dialog. function global:Read-InputBox { param($Prompt, $Title, $Default, $Text1, $Text2, $State) Add-Type -AssemblyName System.Windows.Forms $form = New-Object System.Windows.Forms.Form $form.Text = $Title $form.TopMost = $true $form.Size = New-Object System.Drawing.Size(400, 132) $form.FormBorderStyle = 'FixedDialog' if ($State -and $State.x -ge 0 -and $State.y -ge 0) { $form.StartPosition = 'Manual' $form.Location = New-Object System.Drawing.Point($State.x, $State.y) } else { $form.StartPosition = 'CenterScreen' } $label = New-Object System.Windows.Forms.Label $label.Location = New-Object System.Drawing.Point(10, 10) $label.Size = New-Object System.Drawing.Size(380, 20) $label.Text = $Prompt $form.Controls.Add($label) $text = New-Object System.Windows.Forms.TextBox $text.Text = $Default $text.Location = New-Object System.Drawing.Point(10, 30) $text.Size = New-Object System.Drawing.Size(365, 20) $form.Controls.Add($text) $ok = New-Object System.Windows.Forms.Button $ok.Location = New-Object System.Drawing.Point(225, 60) $ok.Size = New-Object System.Drawing.Size(75, 23) $ok.Text = $Text1 $ok.DialogResult = 'OK' $form.AcceptButton = $ok $form.Controls.Add($ok) $cancel = New-Object System.Windows.Forms.Button $cancel.Location = New-Object System.Drawing.Point(300, 60) $cancel.Size = New-Object System.Drawing.Size(75, 23) $cancel.Text = $Text2 $cancel.DialogResult = 'Continue' $form.Controls.Add($cancel) $form.add_Load({ $text.Select() $form.Activate() }) $result = $form.ShowDialog() if ($State) { $State.x = [Math]::Max(0, $form.Location.X) $State.y = [Math]::Max(0, $form.Location.Y) } if ($result -eq 'OK') { return $text.Text } if ($result -eq 'Continue') { return 'continue' } 'quit' } # Starts an external file viewer. function global:Watch-Debugger { param([switch]$New) if (($exe = $_Debugger.Watch) -and !$exe.HasExited) { if ($New) { try { $exe.Kill() } catch {} } else { return } } $path = $_Debugger.Path.Replace("'", "''") $app = if ($PSVersionTable.PSEdition -eq 'Core' -and (Get-Command pwsh -ErrorAction 0)) {'pwsh'} else {'powershell'} $_Debugger.Watch = Start-Process $app "-NoProfile -Command `$Host.UI.RawUI.WindowTitle = 'Debug output'; Get-Content -LiteralPath '$path' -Encoding UTF8 -Wait" -PassThru } # Writes the current invocation info. function global:Write-DebuggerInfo { param($InvocationInfo, $State) # write position message if ($_ = $InvocationInfo.PositionMessage) { Write-Debugger ($_.Trim()) } if (!$State.n -and !$State.m) { return } $file = $InvocationInfo.ScriptName if (!$file -or !(Test-Path -LiteralPath $file)) { return } # write file lines $markIndex = $InvocationInfo.ScriptLineNumber - 1 Write-DebuggerFile $file ($markIndex - $State.n) ($State.n + 1 + $State.m) $markIndex } # Writes the specified file lines. function global:Write-DebuggerFile { param($Path, $LineIndex, $LineCount, $MarkIndex) # amend negative start if ($LineIndex -lt 0) { $LineCount += $LineIndex $LineIndex = 0 } # content lines $lines = @(Get-Content -LiteralPath $Path -TotalCount ($LineIndex + $LineCount) -Force -ErrorAction 0) # leading spaces $re = $_Debugger.REIndent1 $indent = ($lines[$LineIndex .. -1] | .{process{ $re.Match($_).Groups[1].Value.Replace("`t", ' ').Length }} | Measure-Object -Minimum).Minimum if ($ansi = $_Debugger.UseAnsi) { $sMark = $PSStyle.Bold+$PSStyle.Background.Yellow $sLine = $PSStyle.Bold $sReset = $PSStyle.Reset } # write lines with a mark Write-Debugger '' $re = $_Debugger.REIndent2 do { $line = $lines[$LineIndex] if (($m = $re.Match($line)).Success) { $line = $m.Groups[1].Value.Replace("`t", ' ').Substring($indent) + $m.Groups[2].Value } $isMark = $LineIndex -eq $MarkIndex if ($isMark -and $ansi) { $line = "$sMark{0,4}:$sReset>> $sLine{1}$sReset" -f ($LineIndex + 1), $line } else { $mark = if ($isMark) {'>>'} else {' '} $line = '{0,4}:{1} {2}' -f ($LineIndex + 1), $mark, $line } Write-Debugger $line } while(++$LineIndex -lt $lines.Length) Write-Debugger '' } Add-Type @' using System; using System.Management.Automation; public class AddDebuggerHelpers { public ScriptBlock DebuggerStopProxy; public EventHandler<DebuggerStopEventArgs> DebuggerStopHandler { get { return OnDebuggerStop; } } void OnDebuggerStop(object sender, DebuggerStopEventArgs e) { SessionState state = ((EngineIntrinsics)ScriptBlock.Create("$ExecutionContext").Invoke()[0].BaseObject).SessionState; state.InvokeCommand.InvokeScript(false, DebuggerStopProxy, null, state.Module, e); } } '@ ### Add DebuggerStop handler. $AddDebuggerHelpers = New-Object AddDebuggerHelpers [runspace]::DefaultRunspace.Debugger.add_DebuggerStop($AddDebuggerHelpers.DebuggerStopHandler) $AddDebuggerHelpers.DebuggerStopProxy = { param($_module, $_args) # write breakpoints if ($_args.Breakpoints) {&{ Write-Debugger '' foreach($bp in $_args.Breakpoints) { if ($bp -is [System.Management.Automation.VariableBreakpoint] -and $bp.Variable -eq 'StackTrace') { Write-Debugger 'TERMINATING ERROR BREAKPOINT' } else { Write-Debugger "Hit $bp" } } }} # write debug location Write-DebuggerInfo $_args.InvocationInfo $_Debugger.State Write-Debugger '' # hide local variables $_Debugger.Module = $_module $_Debugger.Args = $_args Remove-Variable _module, _args -Scope 0 # REPL for() { ### prompt $_Debugger.LastAction = $_Debugger.Action $_Debugger.Action = Read-Debugger 'Step (h or ? for help)' $_Debugger.Action if ($_Debugger.Action) { $_Debugger.Action = $_Debugger.Action.Trim() } Write-Debugger "[DBG]: $($_Debugger.Action)" ### repeat if ($_Debugger.Action -eq '' -and ('s', 'StepInto', 'v', 'StepOver') -contains $_Debugger.LastAction) { $_Debugger.Action = $_Debugger.LastAction $_Debugger.Args.ResumeAction = if (('s', 'StepInto') -contains $_Debugger.Action) {'StepInto'} else {'StepOver'} return } ### Continue if (($null, 'c', 'Continue') -contains $_Debugger.Action) { $_Debugger.Args.ResumeAction = 'Continue' return } ### StepInto if (('s', 'StepInto') -contains $_Debugger.Action) { $_Debugger.Args.ResumeAction = 'StepInto' return } ### StepOver if (('v', 'StepOver') -contains $_Debugger.Action) { $_Debugger.Args.ResumeAction = 'StepOver' return } ### StepOut if (('o', 'StepOut') -contains $_Debugger.Action) { $_Debugger.Args.ResumeAction = 'StepOut' return } ### Quit if (('q', 'Quit') -contains $_Debugger.Action) { $_Debugger.Args.ResumeAction = 'Stop' return } ### Detach if (('d', 'Detach') -contains $_Debugger.Action) { if ($_Debugger.Handlers) { Write-Debugger 'd, Detach - not supported in this environment.' continue } $_Debugger.Args.ResumeAction = 'Continue' Restore-Debugger return } ### history if ('r' -eq $_Debugger.Action) { Write-Debugger $_Debugger.History continue } ### stack if ('k' -ceq $_Debugger.Action) { Write-Debugger (Get-PSCallStack | Format-Table Command, Location, Arguments -AutoSize) continue } if ('K' -ceq $_Debugger.Action) { Write-Debugger (Get-PSCallStack | Format-List) continue } ### <number> if ($_Debugger.REContext.IsMatch($_Debugger.Action)) { &{ $m = $_Debugger.REContext.Match($_Debugger.Action) $n1 = [int]$m.Groups[2].Value $n2 = [int]$(if ($m.Groups[3].Success) {$m.Groups[3].Value} else {$n1}) Write-DebuggerInfo $_Debugger.Args.InvocationInfo @{n=$n1; m=$n2} if ($m.Groups[1].Success) { $_Debugger.State.n = $n1 $_Debugger.State.m = $n2 Save-DebuggerState } } continue } ### new if ('new' -eq $_Debugger.Action -and $_Debugger.Path) { Remove-Item -LiteralPath $_Debugger.Path Write-Debugger (Get-Date) Watch-Debugger -New continue } ### help if (('?', 'h') -contains $_Debugger.Action) { Write-Debugger (@( '' ' s, StepInto Step to the next statement into functions, scripts, etc.' ' v, StepOver Step to the next statement over functions, scripts, etc.' ' o, StepOut Step out of the current function, script, etc.' ' c, Continue Continue operation.' if (!$_Debugger.Handlers) { ' d, Detach Continue operation and detach the debugger.' } ' q, Quit Stop operation and exit the debugger.' ' ?, h Write this help message.' ' k Write call stack (Get-PSCallStack).' ' K Write detailed call stack using Format-List.' '' ' n1 [n2] Write debug location in context of n lines.' ' = n1 [n2] Set location context preference to n lines.' ' k s n1 [n2] Write source at stack s in context of n lines.' '' ' r Write last commands invoked on debugging.' if ($_Debugger.Path) { ' new Remove output file and start watching new.' } ' <empty> Repeat the last command if it was StepInto, StepOver.' ' <command> Invoke any PowerShell <command> and write its output.' '' ) -join [System.Environment]::NewLine) continue } ### stack s n1 [n2] Set-Alias k debug_stack function debug_stack([Parameter()][int]$s, $n1, $n2) { $stack = @(Get-PSCallStack) if ($s -ge $stack.Count) { Write-Debugger 'Out of range of the call stack.' return } $stack = $stack[$s] if (!($file = $stack.ScriptName)) { Write-Debugger 'The caller has no script file.' return } if ($null -eq $n1) { $n1 = 5 $n2 = 5 } else { $n1 = [Math]::Max(0, [int]$n1) $n2 = [Math]::Max(0, $(if ($null -eq $n2) {$n1} else {[int]$n2})) } $markIndex = $stack.ScriptLineNumber - 1 Write-Debugger $file Write-DebuggerFile $file ($markIndex - $n1) ($n1 + 1 + $n2) $markIndex } ### invoke command $_Debugger.History.Remove($_Debugger.Action) $_Debugger.History.Add($_Debugger.Action) try { $_Debugger.q1 = [scriptblock]::Create($_Debugger.Action) $_Debugger.q2 = $global:Error.Count if ($_Debugger.Module) { $_Debugger.q1 = $_Debugger.Module.NewBoundScriptBlock($_Debugger.q1) } Write-Debugger (. $_Debugger.q1) if ($_Debugger.q2 -ne $global:Error.Count) { $_ = $global:Error[0] Write-Debugger $(if ($_.InvocationInfo.ScriptName) {$_} else {"ERROR: $_"}) } } catch { Write-Debugger $(if ($_.InvocationInfo.ScriptName) {$_} else {"ERROR: $_"}) } Write-Debugger '' } } |