From 7662e44bb47267f6379bab5cfba386cf8960dd9e Mon Sep 17 00:00:00 2001 From: Tyler Leonhardt Date: Fri, 4 Oct 2019 16:18:16 -0700 Subject: [PATCH 1/5] Start docs --- README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d7276c92b..b7364565b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ 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 +## PowerShell [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) clients using PowerShell Editor Services The functionality in PowerShell Editor Services is already available in the following editor extensions: @@ -29,6 +29,76 @@ The functionality in PowerShell Editor Services is already available in the foll - The [$psEditor API](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor - A full, terminal-based Integrated Console experience for interactive development and debugging +## Usage + +Looking to integrate PowerShell Editor Services into your [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) compliant editor or client? We support two ways of connecting. + +### Named Pipes/Unix Domain Sockets (recommended) + +If you're looking for the more feature-rich experience, +Named Pipes are the way to go. +They give you all the benefit of the Lanaguge Server Protocol with extra capabilities that you can take advantage of: + +- The PowerShell Integrated Console +- Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) + +The typical command to start PowerShell Editor Services using named pipes is as follows: + +```powershell +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. + +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 one 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](https://user-images.githubusercontent.com/2644648/66245084-6985da80-e6c0-11e9-9c7b-4c8476190df5.png) + +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 has the ability to create arbirary terminals in the editor like below: + +![integrated console in vscode](https://user-images.githubusercontent.com/2644648/66245018-04ca8000-e6c0-11e9-808c-b86144149444.png) + +The Visual Studio Code, Vim, and IntelliJ extensions currently use the PowerShell Integrated Console. + +#### Debugging + +If you want to take advantage of debugging, +your client must support the [Debug Adapter Protocol](https://microsoft.github.io/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 when it comes to the Language Server Protocol and is what we recommend if your editor/client doesn't need to support the PowerShell Integrated Console or debugging. + +The typical command to start PowerShell Editor Services using stdio is as follows: + +```powershell +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. + ## Development ### 1. Install PowerShell 6+ From e086d1bd33b141a72160b6bd96645868337f30ef Mon Sep 17 00:00:00 2001 From: Tyler Leonhardt Date: Mon, 7 Oct 2019 10:40:35 -0700 Subject: [PATCH 2/5] steve and rob's feedback --- README.md | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b7364565b..042a2a3a1 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,20 @@ experience in almost any editor or integrated development environment (IDE). The functionality in PowerShell Editor Services is already available in the following editor extensions: -- [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio -- [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin -- [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) -- [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin + - [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio + - [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin + - [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) + - [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin ## 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor -- A full, terminal-based Integrated Console experience for interactive development and debugging + - 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor + - A full, terminal-based Integrated Console experience for interactive development and debugging ## Usage @@ -39,8 +39,8 @@ If you're looking for the more feature-rich experience, Named Pipes are the way to go. They give you all the benefit of the Lanaguge Server Protocol with extra capabilities that you can take advantage of: -- The PowerShell Integrated Console -- Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) + - The PowerShell Integrated Console + - Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) The typical command to start PowerShell Editor Services using named pipes is as follows: @@ -50,9 +50,11 @@ pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Sta > 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. +> - `$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 one you connect to when you launch the debugger for Debug Adapter Protocol messages. @@ -63,6 +65,8 @@ The Visual Studio Code, Vim, and IntelliJ extensions currently use Named Pipes. ![image](https://user-images.githubusercontent.com/2644648/66245084-6985da80-e6c0-11e9-9c7b-4c8476190df5.png) +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`. @@ -74,6 +78,9 @@ The Visual Studio Code, Vim, and IntelliJ extensions currently use the PowerShel #### 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](https://microsoft.github.io/debug-adapter-protocol/). Your client should use the path to the debug named pipe found in the `session.json` file talked about above. @@ -84,6 +91,9 @@ Currently only the Visual Studio Code extension supports debugging. Stdio is a simpler and more universal mechanism when it comes to the Language Server Protocol and is what we recommend 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 their 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: ```powershell From c7b81f345cad54a7806ff09b48f5fcb524e7e6a0 Mon Sep 17 00:00:00 2001 From: Tyler Leonhardt Date: Mon, 7 Oct 2019 10:48:55 -0700 Subject: [PATCH 3/5] add note on API usage --- README.md | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 042a2a3a1..a91babf44 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,20 @@ experience in almost any editor or integrated development environment (IDE). The functionality in PowerShell Editor Services is already available in the following editor extensions: - - [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio - - [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin - - [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) - - [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin +- [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio +- [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin +- [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) +- [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin ## 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor - - A full, terminal-based Integrated Console experience for interactive development and debugging +- 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor +- A full, terminal-based Integrated Console experience for interactive development and debugging ## Usage @@ -39,8 +39,8 @@ If you're looking for the more feature-rich experience, Named Pipes are the way to go. They give you all the benefit of the Lanaguge Server Protocol with extra capabilities that you can take advantage of: - - The PowerShell Integrated Console - - Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) +- The PowerShell Integrated Console +- Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) The typical command to start PowerShell Editor Services using named pipes is as follows: @@ -50,8 +50,8 @@ pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Sta > 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. +> - `$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. @@ -109,6 +109,16 @@ The important flag is the `-Stdio` flag which enables this communication protoco 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 production environment. + ## Development ### 1. Install PowerShell 6+ From 7d0fb5dcd0ee9712237b0b1d157f1adae130746d Mon Sep 17 00:00:00 2001 From: Tyler Leonhardt Date: Mon, 7 Oct 2019 10:58:10 -0700 Subject: [PATCH 4/5] extra space after - --- README.md | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index a91babf44..c0f22b99a 100644 --- a/README.md +++ b/README.md @@ -14,20 +14,20 @@ experience in almost any editor or integrated development environment (IDE). The functionality in PowerShell Editor Services is already available in the following editor extensions: -- [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio -- [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin -- [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) -- [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin +- [The VSCode PowerShell extension](https://github.com/PowerShell/vscode-powershell), also available in Azure Data Studio +- [coc-powershell](https://github.com/yatli/coc-powershell), a vim/neovim PowerShell plugin +- [The IntelliJ PowerShell plugin](https://github.com/ant-druha/intellij-powershell) +- [lsp-powershell](https://github.com/kiennq/lsp-powershell), an Emacs PowerShell plugin ## 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor -- A full, terminal-based Integrated Console experience for interactive development and debugging +- 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](http://powershell.github.io/PowerShellEditorServices/guide/extensions.html) enables scripting of the host editor +- A full, terminal-based Integrated Console experience for interactive development and debugging ## Usage @@ -39,8 +39,8 @@ If you're looking for the more feature-rich experience, Named Pipes are the way to go. They give you all the benefit of the Lanaguge Server Protocol with extra capabilities that you can take advantage of: -- The PowerShell Integrated Console -- Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) +- The PowerShell Integrated Console +- Debugging using the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) The typical command to start PowerShell Editor Services using named pipes is as follows: @@ -50,8 +50,8 @@ pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Sta > 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. +> - `$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. @@ -102,8 +102,8 @@ pwsh -NoLogo -NoProfile -Command "$PSES_BUNDLE_PATH/PowerShellEditorServices/Sta > 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. +> - `$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. @@ -113,9 +113,9 @@ Currently, the Emacs extension uses Stdio. 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 +- 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 production environment. @@ -157,10 +157,10 @@ contribute code, documentation, tests, or bug reports, please read our [Contribu ## Maintainers -- [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill) -- [Patrick Meinecke](https://github.com/SeeminglyScience) - [@SeeminglyScienc](http://twitter.com/SeeminglyScienc) -- [Tyler Leonhardt](https://github.com/tylerleonhardt) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt) -- [Rob Holt](https://github.com/rjmholt) - no twitter +- [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill) +- [Patrick Meinecke](https://github.com/SeeminglyScience) - [@SeeminglyScienc](http://twitter.com/SeeminglyScienc) +- [Tyler Leonhardt](https://github.com/tylerleonhardt) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt) +- [Rob Holt](https://github.com/rjmholt) - no twitter ## License From 70e125eec9a0781bb5a188f3fa018e8757a9667b Mon Sep 17 00:00:00 2001 From: Tyler James Leonhardt Date: Tue, 8 Oct 2019 16:56:12 -0700 Subject: [PATCH 5/5] Rob's gone social! Co-Authored-By: Robert Holt --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c0f22b99a..93aa56cf9 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ contribute code, documentation, tests, or bug reports, please read our [Contribu - [Keith Hill](https://github.com/rkeithhill) - [@r_keith_hill](http://twitter.com/r_keith_hill) - [Patrick Meinecke](https://github.com/SeeminglyScience) - [@SeeminglyScienc](http://twitter.com/SeeminglyScienc) - [Tyler Leonhardt](https://github.com/tylerleonhardt) - [@TylerLeonhardt](http://twitter.com/tylerleonhardt) -- [Rob Holt](https://github.com/rjmholt) - no twitter +- [Rob Holt](https://github.com/rjmholt) - [@rjmholt](https://twitter.com/rjmholt) ## License