Add remoting docs

docs/remoting.md

@@ -0,0 +1,79 @@
+# PowerShell Remote Editing and Debugging in VSCode
+
+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.
+
+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.
+
+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`.
+
+## Prerequisites
+
+This guide assumes that you have:
+
+* a remote resource (ex: a VM, a container) that you have access to
+* PowerShell running on it and the host machine
+* VSCode and the PowerShell extension for VSCode
+
+NOTE:
+
+This works on Windows PowerShell and the cross-platform version, [PowerShell Core](https://github.com/powershell/powershell).
+
+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)!
+
+## Let's go
+
+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**.
+
+### Local file editing with Open-EditorFile
+
+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.
+
+![Open-EditorFile foo.ps1 works locally](https://user-images.githubusercontent.com/2644648/34895897-7c2c46ac-f79c-11e7-9410-a252aff52f13.png)
+
+NOTE: foo.ps1 must already exist.
+
+From there, we can:
+
+add breakpoints to the gutter
+![adding breakpoint to gutter](https://user-images.githubusercontent.com/2644648/34895893-7bdc38e2-f79c-11e7-8026-8ad53f9a1bad.png)
+
+and hit F5 to debug the PowerShell script.
+![debugging the PowerShell local script](https://user-images.githubusercontent.com/2644648/34895894-7bedb874-f79c-11e7-9180-7e0dc2d02af8.png)
+
+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.
+
+### Remote file editing with Open-EditorFile
+
+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.
+
+There's a cmdlet for that. It's called `Enter-PSSession`.
+
+The watered down explaination of the cmdlet is:
+
+* `Enter-PSSession -ComputerName foo` starts a session via WinRM
+* `Enter-PSSession -ContainerId foo` and `Enter-PSSession -VmId foo` start a session via PowerShell Direct
+* `Enter-PSSession -HostName foo` starts a session via SSH
+
+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).
+
+Since I will be remoting from macOS to an Ubuntu VM in Azure, I will use SSH for this.
+
+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.
+
+NOTE: I've blacked out the IP address.
+
+![The call to Enter-PSSession](https://user-images.githubusercontent.com/2644648/34895896-7c18e0bc-f79c-11e7-9b36-6f4bd0e9b0db.png)
+
+From there, we can do the exact steps as if we were editing a local script.
+
+1. Run `Open-EditorFile test.ps1` or `psedit test.ps1` to open the remote `test.ps1` file
+![Open-EditorFile the test.ps1 file](https://user-images.githubusercontent.com/2644648/34895898-7c3e6a12-f79c-11e7-8bdf-549b591ecbcb.png)
+2. Edit the file/set breakpoints
+![edit and set breakpoints](https://user-images.githubusercontent.com/2644648/34895892-7bb68246-f79c-11e7-8c0a-c2121773afbb.png)
+3. Start debugging (F5) the remote file
+
+![debugging the remote file](https://user-images.githubusercontent.com/2644648/34895895-7c040782-f79c-11e7-93ea-47724fa5c10d.png)
+
+That's all there is to it! We hope that this helped clear up any questions about remote debugging and editing PowerShell in VSCode.
+
+If you have any problems, feel free to open issues [on the GitHub repo](http://github.com/powershell/vscode-powershell).