Merge pull request #233807 from dzsquared/sqlbinding-april2023-csharp

adding tutorial article for output binding

Author: denrea

articles/azure-functions/TOC.yml

@@ -161,14 +161,29 @@
     - name: Connect to a database
       items:
         - name: C#
-          displayName: Connect to a database, Azure Cosmos DB
-          href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-csharp
+          items:
+          - name: Azure Cosmos DB
+            displayName: Connect to a database, Azure Cosmos DB
+            href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-csharp
+          - name: Azure SQL
+            displayName: Connect to a database, Azure SQL
+            href: functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-csharp
         - name: JavaScript
-          displayName: Connect to a database, Azure Cosmos DB
-          href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-javascript
+          items:
+          - name: Azure Cosmos DB
+            displayName: Connect to a database, Azure Cosmos DB
+            href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-javascript
+          - name: Azure SQL
+            displayName: Connect to a database, Azure SQL
+            href: functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-javascript
         - name: Python
-          displayName: Connect to a database, Azure Cosmos DB
-          href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-python
+          items:
+          - name: Azure Cosmos DB
+            displayName: Connect to a database, Azure Cosmos DB
+            href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-python
+          - name: Azure SQL
+            displayName: Connect to a database, Azure SQL
+            href: functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-python
 - name: Tutorials
   items:
     - name: Functions with Logic Apps

articles/azure-functions/create-first-function-vs-code-csharp.md

@@ -79,6 +79,7 @@ The next article depends on your chosen process model.
 > [!div class="nextstepaction"]
 > [Connect to Azure Cosmos DB](functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-csharp&tabs=in-process)
 > [Connect to Azure Queue Storage](functions-add-output-binding-storage-queue-vs-code.md?pivots=programming-language-csharp&tabs=in-process)
+> [Connect to Azure SQL](functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-csharp&tabs=in-process)
 
 # [Isolated process](#tab/isolated-process)
 

articles/azure-functions/create-first-function-vs-code-node.md

@@ -186,6 +186,7 @@ You have used [Visual Studio Code](functions-develop-vs-code.md?tabs=javascript)
 > [!div class="nextstepaction"]
 > [Connect to Azure Cosmos DB](functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-javascript)
 > [Connect to Azure Queue Storage](functions-add-output-binding-storage-queue-vs-code.md?pivots=programming-language-javascript)
+> [Connect to Azure SQL](functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-javascript)
 
 [Azure Functions Core Tools]: functions-run-local.md
 [Azure Functions extension for Visual Studio Code]: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurefunctions

articles/azure-functions/create-first-function-vs-code-python.md

@@ -208,6 +208,7 @@ You have used [Visual Studio Code](functions-develop-vs-code.md?tabs=python) to
 
 > [!div class="nextstepaction"]
 > [Connect to an Azure Storage queue](functions-add-output-binding-storage-queue-vs-code.md?pivots=programming-language-python)
+> [Connect to Azure SQL](functions-add-output-binding-azure-sql-vs-code.md?pivots=programming-language-python)
 
 [Having issues? Let us know.](https://aka.ms/python-functions-qs-survey)
 

articles/azure-functions/functions-add-output-binding-azure-sql-vs-code.md

@@ -4,7 +4,7 @@ description: Learn to use the Azure SQL input binding in Azure Functions.
 author: dzsquared
 ms.topic: reference
 ms.custom: event-tier1-build-2022
-ms.date: 11/10/2022
+ms.date: 4/7/2023
 ms.author: drskwier
 ms.reviewer: glenga
 zone_pivot_groups: programming-languages-set-functions-lang-workers
@@ -65,7 +65,7 @@ namespace AzureSQLSamples
             [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "gettodoitem")]
             HttpRequest req,
             [Sql(commandText: "select [Id], [order], [title], [url], [completed] from dbo.ToDo where Id = @Id",
-                commandText: System.Data.CommandType.Text,
+                commandType: System.Data.CommandType.Text,
                 parameters: "@Id={Query.id}",
                 connectionStringSetting: "SqlConnectionString")]
             IEnumerable<ToDoItem> toDoItem)
@@ -1081,6 +1081,8 @@ The attribute's constructor takes the SQL command text, the command type, parame
 
 Queries executed by the input binding are [parameterized](/dotnet/api/microsoft.data.sqlclient.sqlparameter) in Microsoft.Data.SqlClient to reduce the risk of [SQL injection](/sql/relational-databases/security/sql-injection) from the parameter values passed into the binding.
 
+If an exception occurs when a SQL input binding is executed then the function code will not execute.  This may result in an error code being returned, such as an HTTP trigger returning a 500 error code.
+
 
 ::: zone-end
 

