Merge pull request #252365 from ggailey777/dotnet

[Functions] article clean-up based on tag scanning

Author: American-Dipper

articles/azure-functions/functions-bindings-azure-data-explorer-output.md

@@ -22,7 +22,7 @@ For information on setup and configuration details, see the [overview](functions
 
 [!INCLUDE [functions-bindings-csharp-intro-with-csx](../../includes/functions-bindings-csharp-intro-with-csx.md)]
 
-# [In-process](#tab/in-process)
+### [In-process](#tab/in-process)
 
 More samples for the Azure Data Explorer output binding are available in the [GitHub repository](https://github.com/Azure/Webjobs.Extensions.Kusto/tree/main/samples/samples-csharp).
 
@@ -54,7 +54,7 @@ public class Product
 
 <a id="http-trigger-write-one-record-c"></a>
 
-### HTTP trigger, write one record
+#### HTTP trigger, write one record
 
 The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database. The function uses data provided in an HTTP POST request as a JSON body.
 
@@ -92,7 +92,7 @@ namespace Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.OutputBindingSamples
 
 <a id="http-trigger-write-to-two-tables-c"></a>
 
-### HTTP trigger, write to two tables
+#### HTTP trigger, write to two tables
 
 The following example shows a [C# function](functions-dotnet-class-library.md) that adds records to a database in two different tables (`Products` and `ProductsChangeLog`). The function uses data provided in an HTTP POST request as a JSON body and multiple output bindings.
 
@@ -163,7 +163,7 @@ namespace Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.OutputBindingSamples
 
 <a id="http-trigger-write-records-using-iasynccollector-c"></a>
 
-### HTTP trigger, write records using IAsyncCollector
+#### HTTP trigger, write records using IAsyncCollector
 
 The following example shows a [C# function](functions-dotnet-class-library.md) that ingests a set of records to a table. The function uses data provided in an HTTP POST body JSON array.
 
@@ -204,7 +204,7 @@ namespace Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.OutputBindingSamples
 }
 ```
 
-# [Isolated process](#tab/isolated-process)
+### [Isolated process](#tab/isolated-process)
 
 More samples for the Azure Data Explorer output binding are available in the [GitHub repository](https://github.com/Azure/Webjobs.Extensions.Kusto/tree/main/samples/samples-outofproc).
 
@@ -235,7 +235,7 @@ public class Product
 
 <a id="http-trigger-write-one-record-c-oop"></a>
 
-### HTTP trigger, write one record
+#### HTTP trigger, write one record
 
 The following example shows a [C# function](functions-dotnet-class-library.md) that adds a record to a database. The function uses data provided in an HTTP POST request as a JSON body.
 
@@ -265,7 +265,7 @@ namespace Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.OutputBindin
 
 <a id="http-trigger-write-records-with-mapping-oop"></a>
 
-### HTTP trigger, write records with mapping
+#### HTTP trigger, write records with mapping
 
 The following example shows a [C# function](functions-dotnet-class-library.md) that adds a collection of records to a database. The function uses mapping that transforms a `Product` to `Item`.
 
@@ -316,6 +316,7 @@ namespace Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.OutputBindin
     }
 }
 ```
+---
 
 ::: zone-end
 

articles/azure-functions/functions-bindings-event-grid-output.md

@@ -3,7 +3,7 @@ title: Azure Event Grid output binding for Azure Functions
 description: Learn to send an Event Grid event in Azure Functions.
 
 ms.topic: reference
-ms.date: 08/10/2023
+ms.date: 09/22/2023
 ms.devlang: csharp, java, javascript, powershell, python
 ms.custom: devx-track-csharp, fasttrack-edit, devx-track-python, devx-track-extended-java, devx-track-js
 zone_pivot_groups: programming-languages-set-functions
@@ -114,7 +114,7 @@ public static EventGridEvent Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTim
 }
 ```
 
-It is also possible to use an `out` parameter to accomplish the same thing:
+It's also possible to use an `out` parameter to accomplish the same thing:
 ```csharp
 [FunctionName("EventGridOutput")]
 [return: EventGrid(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
@@ -144,7 +144,7 @@ public static async Task Run(
 }
 ```
 
-Starting in version 3.3.0, it is possible to use Azure Active Directory when authenticating the output binding:
+Starting in version 3.3.0, it's possible to use Azure Active Directory when authenticating the output binding:
 
 ```csharp
 [FunctionName("EventGridAsyncOutput")]
@@ -161,19 +161,16 @@ public static async Task Run(
 }
 ```
 
-When using the Connection property, the `topicEndpointUri` must be specified as a child of the connection setting, and the `TopicEndpointUri` and `TopicKeySetting` properties should not be used. For local development, use the local.settings.json file to store the connection information:
+When you use the `Connection` property, the `topicEndpointUri` must be specified as a child of the connection setting, and you shouldn't use the `TopicEndpointUri` and `TopicKeySetting` properties. For local development, use the local.settings.json file to store the connection information:
+
 ```json
 {
   "Values": {
     "myConnection__topicEndpointUri": "{topicEndpointUri}"
   }
 }
 ```
-When deployed, use the application settings to store this information.
-
-## Authenticating the Event Grid output binding
-
-[!INCLUDE [functions-event-grid-connections](../../includes/functions-event-grid-connections.md)]
+When deployed, you must add this same information to application settings for the function app. For more information, see [Identity-based authentication](#identity-based-authentication).
 
 # [Isolated process](#tab/isolated-process)
 
@@ -296,7 +293,7 @@ To output multiple events, return an array instead of a single object. For examp
 
 # [Model v3](#tab/nodejs-v3)
 
-TypeScript samples are not documented for model v3.
+TypeScript samples aren't documented for model v3.
 
 ---
 
@@ -536,6 +533,7 @@ The following table explains the parameters for the `EventGridAttribute`.
 |---------|---------|----------------------|
 |**TopicEndpointUri** | The name of an app setting that contains the URI for the custom topic, such as `MyTopicEndpointUri`. |
 |**TopicKeySetting** | The name of an app setting that contains an access key for the custom topic. |
+|**Connection**<sup>*</sup> | The value of the common prefix for the setting that contains the topic endpoint URI. For more information about the naming format of this application setting, see [Identity-based authentication](#identity-based-authentication).  | 
 
 # [Isolated process](#tab/isolated-process)
 
@@ -545,6 +543,7 @@ The following table explains the parameters for the `EventGridOutputAttribute`.
 |---------|---------|----------------------|
 |**TopicEndpointUri** | The name of an app setting that contains the URI for the custom topic, such as `MyTopicEndpointUri`. |
 |**TopicKeySetting** | The name of an app setting that contains an access key for the custom topic. |
+|**connection**<sup>*</sup> | The value of the common prefix for the setting that contains the topic endpoint URI. For more information about the naming format of this application setting, see [Identity-based authentication](#identity-based-authentication).  | 
 
 ---
 
@@ -589,6 +588,7 @@ The following table explains the binding configuration properties that you set i
 |**name** | The variable name used in function code that represents the event. |
 |**topicEndpointUri** | The name of an app setting that contains the URI for the custom topic, such as `MyTopicEndpointUri`. |
 |**topicKeySetting** | The name of an app setting that contains an access key for the custom topic. |
+|**connection**<sup>*</sup> | The value of the common prefix for the setting that contains the topic endpoint URI. For more information about the naming format of this application setting, see [Identity-based authentication](#identity-based-authentication).  | 
 
 ---
 
@@ -605,13 +605,16 @@ The following table explains the binding configuration properties that you set i
 |**name** | The variable name used in function code that represents the event. |
 |**topicEndpointUri** | The name of an app setting that contains the URI for the custom topic, such as `MyTopicEndpointUri`. |
 |**topicKeySetting** | The name of an app setting that contains an access key for the custom topic. |
+|**connection**<sup>*</sup> | The value of the common prefix for the setting that contains the topic endpoint URI. For more information about the naming format of this application setting, see [Identity-based authentication](#identity-based-authentication).  | 
 
 ::: zone-end
-
+::: zone pivot="programming-language-csharp,programming-language-javascript,programming-language-powershell,programming-language-python,programming-language-typescript"
+<sup>*</sup>Support for identity-based connections requires version 3.3.x or higher of the extension.
+::: zone-end
 [!INCLUDE [app settings to local.settings.json](../../includes/functions-app-settings-local.md)]
 
 > [!IMPORTANT]
-> Make sure that you set the value of the `TopicEndpointUri` configuration property to the name of an app setting that contains the URI of the custom topic. Don't specify the URI of the custom topic directly in this property.
+> Make sure that you set the value of `TopicEndpointUri` to the name of an app setting that contains the URI of the custom topic. Don't specify the URI of the custom topic directly in this property. The same applies when using `Connection`.
 
 See the [Example section](#example) for complete examples.
 
@@ -625,7 +628,7 @@ The parameter type supported by the Event Grid output binding depends on the Fun
 In-process C# class library functions supports the following types:
 
 + [Azure.Messaging.CloudEvent][CloudEvent]
-+ [Azure.Messaging.EventGrid][EventGridEvent2]
++ [Azure.Messaging.EventGrid.EventGridEvent][EventGridEvent2]
 + [Newtonsoft.Json.Linq.JObject][JObject]
 + [System.String][String]
 
@@ -696,9 +699,55 @@ There are two options for outputting an Event Grid message from a function:
 
 ::: zone-end
 
+## Connections
+
+There are two ways of authenticating to an Event Grid topic when using the Event Grid output binding:
+
+| Authentication method | Description |
+| ----- | ----- |
+| Using a topic key | Set the `TopicEndpointUri` and `TopicKeySetting` properties, as described in [Use a topic key](#use-a-topic-key). | 
+| Using an identity | Set the `Connection` property to the name of a shared prefix for multiple application settings, together defining [identity-based authentication](#identity-based-authentication). This method is supported when using version 3.3.x or higher of the extension. | 
+
+### Use a topic key
+
+Use the following steps to configure a topic key:
+
+1. Follow the steps in [Get access keys](../event-grid/get-access-keys.md) to obtain the topic key for your Event Grid topic.
+
+1. In your application settings, create a setting that defines the topic key value. Use the name of this setting for the `TopicKeySetting` property of the binding.
+ 
+1. In your application settings, create a setting that defines the topic endpoint. Use the name of this setting for the `TopicEndpointUri` property of the binding.
+
+### Identity-based authentication
+
+When using version 3.3.x or higher of the extension, you can connect to an Event Grid topic using an [Azure Active Directory identity](../active-directory/fundamentals/active-directory-whatis.md) to avoid having to obtain and work with topic keys. 
+
+To do this, create an application setting that returns the topic endpoint URI, where the name of the setting combines a unique _common prefix_, such as `myawesometopic`, with the value `__topicEndpointUri`. You then use the common prefix `myawesometopic` when you define the `Connection` property in the binding.
+
+In this mode, the extension requires the following properties:
+
+| Property           | Environment variable template                | Description         | Example value |
+|--------------------|----------------------------------------------|---------------------|---------------|
+| Topic Endpoint URI | `<CONNECTION_NAME_PREFIX>__topicEndpointUri` | The topic endpoint. | `https://<topic-name>.centralus-1.eventgrid.azure.net/api/events`  |
+
+More properties may be set to customize the connection. See [Common properties for identity-based connections](functions-reference.md#common-properties-for-identity-based-connections).
+
+> [!NOTE]
+> When using [Azure App Configuration](../azure-app-configuration/quickstart-azure-functions-csharp.md) or [Key Vault](../key-vault/general/overview.md) to provide settings for managed identity-based connections, setting names should use a valid key separator such as `:` or `/` in place of the `__` to ensure names are resolved correctly.
+> 
+> For example, `<CONNECTION_NAME_PREFIX>:topicEndpointUri`.
+
+[!INCLUDE [functions-identity-based-connections-configuration](../../includes/functions-identity-based-connections-configuration.md)]
+
+[!INCLUDE [functions-event-grid-permissions](../../includes/functions-event-grid-permissions.md)]
+
+
 ## Next steps
 
 * [Dispatch an Event Grid event](./functions-bindings-event-grid-trigger.md)
 
-[EventGridEvent]: /dotnet/api/azure.messaging.eventgrid.eventgridevent
+[EventGridEvent2]: /dotnet/api/azure.messaging.eventgrid.eventgridevent
+[EventGridEvent]: /dotnet/api/microsoft.azure.eventgrid.models.eventgridevent
 [CloudEvent]: /dotnet/api/azure.messaging.cloudevent
+[String]: /dotnet/api/system.string
+[JObject]: https://www.newtonsoft.com/json/help/html/t_newtonsoft_json_linq_jobject.htm

articles/azure-functions/functions-bindings-timer.md

@@ -65,6 +65,7 @@ public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger
 
 :::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Timer/TimerFunction.cs" range="11-17":::
 
+---
 
 ::: zone-end
 ::: zone pivot="programming-language-java"

articles/azure-functions/functions-reference.md

@@ -226,7 +226,7 @@ Choose one of these tabs to learn about permissions for each component:
 
 # [Event Grid extension](#tab/eventgrid)
 
-[!INCLUDE [functions-event-grid-connections](../../includes/functions-event-grid-connections.md)]
+[!INCLUDE [functions-event-grid-permissions](../../includes/functions-event-grid-permissions.md)]
 
 # [Azure Cosmos DB extension](#tab/cosmos)
 

articles/azure-functions/migrate-cosmos-db-version-3-version-4.md

@@ -30,7 +30,7 @@ This article walks you through the process of migrating your function app to run
 
 Update your `.csproj` project file to use the latest extension version for your process model. The following `.csproj` file uses version 4 of the Azure Cosmos DB extension.
 
-### [In-process model](#tab/in-process)
+### [In-process](#tab/in-process)
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
@@ -54,7 +54,7 @@ Update your `.csproj` project file to use the latest extension version for your
 </Project>
 ```
 
-### [Isolated worker model](#tab/isolated-worker)
+### [Isolated process](#tab/isolated-process)
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">

includes/functions-event-grid-connections.md

@@ -0,0 +1,13 @@
+---
+author: ggailey777
+ms.service: azure-functions
+ms.topic: include
+ms.date: 09/29/2023
+ms.author: glenga
+---
+
+You must create a role assignment that provides access to your Event Grid topic at runtime. Management roles like [Owner](../articles/role-based-access-control/built-in-roles.md#owner) are not sufficient. The following table shows built-in roles that are recommended when using the Event Hubs extension in normal operation. Your application may require additional permissions based on the code you write.
+
+| Binding type   | Example built-in roles                                          |
+|----------------|-----------------------------------------------------------------|
+| Output binding | [EventGrid Contributor](../articles/role-based-access-control//built-in-roles.md#eventgrid-contributor), [EventGrid Data Sender](../articles/role-based-access-control/built-in-roles.md#eventgrid-data-sender)  |

includes/functions-event-grid-permissions.md

@@ -29,9 +29,9 @@ If you are using [version 5.x or higher of the extension](../articles/azure-func
 
 In this mode, the extension requires the following properties:
 
-| Property                  | Environment variable template                       | Description                                | Example value                                        |
-|---------------------------|-----------------------------------------------------|--------------------------------------------|------------------------------------------------|
-| Fully Qualified Namespace | `<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace` | The fully qualified Event Hubs namespace. | <event_hubs_namespace>.servicebus.windows.net |
+| Property   | Environment variable template     | Description     | Example value     |
+|--------------|----------|-----|----------|
+| Fully Qualified Namespace | `<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace` | The fully qualified Event Hubs namespace. | `myeventhubns.servicebus.windows.net`|
 
 Additional properties may be set to customize the connection. See [Common properties for identity-based connections](../articles/azure-functions/functions-reference.md#common-properties-for-identity-based-connections).