|
1 | 1 | # Azure WebJobs Event Hubs client library for .NET |
2 | 2 |
|
3 | | -TODO |
| 3 | +This extension provides functionality for accessing Azure Event Hubs from an Azure Function. |
4 | 4 |
|
5 | 5 | ## Getting started |
6 | 6 |
|
7 | 7 | ### Install the package |
8 | 8 |
|
9 | | -Install the Event Grid extension with [NuGet][nuget]: |
| 9 | +Install the Event Hubs extension with [NuGet](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs): |
10 | 10 |
|
11 | 11 | ```Powershell |
12 | 12 | dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs --version 5.0.0-beta.1 |
13 | 13 | ``` |
14 | 14 |
|
15 | 15 | ### Prerequisites |
16 | 16 |
|
17 | | -TODO |
| 17 | +- **Azure Subscription:** To use Azure services, including Azure Event Hubs, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a [free trial](https://azure.microsoft.com/free) or use your [Visual Studio Subscription](https://visualstudio.microsoft.com/subscriptions/) benefits when you [create an account](https://account.windowsazure.com/Home/Index). |
| 18 | + |
| 19 | +- **Event Hubs namespace with an Event Hub:** To interact with Azure Event Hubs, you'll also need to have a namespace and Event Hub available. If you are not familiar with creating Azure resources, you may wish to follow the step-by-step guide for [creating an Event Hub using the Azure portal](https://docs.microsoft.com/azure/event-hubs/event-hubs-create). There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create an Event Hub. |
| 20 | + |
| 21 | +- **Azure Storage account with blob storage:** To persist checkpoints as blobs in Azure Storage, you'll need to have an Azure Storage account with blobs available. If you are not familiar with Azure Storage accounts, you may wish to follow the step-by-step guide for [creating a storage account using the Azure portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal). There, you can also find detailed instructions for using the Azure CLI, Azure PowerShell, or Azure Resource Manager (ARM) templates to create storage accounts. |
| 22 | + |
| 23 | +[](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-sdk-for-net%2Fmaster%2Fsdk%2Feventhub%2FAzure.Messaging.EventHubs.Processor%2Fassets%2Fsamples-azure-deploy.json) |
18 | 24 |
|
19 | 25 | ### Authenticate the Client |
20 | 26 |
|
21 | | -TODO |
| 27 | +For the Event Hubs client library to interact with an Event Hub, it will need to understand how to connect and authorize with it. The easiest means for doing so is to use a connection string, which is created automatically when creating an Event Hubs namespace. If you aren't familiar with using connection strings with Event Hubs, you may wish to follow the step-by-step guide to [get an Event Hubs connection string](https://docs.microsoft.com/azure/event-hubs/event-hubs-get-connection-string). |
| 28 | + |
| 29 | +The `Connection` property of `EventHubAttribute` and `EventHubTriggerAttribute` is used to specify the configuration property that stores the connection string. |
| 30 | + |
| 31 | +The `AzureWebJobsStorage` connection string is used to preserve the processing checkpoint information. |
| 32 | + |
| 33 | +For the local development use the `local.settings.json` file to store the connection string: |
| 34 | + |
| 35 | +```json |
| 36 | +{ |
| 37 | + "Values": { |
| 38 | + "AzureWebJobsStorage": "UseDevelopmentStorage=true", |
| 39 | + "<connection_name>": "Endpoint=sb://<event_hub_name>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8=" |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +When deployed use the [application settings](https://docs.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings) to set the connection string. |
| 45 | + |
| 46 | +#### Managed identity authentication |
| 47 | + |
| 48 | +If your environment has [managed identity](https://docs.microsoft.com/azure/app-service/overview-managed-identity?tabs=dotnet) enabled you can use it to authenticate the Event Hubs extension. |
| 49 | +To use managed identity provide the `<connection_name>__fullyQualifiedNamespace` configuration setting. |
| 50 | + |
| 51 | +```json |
| 52 | +{ |
| 53 | + "Values": { |
| 54 | + "AzureWebJobsStorage": "UseDevelopmentStorage=true", |
| 55 | + "<connection_name>__fullyQualifiedNamespace": "<event_hub_name>.servicebus.windows.net" |
| 56 | + } |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +Or in the case of deployed app set the same setting in [application settings](https://docs.microsoft.com/azure/azure-functions/functions-how-to-use-azure-function-app-settings): |
| 61 | + |
| 62 | +``` |
| 63 | +<connection_name>__fullyQualifiedNamespace=<event_hub_name>.servicebus.windows.net |
| 64 | +``` |
22 | 65 |
|
23 | 66 | ## Key concepts |
24 | 67 |
|
25 | | -TODO |
| 68 | +### Event Hub Trigger |
| 69 | + |
| 70 | +The Event Hub Trigger allows a function to be executed when a message is sent to an Event Hub. |
| 71 | + |
| 72 | +Please follow the [Azure Event Hubs trigger tutorial](https://docs.microsoft.com/azure/azure-functions/functions-bindings-event-hubs-trigger?tabs=csharp) to learn more about Event Hub triggers. |
| 73 | + |
| 74 | +### Event Hub Output Binding |
| 75 | + |
| 76 | +The Event Hub Output Binding allows a function to send Event Hub events. |
| 77 | + |
| 78 | +Please follow the [Azure Event Hubs output binding](https://docs.microsoft.com/azure/azure-functions/functions-bindings-event-hubs-output?tabs=csharp) to learn more about Event Hub bindings. |
26 | 79 |
|
27 | 80 | ## Examples |
28 | 81 |
|
29 | | -TODO |
| 82 | +### Sending individual event |
| 83 | + |
| 84 | +You can send individual events to an Event Hub by applying the `EventHubAttribute` the function return value. The return value can be of `string` or `EventData` type. |
| 85 | + |
| 86 | +```C# Snippet:BindingToReturnValue |
| 87 | +[FunctionName("BindingToReturnValue")] |
| 88 | +[return: EventHub("<event_hub_name>", Connection = "<connection_name>")] |
| 89 | +public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer) |
| 90 | +{ |
| 91 | + // This value would get stored in EventHub event body. |
| 92 | + // The string would be UTF8 encoded |
| 93 | + return $"C# Timer trigger function executed at: {DateTime.Now}"; |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +### Sending multiple events |
| 98 | + |
| 99 | +To send multiple events from a single Azure Function invocation you can apply the `EventHubAttribute` to the `IAsyncCollector<string>` or `IAsyncCollector<EventData>` parameter. |
| 100 | + |
| 101 | + |
| 102 | +```C# Snippet:BindingToCollector |
| 103 | +[FunctionName("BindingToCollector")] |
| 104 | +public static async Task Run( |
| 105 | + [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, |
| 106 | + [EventHub("<event_hub_name>", Connection = "<connection_name>")] IAsyncCollector<EventData> collector) |
| 107 | +{ |
| 108 | + // IAsyncCollector allows sending multiple events in a single function invocation |
| 109 | + await collector.AddAsync(new EventData(new BinaryData($"Event 1 added at: {DateTime.Now}"))); |
| 110 | + await collector.AddAsync(new EventData(new BinaryData($"Event 2 added at: {DateTime.Now}"))); |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +### Per-event triggers |
| 115 | + |
| 116 | +To run a function every time an event is sent to Event Hub apply the `EventHubTriggerAttribute` to a `string` or `EventData` parameter. |
| 117 | + |
| 118 | +```C# Snippet:TriggerSingle |
| 119 | +[FunctionName("TriggerSingle")] |
| 120 | +public static void Run( |
| 121 | + [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] string eventBodyAsString, |
| 122 | + ILogger logger) |
| 123 | +{ |
| 124 | + logger.LogInformation($"C# function triggered to process a message: {eventBodyAsString}"); |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +### Batch triggers |
| 129 | + |
| 130 | +To run a function for a batch of received events apply the `EventHubTriggerAttribute` to a `string[]` or `EventData[]` parameter. |
| 131 | + |
| 132 | +```C# Snippet:TriggerBatch |
| 133 | +[FunctionName("TriggerBatch")] |
| 134 | +public static void Run( |
| 135 | + [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] EventData[] events, |
| 136 | + ILogger logger) |
| 137 | +{ |
| 138 | + foreach (var e in events) |
| 139 | + { |
| 140 | + logger.LogInformation($"C# function triggered to process a message: {e.EventBody}"); |
| 141 | + logger.LogInformation($"EnqueuedTime={e.EnqueuedTime}"); |
| 142 | + } |
| 143 | +} |
| 144 | +``` |
30 | 145 |
|
31 | 146 | ## Troubleshooting |
32 | 147 |
|
33 | | -TODO |
| 148 | +Please refer to [Monitor Azure Functions](https://docs.microsoft.com/azure/azure-functions/functions-monitoring) for troubleshooting guidance. |
34 | 149 |
|
35 | 150 | ## Next steps |
36 | 151 |
|
|
0 commit comments