How to Debug Scripts in Windows PowerShell ISE

This article describes how to debug scripts on a local computer by using the Windows PowerShell Integrated Scripting Environment (ISE) visual debugging features.

How to manage breakpoints

A breakpoint is a designated spot in a script where you would like operation to pause so that you can examine the current state of the variables and the environment in which your script is running. Once your script is paused by a breakpoint, you can run commands in the Console Pane to examine the state of your script. You can output variables or run other commands. You can even modify the value of any variables that are visible to the context of the currently running script. After you have examined what you want to see, you can resume operation of the script.

You can set three types of breakpoints in the Windows PowerShell debugging environment:

Line breakpoint. The script pauses when the designated line is reached during the operation of the script

Variable breakpoint. The script pauses whenever the designated variable’s value changes.

Command breakpoint. The script pauses whenever the designated command is about to be run during the operation of the script. It can include parameters to further filter the breakpoint to only the operation you want. The command can also be a function you created.

Of these, in the Windows PowerShell ISE debugging environment, only line breakpoints can be set by using the menu or the keyboard shortcuts. The other two types of breakpoints can be set, but they are set from the Console Pane by using the Set-PSBreakpoint cmdlet. This section describes how you can perform debugging tasks in Windows PowerShell ISE by using the menus where available, and perform a wider range of commands from the Console Pane by using scripting.

To set a breakpoint

A breakpoint can be set in a script only after it has been saved. Right-click the line where you want to set a line breakpoint, and then click Toggle Breakpoint. Or, click the line where you want to set a line breakpoint, and press F9 or, on the Debug menu, click Toggle Breakpoint.

The following script is an example of how you can set a variable breakpoint from the Console Pane by using the Set-PSBreakpoint cmdlet.

List all breakpoints

Displays all breakpoints in the current Windows PowerShell session.

On the Debug menu, click List Breakpoints. The following script is an example of how you can list all breakpoints from the Console Pane by using the Get-PSBreakpoint cmdlet.

Remove a breakpoint

Removing a breakpoint deletes it.

If you think you might want to use it again later, consider Disable a Breakpoint it instead. Right-click the line where you want to remove a breakpoint, and then click ToggleBreakpoint. Or, click the line where you want to remove a breakpoint, and on the Debug menu, click Toggle Breakpoint. The following script is an example of how to remove a breakpoint with a specified ID from the Console Pane by using the Remove-PSBreakpoint cmdlet.

Remove All Breakpoints

To remove all breakpoints defined in the current session, on the Debug menu, click Remove All Breakpoints.

The following script is an example of how to remove all breakpoints from the Console Pane by using the Remove-PSBreakpoint cmdlet.

Disable a Breakpoint

Disabling a breakpoint does not remove it; it turns it off until it is enabled. To disable a specific line breakpoint, right-click the line where you want to disable a breakpoint, and then click Disable Breakpoint. Or, click the line where you want to disable a breakpoint, and press F9 or, on the Debug menu, click Disable Breakpoint. The following script is an example of how you can remove a breakpoint with a specified ID from the Console Pane by using the Disable-PSBreakpoint cmdlet.

Disable All Breakpoints

Disabling a breakpoint does not remove it; it turns it off until it is enabled. To disable all breakpoints in the current session, on the Debug menu, click Disable all Breakpoints. The following script is an example of how you can disable all breakpoints from the Console Pane by using the Disable-PSBreakpoint cmdlet.

Enable a Breakpoint

To enable a specific breakpoint, right-click the line where you want to enable a breakpoint, and then click Enable Breakpoint. Or, click the line where you want to enable a breakpoint, and then press F9 or, on the Debug menu, click Enable Breakpoint. The following script is an example of how you can enable specific breakpoints from the Console Pane by using the Enable-PSBreakpoint cmdlet.

Enable All Breakpoints

To enable all breakpoints defined in the current session, on the Debug menu, click Enable all Breakpoints. The following script is an example of how you can enable all breakpoints from the Console Pane by using the Enable-PSBreakpoint cmdlet.

How to manage a debugging session

