Microsoft.Azure.WebJobs.Extensions.EventHubs 6.1.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs --version 6.1.0
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.EventHubs -Version 6.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventHubs" Version="6.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Microsoft.Azure.WebJobs.Extensions.EventHubs --version 6.1.0
#r "nuget: Microsoft.Azure.WebJobs.Extensions.EventHubs, 6.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Microsoft.Azure.WebJobs.Extensions.EventHubs as a Cake Addin
#addin nuget:?package=Microsoft.Azure.WebJobs.Extensions.EventHubs&version=6.1.0

// Install Microsoft.Azure.WebJobs.Extensions.EventHubs as a Cake Tool
#tool nuget:?package=Microsoft.Azure.WebJobs.Extensions.EventHubs&version=6.1.0

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 with NuGet:

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 a free trial or use your Visual Studio Subscription benefits when you create 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 for creating 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 for creating 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.

Deploy button

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.

Identity-based 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 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 in application settings:

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

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

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. A partition keys may not be specified when using a return value; to do so, you'll need to bind to the IAsyncCollector<EventData>, as shown in Sending 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 the EventHubAttribute to the IAsyncCollector<string> or IAsyncCollector<EventData> parameter. Partition keys may only be used when binding to IAsyncCollector<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 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($"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 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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (6)

Showing the top 5 NuGet packages that depend on Microsoft.Azure.WebJobs.Extensions.EventHubs:

Package Downloads
MassTransit.WebJobs.EventHubs The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

MassTransit Azure WebJobs Event Hubs support; MassTransit provides a developer-focused, modern platform for creating distributed applications without complexity.

Microsoft.Azure.Workflows.WebJobs.Extension The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Extensions for running workflows in Azure Functions

RedQuick

Package Description

Amido.Stacks.Messaging.Azure.EventHub

Package Description

Beef.Events.EventHubs

Business Entity Execution Framework (Beef) Event Hubs framework.

GitHub repositories (11)

Showing the top 5 popular GitHub repositories that depend on Microsoft.Azure.WebJobs.Extensions.EventHubs:

Repository Stars
MassTransit/MassTransit
Distributed Application Framework for .NET
mspnp/cloud-design-patterns
Sample implementations for cloud design patterns found in the Azure Architecture Center.
Azure/azure-webjobs-sdk
Azure WebJobs SDK
Azure-Samples/saga-orchestration-serverless
An orchestration-based saga implementation reference in a serverless architecture
JamesRandall/FunctionMonkey
Write more elegant Azure Functions with less boilerplate, more consistency, and support for REST APIs. Docs can be found at https://functionmonkey.azurefromthetrenches.com
Version Downloads Last updated
6.1.0 8,028 2/14/2024
6.0.2 121,551 11/13/2023
6.0.1 134,259 10/11/2023
6.0.0 48,113 9/12/2023
5.5.0 126,791 8/14/2023
5.4.0 274,926 6/6/2023
5.3.0 241,721 4/11/2023
5.2.0 152,966 2/23/2023
5.1.2 823,722 8/10/2022
5.1.1 654,622 6/21/2022
5.1.0 385,675 4/21/2022
5.0.1 189,887 3/9/2022
5.0.0 679,573 10/26/2021
5.0.0-beta.7 68,859 7/9/2021
5.0.0-beta.6 43,753 6/9/2021
5.0.0-beta.5 18,514 5/18/2021
5.0.0-beta.4 17,665 4/6/2021
5.0.0-beta.3 17,491 3/11/2021
5.0.0-beta.2 18,541 3/9/2021
5.0.0-beta.1 22,326 2/10/2021
4.3.1 257,416 2/15/2022
4.3.0 423,869 10/26/2021
4.2.0 847,034 12/11/2020
4.1.1 1,325,989 2/5/2020
4.1.0 180,870 10/31/2019
4.0.1 408,974 10/1/2019
4.0.0 143,445 9/19/2019
4.0.0-beta2 947 8/5/2019
4.0.0-beta1 10,903 5/14/2019
3.0.6 298,776 7/23/2019
3.0.5 220,043 5/3/2019
3.0.4 66,179 3/29/2019
3.0.3 240,401 3/7/2019
3.0.2 49,815 1/25/2019
3.0.1 122,996 10/17/2018
3.0.0 138,264 9/19/2018
3.0.0-rc1 2,865 9/14/2018
3.0.0-beta8 8,481 8/30/2018
3.0.0-beta5 15,011 3/26/2018
3.0.0-beta4 5,220 11/28/2017
3.0.0-beta3 1,439 9/15/2017