articles/azure-functions/functions-bindings-azure-sql-input.md

@@ -4,7 +4,7 @@ description: Learn to use the Azure SQL output binding in Azure Functions.
 author: dzsquared
 ms.topic: reference
 ms.custom: event-tier1-build-2022
-ms.date: 11/10/2022
+ms.date: 4/7/2023
 ms.author: drskwier
 ms.reviewer: glenga
 zone_pivot_groups: programming-languages-set-functions-lang-workers
@@ -162,20 +162,29 @@ This section contains the following examples:
 
 * [HTTP trigger, write one record](#http-trigger-write-one-record-c-oop)
 * [HTTP trigger, write to two tables](#http-trigger-write-to-two-tables-c-oop)
-* [HTTP trigger, write records using IAsyncCollector](#http-trigger-write-records-using-iasynccollector-c-oop)
 
 The examples refer to a `ToDoItem` class and a corresponding database table:
 
 :::code language="csharp" source="~/functions-sql-todo-sample/ToDoModel.cs" range="6-16":::
 
 :::code language="sql" source="~/functions-sql-todo-sample/sql/create.sql" range="1-7":::
 
+To return [multiple output bindings](./dotnet-isolated-process-guide.md#multiple-output-bindings) in our samples, we will create a custom return type:
+
+```cs
+public static class OutputType
+{
+    [SqlOutput("dbo.ToDo", connectionStringSetting: "SqlConnectionString")]
+    public ToDoItem ToDoItem { get; set; }
+    public HttpResponseData HttpResponse { get; set; }
+}
+```
 
 <a id="http-trigger-write-one-record-c-oop"></a>
 
 ### HTTP trigger, write one record
 
-The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database, using data provided in an HTTP POST request as a JSON body.
+The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database, using data provided in an HTTP POST request as a JSON body.  The return object is the `OutputType` class we created to handle both an HTTP response and the SQL output binding.
 
 ```cs
 using System;
@@ -195,11 +204,13 @@ namespace AzureSQL.ToDo
         // create a new ToDoItem from body object
         // uses output binding to insert new item into ToDo table
         [FunctionName("PostToDo")]
-        public static async Task<IActionResult> Run(
-            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "PostFunction")] HttpRequest req,
-            ILogger log,
-            [SqlOutput(commandText: "dbo.ToDo", connectionStringSetting: "SqlConnectionString")] IAsyncCollector<ToDoItem> toDoItems)
+        public static async Task<OutputType> Run(
+            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "PostFunction")] HttpRequestData req,
+                FunctionContext executionContext)
         {
+            var logger = executionContext.GetLogger("HttpExample");
+            logger.LogInformation("C# HTTP trigger function processed a request.");
+
             string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
             ToDoItem toDoItem = JsonConvert.DeserializeObject<ToDoItem>(requestBody);
 
@@ -215,13 +226,21 @@ namespace AzureSQL.ToDo
                 toDoItem.completed = false;
             }
 
-            await toDoItems.AddAsync(toDoItem);
-            await toDoItems.FlushAsync();
-            List<ToDoItem> toDoItemList = new List<ToDoItem> { toDoItem };
-
-            return new OkObjectResult(toDoItemList);
+            return new OutputType()
+            {
+                ToDoItem = toDoItem,
+                HttpResponse = req.CreateResponse(System.Net.HttpStatusCode.Created)
+            }
         }
     }
+
+    public static class OutputType
+    {
+        [SqlOutput("dbo.ToDo", connectionStringSetting: "SqlConnectionString")]
+        public ToDoItem ToDoItem { get; set; }
+
+        public HttpResponseData HttpResponse { get; set; }
+    }
 }
 ```
 
@@ -239,6 +258,7 @@ CREATE TABLE dbo.RequestLog (
 )
 ```
 
+To use an additional output binding, we add a class for `RequestLog` and  modify our `OutputType` class:
 
 ```cs
 using System;
@@ -258,11 +278,9 @@ namespace AzureSQL.ToDo
         // create a new ToDoItem from body object
         // uses output binding to insert new item into ToDo table
         [FunctionName("PostToDo")]
-        public static async Task<IActionResult> Run(
-            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "PostFunction")] HttpRequest req,
-            ILogger log,
-            [SqlOutput(commandText: "dbo.ToDo", connectionStringSetting: "SqlConnectionString")] IAsyncCollector<ToDoItem> toDoItems,
-            [SqlOutput(commandText: "dbo.RequestLog", connectionStringSetting: "SqlConnectionString")] IAsyncCollector<RequestLog> requestLogs)
+        public static async Task<OutputType> Run(
+            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "PostFunction")] HttpRequestData req,
+                FunctionContext executionContext)
         {
             string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
             ToDoItem toDoItem = JsonConvert.DeserializeObject<ToDoItem>(requestBody);
@@ -279,69 +297,41 @@ namespace AzureSQL.ToDo
                 toDoItem.completed = false;
             }
 
