If a powerJobs Processor job runs into an issue it is possible to identify the issue using different methods.
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"}
Problematic lines displayed in Trace Window
When a job runs into an error you can see the error message in the powerJobs Processor Trace Window. The error message also contains the script name and the line number where the error occurred.
Identifying problematic lines via Logfile
To narrow down where the execution of a job script failed, the first step is to check the powerJobs Processor log files. The logfiles can be accessed by clicking on the "powerJobs Processor Logs" shortcut in the Windows Start Menu.
It provides information to determine which PowerShell script or module is causing the error and on which line the terminating error occurred, as in the following example:
2021-01-29 10:58:15,749 [Pipeline Execution Thread] 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
Show-Inspector
The powerVault cmdlet Show-Inspector shows all the variables that are used in the job script or module. It can be very useful to check variables at specified points in your code. Therefore the powerVault module is already available after importing the powerJobs module.
After showing the inspector window, the script execution gets stopped until the window is closed. You can also highlight a specific variable, like the $file variable used in the job script:
Show-Inspector -Highlight $file
Using the $Host variable you can take actions like showing the inspector dialog every time when a terminating powerShell error occurs in a Job executed by the powerJobs Processor. To do so you can modify the PrivateData property of $Host as for the following example:
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 terminating errors in job scripts since the exeuction of the scripts gets stopped until the Inspector window is closed!
$global:Host.PrivateData.OnTerminatingError = [System.Delegate]::Combine([Action[System.Management.Automation.RuntimeException]] { param($terminatingError) Show-Inspector 'terminatingError' }, $global:Host.PrivateData.OnTerminatingError)