mirror of
https://github.com/ckaczor/sqltoolsservice.git
synced 2026-01-13 17:23:02 -05:00
More documentation updates (#202)
* Add some content to the design page. * More design doc updates * Update user guide docs
This commit is contained in:
Karl Burtram
@@ -1,11 +1,64 @@
|
||||
# Design and Implementation
|
||||
|
||||
Design and implementation notes.
|
||||
The SQL Tools Service is designed as a stand-alone collection of database management operations. The service can be integrated into a
|
||||
variety SQL data developer and DBA host applications. For example, the below image illustrates the high-level MSSQL for VS Code
|
||||
composition. The extension's UI components run in the VS Code process. This code is written in TypeScipt and communicates with
|
||||
the service process over a JSON-RPC stdio channel.
|
||||
|
||||
|
||||
The service process consists of SMO SDK for .Net Core and higher-level SQL management components. The service provides features such as
|
||||
common language service operations (IntelliSense auto-complete suggestions, peek definition, SQL error diagnostics, quickinfo hovers), connection management,
|
||||
and query execution.
|
||||
|
||||
|
||||
<img src='../images/hostprocess.png' width='800px' />
|
||||
|
||||
|
||||
The SQL Tools Service is built on top of the SMO SDK for .Net Core and System.Data components built into .Net Core. This allows the service
|
||||
to provide rich SQL Server support that runs on Windows, Mac OS, and Linux operating systems. The service can work with on-prem SQL Server,
|
||||
SQL DB, and Azure SQL DW instances.
|
||||
|
||||
## Language Service
|
||||
The SQL Tools Service implements the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md)
|
||||
implemented by VS Code. This includes support for the following operations.
|
||||
|
||||
* Autocomplete suggestions
|
||||
* Peek\Go to definition
|
||||
* SQL error checking diagnostics
|
||||
* QuickInfo hover tooltips
|
||||
* Function signature info
|
||||
|
||||
The language service is primarily implemented in @Microsoft.SqlTools.ServiceLayer.LanguageServices
|
||||
([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/LanguageService.cs)).
|
||||
The language service depends heavily on the Microsoft.SqlServer.SqlParser assembly.
|
||||
|
||||
The language service component shares database connections across editor windows. Operations are routed
|
||||
through a queue to control concurrency when accessing shared database connection and metadata resources.
|
||||
The binding queue is implemented in @Microsoft.SqlTools.ServiceLayer.LanguageServices.ConnectedBindingQueue
|
||||
([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/ConnectedBindingQueue.cs) and
|
||||
[src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/LanguageServices/BindingQueue.cs)).
|
||||
|
||||
<img src='../images/connected_bind.png' width='800px' />
|
||||
|
||||
## Message Dispatcher
|
||||
|
||||
The JSON-RPC mechanism is build on a message dispatcher. Messages are read from stdio and serialized\deserialized
|
||||
using JSON.Net. Message handlers are registered with the dispatcher. Ass the messages are processed by
|
||||
the dispatcher queue they are routed to any registered handlers. The dispatch queue processes messages
|
||||
serially.
|
||||
|
||||
<img src='../images/msgdispatch.png' width='650px' />
|
||||
|
||||
The below sequence diagram show an example of how the language service may process a error checking diagnostics
|
||||
workflow. In this example the editor hosts a language service client that responds to user initiated editing events.
|
||||
The user actions are translated into a sequence of request\response pairs and one-way event notifications.
|
||||
Messages can be initiated from either the server or the client.
|
||||
|
||||
<img src='../images/msgdispatchexample.png' width='800px' />
|
||||
|
||||
## Query Execution
|
||||
The Query Execution component provides the ability to execute SQL scripts against SQL Server instances.
|
||||
This functionality builds onto the support in System.Data to provide features batch processing support
|
||||
and a file-backed cache for large resultsets.
|
||||
|
||||
@Microsoft.SqlTools.ServiceLayer.QueryExecution.QueryExecutionService
|
||||
([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/QueryExecution/QueryExecutionService.cs))
|
||||
is the class that implements the query execution protocol.
|
||||
|
||||
|
||||
|
||||
@@ -4,8 +4,13 @@
|
||||
> important information. If you feel that a particular area is missing or
|
||||
> poorly explained, please feel free to file an issue at our [GitHub site](https://github.com/Microsoft/sqltoolsservice/issues)
|
||||
|
||||
SQL Tools Service is a tool that provides useful services to code
|
||||
editors that need a great SQL Server editing experience.
|
||||
SQL Tools Service is a API that provides useful services to database developer
|
||||
and management tools.
|
||||
|
||||
## The JSON-RPC API
|
||||
The SQL Tools Service exposes its feature set as a JSON-RPC over stdio. See
|
||||
the API details at [JSON-RPC Protocol](jsonrpc_protocol.md) and checkout some
|
||||
usage examples at [Using the JSON-RPC API](using_the_jsonrpc_api.md).
|
||||
|
||||
## The .NET API
|
||||
|
||||
@@ -13,5 +18,4 @@ The .NET API provides the complete set of services which can be used in
|
||||
code editors or any other type of application.
|
||||
|
||||
If you're a developer that would like to use SQL Tools Service in
|
||||
a .NET application, read the page titled [Using the .NET API](using_the_dotnet_api.md)
|
||||
to learn more.
|
||||
a .NET application, checkout the [.Net API reference](../api/index.md).
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Using the JSON-RPC API
|
||||
# JSON-RPC Protocol
|
||||
|
||||
The JSON-RPC API provides an host-agnostic interface for
|
||||
leveraging the core .NET API.
|
||||
@@ -19,28 +19,31 @@ which contains all of the user's SQL script files for a given project.
|
||||
|
||||
## Messages overview
|
||||
|
||||
The SQL Tools Service implements portions of the
|
||||
[language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md)
|
||||
defined by VS Code. Some portions of this protocol reference have been duplicated here for
|
||||
convenience.
|
||||
|
||||
It additionally implements several other API to provide database management
|
||||
services such as connection management or query execution.
|
||||
|
||||
This document provides the protocol specification for all the service's JSON-RPC APIs.
|
||||
|
||||
General
|
||||
|
||||
* :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)
|
||||
|
||||
Window
|
||||
Language Service
|
||||
|
||||
* :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)
|
||||
|
||||
Workspace
|
||||
|
||||
* :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration)
|
||||
* :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles)
|
||||
* :leftwards_arrow_with_hook: [workspace/symbol](#workspace_symbol)
|
||||
|
||||
Document
|
||||
|
||||
* :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics)
|
||||
* :arrow_right: [textDocument/didChange](#textDocument_didChange)
|
||||
* :arrow_right: [textDocument/didClose](#textDocument_didClose)
|
||||
@@ -51,18 +54,12 @@ Document
|
||||
* :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/documentHighlight](#textDocument_documentHighlight)
|
||||
* :leftwards_arrow_with_hook: [textDocument/documentSymbol](#textDocument_documentSymbol)
|
||||
* :leftwards_arrow_with_hook: [textDocument/formatting](#textDocument_formatting)
|
||||
* :leftwards_arrow_with_hook: [textDocument/rangeFormatting](#textDocument_rangeFormatting)
|
||||
* :leftwards_arrow_with_hook: [textDocument/onTypeFormatting](#textDocument_onTypeFormatting)
|
||||
* :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition)
|
||||
* :leftwards_arrow_with_hook: [textDocument/codeAction](#textDocument_codeAction)
|
||||
* :leftwards_arrow_with_hook: [textDocument/codeLens](#textDocument_codeLens)
|
||||
* :leftwards_arrow_with_hook: [codeLens/resolve](#codeLens_resolve)
|
||||
* :leftwards_arrow_with_hook: [textDocument/documentLink](#textDocument_documentLink)
|
||||
* :leftwards_arrow_with_hook: [documentLink/resolve](#documentLink_resolve)
|
||||
* :leftwards_arrow_with_hook: [textDocument/rename](#textDocument_rename)
|
||||
|
||||
Connection Management
|
||||
|
||||
Query Execution
|
||||
|
||||
|
||||
# Message Protocol
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
# [Introduction](introduction.md)
|
||||
# [Using the JSON-RPC API](using_the_host_process.md)
|
||||
# [Using the .NET API](using_the_dotnet_api.md)
|
||||
# [JSON-RPC Protocol](jsonrpc_protocol.md)
|
||||
# [Using the JSON-RPC API](using_the_jsonrpc_api.md)
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Using the SQL Tools Service .NET API
|
||||
# Using the JSON-RPC API
|
||||
|
||||
> NOTE: The [API Reference](../api/index.md) is the best starting point for working directly with
|
||||
> the .NET API.
|
||||
Reference in New Issue
Block a user