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

The Connection property of EventHubAttribute and EventHubTriggerAttribute is used to specify the configuration property that stores the connection string.

The AzureWebJobsStorage connection string is used to preserve the processing checkpoint information.

For the local development use the local.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 the application settings to set the connection string.

Managed identity authentication

If your environment has managed 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 the Azure Functions developer guide.

To use managed identity 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 in application settings:

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

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 the Azure 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 the Azure 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 the EventHubAttribute the function return value. The return value can be of string or EventData type.

[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 the EventHubAttribute to the IAsyncCollector<string> or IAsyncCollector<EventData> parameter.

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

Using binding to strongly-typed models

To use strongly-typed model classes with the EventHub binding apply the EventHubAttribute 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 the EventHubProducerClient 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(new BinaryData($"Event 1 added at: {DateTime.Now}")),
        new EventData(new BinaryData($"Event 2 added at: {DateTime.Now}"))
    });
}

Per-event triggers

To run a function every time an event is sent to Event Hub apply the EventHubTriggerAttribute to a string or EventData 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 the EventHubTriggerAttribute to a string[] or EventData[] 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 to Monitor Azure Functions for troubleshooting guidance.

Next steps

Read the introduction to Azure Functions or creating an Azure Function guide.

Contributing

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

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.