Chapter 25: Debugging techniques
The introduction distinguishes bugs from anticipated errors and frames debugging as finding mistakes in scripts.
After this chapter you will be able to
- Bugs versus anticipated errors. Distinguish the expected errors and exceptions discussed in the previous chapter from bugs that arise through human mistakes as scripts grow more complex.
- Debug stream clues. Explain how strategically placed Write-* statements and the debug stream help locate a script bug. Describe how the example’s debug output points to a missing macOS run.
- F8 selection behavior. Explain how Run Selection (F8) executes either the selected snippet or, when nothing is selected, the current line in the PowerShell Integrated Console. Distinguish it from Run, which executes the entire script.
- Shared console state. Describe how values set by script lines persist in the PowerShell Integrated Console, where you can inspect or change them before running another line. Explain why manually changed values must be tracked and how restarting the session provides a clean slate.
- Incremental debugging workflow. Describe the section’s workflow for preparing parameter values, running a trusted portion of a script, inspecting variables or function results, and advancing through the script. Explain what to do when a result looks wrong.
- Breakpoint debugging purpose. Explain that a breakpoint marks a line where a script should stop during a debugging run so you can inspect what is happening.
- VS Code breakpoint workflow. Describe how to set a breakpoint beside a line number in VS Code and run the script with debugging using Run or F5.
What it builds on
- Handling exceptions (chapter 24) · Handling expected exceptions.
- Other ways to write (chapter 17) · PowerShell’s different ways to write output
Section by section
Introduction
The introduction distinguishes bugs from anticipated errors and frames debugging as finding mistakes in scripts.
- Bugs versus anticipated errors: Distinguish the expected errors and exceptions discussed in the previous chapter from bugs that arise through human mistakes as scripts grow more complex.
Why it matters: This distinction explains why finding bugs is a different task from handling errors you anticipated.
Key terms: errors and exceptions, bugs
25.1 Output everything
Shows how PowerShell output streams can reveal what a script is doing and help locate a bug, especially when the script runs in a noninteractive environment.
- Debug stream clues: Explain how strategically placed Write-* statements and the debug stream help locate a script bug. Describe how the example’s debug output points to a missing macOS run.
Why it matters: Debug output can narrow down where a script stopped behaving as expected. - Noninteractive debugging value: Justify using PowerShell streams to debug scripts running in environments such as Azure Pipelines or GitHub Actions.
Why it matters: Stream output may be the practical way to investigate a script you cannot inspect while it runs.
Key terms: Write-* statements, Write-Debug, debug stream, debug preference, Continue, Azure Pipelines, GitHub Actions, PowerShell’s streams
25.2 One line at a time
This section shows how to debug a PowerShell script incrementally in VS Code by running selected code in the PowerShell Integrated Console and inspecting its state.
- F8 selection behavior: Explain how Run Selection (F8) executes either the selected snippet or, when nothing is selected, the current line in the PowerShell Integrated Console. Distinguish it from Run, which executes the entire script.
Why it matters: Running only the relevant code can avoid repeated, time-consuming runs of an entire script. - Shared console state: Describe how values set by script lines persist in the PowerShell Integrated Console, where you can inspect or change them before running another line. Explain why manually changed values must be tracked and how restarting the session provides a clean slate.
Why it matters: The shared state lets you see what the script is doing as it happens and test how it behaves with different inputs. - Incremental debugging workflow: Describe the section’s workflow for preparing parameter values, running a trusted portion of a script, inspecting variables or function results, and advancing through the script. Explain what to do when a result looks wrong.
Why it matters: Checking results as you advance helps locate what went wrong without waiting for an entire script run to finish.
Key terms: F8 debugging, Run Selection, PowerShell Integrated Console, $processName, PowerShell: Restart Current Session, parameters, variables, functions
25.3 Hey, script, stop right there . . . with breakpoints
Explains how to set a breakpoint in VS Code and run a PowerShell script so it pauses at that line for inspection.
- Breakpoint debugging purpose: Explain that a breakpoint marks a line where a script should stop during a debugging run so you can inspect what is happening.
Why it matters: Pausing at a chosen line gives you a way to investigate a script problem. - VS Code breakpoint workflow: Describe how to set a breakpoint beside a line number in VS Code and run the script with debugging using Run or F5.
Why it matters: These steps let you pause a real script at the line you want to investigate.
Key terms: breakpoint debugging, breakpoints, F8 debugging, gutter, Run button, F5, with debugging
25.4 Lab
Concepts explained in this chapter
- f8 debuggingF8 debugging is an interactive debugging technique that executes a script one line or selected snippet at a time while preserving the console state.
- Run SelectionRun Selection is a Visual Studio Code editor action that executes selected PowerShell code, or the current line when no code is selected.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.