From 2b4bec866666dbc31799677c99c6c4f88acf2848 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 26 Jul 2015 10:13:36 -0700 Subject: [PATCH 1/6] Create draft contributing.md document This change establishes a draft for the Contribution Guidelines document. More changes will be added later to provide better formatting and internal linking between sections. --- docs/contributing.md | 149 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 000000000..60c271879 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,149 @@ +# Contribution Guidelines + +We welcome many kinds of community contributions to this project! Whether it's a feature implementation, +bug fix, or a good idea, please create an issue so that we can discuss it. It is not necessary to create an +issue before sending a pull request but it may speed up the process if we can discuss your idea before +you start implementing it. + +Because this project exposes a couple different public APIs, we must be very mindful of any potential breaking +changes. Some contributions may not be accepted if they risk introducing breaking changes or if they +don't match the goals of the project. The core maintainer team has the right of final approval over +any contribution to this project. However, we are very happy to hear community feedback on any decision +so that we can ensure we are solving the right problems in the right way. Check out our [governance] +(governance.md) page to learn more about how we run this project. + +## Ways to Contribute + +- File a bug or feature request as an [issue](https://github.com/PowerShell/PowerShellEditorServices/issues) +- Comment on existing issues to give your feedback on how they should be fixed/implemented +- Contribute a bug fix or feature implementation by submitting a pull request +- Contribute more unit tests for feature areas that lack good coverage +- Review the pull requests that others submit to ensure they follow [established guidelines] + (#pull-request-guidelines) +- Help others gets started with the project by contributing documentation or hanging out + in the Slack chatroom [**TODO: Need to set this up!**] + +## Code Contribution Guidelines + +Here's a high level list of guidelines to follow to ensure your code contribution is accepted: + +- Make sure your change aligns with project goals +- Follow established guidelines for coding style and design +- Follow established guidelines for commit hygiene +- Write unit tests to validate new features and bug fixes +- Ensure that the 'Release' build and unit tests pass locally +- Ensure that the AppVeyor build passes for your change +- Respond to all review feedback and final commit cleanup + +### Practice Good Commit Hygiene + +First of all, make sure you are practicing [good commit hygiene](http://blog.ericbmerritt.com/2011/09/21/commit-hygiene-and-git.html) +so that your commits provide a good history of the changes you are making. To be more specific: + +- **Write good commit messages** + + Commit messages should be clearly written so that a person can look at the commit log and understand + how and why a given change was made. Here is a great model commit message taken from a [blog post + by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html): + + Capitalized, short (50 chars or less) summary + + More detailed explanatory text, if necessary. Wrap it to about 72 + characters or so. In some contexts, the first line is treated as the + subject of an email and the rest of the text as the body. The blank + line separating the summary from the body is critical (unless you omit + the body entirely); tools like rebase can get confused if you run the + two together. + + Write your commit message in the imperative: "Fix bug" and not "Fixed bug" + or "Fixes bug." This convention matches up with commit messages generated + by commands like git merge and git revert. + + Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, followed by a + single space, with blank lines in between, but conventions vary here + + - Use a hanging indent + + A change that fixes a known bug with an issue filed should use the proper syntax so that the [issue + is automatically closed](https://help.github.com/articles/closing-issues-via-commit-messages/) once + your change is merged. Here's an example of what such a commit message should look like: + + Fix #3: Catch NullReferenceException from DoThing + + This change adds a try/catch block to catch a NullReferenceException that + gets thrown by DoThing [...] + +- **Squash your commits** + + If you are introducing a new feature but have implemented it over multiple commits, + please [squash those commits](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) + into a single commit that contains all the changes in one place. This especially applies to any "oops" + commits where a file is forgotten or a typo is being fixed. Following this approach makes it a lot easier + to pull those changes to other branches or roll back the change if necessary. + +- **Keep individual commits for larger changes** + + You can certainly maintain individual commits for different phases of a big change. For example, if + you want to reorganize some files before adding new functionality, have your first commit contain all + of the file move changes and then the following commit can have all of the feature additions. We + highly recommend this approach so that larger commits don't turn into a jumbled mess. + +### Add Unit Tests for New Code + +If you're adding a new feature to the project, please make sure to include adequate [xUnit](http://xunit.github.io/) +tests with your change. In this project, we have chosen write out unit tests in a way that uses the +actual PowerShell environment rather than extensive interface mocking. This allows us to be sure that +our features will work in practice. + +We do both component-level and scenario-level testing depending on what code is being tested. We don't +expect contributors to test every possible edge case. Testing mainline scenarios and the most common +failure scenarios is often good enough. + +We are very happy to accept unit test contributions for any feature areas that are more error-prone than +others. Also, if you find that a feature fails for you in a specific case, please feel free to file an issue +that includes a unit test which reproduces the problem. This will allow us to quickly implement a fix +that resolves the problem. + +### Build 'Release' Before Submitting + +Before you send out your pull request, make sure that you have run a Release configuration build of the +project and that all new and existing tests are passing. The Release configuration build ensures that +all public API interfaces have been documented correctly otherwise it throws an error. We have turned +on this check so that our project will always have good generated documentation. + +### Follow the Pull Request Process + +- **Create your pull request** + + Use the [typical process](https://help.github.com/articles/using-pull-requests/) to send a pull request + from your fork of the project. In your pull request message, please give a high-level summary of the + changes that you have made so that reviewers understand the intent of the changes. You should receive + initial comments within a day or two, but please feel free to ping if things are taking longer than + expected. + +- **The build and unit tests must run green** + + When you submit your pull request, our automated build system on AppVeyor will attempt to run a + Release build of your changes and then run all unit tests against the build. If you notice that + any of your unit tests have failed, please fix them by creating a new commit and then pushing it + to your branch. If you see that some unrelated test has failed, try re-running the build for your + pull request. If you continue to see issues, write a comment on the pull request and we will + look into it. + +- **Respond to code review feedback** + + If the reviewers ask you to make changes, make them as a new commit to your branch and push them so + that they are made available for a final review pass. Do not rebase the fixes just yet so that the + commit hash changes don't upset GitHub's pull request UI. + +- **If necessary, do a final rebase** + + Once your final changes have been accepted, we may ask you to do a final rebase to have your commits + so that they follow our commit guidelines. If specific guidance is given, please follow it when + rebasing your commits. Once you do your final push and we see the AppVeyor build pass, we will + merge your changes! + From f25b1293ccb3c941779ad0d5dd5d3ad52545c29f Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 26 Jul 2015 10:20:41 -0700 Subject: [PATCH 2/6] Update README.md to add link to contribution guide --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index e8560c212..301a03b84 100644 --- a/README.md +++ b/README.md @@ -33,3 +33,8 @@ git submodule init git submodule update ``` +## 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] +(docs/contributing.md) to learn more. From 40cda914b1da6af1e701de0e731ac937b65afc1e Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 1 Nov 2015 20:23:53 -0800 Subject: [PATCH 3/6] Add API and host process usage documentation This change introduces new documentation that explains the usage of both the .NET API and the host process. --- README.md | 14 +- docs/using_the_dotnet_api.md | 3 + docs/using_the_host_process.md | 1120 ++++++++++++++++++++++++++++++++ 3 files changed, 1135 insertions(+), 2 deletions(-) create mode 100644 docs/using_the_dotnet_api.md create mode 100644 docs/using_the_host_process.md diff --git a/README.md b/README.md index 301a03b84..9c848600c 100644 --- a/README.md +++ b/README.md @@ -10,14 +10,24 @@ across multiple editors. - The Language Service provides code navigation actions (find references, go to definition) and statement completions (IntelliSense) - The Analysis Service integrates PowerShell Script Analyzer to provide real-time semantic analysis of scripts -- The Console Service provides a simplified PowerShell host for an interactive console (REPL) -- The Debugging Service simplifies interaction with the PowerShell debugger (breakpoints, locals, etc) - COMING SOON +- The Debugging Service simplifies interaction with the PowerShell debugger (breakpoints, variables, call stack, etc) The core Editor Services library is intended to be consumed in any type of host application, whether it is a WPF UI, console application, or web service. A standard console application host is included so that you can easily consume Editor Services functionality in any editor using either the included standard input/output transport protocol or a transport of your own design. +## Documentation + +Check out the following two pages for information about how to use the API and host process: + +- **[Using the .NET API](docs/using_the_dotnet_api.md)** - Read this if you want to use the API in your .NET application +- **[Using the Host Process](docs/using_the_host_process.md)** - Read this if you want to use the API in a non-.NET application such as a code editor + +## Installation + +**TODO**: Add information about acquiring packages from NuGet. + ## Cloning the Code To clone the repository and initialize all the submodules at once you can run: diff --git a/docs/using_the_dotnet_api.md b/docs/using_the_dotnet_api.md new file mode 100644 index 000000000..4d3da4669 --- /dev/null +++ b/docs/using_the_dotnet_api.md @@ -0,0 +1,3 @@ +# Using the PowerShell Editor Services .NET API + +**TODO:** Provide conceptual overview and code examples. \ No newline at end of file diff --git a/docs/using_the_host_process.md b/docs/using_the_host_process.md new file mode 100644 index 000000000..218d24d57 --- /dev/null +++ b/docs/using_the_host_process.md @@ -0,0 +1,1120 @@ +# Using the PowerShell Editor Services Host Process + +The PowerShell Editor Services host process provides an editor-agnostic interface for +leveraging the core .NET API. + +## Launching the Host Process + +From your editor's PowerShell plugin code, launch `Microsoft.PowerShell.EditorServices.Host.exe` +using an editor-native process API that allows you to read and write this process' standard in/out +streams. All communication with the host process occurs via this channel. + +It is recommended that the process I/O be dealt with as a byte stream rather than read as a +string since different parts of the message format could be sent with different text encodings +(see next section). + +It is expected that an editor will launch one instance of the host process for each PowerShell +'workspace' that the user has opened. Generally this would map to a single top-level folder +which contains all of the user's PowerShell script files for a given project. + +# Message Protocol + +A message consists of two parts: a header section and the message body. For now, there is +only one header, `Content-Length`. This header, written with ASCII encoding, specifies the +UTF-8 byte length of the message content to follow. The host process expects that all messages +sent to it will come with an accurate `Content-Length` header so that it knows exactly how many +bytes to read. Likewise, all messages returned from the host process will be sent in this manner. + +## Message Schema + +The body of a message is encoded in JSON and conforms to a specific schema. There are three types of +messages that can be transmitted between editor and host process: `Request`, `Response`, and `Event`. + +### Common Fields + +The common fields shared between all message types are as follows: + +- `seq`: A sequence number that increases with each message sent from the editor to the host. + Even though this field shows up on all message types, it is generally only used to correlate + reponse messages to the initial request that caused it. +- `type`: The type of message being transmitted, either `request`, `response`, or `event`. + +### Request Fields + +A request gets sent by the editor when a particular type of behavior is needed. +In this case, the `type` field will be set to `request`. + +- `command`: The request type. There are a variety of request types that will be enumerated + later in this document. +- `arguments`: A JSON object containing arguments for the request, varies per each request `command`. + +*NOTE: Some `request` types do not require a matching `response` or may cause `events` to be raised at a later time* + +### Response Fields + +A response gets sent by the host process when a request completes or fails. In this case, +the `type`field will be set to `response`. + +- `request_seq`: The `seq` number that was included with the original request, used to help + the editor correlate the response to the original request +- `command`: The name of the request command to which this response relates +- `body`: A JSON object body for the response, varies per each response `command`. +- `success`: A boolean indicating whether the request was successful +- `message`: An optional response message, generally used when `success` is set to `false`. + +### Event Fields + +An event gets sent by the host process when + +- `event`: The name of the event type to which this event relates +- `body`: A JSON object body for the event, varies per each `event` type + +# Request and Response Types + +## File Management + +### `open` + +This request is sent by the editor when the user opens a file with a known PowerShell extension. It causes +the file to be opened by the language service and parsed for syntax errors. + +#### Request + +The arguments object specifies the absolute file path to be loaded. + +```json + { + "seq": 0, + "type": "request", + "command": "open", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1" + } + } +``` + +#### Response + +No response is needed for this command. + +### `close` + +This request is sent by the editor when the user closes a file with a known PowerShell extension which was +previously opened in the language service. + +#### Request + +The arguments object specifies the absolute file path to be closed. + +```json + { + "seq": 3, + "type": "request", + "command": "close", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1" + } + } +``` + +#### Response + +No response is needed for this command. + +### `change` + +This request is sent by the editor when the user changes the contents of a PowerShell file that has previously +been opened in the language service. Depending on how the request arguments are specified, the file change could +either be an arbitrary-length string insertion, region delete, or region replacement. + +It is up to the editor to decide how often to send these requests in response +to the user's typing activity. The language service can deal with change deltas of any length, so it is really +just a matter of preference how often `change` requests are sent. + +#### Request + +The arguments for this request specify the absolute path of the `file` being changed as well as the complete details +of the edit that the user performed. The `line`/`endLine` and `offset`/`endOffset` (column) numbers indicate the +1-based range of the file that is being replaced. The `insertString` field indicates the string that will be +inserted. In the specified range. + +*NOTE: In the very near future, all file locations will be specified with zero-based coordinates.* + +```json + { + "seq": 9, + "type": "request", + "command": "change", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 39, + "offset": 5, + "endLine": 39, + "endOffset": 5, + "insertString": "Test\r\nchange" + } + } +``` + +#### Response + +No response is needed for this command. + +### `geterr` + +This request causes script diagnostics to be performed on a list of script file paths. The editor +will typically send this request after every successful `change` request (though it is best to throttle +these requests on the editor side so that it doesn't overwhelm the host). Responses will be sent back +as `syntaxDiag` and `semanticDiag` events. + +#### Request + +The arguments for this request specify the list of `files` to be analyzed (sorted by those most recently changed) +and a millisecond `delay` value which instructs the language service to wait for some period before performing +diagnostics. If another `geterr` request is sent before the specified `delay` expires, the original request will +be cancelled server-side and a new delay period will start. + +```json + { + "seq": 1, + "type": "request", + "command": "geterr", + "arguments": { + "delay": 750, + "files": [ + "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1" + ] + } + } +``` + +## Code Completions + +### `completions` + +### Request + +```json + { + "seq": 34, + "type": "request", + "command": "completions", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 34, + "offset": 9 + } + } +``` + +#### Response + +```json + { + "request_seq": 34, + "success": true, + "command": "completions", + "message": null, + "body": [ + { + "name": "Get-Acl", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + { + "name": "Get-Alias", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + { + "name": "Get-AliasPattern", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + { + "name": "Get-AppLockerFileInformation", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + { + "name": "Get-AppLockerPolicy", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + { + "name": "Get-AppxDefaultVolume", + "kind": "method", + "kindModifiers": null, + "sortText": null + }, + + ... many more completions ... + + ], + "seq": 0, + "type": "response" + } +``` + +### `completionEntryDetails` + +#### Request + +```json + { + "seq": 37, + "type": "request", + "command": "completionEntryDetails", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 34, + "offset": 9, + "entryNames": [ + "Get-Acl" + ] + } + } +``` + +#### Response + +```json + { + "request_seq": 37, + "success": true, + "command": "completionEntryDetails", + "message": null, + "body": [ + { + "name": null, + "kind": null, + "kindModifiers": null, + "displayParts": null, + "documentation": null, + "docString": null + } + ], + "seq": 0, + "type": "response" + } +``` + +### `signatureHelp` + +#### Request + +```json + { + "seq": 36, + "type": "request", + "command": "signatureHelp", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 34, + "offset": 9 + } + } +``` + +#### Response + +** TODO: This is a bad example, find another** + +```json + { + "request_seq": 36, + "success": true, + "command": "signatureHelp", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +```` + +## Symbol Operations + +### `definition` + +#### Request + +```json + { + "seq": 20, + "type": "request", + "command": "definition", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/StopTest.ps1", + "line": 8, + "offset": 10 + } + } +``` + +#### Response + +```json + { + "request_seq": 20, + "success": true, + "command": "definition", + "message": null, + "body": [ + { + "file": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\Stop-Process2.ps1", + "start": { + "line": 11, + "offset": 10 + }, + "end": { + "line": 11, + "offset": 23 + } + } + ], + "seq": 0, + "type": "response" + } +``` + +### `references` + +#### Request + +```json + { + "seq": 2, + "type": "request", + "command": "references", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 38, + "offset": 12 + } + } +``` + +#### Response + +```json + { + "request_seq": 2, + "success": true, + "command": "references", + "message": null, + "body": { + "refs": [ + { + "lineText": "\t\t\tforeach ($process in $processes)", + "isWriteAccess": true, + "file": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\Stop-Process2.ps1", + "start": { + "line": 32, + "offset": 13 + }, + "end": { + "line": 32, + "offset": 21 + } + } + ], + "symbolName": "$process", + "symbolStartOffest": 690, + "symbolDisplayString": "$process" + }, + "seq": 0, + "type": "response" + } +``` + +### `occurrences` + +#### Request + +```json + { + "seq": 53, + "type": "request", + "command": "occurrences", + "arguments": { + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "line": 32, + "offset": 17 + } + } +``` + +#### Response + +```json + { + "request_seq": 53, + "success": true, + "command": "occurrences", + "message": null, + "body": [ + { + "isWriteAccess": true, + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "start": { + "line": 32, + "offset": 13 + }, + "end": { + "line": 32, + "offset": 21 + } + }, + { + "isWriteAccess": true, + "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", + "start": { + "line": 35, + "offset": 11 + }, + "end": { + "line": 35, + "offset": 19 + } + }, + + ... more occurrences ... + + ], + "seq": 0, + "type": "response" + } +``` + +## Debugger Operations + +### `initialize` + +### `launch` + +This request is sent by the editor when the user wants to launch a given script file in the +debugger. + +#### Request + +```json + { + "type": "request", + "seq": 3, + "command": "launch", + "arguments": { + "program": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "stopOnEntry": false, + "arguments": null, + "workingDirectory": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples", + "runtimeExecutable": null, + "runtimeArguments": null + } + } +``` + +```json + { + "request_seq": 3, + "success": true, + "command": "launch", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `disconnect` + +This request is sent by the editor when the user wants to terminate the debugging session before +the script completes. When this message is received, execution of the script is aborted and the +instance of the host process is aborted. + +*NOTE: For now, it is assumed that debugging will be performed in a separate instance of the + host process. This will change in the next couple of minor releases.* + +#### Request + +```json + { + "type": "request", + "seq": 22, + "command": "disconnect", + "arguments": { + "extensionHostData": { + "restart": false + } + } + } +``` + +#### Response + +```json + { + "request_seq": 0, + "success": false, + "command": "disconnect", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `setBreakpoints` + +#### Request + +```json + { + "type": "request", + "seq": 2, + "command": "setBreakpoints", + "arguments": { + "source": { + "path": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1" + }, + "lines": [ + 10 + ] + } + } +``` + +#### Response + +```json + { + "request_seq": 2, + "success": true, + "command": "setBreakpoints", + "message": null, + "body": { + "breakpoints": [ + { + "verified": true, + "line": 10 + } + ] + }, + "seq": 0, + "type": "response" + } +``` + +### `pause` + +#### Request + +```json + { + "type": "request", + "seq": 4, + "command": "pause" + } +``` + +#### Response + +No response needed for this command. The debugging service will send a `stopped` event +when execution is stopped due to this request. + +### `continue` + +#### Request + +```json + { + "type": "request", + "seq": 9, + "command": "continue" + } +``` + +#### Response + +```json + { + "request_seq": 9, + "success": true, + "command": "continue", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `next` + +#### Request + +```json + { + "type": "request", + "seq": 9, + "command": "next" + } +``` + +#### Response + +```json + { + "request_seq": 9, + "success": true, + "command": "next", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `stepIn` + +#### Request + +```json + { + "type": "request", + "seq": 13, + "command": "stepIn" + } +``` + +#### Response + +```json + { + "request_seq": 13, + "success": true, + "command": "stepIn", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `stepOut` + +#### Request + +```json + { + "type": "request", + "seq": 17, + "command": "stepOut" + } +``` + +#### Response + +```json + { + "request_seq": 17, + "success": true, + "command": "stepOut", + "message": null, + "body": null, + "seq": 0, + "type": "response" + } +``` + +### `threads` + +#### Request + +```json + { + "type": "request", + "seq": 5, + "command": "threads" + } +``` + +#### Response + +```json + { + "request_seq": 5, + "success": true, + "command": "threads", + "message": null, + "body": { + "threads": [ + { + "id": 1, + "name": "Main Thread" + } + ] + }, + "seq": 0, + "type": "response" + } +``` + +### `scopes` + +#### Request + +```json + { + "type": "request", + "seq": 7, + "command": "scopes", + "arguments": { + "frameId": 1 + } + } +``` + +#### Response + +```json + { + "request_seq": 7, + "success": true, + "command": "scopes", + "message": null, + "body": { + "scopes": [ + { + "name": "Locals", + "variablesReference": 1, + "expensive": false + } + ] + }, + "seq": 0, + "type": "response" + } +``` + +### `variables` + +#### Request + +```json + { + "type": "request", + "seq": 8, + "command": "variables", + "arguments": { + "variablesReference": 1 + } + } +``` + +#### Response + +```json + { + "request_seq": 8, + "success": true, + "command": "variables", + "message": null, + "body": { + "variables": [ + { + "name": "?", + "value": "True", + "variablesReference": 0 + }, + { + "name": "args", + "value": " ", + "variablesReference": 11 + }, + { + "name": "ConsoleFileName", + "value": "", + "variablesReference": 0 + }, + { + "name": "ExecutionContext", + "value": " ", + "variablesReference": 13 + }, + { + "name": "false", + "value": "False", + "variablesReference": 0 + }, + { + "name": "HOME", + "value": "C:\\Users\\daviwil", + "variablesReference": 0 + }, + + ... more variables ... + + ] + }, + "seq": 0, + "type": "response" + } +``` + +### `stackTrace` + +#### Request + +```json + { + "type": "request", + "seq": 6, + "command": "stackTrace", + "arguments": { + "threadId": 1, + "levels": 20 + } + } +``` + +#### Response + +```json + { + "request_seq": 6, + "success": true, + "command": "stackTrace", + "message": null, + "body": { + "stackFrames": [ + { + "id": 1, + "name": "Write-Item", + "source": { + "name": null, + "path": "C:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "sourceReference": null + }, + "line": 10, + "column": 9 + }, + { + "id": 2, + "name": "Do-Work", + "source": { + "name": null, + "path": "C:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "sourceReference": null + }, + "line": 18, + "column": 5 + }, + { + "id": 3, + "name": "", + "source": { + "name": null, + "path": "C:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "sourceReference": null + }, + "line": 23, + "column": 1 + } + ] + }, + "seq": 0, + "type": "response" + } +``` + +### `evaluate` + +#### Request + +```json + { + "type": "request", + "seq": 13, + "command": "evaluate", + "arguments": { + "expression": "i", + "frameId": 1 + } + } +``` + +#### Response + +```json + { + "request_seq": 13, + "success": true, + "command": "evaluate", + "message": null, + "body": { + "result": "2", + "variablesReference": 0 + }, + "seq": 0, + "type": "response" + } +``` + +# Event Types + +## Script Diagnostics + +### `syntaxDiag` + +```json + { + "event": "syntaxDiag", + "body": { + "file": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "diagnostics": [ + { + "start": { + "line": 3, + "offset": 1 + }, + "end": { + "line": 3, + "offset": 2 + }, + "text": "Missing closing '}' in statement block or type definition.", + "severity": 2 + } + ] + }, + "seq": 0, + "type": "event" + } +``` + +### `semanticDiag` + +```json + { + "event": "semanticDiag", + "body": { + "file": "c:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "diagnostics": [ + { + "start": { + "line": 14, + "offset": 1 + }, + "end": { + "line": 21, + "offset": 2 + }, + "text": "The cmdlet 'Do-Work' uses an unapproved verb.", + "severity": 1 + }, + { + "start": { + "line": 20, + "offset": 5 + }, + "end": { + "line": 20, + "offset": 23 + }, + "text": "File '' uses Write-Host. This is not recommended because it may not work in some hosts or there may even be no hosts at all. Use Write-Output instead.", + "severity": 1 + }, + { + "start": { + "line": 18, + "offset": 16 + }, + "end": { + "line": 18, + "offset": 26 + }, + "text": "Variable 'workcount' is not initialized. Non-global variables must be initialized. To fix a violation of this rule, please initialize non-global variables.", + "severity": 1 + } + ] + }, + "seq": 0, + "type": "event" + } +``` + +## Language Service Events + +### `started` + +This message is sent as soon as the language service finishes initializing. The editor will +wait for this message to be received before it starts sending requests to the host. This event +has no body and will always be `null`. + +```json + { + "event": "started", + "body": null, + "seq": 0, + "type": "event" + } +``` + +## Debugger Events + +### `initialized` + +```json + { + "event": "initialized", + "body": null, + "seq": 0, + "type": "event" + } +``` + +### `stopped` + +```json + { + "event": "stopped", + "body": { + "reason": "breakpoint", + "threadId": 1, + "source": { + "name": null, + "path": "C:\\Users\\daviwil\\.vscode\\extensions\\vscode-powershell\\examples\\DebugTest.ps1", + "sourceReference": null + }, + "line": 10, + "column": 9, + "text": null + }, + "seq": 0, + "type": "event" + } +``` + +### `terminated` + +```json + { + "event": "terminated", + "body": null, + "seq": 0, + "type": "event" + } +``` + +# Host Process Lifecycle + +Right now, language and debugging service generally run separately. + +## Language Service + +`started` event, etc + +## Debugging Service \ No newline at end of file From ba216354e4abdb2eef341708228016ccc5a061e4 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 6 Dec 2015 10:43:06 -0800 Subject: [PATCH 4/6] Update contributing.md --- docs/contributing.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 60c271879..ab21582ea 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -9,8 +9,7 @@ Because this project exposes a couple different public APIs, we must be very min changes. Some contributions may not be accepted if they risk introducing breaking changes or if they don't match the goals of the project. The core maintainer team has the right of final approval over any contribution to this project. However, we are very happy to hear community feedback on any decision -so that we can ensure we are solving the right problems in the right way. Check out our [governance] -(governance.md) page to learn more about how we run this project. +so that we can ensure we are solving the right problems in the right way. ## Ways to Contribute @@ -21,13 +20,12 @@ so that we can ensure we are solving the right problems in the right way. Check - Review the pull requests that others submit to ensure they follow [established guidelines] (#pull-request-guidelines) - Help others gets started with the project by contributing documentation or hanging out - in the Slack chatroom [**TODO: Need to set this up!**] + in the #editors room in the [PowerShell community Slack chat](http://slack.poshcode.org). ## Code Contribution Guidelines Here's a high level list of guidelines to follow to ensure your code contribution is accepted: -- Make sure your change aligns with project goals - Follow established guidelines for coding style and design - Follow established guidelines for commit hygiene - Write unit tests to validate new features and bug fixes From 600c7ce6c52c37db86819b5bab77111d46b269c5 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 6 Dec 2015 10:43:15 -0800 Subject: [PATCH 5/6] Update README.md --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9c848600c..58fb6b1de 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,17 @@ across multiple editors. ## Features -- The Language Service provides code navigation actions (find references, go to definition) and statement completions (IntelliSense) -- The Analysis Service integrates PowerShell Script Analyzer to provide real-time semantic analysis of scripts +- 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 + - Basic script evaluation - The Debugging Service simplifies interaction with the PowerShell debugger (breakpoints, variables, call stack, etc) The core Editor Services library is intended to be consumed in any type of host application, whether it is a WPF UI, console application, or web service. A standard console application host is included -so that you can easily consume Editor Services functionality in any editor using either the included -standard input/output transport protocol or a transport of your own design. +so that you can easily consume Editor Services functionality in any editor using the JSON API that it +exposes. ## Documentation @@ -26,7 +29,7 @@ Check out the following two pages for information about how to use the API and h ## Installation -**TODO**: Add information about acquiring packages from NuGet. +**TODO**: Add information about acquiring packages from NuGet once those are available. ## Cloning the Code From 9cb5bbf0ded4479ad3842c1aff265c451a92dd51 Mon Sep 17 00:00:00 2001 From: David Wilson Date: Sun, 6 Dec 2015 10:46:04 -0800 Subject: [PATCH 6/6] Update host process API docs --- docs/using_the_host_process.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/using_the_host_process.md b/docs/using_the_host_process.md index 218d24d57..20c9d53bd 100644 --- a/docs/using_the_host_process.md +++ b/docs/using_the_host_process.md @@ -3,6 +3,10 @@ The PowerShell Editor Services host process provides an editor-agnostic interface for leveraging the core .NET API. +**WARNING: Some of the information in this file is out of date due to recent protocol +changes. The general details in the document still apply but the schema of the language service +message has changed a lot. This document will be updated soon with the correct details.** + ## Launching the Host Process From your editor's PowerShell plugin code, launch `Microsoft.PowerShell.EditorServices.Host.exe`