Before you start debugging, you must set one or more breakpoints. You cannot set a breakpoint unless the script that you want to debug is saved. For directions on of how to set a breakpoint, see How to manage breakpoints or Set-PSBreakpoint. After you start debugging, you cannot edit a script until you stop debugging. A script that has one or more breakpoints set is automatically saved before it is run.

To start debugging

Press F5 or, on the toolbar, click the Run Script icon, or on the Debug menu click Run/Continue. The script runs until it encounters the first breakpoint. It pauses operation there and highlights the line on which it paused.

To continue debugging

Press F5 or, on the toolbar, click the Run Script icon, or on the Debug menu, click Run/Continue or, in the Console Pane, type C and then press ENTER . This causes the script to continue running to the next breakpoint or to the end of the script if no further breakpoints are encountered.

To view the call stack

The call stack displays the current run location in the script. If the script is running in a function that was called by a different function, then that is represented in the display by additional rows in the output. The bottom-most row displays the original script and the line in it in which a function was called. The next line up shows that function and the line in it in which another function might have been called. The top-most row shows the current context of the current line on which the breakpoint is set.

While paused, to see the current call stack, press CTRL + SHIFT + D or, on the Debug menu, click Display Call Stack or, in the Console Pane, type K and then press ENTER .

To stop debugging

Press SHIFT + F5 or, on the Debug menu, click Stop Debugger, or, in the Console Pane, type Q and then press ENTER .

How to step over, step into, and step out while debugging

Stepping is the process of running one statement at a time. You can stop on a line of code, and examine the values of variables and the state of the system. The following table describes common debugging tasks such as stepping over, stepping into, and stepping out.

Debugging Task	Description	How to accomplish it in PowerShell ISE
Step Into	Executes the current statement and then stops at the next statement. If the current statement is a function or script call, then the debugger steps into that function or script, otherwise it stops at the next statement.	Press F11 or, on the Debug menu, click Step Into, or in the Console Pane, type S and press ENTER .
Step Over	Executes the current statement and then stops at the next statement. If the current statement is a function or script call, then the debugger executes the whole function or script, and it stops at the next statement after the function call.	Press F10 or, on the Debug menu, click Step Over, or in the Console Pane, type V and press ENTER .
Step Out	Steps out of the current function and up one level if the function is nested. If in the main body, the script is executed to the end, or to the next breakpoint. The skipped statements are executed, but not stepped through.	Press SHIFT + F11 , or on the Debug menu, click Step Out, or in the Console Pane, type O and press ENTER .
Continue	Continues execution to the end, or to the next breakpoint. The skipped functions and invocations are executed, but not stepped through.	Press F5 or, on the Debug menu, click Run/Continue, or in the Console Pane, type C and press ENTER .

How to display the values of variables while debugging

You can display the current values of variables in the script as you step through the code.

To display the values of standard variables

Use one of the following methods:

In the Script Pane, hover over the variable to display its value as a tool tip.

In the Console Pane, type the variable name and press ENTER .

All panes in ISE are always in the same scope. Therefore, while you are debugging a script, the commands that you type in the Console Pane run in script scope. This allows you to use the Console Pane to find the values of variables and call functions that are defined only in the script.

To display the values of automatic variables

You can use the preceding method to display the value of almost all variables while you are debugging a script. However, these methods do not work for the following automatic variables.

If you try to display the value of any of these variables, you get the value of that variable for in an internal pipeline the debugger uses, not the value of the variable in the script. You can work around this for a few variables ( $_ , $Input , $MyInvocation , $PSBoundParameters , and $Args ) by using the following method:

In the script, assign the value of the automatic variable to a new variable.

Display the value of the new variable, either by hovering over the new variable in the Script Pane, or by typing the new variable in the Console Pane.

For example, to display the value of the $MyInvocation variable, in the script, assign the value to a new variable, such as $scriptName , and then hover over or type the $scriptName variable to display its value.

Installing PowerShell on Windows

There are multiple ways to install PowerShell in Windows.

Prerequisites

The latest release of PowerShell is supported on Windows 7 SP1, Server 2008 R2, and later versions.

To enable PowerShell remoting over WSMan, the following prerequisites need to be met:

• Install the Universal C Runtime on Windows versions predating Windows 10. It’s available via direct download or Windows Update. Fully patched systems already have this package installed.
• Install the Windows Management Framework (WMF) 4.0 or newer on Windows 7 and Windows Server 2008 R2. For more information about WMF, see WMF Overview.

