Debugging Tips

The tips are focused on debugging and troubleshooting in VSCode with the PowerShell extension. They are not limited to this PowerShell host and environment. But VSCode is quite powerful and easily available.

Breakpoints in build scripts

Open your build script in the editor and set the required breakpoints by F9.

Currently, VSCode editor breakpoints are not always synchronised with the PowerShell breakpoints. To work around this, hit F5 as if you are about to debug a build script directly. This fails with an error like "The term 'task' is not recognized..." but makes breakpoints ready.

Invoke your build scenario in VSCode normally, i.e. type a build command in the integrated PowerShell console or use Invoke-Task-from-VSCode to invoke the current task from the build script in the editor. Make sure you save the changes before invoking (#258).

As a result, you break into the debugger when breakpoints are hit during the build. Use VSCode debugger as usual, i.e. explore the stack, variables, type commands in the integrated console, and etc.

Break on terminating errors

Use the little handy script Debug-Error.ps1 in order to break into the debugger on terminating errors automatically. See its help for the details.

It is recommended to limit the scope of errors to the scripts of interest, i.e. the build script. That is, use the command

    Debug-Error MyProject.build.ps1

in order to enable stops exactly in MyProject.build.ps1 and skip related noise stops in the build engine. Errors are caught and re-thrown several times in the engine code and you do not want to stop there on each.

Other techniques

Invoke-Build scripts are usual PowerShell code and the standard PowerShell debugging tools are available. You can set some interesting breakpoints by Set-PSBreakpoint.

To break when a function is called

    Set-PSBreakpoint -Command MyBuildFunction

To break when a variable is read or written

    Set-PSBreakpoint -Variable MyBuildVariable [-Mode Read | Write | ReadWrite]