PowerShell Editor Services

PowerShell Editor Services is a PowerShell module that provides common functionality needed to enable a consistent and robust PowerShell development experience in almost any editor or integrated development environment (IDE).

Language Server Protocol clients using PowerShell Editor Services:

The functionality in PowerShell Editor Services is available in the following editor extensions:

PowerShell for Visual Studio Code, also available in Azure Data Studio
lsp-pwsh, an Emacs PowerShell plugin
intellij-powershell, adds PowerShell language support to IntelliJ-based IDEs
coc-powershell, a Vim and Neovim plugin

Please note that other than PowerShell for Visual Studio Code, these clients are community maintained and may be very out of date. It is recommended that you simply use an LSP plugin for your editor and configure it as demonstrated below.

Features

The Language Service provides common editor features for the PowerShell language:
- Code navigation actions (find references, go to definition)
- Statement completions (IntelliSense)
- Real-time semantic analysis of scripts using PowerShell Script Analyzer
The Debugging Service simplifies interaction with the PowerShell debugger (breakpoints, variables, call stack, etc.)
The $psEditor API enables scripting of the host editor
A full, Extension Terminal experience for interactive development and debugging

Usage

If you're looking to integrate PowerShell Editor Services into your Language Server Protocol compliant editor or client, we support two ways of connecting.

Named Pipes / Unix Domain Sockets

If you're looking for a more feature-rich experience, named pipes (AKA sockets) are the way to go. They give you all the benefits of the Language Server Protocol with extra capabilities that you can take advantage of:

The PowerShell Extension Terminal
Debugging using the Debug Adapter Protocol

The typical command to start PowerShell Editor Services using named pipes / sockets is as follows:

pwsh -NoLogo -NoProfile -Command "./PowerShellEditorServices/Start-EditorServices.ps1 -SessionDetailsPath ./session.json"

The start script, Start-EditorServices.ps1, is found in the PowerShellEditorServices folder instead the PowerShellEditorServices.zip downloaded from the GitHub releases.

The session details (which named pipes were created) will be written to the given session details path, and the client needs to point to these in order to connect.

The Visual Studio Code, Vim, and IntelliJ extensions use named pipes.

Standard Input and Output

Alternatively, the -SessionDetailsPath ./session.json argument can be replaced with just -Stdio. The use of stdio is the simplest way to connect with most LSP clients, but will limit some features, such as the debugger and Extension Terminal. This is because because these two features require their own IO streams and stdio only provides a single pair of streams.

Please see the emacs-simple-test.el, emacs-test.el, vim-simple-test.el and vim-test.vim for examples of end-to-end tested configurations. They use eglot for Emacs and LanguageClient-neovim.

Advanced Usage

If you are trying to automate the service in PowerShell, you can also run it under Start-Process to prevent hanging your script. It also gives you access to process automation features like $process.Close() or $process.Kill(). The Start-EditorServices.ps1 script takes many more optional arguments, but they no longer need to be specified.

$command = @(
    "$PSES_BUNDLE_PATH/PowerShellEditorServices/Start-EditorServices.ps1",
        "-BundledModulesPath $PSES_BUNDLE_PATH",
        "-LogPath ./logs",
        "-SessionDetailsPath ./session.json",
        "-FeatureFlags @()",
        "-AdditionalModules @()",
        "-HostName 'My Client'",
        "-HostProfileId 'myclient'",
        "-HostVersion 1.0.0",
        "-LogLevel Diagnostic"
) -join " "

$pwsh_arguments = "-NoLogo -NoProfile -Command $command"
$process = Start-Process pwsh -ArgumentList $arguments -PassThru
...
$process.Close(); #$process.Kill();

Once the command is run, PowerShell Editor Services will wait until the client connects to the named pipe. The session.json will contain the paths of the named pipes that you will connect to. There will be one you immediately connect to for Language Server Protocol messages, and once you connect to when you launch the debugger for Debug Adapter Protocol messages.

PowerShell Extension Terminal

The PowerShell Extension Terminal uses the host process' stdio streams for console input and output. Please note that this is mutually exclusive from using stdio for the Language Server Protocol messages.

If you want to take advantage of the PowerShell Extension Terminal, you must include the -EnableConsoleRepl switch when calling Start-EditorServices.ps1.

This is typically used if your client can create arbitrary terminals in the editor like below:

The Visual Studio Code, Vim, and IntelliJ extensions currently use the PowerShell Extension Terminal.

Debugging

Debugging support is also exposed with PowerShell Editor Services. It is handled within the same process as the Language Server Protocol. This provides a more integrated experience for end users but is something to note as not many other language servers work in the same way. If you want to take advantage of debugging, your client must support the Debug Adapter Protocol. Your client should use the path to the debug named pipe found in the session.json file talked about above.

Currently, only the Visual Studio Code extension supports debugging.

API Usage

Please note that we only consider the following as stable APIs that can be relied on:

Language Server Protocol connection
Debug Adapter Protocol connection
Start-up mechanism

The types of PowerShell Editor Services can change at any moment and should not be linked against in a production environment.

Development

NOTE: The easiest way to manually test changes you've made in PowerShellEditorServices is to follow the vscode-powershell development doc to get a local build of the VS Code extension to use your local build of PowerShellEditorServices.

1. Install PowerShell 7+

Install PowerShell 7+ with these instructions.

2. Clone the GitHub repository

git clone https://github.com/PowerShell/PowerShellEditorServices.git

3. Install Invoke-Build

Install-Module InvokeBuild -Scope CurrentUser
Install-Module platyPS -Scope CurrentUser

Now you're ready to build the code. You can do so in one of two ways:

Building the code from PowerShell

PS C:\path\to\PowerShellEditorServices> Invoke-Build Build

Building the code from Visual Studio Code

Open the PowerShellEditorServices folder that you cloned locally and press Ctrl+Shift+B (or Cmd+Shift+B on macOS).

Contributions Welcome

We would love to incorporate community contributions into this project. If you would like to contribute code, documentation, tests, or bug reports, please read our Contribution Guide to learn more.

Maintainers

Emeriti

License

This project is licensed under the MIT License.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

dkattan/PowerShellEditorServices