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 job

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


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)