• Stars
    star
    623
  • Rank 72,088 (Top 2 %)
  • Language
    C#
  • License
    MIT License
  • Created over 9 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A common platform for PowerShell development support in any editor or application!

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, 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 (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.

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/PID automation features like $process.Close() or $process.Kill()

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

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

PowerShell Extension Terminal

image

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 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:

Extension Terminal in vscode

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 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 Extension Terminal or debugging.

NOTE: Debugging and the Extension Terminal 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
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 [email protected] with any additional questions or comments.

More Repositories

1

PowerShell

PowerShell for every system!
C#
45,459
star
2

Win32-OpenSSH

Win32 port of OpenSSH
7,290
star
3

PSReadLine

A bash inspired readline implementation for PowerShell
C#
3,700
star
4

PSScriptAnalyzer

Download ScriptAnalyzer from PowerShellGallery
C#
1,842
star
5

vscode-powershell

Provides PowerShell language and debugging support for Visual Studio Code
TypeScript
1,687
star
6

DscResources

Central repository for PowerShell Desired State Configuration (DSC) resources.
772
star
7

ConsoleGuiTools

Modules that mix PowerShell and GUIs/CUIs!
C#
772
star
8

platyPS

Write PowerShell External Help in Markdown
C#
765
star
9

Polaris

A cross-platform, minimalist web framework for PowerShell
PowerShell
507
star
10

PSResourceGet

PSResourceGet is the package manager for PowerShell
C#
483
star
11

PowerShellGetv2

PowerShellGet is the Package Manager for PowerShell
PowerShell
430
star
12

PowerShell-RFC

RFC (Request for Comments) documents for community feedback on design changes and improvements to PowerShell ecosystem
PowerShell
430
star
13

PowerShell-Docker

Repository for building PowerShell Docker images
Dockerfile
400
star
14

Crescendo

a module for wrapping native applications in a PowerShell function and module
PowerShell
397
star
15

SecretManagement

PowerShell module to consistent usage of secrets through different extension vaults
C#
321
star
16

JEA

Just Enough Administration
PowerShell
254
star
17

PowerShellGallery

PowerShell
228
star
18

Operation-Validation-Framework

PowerShell
223
star
19

DSC

This repo is for the DSC v3 project
Rust
192
star
20

SHiPS

Simple Hierarchy in PowerShell - developing PowerShell provider got so much easier
C#
188
star
21

PSSwagger

The cmdlet generator from OpenAPI (f.k.a Swagger) specification
PowerShell
164
star
22

PowerShellStandard

C#
157
star
23

SecretStore

C#
155
star
24

PSPrivateGallery

DSC Resources and Configurations to deploy and manage Private PowerShell Gallery
PowerShell
148
star
25

CompletionPredictor

C#
145
star
26

GPRegistryPolicyParser

PowerShell
140
star
27

WindowsCompatibility

Module that allows Windows PowerShell Modules to be used from PSCore6
PowerShell
137
star
28

PowerShell-Tests

Pester based tests for testing PowerShell
PowerShell
130
star
29

PowerShell-IoT

Interact with I2C, SPI & GPIO devices using PowerShell Core!
C#
130
star
30

PSDscResources

PowerShell
129
star
31

EditorSyntax

PowerShell syntax highlighting for editors (VS Code, Atom, SublimeText, TextMate, etc.) and GitHub!
PowerShell
127
star
32

Modules

C#
111
star
33

Phosphor

A library and PowerShell module for generating user interfaces from PowerShell modules
TypeScript
109
star
34

GPRegistryPolicy

PowerShell
102
star
35

Community-Blog

Submissions for posts to the PowerShell Community Blog -https://devblogs.microsoft.com/powershell-community
102
star
36

psl-omi-provider

PSRP Linux support library
C
100
star
37

Microsoft.PowerShell.Archive

Archive PowerShell module contains cmdlets for working with ZIP archives
C#
93
star
38

PSArm

PSArm is a PowerShell module that provides a PowerShell-embedded domain-specific language (DSL) for Azure Resource Manager (ARM) templates
C#
77
star
39

Remotely

Enable remote execution of scripts. Works with Pester.
PowerShell
74
star
40

TextUtility

Microsoft.PowerShell.TextUtility module
C#
64
star
41

PSDesiredStateConfiguration

Source for https://www.powershellgallery.com/packages/PSDesiredStateConfiguration module
PowerShell
59
star
42

ProjectMercury

An interactive shell to work with AI-powered assistance providers
C#
56
star
43

Demo_CI

PowerShell
55
star
44

PowerShellGet

This module provide functions used with PowerShellGet v3 to provide compatibility with scripts expecting PowerShellGet v2
PowerShell
55
star
45

DscResource.Tests

Common meta tests for PowerShell DSC resources repositories.
PowerShell
51
star
46

PowerShell-Native

C++
48
star
47

Whitepapers

Staging area for new documents and whitepapers
46
star
48

AzurePSDrive

Navigate Azure Resources Just like A FileSystem
PowerShell
41
star
49

ContainerProvider

ContainerImageProvider
PowerShell
38
star
50

PrivateCloud.DiagnosticInfo

PowerShell
38
star
51

PackageManagementProviderResource

Modules with DSC resources for the PackageManagement(aka OneGet) providers.
PowerShell
37
star
52

Pager

Project for console pager, which is published as a NuGet package Microsoft.PowerShell.Pager
C#
34
star
53

MarkdownRender

C#
32
star
54

DSC-Samples

Samples and tutorials for DSC v3
Go
29
star
55

PlasterBuild

Provides common build tasks for PowerShell module projects
PowerShell
29
star
56

PowerShell-Snap

PowerShell
28
star
57

SelfSignedCertificate

A module for generating self-signed certificates in PowerShell Core
PowerShell
27
star
58

CimPSDrive

SHiPS based provider to navigate CIM classes and namespaces
PowerShell
27
star
59

DscConfigurations

PowerShell
27
star
60

tree-sitter-PowerShell

JavaScript
25
star
61

GitHub-Actions

PowerShell
25
star
62

MMI

C#
24
star
63

Microsoft.PowerShell.Kubectl

PowerShell module to manage Kubernetes
PowerShell
23
star
64

LibreSSL

C
22
star
65

ODataUtils

PowerShell Module to generate cmdlets from an OData endpoint
PowerShell
22
star
66

ThreadJob

PowerShell
22
star
67

WmiNamespaceSecurityDsc

This module contains DSC resources to manage WMI Namespace Security.
PowerShell
21
star
68

FileUtility

C#
21
star
69

UnixCompleters

C#
20
star
70

Homebrew-Tap

Ruby
19
star
71

underhanded-powershell

Underhanded PowerShell Contest Repository
PowerShell
18
star
72

Hardware-Management-Module

PowerShell
17
star
73

generator-powershell

Create PowerShell modules and scripts using Yeoman!
JavaScript
16
star
74

Announcements

PowerShell Team Announcements
15
star
75

JsonAdapter

C#
14
star
76

PowerShellModuleCoverage

Track issues related to using Windows PowerShell modules with PowerShell
13
star
77

whatsnew

PowerShell
13
star
78

PSRelease

PowerShell
11
star
79

AwsDscToolkit

AWS DSC Toolkit
PowerShell
10
star
80

DscResource.Template

PowerShell
10
star
81

command-not-found

C#
10
star
82

TemplateConfig

Provides template for organizing DSC configuration scripts and supporting modules
PowerShell
10
star
83

SystemLocaleDsc

DSC Resource for configuring Windows System Locale
PowerShell
9
star
84

SmartPackageProvider

A PackageManagement provider to find and install packages using search engines
C#
9
star
85

xDisk

PowerShell
8
star
86

psl-pester

Fork of Pester for compatibility with PowerShell on Linux.
PowerShell
8
star
87

PowerShell-Blog-Samples

Samples for the PowerShell blog
PowerShell
8
star
88

ZLib

C
7
star
89

AWSBootStrapper

PowerShell
6
star
90

WSAProvider

A PackageManagement provider to find and install packages for Appx based packaging format
PowerShell
6
star
91

PowerShellGetDsc

DSCResources for the PowerShellGet module
PowerShell
5
star
92

DscConfiguration.Tests

Test automation scripts for evaluating the quality of DSC Configurations using Azure virtual machines and Azure Automation DSC.
PowerShell
5
star
93

SILDeploymentHelper

PowerShell
4
star
94

vscode-powershellise-keybindings

A Visual Studio Code extension that configures PowerShell ISE keybindings.
TypeScript
4
star
95

PSPackageProject

PowerShell
4
star
96

Compliance

3
star
97

.github

3
star
98

ISEAddOnExamples

3
star
99

pscore-docs-dotnet

PowerShell
2
star
100

JsonAdapterFeedbackPredictor

1
star