Docs | Add XML documentation for publishing library to .Net API Reference (#210)

Contributors:
@JRahnama @v-kaywon @cheenamalhotra 

Changes with this PR:
- Adds common XML doc snippets to be extracted for XML documentation
- Adds Samples to repository included in documentation
- Updated both NetFx and NetCore drivers with documentation includes.
- GitIgnore update to exclude `nuget.exe`
- build.proj now defaults to `BuildAllConfigurations` target. Addresses #197
- Added include tags in 'ref' classes for Visual Studio Intellisense support.

Additional Changes in this PR:
- `Microsoft.Data.SqlTypes.SqlFileStream` added in NetFx.
- Existing tests run against the newly added SqlFileStream class.

As of now, this PR brings documentation over from System.Data.SqlClient.
Work to be continued to enhance missing docs in future PRs.

Author: cheenamalhotra

.gitignore

@@ -39,6 +39,9 @@ bld/
 # Visual Studio 2017 auto generated files
 Generated\ Files/
 
+# Visual Studio Code settings
+.vscode/
+
 # MSTest test Results
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*
@@ -351,3 +354,6 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+# Nuget package files
+.nuget/

build.proj

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="15.0" DefaultTargets="BuildAll" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+<Project ToolsVersion="15.0" DefaultTargets="BuildAllConfigurations" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="src/Directory.Build.props" />
   <Import Project="$(ToolsDir)targets\GenerateNugetPackage.targets" />
 

doc/samples/DataColumn_DataType.cs

@@ -0,0 +1,86 @@
+using System;
+using System.Data;
+// <Snippet1>
+using Microsoft.Data.SqlClient;
+using System.Data.SqlTypes;
+
+class Program
+{
+    static void Main()
+    {
+        string connectionString = GetConnectionString();
+        GetSqlTypesAW(connectionString);
+        Console.ReadLine();
+    }
+    static private void GetSqlTypesAW(string connectionString)
+    {
+        // Create a DataTable and specify a SqlType
+        // for each column.
+        DataTable table = new DataTable();
+        DataColumn icolumnolumn =
+            table.Columns.Add("SalesOrderID", typeof(SqlInt32));
+        DataColumn priceColumn =
+            table.Columns.Add("UnitPrice", typeof(SqlMoney));
+        DataColumn totalColumn =
+            table.Columns.Add("LineTotal", typeof(SqlDecimal));
+        DataColumn columnModifiedDate =
+            table.Columns.Add("ModifiedDate", typeof(SqlDateTime));
+
+        // Open a connection to SQL Server and fill the DataTable
+        // with data from the Sales.SalesOrderDetail table
+        // in the AdventureWorks sample database.
+        using (SqlConnection connection = new SqlConnection(connectionString))
+        {
+            string queryString =
+                "SELECT TOP 5 SalesOrderID, UnitPrice, LineTotal, ModifiedDate "
+                + "FROM Sales.SalesOrderDetail WHERE LineTotal < @LineTotal";
+
+            // Create the SqlCommand.
+            SqlCommand command = new SqlCommand(queryString, connection);
+
+            // Create the SqlParameter and assign a value.
+            SqlParameter parameter =
+                new SqlParameter("@LineTotal", SqlDbType.Decimal);
+            parameter.Value = 1.5;
+            command.Parameters.Add(parameter);
+
+            // Open the connection and load the data.
+            connection.Open();
+            SqlDataReader reader =
+                command.ExecuteReader(CommandBehavior.CloseConnection);
+            table.Load(reader);
+
+            // Close the SqlDataReader.
+            reader.Close();
+        }
+
+        // Display the SqlType of each column.
+        Console.WriteLine("Data Types:");
+        foreach (DataColumn column in table.Columns)
+        {
+            Console.WriteLine(" {0} -- {1}",
+                column.ColumnName, column.DataType.UnderlyingSystemType);
+        }
+
+        // Display the value for each row.
+        Console.WriteLine("Values:");
+        foreach (DataRow row in table.Rows)
+        {
+            Console.Write(" {0}, ", row["SalesOrderID"]);
+            Console.Write(" {0}, ", row["UnitPrice"]);
+            Console.Write(" {0}, ", row["LineTotal"]);
+            Console.Write(" {0} ", row["ModifiedDate"]);
+            Console.WriteLine();
+        }
+    }
+
+    static private string GetConnectionString()
+    {
+        // To avoid storing the connection string in your code, 
+        // you can retrieve it from a configuration file, using the 
+        // System.Configuration.ConfigurationSettings.AppSettings property 
+        return "Data Source=(local);Initial Catalog=AdventureWorks;"
+            + "Integrated Security=SSPI;";
+    }
+}
+// </Snippet1>

doc/samples/DataTableReader_GetValues.cs

@@ -0,0 +1,72 @@
+// <Snippet1>
+using System;
+using System.Data;
+using Microsoft.Data.SqlClient;
+
+class Program
+{
+    // using Microsoft.Data.SqlClient;
+    private static void TestGetValues(DataTableReader reader)
+    {
+        // Given a DataTableReader, use the GetValues
+        // method to retrieve a full row of data.
+        // Test the GetValues method, passing in an array large
+        // enough for all the columns.
+        Object[] values = new Object[reader.FieldCount];
+        int fieldCount = reader.GetValues(values);
+
+        Console.WriteLine("reader.GetValues retrieved {0} columns.",
+            fieldCount);
+        for (int i = 0; i < fieldCount; i++)
+            Console.WriteLine(values[i]);
+
+        Console.WriteLine();
+
+        // Now repeat, using an array that may contain a different 
+        // number of columns than the original data. This should work correctly,
+        // whether the size of the array is larger or smaller than 
+        // the number of columns.
+
+        // Attempt to retrieve three columns of data.
+        values = new Object[3];
+        fieldCount = reader.GetValues(values);
+        Console.WriteLine("reader.GetValues retrieved {0} columns.",
+            fieldCount);
+        for (int i = 0; i < fieldCount; i++)
+            Console.WriteLine(values[i]);
+    }
+    // </Snippet1>
+
+    // <Snippet2>
+    // using Microsoft.Data.SqlClient;
+    private static void TestGetValues(SqlDataReader reader)
+    {
+        // Given a SqlDataReader, use the GetValues
+        // method to retrieve a full row of data.
+        // Test the GetValues method, passing in an array large
+        // enough for all the columns.
+        Object[] values = new Object[reader.FieldCount];
+        int fieldCount = reader.GetValues(values);
+
+        Console.WriteLine("reader.GetValues retrieved {0} columns.",
+            fieldCount);
+        for (int i = 0; i < fieldCount; i++)
+            Console.WriteLine(values[i]);
+
+        Console.WriteLine();
+
+        // Now repeat, using an array that may contain a different 
+        // number of columns than the original data. This should work correctly,
+        // whether the size of the array is larger or smaller than 
+        // the number of columns.
+
+        // Attempt to retrieve three columns of data.
+        values = new Object[3];
+        fieldCount = reader.GetValues(values);
+        Console.WriteLine("reader.GetValues retrieved {0} columns.",
+            fieldCount);
+        for (int i = 0; i < fieldCount; i++)
+            Console.WriteLine(values[i]);
+    }
+    // </Snippet2>
+}

doc/samples/IBinarySerialize.cs

@@ -0,0 +1,109 @@
+using System;
+using System.IO;
+using System.Data;
+using System.Data.SqlTypes;
+using Microsoft.Data.SqlClient.Server;
+using System.Text;
+
+namespace test
+{
+
+    public class Class1 : IBinarySerialize
+    {
+
+        [STAThread]
+        static void Main(string[] args)
+        {
+            string fileName = "info.dat";
+            Class1 temp = new Class1();
+
+            FileStream fs = new FileStream(fileName, FileMode.Create);
+            BinaryWriter w = new BinaryWriter(fs);
+
+            temp.Write(w);
+
+            w.Close();
+            fs.Close();
+
+            fs = new FileStream(fileName, FileMode.Open, FileAccess.Read);
+            BinaryReader r = new BinaryReader(fs);
+
+            temp.Read(r);
+
+            Console.WriteLine("String value: " + temp.StringValue);
+            Console.WriteLine("Double value: " + temp.DoubleValue);
+
+            r.Close();
+            fs.Close();
+        }
+
+        public string StringValue;
+        public double DoubleValue;
+
+        //<Snippet1>
+        // The binary layout is as follows:
+        //    Bytes 0 - 19: string text, padded to the right with null characters
+        //    Bytes 20+: Double value
+
+        // using Microsoft.Data.SqlClient.Server;
+        public void Read(System.IO.BinaryReader r)
+        {
+
+            int maxStringSize = 20;
+            char[] chars;
+            int stringEnd;
+            string stringValue;
+            double doubleValue;
+
+            // Read the characters from the binary stream.
+            chars = r.ReadChars(maxStringSize);
+
+            // Find the start of the null character padding.
+            stringEnd = Array.IndexOf(chars, '\0');
+
+            if (stringEnd == 0)
+            {
+                stringValue = null;
+                return;
+            }
+
+            // Build the string from the array of characters.
+            stringValue = new String(chars, 0, stringEnd);
+
+            // Read the double value from the binary stream.
+            doubleValue = r.ReadDouble();
+
+            // Set the object's properties equal to the values.
+            this.StringValue = stringValue;
+            this.DoubleValue = doubleValue;
+        }
+        //</Snippet1>
+
+        //<Snippet2>
+        // The binary layout is as follows:
+        //    Bytes 0 - 19: string text, padded to the right with null characters
+        //    Bytes 20+: Double value
+
+        // using Microsoft.Data.SqlClient.Server;
+        public void Write(System.IO.BinaryWriter w)
+        {
+            int maxStringSize = 20;
+            string stringValue = "The value of PI: ";
+            string paddedString;
+            double value = 3.14159;
+
+            // Pad the string from the right with null characters.
+            paddedString = stringValue.PadRight(maxStringSize, '\0');
+
+            // Write the string value one byte at a time.
+            for (int i = 0; i < paddedString.Length; i++)
+            {
+                w.Write(paddedString[i]);
+            }
+
+            // Write the double value.
+            w.Write(value);
+        }
+        //</Snippet2>
+    }
+}

doc/samples/IDbCommand_CommandTimeout.cs

@@ -0,0 +1,22 @@
+// <Snippet1>
+using System;
+using System.Xml;
+using System.Data;
+using Microsoft.Data.SqlClient;
+using System.Data.Common;
+using System.Windows.Forms;
+
+public class Form1 : Form
+{
+    protected DataSet DataSet1;
+    protected DataGrid dataGrid1;
+
+
+    public void CreateSqlCommand()
+    {
+        SqlCommand command = new SqlCommand();
+        command.CommandTimeout = 15;
+        command.CommandType = CommandType.Text;
+    }
+    // </Snippet1>
+}