Using debugger functions

With PowerShell Version 5, we have great functions, such as debugging scripts, and code in PowerShell was added. This was introduced in the Windows Management Framework 5.0 preview. In this recipe, we will take a look at it in more depth. This recipe is more like a general PowerShell function but can, of course, be applied to Exchange scripts.

Let's take a look at two of these functions in detail and start with the basics and then advance from there. Both these examples can be used in the PowerShell console and in Windows PowerShell ISE.

The first method we are going to take a look at is called Break All and was introduced in PowerShell v5. This method gives us the option to debug the PowerShell workflow and supports command and tab completion. We can debug nested workflow functions both in local and remote sessions.

The second function in this recipe that we will use is the Debug-Job cmdlet inside more complex and advanced scripts. It uses the same basis as the Break All function.

How to do it...

First, we create a variable named $i with a value of 1, and then create a loop using the Do While operator. The loop will run until $i is less than or equal to 20. Within the loop, a text string is written to the console with a text Value and the value of $i:

$i = 1
Do {
Write-Host "Value: $i"
  $i++
  Start-Sleep –Milliseconds 200
}
While ($i –le 20)

As this is a basic example of how the debugger can be used, this method would be helpful for production, when executing scripts. The debugger mode can be used when the script is running by pressing CTRL + Break or CTRL + B. When breaking a script, it will look similar to the following screenshot:

We can see that the script called loop.ps1 is stopped and has entered the debug mode. When pressing h or ?, the help information will show up.

In the debug mode, we can see the full source code (using l) in the current script, we can also step through every row in the script (using s), go to the next statement (using v), and of course, continue running the script (using c) or stop the operation and exit the debug mode (using q).

How it works...

By initializing the debugging mode, the script is stopped until using either the Continue or Quit commands. The debugging can be very helpful; and for example, you can step through the code, view the source code, verify variables, view the environment state, and execute commands.

In the preceding screenshot, let's take a look at what the value in the $i variable is by typing the following command:

[PS] C:\Scripts>$i
5

Here, we see that the value is 5 as the loop was stopped at that stage.

Tip

One thing to mention here is that the script debugging method will only debug the executed script itself and cannot collect any information from external native commands or scripts and sends back the result in the debugging mode. For more advanced debugging, use the managed code together with Visual Studio or WinDbg.

There's more…

Together with the code debugger function, we can use the Debug-Job cmdlet that was introduced in Version 5 of PowerShell.

The Debug-Job cmdlet lets you break into the script debugger while running a job in a similar way, as the Break All function lets us break into a running script from the console or ISE.

A typical scenario where we could use Debug-Job is when we are running a long, complex script as a job, and for one reason or another, we suspect that the script is not executing correctly. It may take longer than expected or some of the output data doesn't seem right. Now we can drop the job in the debugger using the Debug-Job cmdlet, which allows us to verify that the code is being executed the way it's expected to be; it's a great and helpful function.

As you probably are aware of or the problem that you might face in the future is that while debugging scripts interactively, they work as expected but when they are running as jobs in production, they fail. However, this can now be debugged with this new feature by setting breakpoints or using the Wait-Debugger cmdlet.

In the following example, we are setting a breakpoint at Line 4 to debug the script and run it as a job, and use the Debug-Job cmdlet:

$job = Start-Job -ScriptBlock { Set-PSBreakpoint ` C:\Scripts\MyJob.ps1-Line 4; C:\Scripts\MyJob.ps1 `
}
$job
Debug-Job $job

By doing this, we will be able to enter the debugging mode and can reach variables, execute commands, view the environment state, view the source code, and step through the code:

The preceding screenshot shows you that the job state is AtBreakpoint, which means that it is waiting to be debugged. This method works in a similar way as the Break All method; it will only debug the script itself and cannot debug any external commands.

To continue with the process and leave the debugging mode, use the detach command.

See also

• Understanding the new execution policy
• Creating custom objects
• Using the Save-Help function