Download the installer package

To install PowerShell on Windows, download the latest install package from GitHub. You can also find the latest preview version. Scroll down to the Assets section of the Release page. The Assets section may be collapsed, so you may need to click to expand it.

Installing the MSI package

The MSI file looks like PowerShell- -win- .msi . For example:

Once downloaded, double-click the installer and follow the prompts.

The installer creates a shortcut in the Windows Start Menu.

• By default the package is installed to $env:ProgramFiles\PowerShell\
• You can launch PowerShell via the Start Menu or $env:ProgramFiles\PowerShell\ \pwsh.exe

PowerShell 7.1 installs to a new directory and runs side-by-side with Windows PowerShell 5.1. PowerShell 7.1 is an in-place upgrade that replaces PowerShell 6.x. or PowerShell 7.0.

• PowerShell 7.1 is installed to $env:ProgramFiles\PowerShell\7
• The $env:ProgramFiles\PowerShell\7 folder is added to $env:PATH
• The $env:ProgramFiles\PowerShell\6 folder is deleted

If you need to run PowerShell 7.1 side-by-side with other versions, use the ZIP install method to install the other version to a different folder.

Administrative install from the command line

MSI packages can be installed from the command line allowing administrators to deploy packages without user interaction. The MSI package includes the following properties to control the installation options:

• ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL — This property controls the option for adding the Open PowerShell item to the context menu in Windows Explorer.
• ADD_FILE_CONTEXT_MENU_RUNPOWERSHELL — This property controls the option for adding the Run with PowerShell item to the context menu in Windows Explorer.
• ENABLE_PSREMOTING — This property controls the option for enabling PowerShell remoting during installation.
• REGISTER_MANIFEST — This property controls the option for registering the Windows Event Logging manifest.

The following example shows how to silently install PowerShell with all the install options enabled.

For a full list of command-line options for Msiexec.exe , see Command line options.

Registry keys created during installation

Beginning in PowerShell 7.1, the MSI package creates registry keys that store the installation location and version of PowerShell. These values are located in HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\ . The value of is unique for each build type (release or preview), major version, and architecture.

Release	Architecture	Registry Key
7.1.x Release	x86	HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\1d00683b-0f84-4db8-a64f-2f98ad42fe06
7.1.x Release	x64	HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\31ab5147-9a97-4452-8443-d9709f0516e1
7.1.x Preview	x86	HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\86abcfbd-1ccc-4a88-b8b2-0facfde29094
7.1.x Preview	x64	HKLM\Software\Microsoft\PowerShellCore\InstalledVersions\39243d76-adaf-42b1-94fb-16ecf83237c8

This can be used by administrators and developers to find the path to PowerShell. The values will be the same for all preview and minor version releases. The values are changed for each major release.

Installing the ZIP package

PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. Download one of the following ZIP archives from the [releases][releases] page.

• PowerShell-7.1.3-win-x64.zip
• PowerShell-7.1.3-win-x86.zip
• PowerShell-7.1.3-win-arm64.zip
• PowerShell-7.1.3-win-arm32.zip

Depending on how you download the file you may need to unblock the file using the Unblock-File cmdlet. Unzip the contents to the location of your choice and run pwsh.exe from there. Unlike installing the MSI packages, installing the ZIP archive doesn’t check for prerequisites. For remoting over WSMan to work properly, ensure that you’ve met the prerequisites.

Use this method to install the ARM-based version of PowerShell on computers like the Microsoft Surface Pro X. For best results, install PowerShell to the to $env:ProgramFiles\PowerShell\7 folder.

You can use this method to install any version of PowerShell including the latest:

Deploying on Windows 10 IoT Enterprise

Windows 10 IoT Enterprise comes with Windows PowerShell, which we can use to deploy PowerShell 7.

Create PSSession to target device

Copy the ZIP package to the device

Connect to the device and expand the archive

Set up remoting to PowerShell 7

Connect to PowerShell 7 endpoint on device

Deploying on Windows 10 IoT Core

