ckaczor/sqltoolsservice
1
0
Fork 0
mirror of https://github.com/ckaczor/sqltoolsservice.git synced 2026-01-13 17:23:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

More documentation updates. (#205)

Browse Source 
* Add additional documentation.

* More docs updates.

* Update docs.  Add building info.
This commit is contained in:
Karl Burtram
2016-12-22 18:44:45 -08:00
committed by GitHub
parent d5f19031f2
commit 323374d123
6 changed files with 332 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
docs/design/index.md
View File

@@ -15,6 +15,22 @@ The SQL Tools Service is built on top of the SMO SDK for .Net Core and System.Da
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.
## 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' />
## 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.
@@ -37,21 +53,13 @@ The binding queue is implemented in @Microsoft.SqlTools.ServiceLayer.LanguageSer
<img src='../images/connected_bind.png' width='800px' />
## Message Dispatcher
## Connection Management
The Connection Management component provides functionality to establish connections to SQL Server instances.
A connection is required to work with many language service and query execution APIs.
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' />
@Microsoft.SqlTools.ServiceLayer.Connection.ConnectionService
([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/Connection/ConnectionService.cs))
is the class that implements the connection management protocol.
## Query Execution
The Query Execution component provides the ability to execute SQL scripts against SQL Server instances.
@@ -61,4 +69,3 @@ 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.

55
docs/guide/building_sqltoolsservice.md Normal file
View File

@@ -0,0 +1,55 @@
## Build the SQL Tools Service
> SQL Tools Service depends on .Net Core SDK. Please install .Net Core SDK before building.
> Please see [https://dotnet.github.io](https://dotnet.github.io/) for additional information on .Net Core.
1. Clone the SQL Tools Service repo from [https://github.com/Microsoft/sqltoolsservice](https://github.com/Microsoft/sqltoolsservice).
2. Run `dotnet restore` from the cloned repo's root directory.
3. Run `dotnet build src/Microsoft.SqlToosl.ServiceLayer` from the cloned repo's root directory.
> *Tip* there is a `build.cmd` or `build.sh` file in the repo's root directory that can be used
> to build and package the service.
## Building the Documentation
> The documentation is generated using docfx. Please install docfx from
> [https://dotnet.github.io/docfx/](https://dotnet.github.io/docfx/).
1. Clone the SQL Tools Service docs repo from [https://github.com/Microsoft/sqltoolssdk](https://github.com/Microsoft/sqltoolssdk).
2. Run `docfx docfx.json --serve` from the docs directory.
3. Copy the contents of the docs/_site directory to the root directory of the sqltoolssdk repo.
## Run Tests
The SQL Tools Service has several different types of tests such as unit tests, "connected" tests,
integration tests, perf tests and stress tests. Additionally, there is also test configuration
scripts to collect code coverage results.
### Running Unit Tests
1. Run `dotnet restore` from the cloned repo's root directory.
2. Run `dotnet test test/Microsoft.SqlToosl.ServiceLayer.Test` from the cloned repo's root directory.
The test output should be similar to the below. There may also be additional debugging output based on
test details and execution environment.
```
xUnit.net .NET CLI test runner (64-bit win10-x64)
Discovering: Microsoft.SqlTools.ServiceLayer.Test
Discovered: Microsoft.SqlTools.ServiceLayer.Test
Starting: Microsoft.SqlTools.ServiceLayer.Test
=== TEST EXECUTION SUMMARY ===
Microsoft.SqlTools.ServiceLayer.Test Total: 434, Errors: 0, Failed: 0, Skipped: 0, Time: 21.139s
SUMMARY: Total: 1 targets, Passed: 1, Failed: 0.
```
### Collecting Code coverage
> Code coverage requires a SQL Server instance installed on the localhost with Integrated Authentication
> configured for the current user executing the test suite.
> Code coverage can only be collected from Windows at this time.
1. Run `npm install` from test/CodeCoverage directory.
2. Run `runintegration.cmd` from test/CodeCoverage directory.
3. Code coverage results will be available in the test/CodeCoverage/reports/index.html report.

237
docs/guide/jsonrpc_protocol.md
View File

@@ -1,6 +1,6 @@
# SQL Tools JSON-RPC Protocol
The SQL Tools JSON-RPC API provides an host-agnostic interface for the SQL Tools Service functionality.
The SQL Tools JSON-RPC API provides a 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
@@ -17,7 +17,7 @@ It is expected that an editor will launch one instance of the host process for e
'workspace' that the user has opened. Generally this would map to a single top-level folder
which contains all of the user's SQL script files for a given project.
## Messages overview
## Messages Overview
The SQL Tools Service implements portions of the
[language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md)
@@ -39,6 +39,9 @@ This document provides the protocol specification for all the service's JSON-RPC
### Query Execution
* :leftwards_arrow_with_hook: [query/execute](#query_execute)
* :leftwards_arrow_with_hook: [query/subset](#query_subset)
* :leftwards_arrow_with_hook: [query/saveCsv](#query_saveCsv)
* :leftwards_arrow_with_hook: [query/saveJson](#query_saveJson)
### Language Service Protocol
@@ -82,7 +85,7 @@ 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.
response messages to the initial request that caused it.
- `type`: The type of message being transmitted, either `request`, `response`, or `event`.
### Request Fields
@@ -263,10 +266,10 @@ interface NotificationMessage extends Message {
}
```
## Example Request and Response Message
## Example JSON-RPC Message Format
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
for more details on the protocol formats for these Language Service events. Below is an example of the JSON-RPC
message format for the `textDocument/didChange` message.
### `textDocument/didChange`
@@ -309,7 +312,9 @@ No response is needed for this command.
# Database Management Protocol
The follow section describes the message protocol format for the common database management
functionaltiy provided by the SQL Tools Service.
functionality provided by the SQL Tools Service. The message formats are described as
C# classes. These classes are packaged inside the common message structures documented above
and serialized to JSON using JSON.Net.
## Connection Management
@@ -519,3 +524,223 @@ Execute a SQL script.
public string Messages { get; set; }
}
```
### <a name="query_subset"></a>`query/subset`
Retrieve a subset of a query results.
#### Request
```typescript
public class QueryExecuteSubsetParams
{
/// <summary>
/// URI for the file that owns the query to look up the results for
/// </summary>
public string OwnerUri { get; set; }
/// <summary>
/// Index of the batch to get the results from
/// </summary>
public int BatchIndex { get; set; }
/// <summary>
/// Index of the result set to get the results from
/// </summary>
public int ResultSetIndex { get; set; }
/// <summary>
/// Beginning index of the rows to return from the selected resultset. This index will be
/// included in the results.
/// </summary>
public int RowsStartIndex { get; set; }
/// <summary>
/// Number of rows to include in the result of this request. If the number of the rows
/// exceeds the number of rows available after the start index, all available rows after
/// the start index will be returned.
/// </summary>
public int RowsCount { get; set; }
}
```
#### Response
```typescript
public class QueryExecuteSubsetResult
{
/// <summary>
/// Subset request error messages. Optional, can be set to null to indicate no errors
/// </summary>
public string Message { get; set; }
/// <summary>
/// The requested subset of results. Optional, can be set to null to indicate an error
/// </summary>
public ResultSetSubset ResultSubset { get; set; }
}
```
### <a name="query_saveCsv"></a>`query/saveCsv`
Save a resultset as CSV to a file.
#### Request
```typescript
public class SaveResultsRequestParams
{
/// <summary>
/// The path of the file to save results in
/// </summary>
public string FilePath { get; set; }
/// <summary>
/// Index of the batch to get the results from
/// </summary>
public int BatchIndex { get; set; }
/// <summary>
/// Index of the result set to get the results from
/// </summary>
public int ResultSetIndex { get; set; }
/// <summary>
/// URI for the editor that called save results
/// </summary>
public string OwnerUri { get; set; }
/// <summary>
/// Start index of the selected rows (inclusive)
/// </summary>
public int? RowStartIndex { get; set; }
/// <summary>
/// End index of the selected rows (inclusive)
/// </summary>
public int? RowEndIndex { get; set; }
/// <summary>
/// Start index of the selected columns (inclusive)
/// </summary>
/// <returns></returns>
public int? ColumnStartIndex { get; set; }
/// <summary>
/// End index of the selected columns (inclusive)
/// </summary>
/// <returns></returns>
public int? ColumnEndIndex { get; set; }
/// <summary>
/// Check if request is a subset of result set or whole result set
/// </summary>
/// <returns></returns>
internal bool IsSaveSelection
{
get
{
return ColumnStartIndex.HasValue && ColumnEndIndex.HasValue
&& RowStartIndex.HasValue && RowEndIndex.HasValue;
}
}
}
public class SaveResultsAsCsvRequestParams: SaveResultsRequestParams
{
/// <summary>
/// Include headers of columns in CSV
/// </summary>
public bool IncludeHeaders { get; set; }
}
```
#### Response
```typescript
public class SaveResultRequestResult
{
/// <summary>
/// Error messages for saving to file.
/// </summary>
public string Messages { get; set; }
}
```
### <a name="query_saveJson"></a>`query/saveJson`
Save a resultset as JSON to a file.
#### Request
```typescript
public class SaveResultsRequestParams
{
/// <summary>
/// The path of the file to save results in
/// </summary>
public string FilePath { get; set; }
/// <summary>
/// Index of the batch to get the results from
/// </summary>
public int BatchIndex { get; set; }
/// <summary>
/// Index of the result set to get the results from
/// </summary>
public int ResultSetIndex { get; set; }
/// <summary>
/// URI for the editor that called save results
/// </summary>
public string OwnerUri { get; set; }
/// <summary>
/// Start index of the selected rows (inclusive)
/// </summary>
public int? RowStartIndex { get; set; }
/// <summary>
/// End index of the selected rows (inclusive)
/// </summary>
public int? RowEndIndex { get; set; }
/// <summary>
/// Start index of the selected columns (inclusive)
/// </summary>
/// <returns></returns>
public int? ColumnStartIndex { get; set; }
/// <summary>
/// End index of the selected columns (inclusive)
/// </summary>
/// <returns></returns>
public int? ColumnEndIndex { get; set; }
/// <summary>
/// Check if request is a subset of result set or whole result set
/// </summary>
/// <returns></returns>
internal bool IsSaveSelection
{
get
{
return ColumnStartIndex.HasValue && ColumnEndIndex.HasValue
&& RowStartIndex.HasValue && RowEndIndex.HasValue;
}
}
}
```
#### Response
```typescript
public class SaveResultRequestResult
{
/// <summary>
/// Error messages for saving to file.
/// </summary>
public string Messages { get; set; }
}
```

1
docs/guide/toc.md
View File

@@ -1,3 +1,4 @@
# [Introduction](introduction.md)
# [SQL Tools JSON-RPC Protocol](jsonrpc_protocol.md)
# [Using the JSON-RPC API](using_the_jsonrpc_api.md)
# [Building the SQL Tools API](building_sqltoolsservice.md)

20
docs/guide/using_the_jsonrpc_api.md
View File

@@ -1,11 +1,29 @@
# Using the JSON-RPC API
# Using the SQL Tools JSON-RPC API
The SQL Tools JSON-RPC API is the best way to consume the services
functionality in SQL tools. The JSON-RPC API available through stdio
of the SQL Tools Service process.
> NOTE: The [API Reference](../api/index.md) is the best starting point for working directly with
> the .NET API.
## Download SQL Tools Service binaries
To get started using the SQL Tools Service you'll need to install the service binaries.
Download the SQL Tools Service binaries from the
[sqltoolsservice release page](https://github.com/Microsoft/sqltoolsservice/releases).
Daily development builds will end with "-alpha". Release builds will end with " Release".
For example, here is the [0.2.0 release](https://github.com/Microsoft/sqltoolsservice/releases/tag/v0.2.0).
It is also possible to build the SQL Tools Service directly from source.
## Query Execution Example using JSON-RPC API
An example of using the JSON RPC API from a .Net Core console application is available at docs/samples/jsonrpc/netcore.
The following snippet provides a basic example of how to connect to a database and execute a query.
See the [full source code](https://github.com/Microsoft/sqltoolsservice/blob/dev/docs/samples/jsonrpc/netcore/executequery/Program.cs)
for this sample.
```typescript
internal static async Task ExecuteQuery(string query)
{

6
src/Microsoft.SqlTools.ServiceLayer/QueryExecution/Contracts/SaveResultsRequest.cs
View File

@@ -72,7 +72,8 @@ namespace Microsoft.SqlTools.ServiceLayer.QueryExecution.Contracts
/// <summary>
/// Parameters to save results as CSV
/// </summary>
public class SaveResultsAsCsvRequestParams: SaveResultsRequestParams{
public class SaveResultsAsCsvRequestParams: SaveResultsRequestParams
{
/// <summary>
/// Include headers of columns in CSV
/// </summary>
@@ -82,7 +83,8 @@ namespace Microsoft.SqlTools.ServiceLayer.QueryExecution.Contracts
/// <summary>
/// Parameters to save results as JSON
/// </summary>
public class SaveResultsAsJsonRequestParams: SaveResultsRequestParams{
public class SaveResultsAsJsonRequestParams: SaveResultsRequestParams
{
//TODO: define config for save as JSON
}