Issue

A script is not working as expected or is throwing errors. A way to analyze the script is needed because the cause is not clear.


Solution

Many scripting environments come with a debugging tool. Using that it is possible to step trough the single lines of code or stop the execution of the script at a defined point so you can analyze it while it is running. It is also possible to look at the variables to see exactly what happens.


Breakpoints

While using the debugger it is possible to set Breakpoints in your code. A Breakpoint will pause the execution of a script until you manually continue. You can step trough every single line or continue the execution until the next Breakpoint is reached. This is also helpful to check the variables and keep track of the changes or check whether an if statement or a loop are working correctly.


Debugging a powerJobs Processor job

Identifying problematic lines

To narrow down where a job failed, the first step is to check the powerJobs Processor log files (the "powerJobs Processor Logs" start menu shortcut can be used to access the log files) to determine which script is causing the error and on which line the error occurred. Look for a log entry similar to the following:

ERROR coolOrange.Powershell.Hosting.Host.PowershellHost - The script execution terminated because of an error generated by script, functions or commands.
System.Management.Automation.MethodInvocationException: Exception calling "Open" with "2" argument(s): "Could not find file 'C:\TEMP\MissingFile.ipt'."
   at C:\ProgramData\coolOrange\powerJobs\Jobs\Problematic.Job.ps1: line 4

In this example the log message tells us that a missing file was the problem and that the error occurred in the a job script named "Problematic.Job.ps1" on line 4.

Debugging a job script

If you want to debug a job you will have to import the powerJobs module into the scripting environment, open a connection to Vault and get a file on which the job will be executed. Afterwards you can execute the job directly in the scripting environment and debug it. Insert following code, change the values of Open-VaultConnection and pass a valid filename that exists in your Vault in the Get-VaultFile cmdlet:

Import-Module powerJobs
Open-VaultConnection -Vault "VaultName" -Server "ServerName" -User "Username" -Password "Password"
$file = Get-VaultFile -Properties @{Name = "FileName"}


Show-Inspector

The powerVault cmdlet Show-Inspector shows all the variables that are used in the script. This can be very useful to check variables at specified points in your code. This will show the inspector window and stop the execution of the script until the window is closed. You can also highlight a specific variable. To use the Inspector the powerVault module must be imported and following code has to be executed. In this example $file is highlighted:

Import-Module powerVault
Show-Inspector -Highlight $file


Show-Inspector on terminating error

Using $Host you can take actions like show the inspector dialog when a job fails when it runs in powerJobs Processor. To do so you can modify the PrivateData property of $Host. The following example opens an inspector dialog when a job runs into an terminating error.

This example only works when the job is executed through powerJobs Processor, it does not work in a PowerShell IDE!
This should only be used while analyzing the job since it stops the execution of the job until the Inspector dialog is closed!

$global:Host.PrivateData.OnTerminatingError = [System.Delegate]::Combine([Action[System.Management.Automation.RuntimeException]] {
    param($terminatingError)
        Show-Inspector 'terminatingError' 
    }, $global:Host.PrivateData.OnTerminatingError)


PowerShell ISE

When opening your script in a powerShell ISE there is a "Debug" button in the toolbar. When you click on that you can click "Toggle Breakpoint" to set a Breakpoint at the desired line of code. You can also press F9 while the cursor is in that line. Before you can start debugging your script has to be saved.


Once you have created the Breakpoints at the required locations you can execute the code. It will stop at the first Breakpoint. Now it is possible e.g. to check the variables writing them in the console and pressing Enter.


At this point you can press F5 to execute the code until the next Breakpoint or press F10 to step trough every line. If there is e.g. a function in the code you can press F11 to step into that function so you can also see what is happening in the function. When using F10 it will just execute the function but without stepping trough it.


Visual Studio code

Visual Studio Code provides some additional debugging features but you'll have to install the powerShell extension.


Install a powerShell extension

Since Visual Studio Code works with extensions to add features, first of all an extension capable of the powerShell scripting language. We recommend the "PowerShell" extension from Microsoft. To install an extension click on the extensions button on the sidebar, then search for "PowerShell" and install it.


Begin debugging

Now you can open the script and set the Breakpoints where they are needed. It is possible to set Breakpoints by clicking on the space left to the Line Numbers or by pressing F9 while on that line of code. Press F5 to begin debugging. Visual Studio Code  will show you a list of current variables in the Auto section on the left and you can also watch important variables to better track the values. To watch a variable click on the Plus ( + ) symbol and insert the name of the variable to watch. At the top of the application you can find the controls for the debugger.


See Also

Show-Inspector (coolOrange Wiki)

Debug with Visual Studio Code (Microsoft Devblogs)

Debug with powerShell ISE (Microsoft docs)

If statement (Microsoft docs)

foreach loop (Microsoft docs)