|
| 1 | +# PowerShell Remote Editing and Debugging in VSCode |
| 2 | + |
| 3 | +For those of you that were familiar with the ISE, you may recall that you were able to use run `psedit file.ps1` from the integrated console to open files - local or remote - right in the ISE. |
| 4 | + |
| 5 | +As it turns out, this feature is also availible out of the box in the PowerShell extension for VSCode. This guide will show you how to do it. |
| 6 | + |
| 7 | +NOTE: `Open-EditorFile` was added in 1.6.0. Pre-1.6.0 it was called `psedit`. In 1.6.0+ `psedit` is an alias of `Open-EditorFile`. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +This guide assumes that you have: |
| 12 | + |
| 13 | +* a remote resource (ex: a VM, a container) that you have access to |
| 14 | +* PowerShell running on it and the host machine |
| 15 | +* VSCode and the PowerShell extension for VSCode |
| 16 | + |
| 17 | +NOTE: |
| 18 | + |
| 19 | +This works on Windows PowerShell and the cross-platform version, [PowerShell Core](https://github.com/powershell/powershell). |
| 20 | + |
| 21 | +This also works when connecting to a remote machine via WinRM, PowerShell Direct, or SSH. If you want to use SSH, but are using Windows, check out the Win32 version of SSH [here](https://github.com/PowerShell/Win32-OpenSSH)! |
| 22 | + |
| 23 | +## Let's go |
| 24 | + |
| 25 | +In this section, I will walk through remote editing and debugging from my MacBook Pro, to an Ubuntu VM running in Azure. I might not be using Windows, but **the process is identical**. |
| 26 | + |
| 27 | +### Local file editing with Open-EditorFile |
| 28 | + |
| 29 | +With the PowerShell extension for VSCode started and the PowerShell Integrated Console opened, we can type `Open-EditorFile foo.ps1` or `psedit foo.ps1` to open the local foo.ps1 file right in the editor. |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +NOTE: foo.ps1 must already exist. |
| 34 | + |
| 35 | +From there, we can: |
| 36 | + |
| 37 | +add breakpoints to the gutter |
| 38 | + |
| 39 | + |
| 40 | +and hit F5 to debug the PowerShell script. |
| 41 | + |
| 42 | + |
| 43 | +While debugging, you can interact with the debug console, check out the variables in the scope on the left, and all the other standard debugging tools. |
| 44 | + |
| 45 | +### Remote file editing with Open-EditorFile |
| 46 | + |
| 47 | +Now let's get into remote file editing and debugging. The steps are nearly the same, there's just one thing we need to do first - enter our PowerShell session to the remote server. |
| 48 | + |
| 49 | +There's a cmdlet for that. It's called `Enter-PSSession`. |
| 50 | + |
| 51 | +The watered down explaination of the cmdlet is: |
| 52 | + |
| 53 | +* `Enter-PSSession -ComputerName foo` starts a session via WinRM |
| 54 | +* `Enter-PSSession -ContainerId foo` and `Enter-PSSession -VmId foo` start a session via PowerShell Direct |
| 55 | +* `Enter-PSSession -HostName foo` starts a session via SSH |
| 56 | + |
| 57 | +For more info on `Enter-PSSession`, check out the docs [here](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/enter-pssession?view=powershell-6). |
| 58 | + |
| 59 | +Since I will be remoting from macOS to an Ubuntu VM in Azure, I will use SSH for this. |
| 60 | + |
| 61 | +First, in the Integrated Console, let's run our Enter-PSSession. You will know that you're in the session because `[something]` will show up to the left of your prompt. |
| 62 | + |
| 63 | +NOTE: I've blacked out the IP address. |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +From there, we can do the exact steps as if we were editing a local script. |
| 68 | + |
| 69 | +1. Run `Open-EditorFile test.ps1` or `psedit test.ps1` to open the remote `test.ps1` file |
| 70 | + |
| 71 | +2. Edit the file/set breakpoints |
| 72 | + |
| 73 | +3. Start debugging (F5) the remote file |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +That's all there is to it! We hope that this helped clear up any questions about remote debugging and editing PowerShell in VSCode. |
| 78 | + |
| 79 | +If you have any problems, feel free to open issues [on the GitHub repo](http://github.com/powershell/vscode-powershell). |
0 commit comments