More documentation updates. (#205)

* Add additional documentation.

* More docs updates.

* Update docs.  Add building info.

docs/design/index.md

@@ -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
+@Microsoft.SqlTools.ServiceLayer.Connection.ConnectionService
-using JSON.Net.  Message handlers are registered with the dispatcher.  Ass the messages are processed by
+([src link](https://github.com/Microsoft/sqltoolsservice/blob/dev/src/Microsoft.SqlTools.ServiceLayer/Connection/ConnectionService.cs)) 
-the dispatcher queue they are routed to any registered handlers.  The dispatch queue processes messages 
+is the class that implements the connection management protocol.
-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.
@@ -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.
-

docs/guide/building_sqltoolsservice.md

@@ -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.

docs/guide/jsonrpc_protocol.md

@@ -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; }
+    }
+```

docs/guide/toc.md

@@ -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)

docs/guide/using_the_jsonrpc_api.md

@@ -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)
 {    

src/Microsoft.SqlTools.ServiceLayer/QueryExecution/Contracts/SaveResultsRequest.cs

@@ -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
     }