PowerShell debugging, amplified

This article is about the PowerShell module that I am most proud of and that I have personally found more useful than any other module I have created.  I hope that you enjoy it as much as I do.

Every programming language must be designed with debugging in mind, and PowerShell is no exception.  No matter who you are, no matter how well you know the language, you will inevitably come across something that isn’t working like it should.  What you do in these situations depends on your comfort level with programming and debugging.  For some, this means adding lines to the code that produce extra output so that they can get a handle on what is going on.  For others, this means rolling up the sleeves and stepping through the code in a debugger.  And there are others still who aren’t comfortable enough with programming or debugging, so they turn to others for assistance.  Regardless of which of these approaches you would take, I believe I have a module that can help.

DebugPx is a free, open source PowerShell module that was designed to make it easier to troubleshoot problems in PowerShell code.  It comes with two core commands: breakpoint and ifdebug.  It also includes a few helpful utility commands to control how the breakpoint command works.  The core commands are described as follows:

breakpoint The breakpoint command is used to trigger a breakpoint at the current location.  By default, the breakpoint command causes Windows PowerShell to immediately enter the debugger whenever it is invoked in an interactive session.  If it is invoked with its optional ConditionScript parameter, it will only trigger the breakpoint if the script block expression that was provided for the ConditionScript parameter evaluates to true.  It also accepts an optional string Message parameter, and it will write the message provided to this parameter to the current host whenever the breakpoint is triggered.

The ifdebug command is used to identify a block of PowerShell script that you only want to run in one of two scenarios: when you invoke a command with -Debug, or when the $DebugPreference variable is set to anything either than SilentlyContinue or Ignore.

Both of these commands are very powerful and they can make troubleshooting problems in PowerShell scripts a lot easier.  Let me provide some background details so that you understand the problems that these commands solve, problems that still exist in PowerShell 5.0 today.

PowerShell version 1.0 did not come with breakpoint support.  It had a debugger, and that debugger is still useful today, even though a new debugger has been in PowerShell since version 2.0.  It had a -Debug common parameter that was available on every cmdlet and, since version 2.0 of PowerShell, on every advanced function as well.  It had a $DebugPreference built-in variable.  It also had a Write-Debug cmdlet that allowed you to have some level of debugger control over your scripts.  The behaviour of the Debug common parameter, $DebugPreference and how those affect Write-Debug behaviour is quite interesting, and once you understand how those work together, you may see why their implementation leaves some opportunities on the table.

When you invoke a cmdlet or an advanced function with the -Debug common parameter, PowerShell internally sets the $DebugPreference variable value to Inquire within the scope of that command.  As far as PowerShell preference variables go, a value of Inquire means that PowerShell will prompt the user to ask if they want to continue the execution of the associated command, stop the associated command immediately, or enter a the debugger at that point, allowing the user to invoke PowerShell commands to troubleshoot the system.  This behaviour seems like it was designed to fill the void when PowerShell did not have breakpoints, because it allowed scripters to enter the debugger as long as they threw a few Write-Debug commands into their scripts.

The problem with this approach is that it tries to do too many things and mixes up several distinct needs in the process.  The ability to write debug information to the debug stream during script execution, and the ability to enter the debugger on a breakpoint at a specific location in a script are two distinct needs that are mashed together when they shouldn’t be.  Another limitation with this approach is that scripters can’t simply change the way a script is invoked in order to gather additional debug information from an environment where they aren’t able to debug with breakpoints as easily, because using -Debug meant prompting the user every time Write-Debug would be called, and often you’re trying to help a user who is having a problem in this scenario, not confuse them by asking them to continue a bunch of Write-Debug calls while telling you what is happening.  Yet another limitation with this approach is that there is no easy way to include PowerShell commands inside of an advanced function or script that will only execute when you are debugging, allowing a command or script author to include support for generating debug output but only when that command or script is invoked with -Debug.

