This is the second of a series of blogs discussing the new PowerShell 5.0 script debugging features. These new features are available through the PowerShell 5.0 preview, which is part of the WMF (Windows Management Foundation) 5.0 preview that you can get from HERE.
In this blog I will discuss the new features that support remote script debugging in the PowerShell ISE (Integrated Script Environment). Remote script debugging support was added to PowerShell 4.0 but only for the PowerShell console and not the ISE. We have rectified this for PowerShell 5.0 and have also added the ability to open, edit and save remote script files. The PowerShell console does not provide for editing remote script files and so we felt this was an important feature for the ISE. In addition you can now also edit remote files in the ISE that have been opened for debugging. Thus you can perform full open/edit/run/debug/edit/run iterations in the ISE on remote session files.
You open a remote file for editing inside a PowerShell remote session from the ISE console pane using the PSEdit command.
PSEdit [-FileNames] <string[]> [CommonParameters]
[RemoteMachine] PS C:\> PSEdit MyScript.ps1
I want to stress that this is not the same as opening a file using the ISE File Open Dialog. This dialog uses the Windows file system to navigate and open files, and you can even open remote files with the Windows network file system support. But the new PSEdit command support in remote sessions opens files through the current remote session. In other words it uses the same session connection your remote session uses and completely bypasses the network file system. It is also integrated with the ISE debugger so that remote files are automatically opened for debugging which are then available for editing. When the ISE opens a remote file for editing or debugging it simply copies the file from the remote machine to the local machine and stores it in a temporary local file. When you save changes to the file, the file is then copied from the local machine back to the remote machine. If you end the remote session (by running the Exit-PSSession Cmdlet) all remote files opened in the ISE are automatically closed since the remote connection supporting the file transfer no longer exists. We currently don’t provide any way to save the remote file permanently onto the local machine but it is something we are considering.
The PSEdit command actually already exists in the ISE when you are in a local session (ISE default mode) and it is a way to open local files from the ISE console command line.
This change simply extends this command to work in remote sessions too.
To see how this works try doing the following (after installing the latest PowerShell 5.0 preview).
- Start PowerShell ISE
- Start a remote session by selecting the File -> New Remote PowerShell Tab… menu item.
- If you have a second machine select that for the target of the remote session, but make sure that machine also has the latest PowerShell 5.0 preview installed.
- As an alternative and for experimentation purposes you can use “localhost” as the computer name in the New Remote PowerShell Tab dialog. This will create a remote connection back to your same machine.
- In the PowerShell console use the PSEdit command to open an existing remote file.
[paulhig-1]: PS C:\> PSEdit C:\MyScripts\MyScript.ps1
- Or alternatively create a new empty file and open that to create a new script file.
[paulhig-1]: PS C:\> New-Item C:\MyScripts\MyNewScript.ps1
[paulhig-1]: PS C:\> PSEdit C:\MyScripts\MyNewScript.ps1
- Your selected remote file is now open and displayed in the ISE.
- Set line breakpoints in the script file.
- Run the script. Let the script run to the breakpoint and step through the script.
- Stop the debugger. Edit the script. Save and run it again.
That is really all there is to it. It is a fairly simple feature addition but makes creating, opening, editing, running, and debugging PowerShell script files on a remote machine a much better experience.
Paul Higinbotham [MSFT]
Windows PowerShell Development