Azure WebJobs Event Hubs client library for .NET

This extension provides functionality for accessing Azure Event Hubs from an Azure Function.

Getting started

Install the package

Install the Event Hubs extension withNuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs

Prerequisites

• 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 afree trial or use yourVisual Studio Subscription benefits when youcreate an account.

• 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 forcreating an Event Hub using the Azure portal. 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.

• 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 forcreating a storage account using the 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.

Authenticate the Client

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 toget an Event Hubs connection string.

TheConnection property ofEventHubAttribute andEventHubTriggerAttribute is used to specify the configuration property that stores the connection string.

TheAzureWebJobsStorage connection string is used to preserve the processing checkpoint information.

For the local development use thelocal.settings.json file to store the connection string:

{  "Values": {    "AzureWebJobsStorage": "UseDevelopmentStorage=true",    "<connection_name>": "Endpoint=sb://<event_hubs_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8="  }}

When deployed use theapplication settings to set the connection string.

Identity-based authentication

If your environment hasmanaged identity enabled you can use it to authenticate the Event Hubs extension. Before doing so, you will need to ensure that permissions have been configured as described in theAzure Functions developer guide.

To use identity-based authentication provide the<connection_name>__fullyQualifiedNamespace configuration setting.

{  "Values": {    "AzureWebJobsStorage": "UseDevelopmentStorage=true",    "<connection_name>__fullyQualifiedNamespace": "{event_hubs_namespace}.servicebus.windows.net"  }}

Or in the case of deployed app set the same setting inapplication settings:

<connection_name>__fullyQualifiedNamespace={event_hubs_namespace}.servicebus.windows.net

More details about configuring an identity-based connection can be foundhere.

Key concepts

Event Hub Trigger

The Event Hub Trigger allows a function to be executed when a message is sent to an Event Hub.

Please follow theAzure Event Hubs trigger tutorial to learn more about Event Hub triggers.

Event Hub Output Binding

The Event Hub Output Binding allows a function to send Event Hub events.

Please follow theAzure Event Hubs output binding to learn more about Event Hub bindings.

Supported types

The following types are supported for trigger and output bindings:

• EventData
• string - value would be encoded using UTF8 encoding
• BinaryData
• byte[]
• Custom model types will be JSON-serialized using Newtonsoft.Json
• IAsyncCollector<T> of any of the above types for batch triggers
• EventHubProducerClient for output bindings

Examples

Sending individual event

You can send individual events to an Event Hub by applying theEventHubAttribute the function return value. The return value can be ofstring orEventData type. A partition keys may not be specified when using a return value; to do so, you'll need to bind to theIAsyncCollector<EventData>, as shown inSending multiple events.

[FunctionName("BindingToReturnValue")][return: EventHub("<event_hub_name>", Connection = "<connection_name>")]public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer){    // This value would get stored in EventHub event body.    // The string would be UTF8 encoded    return $"C# Timer trigger function executed at: {DateTime.Now}";}

Sending multiple events

To send multiple events from a single Azure Function invocation you can apply theEventHubAttribute to theIAsyncCollector<string> orIAsyncCollector<EventData> parameter. Partition keys may only be used when binding toIAsyncCollector<EventData>.

[FunctionName("BindingToCollector")]public static async Task Run(    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,    [EventHub("<event_hub_name>", Connection = "<connection_name>")] IAsyncCollector<EventData> collector){    // When no partition key is used, partitions will be assigned per-batch via round-robin.    await collector.AddAsync(new EventData($"Event 1 added at: {DateTime.Now}"));    await collector.AddAsync(new EventData($"Event 2 added at: {DateTime.Now}"));    // Using a partition key will help group events together; events with the same key    // will always be assigned to the same partition.    await collector.AddAsync(new EventData($"Event 3 added at: {DateTime.Now}"), "sample-key");    await collector.AddAsync(new EventData($"Event 4 added at: {DateTime.Now}"), "sample-key");}

Using binding to strongly-typed models

To use strongly-typed model classes with the EventHub binding apply theEventHubAttribute to the model parameter.

[FunctionName("TriggerSingleModel")]public static void Run(    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] Dog dog,    ILogger logger){    logger.LogInformation($"Who's a good dog? {dog.Name} is!");}

Sending multiple events using EventHubProducerClient

You can also bind to theEventHubProducerClient directly to have the most control over the event sending.

[FunctionName("BindingToProducerClient")]public static async Task Run(    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,    [EventHub("<event_hub_name>", Connection = "<connection_name>")] EventHubProducerClient eventHubProducerClient){    // IAsyncCollector allows sending multiple events in a single function invocation    await eventHubProducerClient.SendAsync(new[]    {        new EventData($"Event 1 added at: {DateTime.Now}"),        new EventData($"Event 2 added at: {DateTime.Now}")    });}

Per-event triggers

To run a function every time an event is sent to Event Hub apply theEventHubTriggerAttribute to astring orEventData parameter.

[FunctionName("TriggerSingle")]public static void Run(    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] string eventBodyAsString,    ILogger logger){    logger.LogInformation($"C# function triggered to process a message: {eventBodyAsString}");}

Batch triggers

To run a function for a batch of received events apply theEventHubTriggerAttribute to astring[] orEventData[] parameter.

[FunctionName("TriggerBatch")]public static void Run(    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] EventData[] events,    ILogger logger){    foreach (var e in events)    {        logger.LogInformation($"C# function triggered to process a message: {e.EventBody}");        logger.LogInformation($"EnqueuedTime={e.EnqueuedTime}");    }}

Troubleshooting

Please refer toMonitor Azure Functions for troubleshooting guidance.

Next steps

Read theintroduction to Azure Functions orcreating an Azure Function guide.

Contributing

See ourCONTRIBUTING.md for details on building,testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions requireyou to agree to a Contributor License Agreement (CLA) declaring that you havethe right to, and actually do, grant us the rights to use your contribution. Fordetails, visitcla.microsoft.com.

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQor contactopencode@microsoft.com with anyadditional questions or comments.