When breakpoints were later added along with a new debugger in PowerShell 2.0, PowerShell script authors were suddenly able to set breakpoints in their scripts, either visually using PowerShell ISE or for conditional breakpoints, command breakpoints, or variable breakpoints using the Set-PSBreakpoint cmdlet.  This functionality solved the need for breakpoints, and it started the separation of the need to enter the debugger from the need to be able to write debug output; however, the -Debug common parameter behaviour didn’t change, so there still wasn’t a good vehicle for writing information to the debug stream without any requirement for user interaction during the process.  Also, while this breakpoint functionality was useful, it came with its own share of limitations.  If you were working in an environment other than PowerShell ISE that didn’t have visual support for setting PowerShell breakpoints (such as notepad++, sublime text, or some other awesome editor), you simply had no choice but to work with the Set-PSBreakpoint cmdlet, which isn’t a very friendly way to set breakpoints in PowerShell, putting it mildly.  Also, if you were debugging PowerShell code across multiple sessions, you would have to reset your breakpoints every time, either manually or using a profile or some other script, none of which is very practical.

DebugPx was designed to solve almost all of these problems with the breakpoint and ifdebug commands.  With the DebugPx module installed and discoverable via the PSModulePath environment variable, you can trigger a breakpoint at a specific location by simply invoking the breakpoint command (or the bp alias, for short).  These breakpoints are identifiable in any editor because you can see the commands in the files where they are used.  They work in unsaved files.  They even work in an interactive PowerShell prompt, or inside of a block that you run in PowerShell using copy/paste, or inside of a block that you select in ISE and run by using the Run Selection (F8) feature.  They are properly ignored if they are inside of a function that uses the System.Diagnostics.DebuggerHidden attribute.  They are conditional if you invoke them with a condition script block (which would map to the first, ConditionalScript parameter), or unconditional otherwise.  They can be globally enabled or disabled using the Enable-BreakpointCommand or Disable-BreakpointCommand commands.  They will only cause PowerShell to enter the debugger if they are encountered in an interactive session.  And if you want a message to be displayed when the breakpoint activates (for example, as a reminder why you wanted to break when that obscure scenario that you previously couldn’t catch occurs), you can pass a message to the -Message parameter and the breakpoint will output the message to the host when the breakpoint is triggered.

If you are debugging in other scenarios, where you may not be able to use the breakpoint command to enter a debugger because you are not in an interactive session (such as in background jobs, scheduled tasks, Azure Automation or Service Management Automation scripts, or perhaps in a remote customer’s environment), you can include rich debug information inside of an ifdebug command script block, and anything that is output from inside of that script block will automatically be written to the debug stream without prompting the end user.  This includes object data, text strings, or anything else you want to write to the debug stream in order to figure out what is going on when that script runs.  If the command containing ifdebug is not invoked with -Debug, PowerShell will simply skip directly over that script block, avoiding running debug logic when it is not needed, which is better for performance.

Both the breakpoint command and ifdebug can be used in the middle of a pipeline as well.  This is important because it allows for writing debug information to the debug stream or triggering a breakpoint in the middle of a pipeline during the processing of that pipeline.  If you use the breakpoint command in a pipeline and you either have the breakpoint command disabled or you are in a script block with the DebuggerHidden attribute set, or if you use the ifdebug command in a pipeline and you didn’t run the script with -Debug, both the breakpoint and the ifdebug commands will simply pass the pipeline object down to the next stage in the pipeline for additional processing.

At this point, you’re probably getting a feeling for the kind for the power that these commands provide.  Let me show you a few simple examples that demonstrate how you might use them in practice.  You can try these examples at the command prompt in the PowerShell host of your choice, or in a script file, or in functions you write, or script module files, or workflows, etc.

Enter the debugger in the middle of a series of commands

$services = Get-Service wuauserv,bits
Restart-Service -InputObject $services -WhatIf

Enter the debugger conditionally in the middle of a pipeline (using the bp alias)

gsv audiosrv,bits,wuauserv | bp {$_.Name -eq ‘bits’} | spsv -WhatIf

Display a message as you enter the debugger reminding you why you are doing so

Get-Process -Name Idle,PowerShell,Explorer |
breakpoint {$_.Id -eq 0} -Message ‘Process ID is zero???’ |

Disable the breakpoint command so that you can run without debugging

gsv audiosrv,bits,wuauserv | breakpoint {$_.Name -eq ‘bits’} | spsv -WhatIf
‘See, the breakpoint command did not cause PowerShell to enter the debugger!’

Re-enable the breakpoint command so that it functions normally again


Skip over breakpoints in a script block by using the DebuggerHidden attribute

