Skip to content

Commit 3f759c0

Browse files
KirkMunroKirkMunro
committed
fixed support for the q debugger command to quit debugging when on an Enter-Debugger command breakpoint; added Debug-Module cmdlet; added Get-/Set-CommandDebugMode functions; simplified use of script variables for easier interaction with the binary module; updated documentation
1 parent 67c61a5 commit 3f759c0

12 files changed

+279
-158
lines changed

‎DebugPx.dll

4.5 KB
Binary file not shown.

‎DebugPx.psd1

+25-20
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ debugging capabilities in PowerShell (the callstack, breakpoints, error output
55
and the -Debug common parameter) and provide additional functionality that
66
these features do not provide, enabling a richer debugging experience.
77
8-
Copyright 2015 Kirk Munro
8+
Copyright 2016 Kirk Munro
99
1010
Licensed under the Apache License, Version 2.0 (the "License");
1111
you may not use this file except in compliance with the License.
@@ -23,65 +23,70 @@ limitations under the License.
2323
@{
2424
ModuleToProcess = 'DebugPx.psm1'
2525

26-
ModuleVersion = '1.0.1.9'
26+
ModuleVersion = '1.0.3.14'
2727

2828
GUID = '161b91e7-ca3d-40e2-8d0e-e00b31740f90'
2929

3030
Author = 'Kirk Munro'
3131

3232
CompanyName = 'Poshoholic Studios'
3333

34-
Copyright = 'Copyright 2015 Kirk Munro'
34+
Copyright = 'Copyright 2016 Kirk Munro'
3535

3636
Description = 'The DebugPx module provides a set of commands that make it easier to debug PowerShell scripts, functions and modules. These commands leverage the native debugging capabilities in PowerShell (the callstack, breakpoints, error output and the -Debug common parameter) and provide additional functionality that these features do not provide, enabling a richer debugging experience.'
3737

3838
PowerShellVersion = '3.0'
39-
39+
4040
NestedModules = @(
4141
'DebugPx.dll'
4242
'SnippetPx'
4343
)
4444

45-
CmdletsToExport = @(
46-
'Enter-Debugger'
47-
'Invoke-IfDebug'
48-
)
49-
50-
FunctionsToExport = @(
51-
'Disable-BreakpointCommand'
52-
'Enable-BreakpointCommand'
53-
'Get-CommandDebugMode'
54-
'Set-CommandDebugMode'
55-
)
56-
5745
AliasesToExport = @(
5846
'breakpoint'
5947
'bp'
6048
'dbpc'
49+
'dgmo'
50+
'Disable-BreakpointCommand'
6151
'ebpc'
52+
'Enable-BreakpointCommand'
6253
'gcmdm'
6354
'ifdebug'
6455
'scmdm'
6556
)
6657

58+
FunctionsToExport = @(
59+
'Disable-EnterDebuggerCommand'
60+
'Enable-EnterDebuggerCommand'
61+
'Get-CommandDebugMode'
62+
'Set-CommandDebugMode'
63+
)
64+
65+
CmdletsToExport = @(
66+
'Debug-Module'
67+
'Enter-Debugger'
68+
'Invoke-IfDebug'
69+
)
70+
71+
VariablesToExport = @()
72+
6773
FileList = @(
6874
'DebugPx.psd1'
6975
'DebugPx.psm1'
7076
'DebugPx.dll'
7177
'LICENSE'
7278
'NOTICE'
7379
'en-us\DebugPx.dll-Help.xml'
74-
'functions\Disable-BreakpointCommand.ps1'
75-
'functions\Enable-BreakpointCommand.ps1'
80+
'functions\Disable-EnterDebuggerCommand.ps1'
81+
'functions\Enable-EnterDebuggerCommand.ps1'
7682
'functions\Get-CommandDebugMode.ps1'
7783
'functions\Set-CommandDebugMode.ps1'
78-
'helpers\New-BreakpointCommandBreakpoint.ps1'
7984
'scripts\Export-BinaryModule.ps1'
8085
)
8186

8287
PrivateData = @{
8388
PSData = @{
84-
Tags = 'breakpoint debug debugger write-debug set-psbreakpoint'
89+
Tags = 'breakpoint','debug','debugger','write-debug','set-psbreakpoint'
8590
LicenseUri = 'http://apache.org/licenses/LICENSE-2.0.txt'
8691
ProjectUri = 'https://github.com/KirkMunro/DebugPx'
8792
IconUri = ''

‎DebugPx.psm1

+56-43
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ debugging capabilities in PowerShell (the callstack, breakpoints, error output
55
and the -Debug common parameter) and provide additional functionality that
66
these features do not provide, enabling a richer debugging experience.
77
8-
Copyright 2015 Kirk Munro
8+
Copyright 2016 Kirk Munro
99
1010
Licensed under the Apache License, Version 2.0 (the "License");
1111
you may not use this file except in compliance with the License.
@@ -20,17 +20,18 @@ See the License for the specific language governing permissions and
2020
limitations under the License.
2121
#############################################################################>
2222

23-
#region Initialize the module.
23+
[System.Diagnostics.DebuggerHidden()]
24+
param()
2425

25-
Invoke-Snippet -Name Module.Initialize
26+
#region Set up a module scope trap statement so that terminating errors actually terminate.
27+
28+
trap {throw $_}
2629

2730
#endregion
2831

29-
#region Import helper (private) function definitions.
32+
#region Initialize the module.
3033

31-
Invoke-Snippet -Name ScriptFile.Import -Parameters @{
32-
Path = Join-Path -Path $PSModuleRoot -ChildPath helpers
33-
}
34+
Invoke-Snippet -Name Module.Initialize
3435

3536
#endregion
3637

@@ -48,65 +49,77 @@ Invoke-Snippet -Name ScriptFile.Import -Parameters @{
4849

4950
#endregion
5051

51-
#region Define the breakpoints that are used by this module.
52-
53-
$Breakpoint = @{
54-
Command = New-BreakpointCommandBreakpoint
55-
}
52+
#region Set up a hashtable for module-local storage of Enter-Debugger command breakpoint metadata.
5653

57-
#endregion
54+
$EnterDebuggerCommandBreakpointMetadata = @{
55+
# A flag that tracks whether or not the condition was met (for conditional breakpointing)
56+
ConditionMet = $false
5857

59-
#region If we are not in an interactive session, disable the breakpoints by default.
58+
# The action that will be invoked when the breakpoint is hit
59+
Action = {
60+
[System.Diagnostics.DebuggerHidden()]
61+
param()
62+
if ($script:EnterDebuggerCommandBreakpointMetadata['ConditionMet']) {
63+
break
64+
}
65+
}
6066

61-
if (-not [System.Environment]::UserInteractive) {
62-
Disable-BreakpointCommand
67+
# An event handler that will re-create the breakpoints used by this script if they are manually removed
68+
OnBreakpointUpdated = {
69+
param(
70+
[System.Object]$sender,
71+
[System.Management.Automation.BreakpointUpdatedEventArgs]$eventArgs
72+
)
73+
if (($eventArgs.UpdateType -eq [System.Management.Automation.BreakpointUpdateType]::Removed) -and
74+
($eventArgs.Breakpoint.Id -eq $script:EnterDebuggerCommandBreakpointMetadata['Breakpoint'].Id)) {
75+
#region If the breakpoint command breakpoint was removed, re-create it and warn the user about the requirement.
76+
77+
$enabled = $eventArgs.Breakpoint.Enabled
78+
Write-Warning -Message "The breakpoint command breakpoint is required by the DebugPx module and cannot be manually removed. You can disable this breakpoint by invoking ""Disable-EnterDebuggerCommand"", or you can remove it by invoking ""Remove-Module -Name DebugPx"". This breakpoint is currently $(if ($enabled) {'enabled'} else {'disabled'})."
79+
$script:EnterDebuggerCommandBreakpointMetadata['Breakpoint'] = Set-PSBreakpoint -Command Enter-Debugger -Action $script:EnterDebuggerCommandBreakpointMetadata['Action'] -ErrorAction Stop
80+
if (-not $enabled) {
81+
Disable-EnterDebuggerCommand
82+
}
83+
84+
#endregion
85+
break
86+
}
87+
}
6388
}
6489

90+
# Add the breakpoint itself separately since it references the action which must already exist in the hashtable
91+
$EnterDebuggerCommandBreakpointMetadata['Breakpoint'] = Set-PSBreakpoint -Command Enter-Debugger -Action $script:EnterDebuggerCommandBreakpointMetadata['Action'] -ErrorAction Stop
92+
6593
#endregion
6694

67-
#region Define an event handler that will re-create the breakpoints used by this script if they are manually removed.
68-
69-
$OnBreakpointUpdated = {
70-
param(
71-
[System.Object]$sender,
72-
[System.Management.Automation.BreakpointUpdatedEventArgs]$eventArgs
73-
)
74-
if (($eventArgs.UpdateType -eq [System.Management.Automation.BreakpointUpdateType]::Removed) -and
75-
($eventArgs.Breakpoint.Id -eq $script:Breakpoint.Command.Id)) {
76-
#region If the breakpoint command breakpoint was removed, re-create it and warn the user about the requirement.
77-
78-
$enabled = $eventArgs.Breakpoint.Enabled
79-
Write-Warning "The breakpoint command breakpoint is required by the DebugPx module and cannot be manually removed. You can disable this breakpoint by invoking ""Disable-BreakpointCommand"", or you can remove it by invoking ""Remove-Module -Name DebugPx"". This breakpoint is currently $(if ($enabled) {'enabled'} else {'disabled'})."
80-
$script:Breakpoint['Command'] = New-BreakpointCommandBreakpoint
81-
if (-not $enabled) {
82-
Disable-BreakpointCommand
83-
}
95+
#region If we are not in an interactive session, disable the breakpoints by default.
8496

85-
#endregion
86-
break
87-
}
97+
if (-not [System.Environment]::UserInteractive) {
98+
Disable-EnterDebuggerCommand
8899
}
89100

90101
#endregion
91102

92103
#region Activate the OnBreakpointUpdated event handler.
93104

94-
$Host.Runspace.Debugger.add_BreakpointUpdated($OnBreakpointUpdated)
105+
$Host.Runspace.Debugger.add_BreakpointUpdated($EnterDebuggerCommandBreakpointMetadata['OnBreakpointUpdated'])
95106

96107
#endregion
97108

109+
#region Clean-up the module when it is removed.
110+
98111
$PSModule.OnRemove = {
99112
#region Deactivate the OnBreakpointUpdated event handler.
100113

101-
$Host.Runspace.Debugger.remove_BreakpointUpdated($OnBreakpointUpdated)
114+
$Host.Runspace.Debugger.remove_BreakpointUpdated($script:EnterDebuggerCommandBreakpointMetadata['OnBreakpointUpdated'])
102115

103116
#endregion
104117

105-
#region Remove any breakpoints that are used by this module.
118+
#region Remove the breakpoint that is used by this module.
106119

107-
foreach ($key in $Breakpoint.Keys) {
108-
Remove-PSBreakpoint -Breakpoint $Breakpoint.$key -ErrorAction Ignore
109-
}
120+
Remove-PSBreakpoint -Breakpoint $script:EnterDebuggerCommandBreakpointMetadata['Breakpoint'] -ErrorAction Ignore
110121

111122
#endregion
112-
}
123+
}
124+
125+
#endregion

‎NOTICE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
DebugPx
2-
Copyright 2014 Kirk Munro
2+
Copyright 2016 Kirk Munro
33

44
This product includes software developed by Kirk Munro (http://kirkmunro.com).

‎README.md

+6-5
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ these features do not provide, enabling a richer debugging experience.
1717

1818
### License and Copyright
1919

20-
Copyright 2014 Kirk Munro
20+
Copyright 2016 Kirk Munro
2121

2222
Licensed under the Apache License, Version 2.0 (the "License");
2323
you may not use this file except in compliance with the License.
@@ -66,10 +66,10 @@ unless you want it to take longer), and invoke one of the following commands:
6666
```powershell
6767
# If you want to install DebugPx for all users or update a version already installed
6868
# (recommended, requires elevation for new install for all users)
69-
& ([scriptblock]::Create((iwr -uri http://tinyurl.com/Install-GitHubHostedModule).Content)) -ModuleName DebugPx,SnippetPx
69+
& ([scriptblock]::Create((iwr -uri http://bit.ly/Install-ModuleFromGitHub).Content)) -ModuleName DebugPx,SnippetPx
7070
7171
# If you want to install DebugPx for the current user
72-
& ([scriptblock]::Create((iwr -uri http://tinyurl.com/Install-GitHubHostedModule).Content)) -ModuleName DebugPx,SnippetPx -Scope CurrentUser
72+
& ([scriptblock]::Create((iwr -uri http://bit.ly/Install-ModuleFromGitHub).Content)) -ModuleName DebugPx,SnippetPx -Scope CurrentUser
7373
```
7474

7575
### Using the DebugPx module
@@ -136,8 +136,9 @@ Note that the breakpoint command will only trigger breakpoints in interactive
136136
sessions. It will not trigger breakpoints in background jobs, scheduled tasks,
137137
etc. Also note that even when working interactively, you can choose when you
138138
want to trigger on the breakpoint command and when you do not, by invoking the
139-
Enable-BreakpointCommand or Disable-BreakpointCommand commands. By default the
140-
breakpoint command is enabled when DebugPx is loaded in an interactive session.
139+
Enable-EnterDebuggerCommand or Disable-EnterDebuggerCommand commands. By default
140+
the breakpoint command is enabled when DebugPx is loaded in an interactive
141+
session.
141142

142143
The other focus area for this module is debug logging. Since version 1,
143144
PowerShell has had a command for debug logging: Write-Debug. Write-Debug will

0 commit comments

Comments
 (0)