Code Monkey home page Code Monkey logo

powershelleditorservices's Introduction

PowerShell Editor Services

Build Status Discord Join the chat at https://gitter.im/PowerShell/PowerShellEditorServices

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).

PowerShell Language Server Protocol clients using PowerShell Editor Services

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

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, terminal-based Integrated Console 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 (recommended)

If you're looking for a more feature-rich experience, Named Pipes 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 typical command to start PowerShell Editor Services using named pipes is as follows:

pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Start-EditorServices.ps1 -BundledModulesPath $PSES_BUNDLE_PATH -LogPath $SESSION_TEMP_PATH/logs.log -SessionDetailsPath $SESSION_TEMP_PATH/session.json -FeatureFlags @() -AdditionalModules @() -HostName 'My Client' -HostProfileId 'myclient' -HostVersion 1.0.0 -LogLevel Normal"

NOTE: In the example above,

  • $PSES_BUNDLE_PATH is the root of the PowerShellEditorServices.zip downloaded from the GitHub releases.
  • $SESSION_TEMP_PATH is the folder path that you'll use for this specific editor session.

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.

The Visual Studio Code, Vim, and IntelliJ extensions currently use Named Pipes.

PowerShell Integrated Console

image

The PowerShell Integrated Console 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 Integrated Console which automatically shares state with the editor-side, you must include the -EnableConsoleRepl switch when called Start-EditorServices.ps1.

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

integrated console in vscode

The Visual Studio Code, Vim, and IntelliJ extensions currently use the PowerShell Integrated Console.

Debugging

Debugging support is also exposed with PowerShell Editor Services. It is handled within the same process as the language server protocol handing. This provides a more integrated experience for end users but is something to note as not many other language servers work in this 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.

Stdio

Stdio is a simpler and more universal mechanism for the Language Server Protocol. We recommend using it if your editor/client doesn't need to support the PowerShell Integrated Console or debugging.

NOTE: Debugging and the Integrated Console are not features of the Stdio channel because each feature requires its own IO streams and since the Stdio model only provides a single set of streams (Stdio), these features cannot be leveraged.

The typical command to start PowerShell Editor Services using stdio is as follows:

pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Start-EditorServices.ps1 -BundledModulesPath $PSES_BUNDLE_PATH -LogPath $SESSION_TEMP_PATH/logs.log -SessionDetailsPath $SESSION_TEMP_PATH/session.json -FeatureFlags @() -AdditionalModules @() -HostName 'My Client' -HostProfileId 'myclient' -HostVersion 1.0.0 -Stdio -LogLevel Normal"

NOTE: In the example above,

  • $PSES_BUNDLE_PATH is the root of the PowerShellEditorServices.zip downloaded from the GitHub releases.
  • $SESSION_TEMP_PATH is the folder path that you'll use for this specific editor session.

The important flag is the -Stdio flag which enables this communication protocol.

Currently, the Emacs extension uses Stdio.

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

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.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

powershelleditorservices's People

Contributors

daviwil avatar andyleejordan avatar rjmholt avatar tylerleonhardt avatar rkeithhill avatar dependabot-preview[bot] avatar bergmeister avatar dependabot[bot] avatar seeminglyscience avatar dfinke avatar justingrote avatar adamdriscoll avatar glennsarti avatar dee-see avatar corbob avatar dkattan avatar powerschill avatar sydneyhsmith avatar nohwnd avatar alexandair avatar vors avatar kamilkosek avatar krishna-vutukuri avatar stevel-msft avatar martingc94 avatar martinsgill avatar justinytchen avatar vladdoster avatar sk82jack avatar robotboyfriend avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.