& {
    ‘The breakpoint command is effectively disabled in the current scope.’
‘But it still works in scopes that do not use the DebuggerHidden attribute.’

Create a function that generates some useful debug information

function Test-IfDebug {
    ifdebug {
        # This may be useful when debugging, but I wouldn’t want to gather
        # this information in everyday use. It is an exaggerated example of
        # what you might want to collect when debugging something.

        ‘*************** Current Operating System ***************’
        Get-WmiObject -Class Win32_OperatingSystem | Format-List *
        ‘*************** Running Services ***************’
        Get-Service | Format-List *
        ‘*************** Running Processes ***************’
        Get-Process | Format-List *
    Get-Service w*

Invoke that function without debugging


Invoke that function with debug output turned on

Test-IfDebug -Debug

Compare the performance of the two

Measure-Command {Test-IfDebug}
Measure-Command {Test-IfDebug –Debug}

I think those examples provide a good demonstration of how these commands work.  As I hinted at earlier in this article, I am super-excited about this module and I’m thrilled that I can share it with you now.  If you want to give it a try, install the latest version in your environment by following the instructions on the DebugPx project page on GitHub.  I have a few more features planned for this debugging toolkit, and I would be very happy to entertain your ideas as well, so please let me know what you think!  Have fun debugging!

Kirk out.

Categories: Powershell

Make working with types in PowerShell easier with TypePx

It is often the little things in life that make a big difference.


Isn’t that a beautiful programming example? That wasn’t a heading you just read, it was a piece of code. It’s simple, it’s very expressive, it’s self-documenting, and it’s pretty hard to misunderstand the intent when you look at it.  That’s not PowerShell code though…it’s Ruby.

Over the past year or so I have taken some MOOCs offered by Coursera and edX.  After playing games that I created for my assignments in Python, I started learning more about Ruby.  Ruby is a wonderful, expressive, dynamic programming language with a vibrant community that has a lot in common with PowerShell.  It also offers more functionality than PowerShell does in some areas, and I started missing some of that expressive syntax that I was able to use in Ruby when I would switch back to working in PowerShell.

Here’s how you can accomplish the same task natively in PowerShell:


It doesn’t offer quite the same punch, does it?  Between all of the brackets, the need to call out to Get-Date, and adding negative days to be able to get a timestamp representing 1 week ago, it just isn’t quite as palatable to me.

The beauty of a more mature language like Ruby is that it’s not just about the availability of a week method for numeric classes, nor the availability of an ago method for a time span class.  It’s the availability of years, months, weeks, days, hours, minutes, seconds and milliseconds, all in singular or plural.  It’s the availability of ago to refer to a date in the past, or fromnow to refer to a date in the future.  Want UTC instead of local time?  There’s a inutc method too, as well as so many other cool things.  Small details matter.

Fortunately, like Ruby, PowerShell is also a dynamic language that has all sorts of extensibility built-in, allowing me to continue to enjoy expressive, Ruby-like syntax, even while working in PowerShell.  I know PowerShell’s extensibility quite well, and have been leveraging it since version 1.  These Ruby features inspired me to create a new PowerShell module, bringing some of the method simplicity, elegance, and usefulness from Ruby into PowerShell for the rest of the PowerShell community to enjoy.  I called it TypePx.  It’s open source, and it defines useful type extensions and simplifies type acceleration to reduce much of the typing that would otherwise be required when working with types in PowerShell.  Also, it works on PowerShell 3.0 or later, and it’s available now.

Here are examples of some of the beautiful things you can do with TypePx:

# Get a timespan in a human readable way

# Use relative dates, as mentioned above

# How about using relative dates in a practical way with event logs?
Get-EventLog -LogName System -After (2).Days.Ago
# You can use it when monitoring file age too
dir *.ps*1 | where LastWriteTime -lt (1).year.ago

# Compact (remove null values) from an array
$a = 1,$null,2,$null,3
# Return unique elements in an array
$a = 1,1,2,3,3,4,4,5,6
# Reverse an array
$a = 1,2,3,4
# Slice an array into chunks
$a = 1,2,3,4,5,6
# Flatten a multi-dimensional array
$a = (1,2),(3,4),(5,6)

These are only a few examples of what you can do with TypePx.  Have you ever worked with hashtables and noticed how annoying collection management is when it comes to hashtable values?  June Blender was looking for a solution to this the other day, and TypePx solves that problem.

$ht = @{}
$ht.Add(‘A’,’This is not a collection’)
$ht.AddArrayItem(‘B’,’This is a collection’)
$ht.AddArrayItem(‘B’,’This adds to the collection’)

By now you have probably seen the cool foreach and where “magic” methods that were added to PowerShell as part of version 4.0.  What about version 3.0 though?  TypePx solves that problem too by adding foreach and where methods to PowerShell 3.0 with all of the bells and whistles that are available in PowerShell 4.0.

Here are a handful of other problems that TypePx makes easier:

  • comparing an array to multiple search strings at the same time in a single call;
  • comparing a string to multiple search strings at the same time in a single call;
  • calculating the sum of an array or of a property on a collection of items;
  • accessing the value hidden inside of a SecureString;

TypePx isn’t just about type extensions either.  It’s also about type acceleration.  In fact, it was originally released as my old TypeAccelerator module that I had previously shared on PowerShell Magazine and posted in the PowerShell Resource Gallery, but then I renamed it and included full documentation for the *-TypeAccelerator commands as well as all of the type extension goodness I described above.  Type acceleration support is a great way to improve the quality of your PowerShell code when you are working with long type names.  Rather than explain it here though, you might want to give my article on PowerShell Magazine a read if you haven’t already since it explains what type acceleration is in more detail and gives examples that show why you might want to know more about it.

To download the latest version of TypePx, please refer to the installation instructions in the readme documentation on GitHub.

That wraps up this article.  Please let me know what you think in the comments!

Now if only PowerShell would properly recognize numeric literals as objects so that you could invoke methods and access properties on them without having to use brackets…

Kirk out.

Categories: Powershell

Watch this space

In case you were wondering, I’m still here.  I’ve just been busy working on all kinds of interesting things, and I’m getting geared up to start sharing the results of that work very, very soon.  Watch this space.

Categories: Powershell

PowerShell Tools for Visual Studio – Now 100% more free!

Adam Driscoll's Blog - Mon, 18-Aug-14 19:28

Recently, the Python Tools for Visual Studio team released support for Visual Studio Express 2013. After emailing the team, I found that there is a white list of extensions that are allowed to be installed in Express. Unfortunately, this is an internal Microsoft process and not available to external developers. Although this was a bummer, they pointed me once again towards the Visual Studio Isolated and Integrated Shell. I had previously experimented with the Isolated Shell with little luck and didn’t pursue it until a nudge from the PyTools team. Rather than having to create an entire Isolated Shell environment, you can instead download and install the Integrated Shell. It provides the entry point to launch the components provided by the Isolated Shell. It certainly was confusing to me but I gave it a shot. Success! You can download and install both the Isolated and Integrated Shells and then install PowerShell Tools for Visual Studio. 100% free!

Installation Steps

1. Download and Install the Isolated Shell
2. Download and Install the Integrated Shell
3. Open Extensions and Updates…
4. Install PowerShell Tools for Visual Studio

Black magic:


So far, it looks like there are a couple features that aren’t working quite correctly.

- Debugging doesn’t seem to work as expected. This really limits the functionality and I’ll be looking into it.
- No built in source control integration. This sucks but is just a limitation of Isolated Shell. There are extensions for Git and SVN available on the gallery.

Otherwise, things stuff as IntelliSense, REPL, Syntax Highlighting and the project system seem to be behaving.

Feel free to try it out and look forward to updates in the near future.

Categories: Powershell

PowerShell Tools – v0.8.0 – Now with REPL!

Adam Driscoll's Blog - Sun, 15-Jun-14 16:19

Today, I’m announcing the release of PowerShell Tools for Visual Studio v0.8.0. There are some important installation changes in this version and I want to make sure people are aware. You can download the latest on the Gallery (2012\2013) or via GitHub.

Installation Changes – Important!

The extension has been broken into two different editions based on Visual Studio version. This was done to fix installation issues caused by how the extension was being built. Building a different version for each version of Visual Studio has corrected this. For Visual Studio 2012 users, you’ll need to uninstall your current version of the extension and install the new version. Installing them side by side will cause issues. This should be the only time you’ll have to do something like this.

REPL Window 

This version adds an interactive REPL window. The REPL window is based on the same REPL that is integrated with the Python and Node tools for Visual Studio. You can run commands just like you would in any other PowerShell command window. You can access the window via View->Other Windows->PowerShell Debug Interactive. Output from your PowerShell scripts now goes to this window rather than the Output pane.


Minor Bug Fixes and Changes

  • Fixed test discovery
  • Removed Project property pages because they were not actually functional
  • Added $DTE variable for StudioShell support and automation accessibility
Categories: Powershell

Thread Slivers eBook at Amazon

Syndicate content