diff --git a/docs/design/index.md b/docs/design/index.md index 0b04951e..23836a03 100644 --- a/docs/design/index.md +++ b/docs/design/index.md @@ -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. -![Host Process](../images/hostprocess.png) +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. -![Connected Binding](../images/connected_bind.png) + -![Message Dispatch](../images/msgdispatch.png) +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)). + + + +## 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. + + + +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. + + + +## 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. -![Message Dispatch Example](../images/msgdispatchexample.png) diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 69271b2b..d86c1a14 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -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). diff --git a/docs/guide/using_the_host_process.md b/docs/guide/jsonrpc_protocol.md similarity index 96% rename from docs/guide/using_the_host_process.md rename to docs/guide/jsonrpc_protocol.md index 7890eace..98b1144f 100644 --- a/docs/guide/using_the_host_process.md +++ b/docs/guide/jsonrpc_protocol.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 diff --git a/docs/guide/toc.md b/docs/guide/toc.md index 2a9f7369..e9546b13 100644 --- a/docs/guide/toc.md +++ b/docs/guide/toc.md @@ -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) diff --git a/docs/guide/using_the_dotnet_api.md b/docs/guide/using_the_jsonrpc_api.md similarity index 98% rename from docs/guide/using_the_dotnet_api.md rename to docs/guide/using_the_jsonrpc_api.md index 97d0c86a..3c1cca3c 100644 --- a/docs/guide/using_the_dotnet_api.md +++ b/docs/guide/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.