Skip to content

Commit cb1515f

Browse files
authoredJan 25, 2018
Add remoting docs (PowerShell#1162)
* add remoting md for 1.6.0 release * didn't know github urls are case-sensitive. asset -> Asset * remove assets * Updated to Open-EditorFile * backcompat
1 parent 1371181 commit cb1515f

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed
 

‎docs/remoting.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
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+
![Open-EditorFile foo.ps1 works locally](https://user-images.githubusercontent.com/2644648/34895897-7c2c46ac-f79c-11e7-9410-a252aff52f13.png)
32+
33+
NOTE: foo.ps1 must already exist.
34+
35+
From there, we can:
36+
37+
add breakpoints to the gutter
38+
![adding breakpoint to gutter](https://user-images.githubusercontent.com/2644648/34895893-7bdc38e2-f79c-11e7-8026-8ad53f9a1bad.png)
39+
40+
and hit F5 to debug the PowerShell script.
41+
![debugging the PowerShell local script](https://user-images.githubusercontent.com/2644648/34895894-7bedb874-f79c-11e7-9180-7e0dc2d02af8.png)
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+
![The call to Enter-PSSession](https://user-images.githubusercontent.com/2644648/34895896-7c18e0bc-f79c-11e7-9b36-6f4bd0e9b0db.png)
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+
![Open-EditorFile the test.ps1 file](https://user-images.githubusercontent.com/2644648/34895898-7c3e6a12-f79c-11e7-8bdf-549b591ecbcb.png)
71+
2. Edit the file/set breakpoints
72+
![edit and set breakpoints](https://user-images.githubusercontent.com/2644648/34895892-7bb68246-f79c-11e7-8c0a-c2121773afbb.png)
73+
3. Start debugging (F5) the remote file
74+
75+
![debugging the remote file](https://user-images.githubusercontent.com/2644648/34895895-7c040782-f79c-11e7-93ea-47724fa5c10d.png)
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

Comments
 (0)
Please sign in to comment.