PowerShell Editor Services (PSES)

PowerShell Editor Services (PSES) is a PowerShell module designed to provide a consistent and robust development experience across various editors and IDEs. It provides core services including:

• Language Service: Enables code navigation (find references, go to definition), statement completions (IntelliSense), and real-time semantic analysis via PowerShell Script Analyzer.
• Debugging Service: Simplifies interaction with the PowerShell debugger, supporting breakpoints, variable inspection, and call stack management.
• $psEditor API: Allows for scripting the host editor.
• Extension Terminal: Provides a full terminal experience for interactive development.

PSES runs as a PowerShell module in currently supported versions of PowerShell 7+. Windows PowerShell 5.1 is supported on a best-effort basis.

To interact with the structure of a script, use these cmdlets:

• Find-Ast: Searches a script file to find a specific Abstract Syntax Tree (AST). It searches all ASTs following the initial starting AST, including those not part of the same tree.
• Get-Token: Retrieves tokens from the current editor context or from a specific ScriptExtent object. Once retrieved, you can use ScriptExtent functions to manipulate the text at those locations.

PowerShell Editor Services provides a generalized extensibility model that allows you to write PowerShell code to automate or extend any host editor (like VS Code) that uses PowerShell Editor Services.

The core of this model is the $psEditor object, which is of type Microsoft.PowerShell.EditorServices.Services.PowerShellContext.EditorObject. This object is the entry point for accessing high-level services in the current editing session, such as the editor's workspace. It is conceptually similar to the $psISE object used in the legacy PowerShell ISE, but designed to be editor-agnostic.

# No direct code snippet for the concept itself, but usage follows:
$psEditor.Workspace.OpenFile($path)

Debugging is handled within the same process as the Language Server Protocol (LSP). To use debugging, your client must support the Debug Adapter Protocol (DAP).

To connect the debugger, the client should use the path to the specific debug named pipe found in the session.json file generated during startup.

Supported extensions include:

• PowerShell for Visual Studio Code
• nvim-dap-powershell for Neovim
• powershell.nvim for Neovim
• intellij-powershell

The Test-ScriptExtent function accepts System.Management.Automation.Language.IScriptExtent objects.

Additionally, you can pass objects that contain a property named Extent. This allows you to use results from other language services directly, such as:

• ASTs from Find-Ast
• Tokens from Get-Token

To make a PowerShell function available as an editor command within PowerShell Editor Services, you must decorate it with the [Microsoft.PowerShell.EditorServices.Services.PowerShellContext.EditorCommand] attribute. This attribute is applied similarly to [CmdletBinding()].

The attribute accepts the following named parameters:

• Name: The internal name of the command.
• DisplayName: The user-facing name displayed in the editor.
• SuppressOutput: A switch parameter that, when present, prevents the command's output from being sent back to the editor's output stream.

function Invoke-MyEditorCommand {
    [CmdletBinding()]
    [Microsoft.PowerShell.EditorServices.Services.PowerShellContext.EditorCommand(DisplayName='My Command', SuppressOutput)]
    param()
    end {
        # Command logic here
    }
}

The module uses ScriptExtent objects to represent specific ranges or positions within a script. You can use the following cmdlets to manage these objects:

• ConvertTo-ScriptExtent: Creates a ScriptExtent object from an object with position-related properties or by specifying parameters directly.
• ConvertFrom-ScriptExtent: Converts ScriptExtent objects into types compatible with $psEditor API methods.
• Join-ScriptExtent: Combines multiple ScriptExtent objects piped into it into a single, unified extent. This is useful for grouping multiple ASTs or tokens.
• Test-ScriptExtent: Determines the spatial relationship between two ScriptExtent objects (e.g., whether one is before, after, or inside another).
• Set-ScriptExtent: Inserts or replaces text at a specific position in a file currently open in PowerShell Editor Services.

The PowerShell Extension Terminal uses the host process's stdio streams for console input and output.

Important Requirements:

1. Mutual Exclusivity: Using the Extension Terminal is mutually exclusive from using stdio for Language Server Protocol (LSP) messages. If you want the terminal, you must use Named Pipes/Unix Domain Sockets for LSP.
2. Activation: You must include the -EnableConsoleRepl switch when calling Start-EditorServices.ps1 to enable this feature.

This feature is used by Visual Studio Code, Vim, and IntelliJ extensions.

# Example activation via named pipes
pwsh -NoLogo -NoProfile -Command "./PowerShellEditorServices/Start-EditorServices.ps1 -SessionDetailsPath ./session.json -EnableConsoleRepl"