-            await toDoItems.AddAsync(toDoItem);
-            await toDoItems.FlushAsync();
-            List<ToDoItem> toDoItemList = new List<ToDoItem> { toDoItem };
-
             requestLog = new RequestLog();
             requestLog.RequestTimeStamp = DateTime.Now;
             requestLog.ItemCount = 1;
-            await requestLogs.AddAsync(requestLog);
-            await requestLogs.FlushAsync();
 
-            return new OkObjectResult(toDoItemList);
+            return new OutputType()
+            {
+                ToDoItem = toDoItem,
+                RequestLog = requestLog,
+                HttpResponse = req.CreateResponse(System.Net.HttpStatusCode.Created)
+            }
         }
     }
 
     public class RequestLog {
         public DateTime RequestTimeStamp { get; set; }
         public int ItemCount { get; set; }
     }
-}
-```
-
-<a id="http-trigger-write-records-using-iasynccollector-c-oop"></a>
-
-### HTTP trigger, write records using IAsyncCollector
-
-The following example shows a [C# function](functions-dotnet-class-library.md) that adds a collection of records to a database, using data provided in an HTTP POST body JSON array.
-
-```cs
-using Microsoft.AspNetCore.Http;
-using Microsoft.AspNetCore.Mvc;
-using Microsoft.Azure.Functions.Worker;
-using Microsoft.Azure.Functions.Worker.Extensions.Sql;
-using Microsoft.Azure.Functions.Worker.Http;
-using Newtonsoft.Json;
-using System.IO;
-using System.Threading.Tasks;
-
-namespace AzureSQLSamples
-{
-    public static class WriteRecordsAsync
+    
+    public static class OutputType
     {
-        [FunctionName("WriteRecordsAsync")]
-        public static async Task<IActionResult> Run(
-            [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "addtodo-asynccollector")]
-            HttpRequest req,
-            [SqlOutput(commandText: "dbo.ToDo", connectionStringSetting: "SqlConnectionString")] IAsyncCollector<ToDoItem> newItems)
-        {
-            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
-            var incomingItems = JsonConvert.DeserializeObject<ToDoItem[]>(requestBody);
-            foreach (ToDoItem newItem in incomingItems)
-            {
-                await newItems.AddAsync(newItem);
-            }
-            // Rows are upserted here
-            await newItems.FlushAsync();
+        [SqlOutput("dbo.ToDo", connectionStringSetting: "SqlConnectionString")]
+        public ToDoItem ToDoItem { get; set; }
 
-            return new CreatedResult($"/api/addtodo-asynccollector", "done");
-        }
+        [SqlOutput("dbo.RequestLog", connectionStringSetting: "SqlConnectionString")]
+        public RequestLog RequestLog { get; set; }
+
+        public HttpResponseData HttpResponse { get; set; }
     }
+
 }
 ```
 
 
+
+
 # [C# Script](#tab/csharp-script)
 
 
@@ -1197,7 +1187,10 @@ The following table explains the binding configuration properties that you set i
 ::: zone pivot="programming-language-csharp,programming-language-javascript,programming-language-powershell,programming-language-python,programming-language-java"
 The `CommandText` property is the name of the table where the data is to be stored. The connection string setting name corresponds to the application setting that contains the [connection string](/dotnet/api/microsoft.data.sqlclient.sqlconnection.connectionstring?view=sqlclient-dotnet-core-5.0&preserve-view=true#Microsoft_Data_SqlClient_SqlConnection_ConnectionString) to the Azure SQL or SQL Server instance.
 
-The output bindings use the T-SQL [MERGE](/sql/t-sql/statements/merge-transact-sql) statement which requires [SELECT](/sql/t-sql/statements/merge-transact-sql#permissions) permissions on the target database. 
+The output bindings use the T-SQL [MERGE](/sql/t-sql/statements/merge-transact-sql) statement which requires [SELECT](/sql/t-sql/statements/merge-transact-sql#permissions) permissions on the target database.
+
+If an exception occurs when a SQL output binding is executed then the function code stop executing.  This may result in an error code being returned, such as an HTTP trigger returning a 500 error code.  If the `IAsyncCollector` is used in a .NET function then the function code can handle exceptions throw by the call to `FlushAsync()`.
+
 
 ::: zone-end