Microsoft.Azure.WebJobs.Extensions.EventHubs
6.3.5
Prefix Reserved
dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs --version 6.3.5
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.EventHubs -Version 6.3.5
<PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventHubs" Version="6.3.5" />
paket add Microsoft.Azure.WebJobs.Extensions.EventHubs --version 6.3.5
#r "nuget: Microsoft.Azure.WebJobs.Extensions.EventHubs, 6.3.5"
// Install Microsoft.Azure.WebJobs.Extensions.EventHubs as a Cake Addin #addin nuget:?package=Microsoft.Azure.WebJobs.Extensions.EventHubs&version=6.3.5 // Install Microsoft.Azure.WebJobs.Extensions.EventHubs as a Cake Tool #tool nuget:?package=Microsoft.Azure.WebJobs.Extensions.EventHubs&version=6.3.5
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.
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 encodingBinaryData
byte[]
- Custom model types will be JSON-serialized using Newtonsoft.Json
IAsyncCollector<T>
of any of the above types for batch triggersEventHubProducerClient
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 | Versions 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. |
-
.NETStandard 2.0
- Azure.Messaging.EventHubs (>= 5.11.5)
- Azure.Storage.Blobs (>= 12.21.1)
- Microsoft.Azure.WebJobs (>= 3.0.37)
- Microsoft.Extensions.Azure (>= 1.7.4)
NuGet packages (6)
Showing the top 5 NuGet packages that depend on Microsoft.Azure.WebJobs.Extensions.EventHubs:
Package | Downloads |
---|---|
MassTransit.WebJobs.EventHubs
MassTransit Azure WebJobs Event Hubs support; MassTransit provides a developer-focused, modern platform for creating distributed applications without complexity. |
|
Microsoft.Azure.Workflows.WebJobs.Extension
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 (9)
Showing the top 5 popular GitHub repositories that depend on Microsoft.Azure.WebJobs.Extensions.EventHubs:
Repository | Stars |
---|---|
MassTransit/MassTransit
Distributed Application Framework for .NET
|
|
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
|
|
ProfessionalCSharp/MoreSamples
Additional code samples the book series Professional C#, Wrox Press
|
Version | Downloads | Last updated |
---|---|---|
6.3.5 | 157,064 | 8/2/2024 |
6.3.4 | 3,848 | 7/25/2024 |
6.3.3 | 57,118 | 6/13/2024 |
6.3.2 | 217,168 | 4/29/2024 |
6.3.1 | 17,492 | 4/17/2024 |
6.3.0 | 11,117 | 4/10/2024 |
6.2.0 | 196,572 | 3/5/2024 |
6.1.0 | 28,384 | 2/14/2024 |
6.0.2 | 317,104 | 11/13/2023 |
6.0.1 | 259,210 | 10/11/2023 |
6.0.0 | 68,203 | 9/12/2023 |
5.5.0 | 217,448 | 8/14/2023 |
5.4.0 | 401,782 | 6/6/2023 |
5.3.0 | 302,494 | 4/11/2023 |
5.2.0 | 174,819 | 2/23/2023 |
5.1.2 | 996,252 | 8/10/2022 |
5.1.1 | 830,849 | 6/21/2022 |
5.1.0 | 438,567 | 4/21/2022 |
5.0.1 | 212,773 | 3/9/2022 |
5.0.0 | 771,271 | 10/26/2021 |
5.0.0-beta.7 | 69,522 | 7/9/2021 |
5.0.0-beta.6 | 44,566 | 6/9/2021 |
5.0.0-beta.5 | 19,150 | 5/18/2021 |
5.0.0-beta.4 | 17,702 | 4/6/2021 |
5.0.0-beta.3 | 17,510 | 3/11/2021 |
5.0.0-beta.2 | 18,562 | 3/9/2021 |
5.0.0-beta.1 | 22,353 | 2/10/2021 |
4.3.1 | 339,282 | 2/15/2022 |
4.3.0 | 508,880 | 10/26/2021 |
4.2.0 | 868,191 | 12/11/2020 |
4.1.1 | 1,363,541 | 2/5/2020 |
4.1.0 | 184,124 | 10/31/2019 |
4.0.1 | 423,285 | 10/1/2019 |
4.0.0 | 144,051 | 9/19/2019 |
4.0.0-beta2 | 993 | 8/5/2019 |
4.0.0-beta1 | 11,616 | 5/14/2019 |
3.0.6 | 302,414 | 7/23/2019 |
3.0.5 | 226,405 | 5/3/2019 |
3.0.4 | 67,826 | 3/29/2019 |
3.0.3 | 248,066 | 3/7/2019 |
3.0.2 | 50,202 | 1/25/2019 |
3.0.1 | 125,376 | 10/17/2018 |
3.0.0 | 139,785 | 9/19/2018 |
3.0.0-rc1 | 2,904 | 9/14/2018 |
3.0.0-beta8 | 8,617 | 8/30/2018 |
3.0.0-beta5 | 15,112 | 3/26/2018 |
3.0.0-beta4 | 5,288 | 11/28/2017 |
3.0.0-beta3 | 1,485 | 9/15/2017 |