Make attribute properties readonly + cleanup (#682)

* Attribute cleanup and clarifications

* more

* Cleanup

* Revert attribute rename

* Undo doc changes

Author: Charles-Gagnon

Worker.Extensions.Sql/src/SqlInputAttribute.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License. See License.txt in the project root for license information.
 
 using System;
+using System.Data;
 using Microsoft.Azure.Functions.Worker.Extensions.Abstractions;
 
 namespace Microsoft.Azure.Functions.Worker.Extensions.Sql
@@ -13,12 +14,23 @@ public sealed class SqlInputAttribute : InputBindingAttribute
         /// </summary>
         /// <param name="commandText">Either a SQL query or stored procedure that will be run in the target database.</param>
         /// <param name="connectionStringSetting">The name of the app setting where the SQL connection string is stored</param>
-        public SqlInputAttribute(string commandText, string connectionStringSetting)
+        /// <param name="commandType">Specifies whether <see cref="CommandText"/> refers to a stored procedure or SQL query string. Defaults to <see cref="CommandType.Text"/></param>
+        /// <param name="parameters">Optional - Specifies the parameters that will be used to execute the SQL query or stored procedure. See <see cref="Parameters"/> for more details.</param>
+        public SqlInputAttribute(string commandText, string connectionStringSetting, CommandType commandType = CommandType.Text, string parameters = null)
         {
             this.CommandText = commandText ?? throw new ArgumentNullException(nameof(commandText));
             this.ConnectionStringSetting = connectionStringSetting ?? throw new ArgumentNullException(nameof(connectionStringSetting));
+            this.CommandType = commandType;
+            this.Parameters = parameters;
         }
 
+        /// <summary>
+        /// Creates an instance of the <see cref="SqlInputAttribute"/>, which takes a SQL query or stored procedure to run and returns the output to the function.
+        /// </summary>
+        /// <param name="commandText">Either a SQL query or stored procedure that will be run in the target database.</param>
+        /// <param name="connectionStringSetting">The name of the app setting where the SQL connection string is stored</param>
+        public SqlInputAttribute(string commandText, string connectionStringSetting) : this(commandText, connectionStringSetting, CommandType.Text, null) { }
+
         /// <summary>
         /// The name of the app setting where the SQL connection string is stored
         /// (see https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection).
@@ -28,18 +40,19 @@ public SqlInputAttribute(string commandText, string connectionStringSetting)
         /// create a ConnectionStringSetting with a name like SqlServerAuthentication. The value of the SqlServerAuthentication app setting
         /// would look like "Data Source=test.database.windows.net;Database=TestDB;User ID={userid};Password={password}".
         /// </summary>
-        public string ConnectionStringSetting { get; set; }
+        public string ConnectionStringSetting { get; }
 
         /// <summary>
         /// Either a SQL query or stored procedure that will be run in the target database.
         /// </summary>
-        public string CommandText { get; set; }
+        public string CommandText { get; }
 
         /// <summary>
         /// Specifies whether <see cref="CommandText"/> refers to a stored procedure or SQL query string.
-        /// Use <see cref="CommandType.StoredProcedure"/> for the former, <see cref="CommandType.Text"/> for the latter
+        /// Use <see cref="CommandType.StoredProcedure"/> for the former, <see cref="CommandType.Text"/> for the latter.
+        /// Defaults to <see cref="CommandType.Text"/>.
         /// </summary>
-        public System.Data.CommandType CommandType { get; set; } = System.Data.CommandType.Text;
+        public CommandType CommandType { get; }
 
         /// <summary>
         /// Specifies the parameters that will be used to execute the SQL query or stored procedure specified in <see cref="CommandText"/>.
@@ -50,6 +63,6 @@ public SqlInputAttribute(string commandText, string connectionStringSetting)
         /// as in "@param1=,@param2=param2"
         /// Note that neither the parameter name nor the parameter value can have ',' or '='
         /// </summary>
-        public string Parameters { get; set; }
+        public string Parameters { get; }
     }
 }

Worker.Extensions.Sql/src/SqlOutputAttribute.cs

