From d5f19031f2f065ee297ae6180fde888b12ffb3b1 Mon Sep 17 00:00:00 2001 From: Karl Burtram Date: Thu, 22 Dec 2016 01:27:15 -0800 Subject: [PATCH] More documentation updates (#203) * Update docs 1 * MOre oc updates * Another set of doc updates * Few more doc cleanups --- docs/guide/jsonrpc_protocol.md | 1279 +++++--------------------------- docs/guide/toc.md | 2 +- 2 files changed, 193 insertions(+), 1088 deletions(-) diff --git a/docs/guide/jsonrpc_protocol.md b/docs/guide/jsonrpc_protocol.md index 98b1144f..0cd66ff9 100644 --- a/docs/guide/jsonrpc_protocol.md +++ b/docs/guide/jsonrpc_protocol.md @@ -1,7 +1,7 @@ -# JSON-RPC Protocol +# SQL Tools JSON-RPC Protocol -The JSON-RPC API provides an host-agnostic interface for -leveraging the core .NET API. +The SQL Tools JSON-RPC API provides an host-agnostic interface for the SQL Tools Service functionality. +The API provides easily consumable operations that allow simple integration into tools applications. ## Launching the Host Process @@ -29,37 +29,39 @@ services such as connection management or query execution. This document provides the protocol specification for all the service's JSON-RPC APIs. -General +### Connection Management -* :leftwards_arrow_with_hook: [initialize](#initialize) -* :leftwards_arrow_with_hook: [shutdown](#shutdown) -* :arrow_right: [exit](#exit) -* :arrow_right: [$/cancelRequest](#cancelRequest) -* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) -* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) +* :leftwards_arrow_with_hook: [connection/connect](#connect_connect) +* :leftwards_arrow_with_hook: [connection/cancelconnect](#connect_cancelconnect) +* :arrow_right: [connection/connectionchanged](#connection_connectionchanged) +* :arrow_right: [connection/complete](#connection_complete) +* :arrow_right: [connection/disconnect](#connection_disconnect) -Language Service +### Query Execution +* :leftwards_arrow_with_hook: [query/execute](#query_execute) -* :arrow_left: [window/showMessage](#window_showMessage) -* :arrow_right_hook: [window/showMessageRequest](#window_showMessageRequest) -* :arrow_left: [window/logMessage](#window_logMessage) -* :arrow_left: [telemetry/event](#telemetry_event) -* :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics) -* :arrow_right: [textDocument/didChange](#textDocument_didChange) -* :arrow_right: [textDocument/didClose](#textDocument_didClose) -* :arrow_right: [textDocument/didOpen](#textDocument_didOpen) -* :arrow_right: [textDocument/didSave](#textDocument_didSave) -* :leftwards_arrow_with_hook: [textDocument/completion](#textDocument_completion) -* :leftwards_arrow_with_hook: [completionItem/resolve](#completionItem_resolve) -* :leftwards_arrow_with_hook: [textDocument/hover](#textDocument_hover) -* :leftwards_arrow_with_hook: [textDocument/signatureHelp](#textDocument_signatureHelp) -* :leftwards_arrow_with_hook: [textDocument/references](#textDocument_references) -* :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition) +### Language Service Protocol -Connection Management - -Query Execution +Documentation for the Language Service Protocol is available at +[language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md). +The SQL Tools Service implements the following portion Language Service Protocol. +* :leftwards_arrow_with_hook: [initialize](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#initialize) +* :leftwards_arrow_with_hook: [shutdown](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#shutdown) +* :arrow_right: [exit](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#exit) +* :arrow_right: [workspace/didChangeConfiguration](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeConfiguration) +* :arrow_right: [workspace/didChangeWatchedFiles](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeWatchedFiles) +* :arrow_left: [textDocument/publishDiagnostics](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_publishDiagnostics) +* :arrow_right: [textDocument/didChange](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didChange) +* :arrow_right: [textDocument/didClose](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didClose) +* :arrow_right: [textDocument/didOpen](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didOpen) +* :arrow_right: [textDocument/didSave](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didSave) +* :leftwards_arrow_with_hook: [textDocument/completion](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_completion) +* :leftwards_arrow_with_hook: [completionItem/resolve](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#completionItem_resolve) +* :leftwards_arrow_with_hook: [textDocument/hover](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_hover) +* :leftwards_arrow_with_hook: [textDocument/signatureHelp](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_signatureHelp) +* :leftwards_arrow_with_hook: [textDocument/references](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_references) +* :leftwards_arrow_with_hook: [textDocument/definition](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_definition) # Message Protocol @@ -113,12 +115,6 @@ 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 - - - - - - ## Base Protocol The base protocol consists of a header and a content part (comparable to HTTP). The header and content part are @@ -146,7 +142,6 @@ The header part is encoded using the 'ascii' encoding. This includes the '\r\n' Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to 'utf8', which is the only encoding supported right now. - ### Example: ``` @@ -268,159 +263,15 @@ interface NotificationMessage extends Message { } ``` -#### Cancellation Support +## Example Request and Response Message ->**New:** The base protocol now offers support for request cancellation. To cancel a request, a notification message with the following properties is sent: - -_Notification_: -* method: '$/cancelRequest' -* params: `CancelParams` defined as follows: -```typescript -interface CancelParams { - /** - * The request id to cancel. - */ - id: number | string; -} -``` +See the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md) +for more details on the protocol formats for these Langauge Service events. Below is an example of the JSON-RPC +message format for the `textDocument/didChange` message. -A request that got canceled still needs to return from the server and send a response back. It can not be left open / hanging. This is in line with the JSON RPC protocol that requires that every request sends a response back. In addition it allows for returning partial results on cancel. +### `textDocument/didChange` -## Language Server Protocol - -The language server protocol defines a set of JSON-RPC request, response and notification messages which are exchanged using the above base protocol. This section starts describing the basic JSON structures used in the protocol. The document uses TypeScript interfaces to describe these. Based on the basic JSON structures, the actual requests with their responses and the notifications are described. - -The protocol currently assumes that one server serves one tool. There is currently no support in the protocol to share one server between different tools. Such a sharing would require additional protocol to either lock a document to support concurrent editing. - -### Basic JSON Structures - -#### URI - -URI's are transferred as strings. The URI's format is defined in [http://tools.ietf.org/html/rfc3986](http://tools.ietf.org/html/rfc3986) - -``` - foo://example.com:8042/over/there?name=ferret#nose - \_/ \______________/\_________/ \_________/ \__/ - | | | | | -scheme authority path query fragment - | _____________________|__ - / \ / \ - urn:example:animal:ferret:nose -``` - -We also maintain a node module to parse a string into `scheme`, `authority`, `path`, `query`, and `fragment` URI components. The GitHub repository is [https://github.com/Microsoft/vscode-uri](https://github.com/Microsoft/vscode-uri) the npm module is [https://www.npmjs.com/package/vscode-uri](https://www.npmjs.com/package/vscode-uri). - - -#### Position - -Position in a text document expressed as zero-based line and character offset. A position is between two characters like an 'insert' cursor in a editor. - -```typescript -interface Position { - /** - * Line position in a document (zero-based). - */ - line: number; - - /** - * Character offset on a line in a document (zero-based). - */ - character: number; -} -``` -#### Range - -A range in a text document expressed as (zero-based) start and end positions. A range is comparable to a selection in an editor. Therefore the end position is exclusive. - -```typescript -interface Range { - /** - * The range's start position. - */ - start: Position; - - /** - * The range's end position. - */ - end: Position; -} -``` - -#### Location - -Represents a location inside a resource, such as a line inside a text file. -```typescript -interface Location { - uri: string; - range: Range; -} -``` - - - - - - - - - - - -# 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 +This request is sent by the editor when the user changes the contents of a SQL 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. @@ -435,15 +286,13 @@ of the edit that the user performed. The `line`/`endLine` and `offset`/`endOffs 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", + "file": "c:/Users/UserName/Documents/test.sql", "line": 39, "offset": 5, "endLine": 39, @@ -457,960 +306,216 @@ inserted. In the specified range. No response is needed for this command. -### `geterr` +# Database Management Protocol -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. +The follow section describes the message protocol format for the common database management +functionaltiy provided by the SQL Tools Service. + +## Connection Management + +### `connection/connect` + +Establish a connection to a database server. #### 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 +```typescript + public class ConnectParams { - "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 - } + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } + /// + /// Contains the required parameters to initialize a connection to a database. + /// A connection will identified by its server name, database name and user name. + /// This may be changed in the future to support multiple connections with different + /// connection properties to the same database. + /// + public ConnectionDetails Connection { get; set; } } ``` #### 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" - } +```typescript + bool ``` -### `completionEntryDetails` +### `connect/cancelconnect` + +Cancel an active connection request. #### Request -```json +```typescript + public class CancelConnectParams { - "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" - ] - } + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } } ``` #### 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" - } +```typescript + bool ``` -### `signatureHelp` +### `connection/connectionchanged` + +Connection changed notification #### Request -```json +```typescript + public class ConnectionChangedParams { - "seq": 36, - "type": "request", - "command": "signatureHelp", - "arguments": { - "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", - "line": 34, - "offset": 9 - } + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } + /// + /// Contains the high-level properties about the connection, for display to the user. + /// + public ConnectionSummary Connection { get; set; } + } +``` + +### `connection/complete` + +Connection complete event. + +#### Request + +```typescript + public class ConnectionCompleteParams + { + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } + + /// + /// A GUID representing a unique connection ID + /// + public string ConnectionId { get; set; } + + /// + /// Gets or sets any detailed connection error messages. + /// + public string Messages { get; set; } + + /// + /// Error message returned from the engine for a connection failure reason, if any. + /// + public string ErrorMessage { get; set; } + + /// + /// Error number returned from the engine for connection failure reason, if any. + /// + public int ErrorNumber { get; set; } + + /// + /// Information about the connected server. + /// + public ServerInfo ServerInfo { get; set; } + + /// + /// Gets or sets the actual Connection established, including Database Name + /// + public ConnectionSummary ConnectionSummary { get; set; } + } +``` + +### `connection/disconnect` + +Disconnect the connection specified in the request. + +#### Request + +```typescript + public class DisconnectParams + { + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } } ``` #### Response -** TODO: This is a bad example, find another** +```typescript + bool +``` -```json - { - "request_seq": 36, - "success": true, - "command": "signatureHelp", - "message": null, - "body": null, - "seq": 0, - "type": "response" - } -```` +### `connection/listdatabases` -## Symbol Operations - -### `definition` +Return a list of databases on the server associated with the active connection. #### Request -```json +```typescript + public class ListDatabasesParams { - "seq": 20, - "type": "request", - "command": "definition", - "arguments": { - "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/StopTest.ps1", - "line": 8, - "offset": 10 - } + /// + /// URI of the owner of the connection requesting the list of databases. + /// + public string OwnerUri { get; set; } } ``` #### Response -```json +```typescript + public class ListDatabasesResponse { - "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" + /// + /// Gets or sets the list of database names. + /// + public string[] DatabaseNames { get; set; } } ``` -### `references` +## Query Execution + +### `query/execute` + +Execute a SQL script. #### Request -```json +```typescript + public class QueryExecuteParams { - "seq": 2, - "type": "request", - "command": "references", - "arguments": { - "file": "c:/Users/daviwil/.vscode/extensions/vscode-powershell/examples/Stop-Process2.ps1", - "line": 38, - "offset": 12 - } + /// + /// The selection from the document + /// + public SelectionData QuerySelection { get; set; } + + /// + /// URI for the editor that is asking for the query execute + /// + public string OwnerUri { get; set; } } ``` #### Response -```json +```typescript + public class QueryExecuteResult { - "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" + /// + /// Informational messages from the query runner. Optional, can be set to null. + /// + public string Messages { get; set; } } ``` - -### `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 - diff --git a/docs/guide/toc.md b/docs/guide/toc.md index e9546b13..fad052ae 100644 --- a/docs/guide/toc.md +++ b/docs/guide/toc.md @@ -1,3 +1,3 @@ # [Introduction](introduction.md) -# [JSON-RPC Protocol](jsonrpc_protocol.md) +# [SQL Tools JSON-RPC Protocol](jsonrpc_protocol.md) # [Using the JSON-RPC API](using_the_jsonrpc_api.md)