Windows 10 IoT Core adds Windows PowerShell when you include IOT_POWERSHELL feature, which we can use to deploy PowerShell 7. The steps defined above for Windows 10 IoT Enterprise can be followed for IoT Core as well.

For adding the latest PowerShell in the shipping image, use Import-PSCoreRelease command to include the package in the workarea and add OPENSRC_POWERSHELL feature to your image.

For ARM64 architecture, Windows PowerShell is not added when you include IOT_POWERSHELL. So the zip based install will not work. You will need to use Import-PSCoreRelease command to add it in the image.

Deploying on Nano Server

These instructions assume that the Nano Server is a «headless» OS that has a version of PowerShell is already running on it. For more information, see the Nano Server Image Builder documentation.

PowerShell binaries can be deployed using two different methods.

1. Offline — Mount the Nano Server VHD and unzip the contents of the zip file to your chosen location within the mounted image.
2. Online — Transfer the zip file over a PowerShell Session and unzip it in your chosen location.

In both cases, you need the Windows 10 x64 ZIP release package. Run the commands within an «Administrator» instance of PowerShell.

Offline Deployment of PowerShell

1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image.
2. Unmount the image and boot it.
3. Connect to the built-in instance of Windows PowerShell.
4. Follow the instructions to create a remoting endpoint using the «another instance technique».

Online Deployment of PowerShell

Deploy PowerShell to Nano Server using the following steps.

Connect to the built-in instance of Windows PowerShell

Copy the file to the Nano Server instance

Enter the session

Extract the ZIP file

If you want WSMan-based remoting, follow the instructions to create a remoting endpoint using the «another instance technique».

Install as a .NET Global tool

If you already have the .NET Core SDK installed, it’s easy to install PowerShell as a .NET Global tool.

The dotnet tool installer adds $env:USERPROFILE\.dotnet\tools to your $env:PATH environment variable. However, the currently running shell doesn’t have the updated $env:PATH . You can start PowerShell from a new shell by typing pwsh .

Install PowerShell via Winget

The winget command-line tool enables developers to discover, install, upgrade, remove, and configure applications on Windows 10 computers. This tool is the client interface to the Windows Package Manager service.

The winget tool is currently a preview. Not all planned functionality is available at this time. You should not use this method in a production deployment scenario. See the winget documentation for a list of system requirements and install instructions.

The following commands can be used to install PowerShell using the published winget packages:

Search for the latest version of PowerShell

Install a version of PowerShell using the —exact parameter

Installing from the Microsoft Store

PowerShell 7.1 has been published to the Microsoft Store. You can find the PowerShell release on the Microsoft Store website or in the Store application in Windows.

Benefits of the Microsoft Store package:

• Automatic updates built right into Windows 10
• Integrates with other software distribution mechanisms like Intune and SCCM

MSIX packages run in an application sandbox that virtualizes access to some filesystem and registry locations.

• All registry changes under HKEY_CURRENT_USER are copied on write to a private, per-user, per-app location. Therefore, those values are not available to other applications.
• Any system-level configuration settings stored in $PSHOME cannot be modified. This includes the WSMAN configuration. This prevents remote sessions from connecting to Store-based installs of PowerShell. User-level configurations and SSH remoting are supported.

Using the MSIX package

The preview builds of PowerShell include an MSIX package. The MSIX package is not officially supported. The package is built for testing purposes during the preview period.

To manually install the MSIX package on a Windows 10 client, download the MSIX package from our GitHub [releases][releases] page. Scroll down to the Assets section of the Release you want to install. The Assets section may be collapsed, so you may need to click to expand it.

The MSIX file looks like this — PowerShell- -win- .msix

To install the package, you must use the Add-AppxPackage cmdlet.

How to create a remoting endpoint

PowerShell supports the PowerShell Remoting Protocol (PSRP) over both WSMan and SSH. For more information, see:

Upgrading an existing installation

For best results when upgrading, you should use the same install method you used when you first installed PowerShell. Each installation method installs PowerShell in a different location. If you are not sure how PowerShell was installed, you can compare the installed location with the package information in this article. If you installed via the MSI package, that information appears in the Programs and Features Control Panel.

Installation support

Microsoft supports the installation methods in this document. There may be other methods of installation available from other sources. While those tools and methods may work, Microsoft cannot support those methods.