@@ -28,16 +28,11 @@ public SqlOutputAttribute(string commandText, string connectionStringSetting)
         /// create a ConnectionStringSetting with a name like SqlServerAuthentication. The value of the SqlServerAuthentication app setting
         /// would look like "Data Source=test.database.windows.net;Database=TestDB;User ID={userid};Password={password}".
         /// </summary>
-        public string ConnectionStringSetting { get; set; }
+        public string ConnectionStringSetting { get; }
 
         /// <summary>
         /// The table name to upsert the values to.
         /// </summary>
-        public string CommandText { get; set; }
-
-        /// <summary>
-        /// Specifies <see cref="CommandText"/> as Text.
-        /// </summary>
-        public System.Data.CommandType CommandType { get; } = System.Data.CommandType.Text;
+        public string CommandText { get; }
     }
 }

docs/SetupGuide_Dotnet.md

@@ -55,9 +55,9 @@ See [Input Binding Overview](./BindingsOverview.md#input-binding) for general in
 
 The [SqlAttribute](https://github.com/Azure/azure-functions-sql-extension/blob/main/src/SqlAttribute.cs) for Input bindings takes four arguments:
 
-- **CommandText**: Passed as a constructor argument to the binding. Represents either a query string or the name of a stored procedure.
-- **ConnectionStringSetting**: Passed as a constructor argument to the binding. Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
-- **CommandType**: Specifies whether CommandText is a query (`System.Data.CommandType.Text`) or a stored procedure (`System.Data.CommandType.StoredProcedure`)
+- **CommandText**: Represents either a query string or the name of a stored procedure based on the value of the CommandType.
+- **ConnectionStringSetting**: Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
+- **CommandType**: Specifies whether CommandText is a query (`System.Data.CommandType.Text`) or a stored procedure (`System.Data.CommandType.StoredProcedure`). Defaults to `CommandType.Text`.
 - **Parameters**: The parameters to the query/stored procedure. This string must follow the format "@param1=param1,@param2=param2" where @param1 is the name of the parameter and param1 is the parameter value. Each pair of parameter name, parameter value is separated by a comma. Within each pair, the parameter name and value is separated by an equals sign. This means that neither the parameter name nor value can contain "," or "=". To specify a `NULL` parameter value, do "@param1=null,@param2=param2". To specify an empty string as a value, do "@param1=,@param2=param2", i.e. do not put any text after the equals sign of the corresponding parameter name. This argument is auto-resolvable (see Query String examples).
 
 The following are valid binding types for the result of the query/stored procedure execution:
@@ -83,8 +83,7 @@ Note: This tutorial requires that a SQL database is setup as shown in [Create a
         [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "employees")] HttpRequest req,
         ILogger log,
         [Sql("select * from Employees",
-        "SqlConnectionString"
-        CommandType = System.Data.CommandType.Text)]
+        "SqlConnectionString")]
         IEnumerable<Employee> employee)
     {
         return new OkObjectResult(employee);
@@ -130,8 +129,7 @@ The input binding executes the `select * from Products where Cost = @Cost` query
       HttpRequest req,
       [Sql("select * from Products where Cost = @Cost",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Cost={cost}")]
+          parameters: "@Cost={cost}")]
       IEnumerable<Product> products)
   {
       return (ActionResult)new OkObjectResult(products);
@@ -169,8 +167,7 @@ In this case, the parameter value of the `@Name` parameter is an empty string.
       HttpRequest req,
       [Sql("select * from Products where Cost = @Cost and Name = @Name",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Cost={cost},@Name=")]
+          parameters: "@Cost={cost},@Name=")]
       IEnumerable<Product> products)
   {
       return (ActionResult)new OkObjectResult(products);
@@ -188,8 +185,7 @@ If the `{name}` specified in the `getproducts-namenull/{name}` URL is "null", th
       HttpRequest req,
       [Sql("if @Name is null select * from Products where Name is null else select * from Products where @Name = name",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Name={name}")]
+          parameters: "@Name={name}")]
       IEnumerable<Product> products)
   {
       return (ActionResult)new OkObjectResult(products);
@@ -207,8 +203,8 @@ If the `{name}` specified in the `getproducts-namenull/{name}` URL is "null", th
       HttpRequest req,
       [Sql("SelectProductsCost",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.StoredProcedure,
-          Parameters = "@Cost={cost}")]
+          System.Data.CommandType.StoredProcedure,
+          "@Cost={cost}")]
       IEnumerable<Product> products)
   {
       return (ActionResult)new OkObjectResult(products);
@@ -225,8 +221,7 @@ public static async Task<IActionResult> Run(
      HttpRequest req,
     [Sql("select * from Products where cost = @Cost",
          "SqlConnectionString",
-         CommandType = System.Data.CommandType.Text,
-         Parameters = "@Cost={cost}")]
+         parameters: "@Cost={cost}")]
      IAsyncEnumerable<Product> products)
 {
     var enumerator = products.GetAsyncEnumerator();
@@ -248,8 +243,8 @@ See [Output Binding Overview](./BindingsOverview.md#output-binding) for general
 
 The [SqlAttribute](https://github.com/Azure/azure-functions-sql-extension/blob/main/src/SqlAttribute.cs) for Output bindings takes two arguments:
 
-- **CommandText**: Passed as a constructor argument to the binding. Represents the name of the table into which rows will be upserted.
-- **ConnectionStringSetting**: Passed as a constructor argument to the binding. Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
+- **CommandText**: Represents the name of the table into which rows will be upserted.
+- **ConnectionStringSetting**: Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
 
 The following are valid binding types for the rows to be upserted into the table:
 
@@ -408,7 +403,7 @@ See [Trigger Binding Overview](./BindingsOverview.md#trigger-binding) for genera
 
 The SqlAttribute for Trigger bindings takes two [arguments](https://github.com/Azure/azure-functions-sql-extension/blob/main/src/TriggerBinding/SqlTriggerAttribute.cs)
 
-- **TableName**: Passed as a constructor argument to the binding. Represents the name of the table to be monitored for changes.
+- **TableName**: Represents the name of the table to be monitored for changes.
 - **ConnectionStringSetting**: Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
 
 The trigger binding can bind to type `IReadOnlyList<SqlChange<T>>`:

docs/SetupGuide_DotnetOutOfProc.md

@@ -66,10 +66,10 @@ See [Input Binding Overview](./BindingsOverview.md#input-binding) for general in
 
 The [SqlInputAttribute](https://github.com/Azure/azure-functions-sql-extension/blob/main/Worker.Extensions.Sql/src/SqlInputAttribute.cs) takes four arguments:
 
-- **CommandText**: Passed as a constructor argument to the binding. Represents either a query string or the name of a stored procedure.
-- **CommandType**: Specifies whether CommandText is a query (`System.Data.CommandType.Text`) or a stored procedure (`System.Data.CommandType.StoredProcedure`)
-- **Parameters**: The parameters to the query/stored procedure. This string must follow the format "@param1=param1,@param2=param2" where @param1 is the name of the parameter and param1 is the parameter value. Each pair of parameter name, parameter value is separated by a comma. Within each pair, the parameter name and value is separated by an equals sign. This means that neither the parameter name nor value can contain "," or "=". To specify a `NULL` parameter value, do "@param1=null,@param2=param2". To specify an empty string as a value, do "@param1=,@param2=param2", i.e. do not put any text after the equals sign of the corresponding parameter name. This argument is auto-resolvable (see Query String examples).
+- **CommandText**: Represents either a query string or the name of a stored procedure.
 - **ConnectionStringSetting**: Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
+- **CommandType**: Specifies whether CommandText is a query (`System.Data.CommandType.Text`) or a stored procedure (`System.Data.CommandType.StoredProcedure`). Default is `Text`
+- **Parameters**: The parameters to the query/stored procedure. This string must follow the format "@param1=param1,@param2=param2" where @param1 is the name of the parameter and param1 is the parameter value. Each pair of parameter name, parameter value is separated by a comma. Within each pair, the parameter name and value is separated by an equals sign. This means that neither the parameter name nor value can contain "," or "=". To specify a `NULL` parameter value, do "@param1=null,@param2=param2". To specify an empty string as a value, do "@param1=,@param2=param2", i.e. do not put any text after the equals sign of the corresponding parameter name. This argument is auto-resolvable (see Query String examples).
 
 The following are valid binding types for the result of the query/stored procedure execution:
 
@@ -96,15 +96,14 @@ Note: This tutorial requires that a SQL database is setup as shown in [Create a
         [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "employees")] HttpRequest req,
         ILogger log,
         [SqlInput("select * from Employees",
-        "SqlConnectionString",
-        CommandType = System.Data.CommandType.Text)]
+        "SqlConnectionString")]
         IEnumerable<Employee> employees)
     {
         return employees;
     }
     ```
 
-    *In the above, `select * from Employees` is the SQL script run by the input binding. The CommandType on the line below specifies whether the first line is a query or a stored procedure. On the next line, the ConnectionStringSetting specifies that the app setting that contains the SQL connection string used to connect to the database is "SqlConnectionString." For more information on this, see the [SqlInputAttribute for Input Bindings](#sqlinputattribute-for-input-bindings) section*
+    *In the above sample, `select * from Employees` is the SQL script run by the input binding. The CommandType on the line below specifies whether the first line is a query or a stored procedure. On the next line, the ConnectionStringSetting parameter specifies that the app setting that contains the SQL connection string used to connect to the database is "SqlConnectionString." For more information on this, see the [SqlInputAttribute for Input Bindings](#sqlinputattribute-for-input-bindings) section*
 - Add 'using Microsoft.Azure.Functions.Worker.Extensions.Sql;' for using *SqlInput*, the out of proc sql input binding.
 - Add 'using System.Collections.Generic;' to the namespaces list at the top of the page.
 - Currently, there is an error for the IEnumerable. We'll fix this by creating an Employee class.
@@ -143,8 +142,7 @@ The input binding executes the `select * from Products where Cost = @Cost` query
       HttpRequestData req,
       [SqlInput("select * from Products where Cost = @Cost",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Cost={cost}")]
+          parameters: "@Cost={cost}")]
       IEnumerable<Product> products)
   {
       return products;
@@ -182,8 +180,7 @@ In this case, the parameter value of the `@Name` parameter is an empty string.
       HttpRequestData req,
       [SqlInput("select * from Products where Cost = @Cost and Name = @Name",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Cost={cost},@Name=")]
+          parameters: "@Cost={cost},@Name=")]
       IEnumerable<Product> products)
   {
       return products;
@@ -201,8 +198,7 @@ If the `{name}` specified in the `getproducts-namenull/{name}` URL is "null", th
       HttpRequestData req,
       [SqlInput("if @Name is null select * from Products where Name is null else select * from Products where @Name = name",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.Text,
-          Parameters = "@Name={name}")]
+          parameters: "@Name={name}")]
       IEnumerable<Product> products)
   {
       return products;
@@ -220,8 +216,8 @@ If the `{name}` specified in the `getproducts-namenull/{name}` URL is "null", th
       HttpRequestData req,
       [SqlInput("SelectProductsCost",
           "SqlConnectionString",
-          CommandType = System.Data.CommandType.StoredProcedure,
-          Parameters = "@Cost={cost}")]
+          System.Data.CommandType.StoredProcedure,
+          "@Cost={cost}")]
       IEnumerable<Product> products)
   {
       return products;
@@ -239,8 +235,7 @@ public static async Task<List<Product>> Run(
      HttpRequestData req,
     [SqlInput("select * from Products where cost = @Cost",
          "SqlConnectionString",
-         CommandType = System.Data.CommandType.Text,
-         Parameters = "@Cost={cost}")]
+         parameters: "@Cost={cost}")]
      IAsyncEnumerable<Product> products)
 {
     var enumerator = products.GetAsyncEnumerator();
@@ -262,7 +257,7 @@ See [Output Binding Overview](./BindingsOverview.md#output-binding) for general
 
 The [SqlOutputAttribute](https://github.com/Azure/azure-functions-sql-extension/blob/main/Worker.Extensions.Sql/src/SqlOutputAttribute.cs) takes two arguments:
 
-- **CommandText**: Passed as a constructor argument to the binding. Represents the name of the table into which rows will be upserted.
+- **CommandText**: Represents the name of the table into which rows will be upserted.
 - **ConnectionStringSetting**: Specifies the name of the app setting that contains the SQL connection string used to connect to a database. The connection string must follow the format specified [here](https://docs.microsoft.com/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-2.0).
 
 The following are valid binding types for the rows to be upserted into the table: