author	ms.service	ms.topic	ms.date	ms.author
ggailey777	azure-functions	include	11/15/2021	glenga

Use the function trigger to respond to an event sent to an event hub event stream. You must have read access to the underlying event hub to set up the trigger. When the function is triggered, the message passed to the function is typed as a string.

Example

::: zone pivot="programming-language-csharp"

In-process

The following example shows a C# function that logs the message body of the Event Hubs trigger.

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

To get access to event metadata in function code, bind to an EventData object. You can also access the same properties by using binding expressions in the method signature. The following example shows both ways to get the same data:

[FunctionName("EventHubTriggerCSharp")]
public void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

To receive events in a batch, make string or EventData an array.

Note

When receiving in a batch you cannot bind to method parameters like in the above example with DateTime enqueuedTimeUtc and must receive these from each EventData object

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

Isolated process

The following example shows a C# function that is triggered based on an event hub, where the input message string is written to the logs:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/EventHubs/EventHubsFunction.cs" range="12-23":::

C# Script

The following example shows an Event Hubs trigger binding in a function.json file and a C# script function that uses the binding. The function logs the message body of the Event Hubs trigger.

The following examples show Event Hubs binding data in the function.json file for Functions runtime version 2.x and later versions.

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Here's the C# script code:

using System;

public static void Run(string myEventHubMessage, TraceWriter log)
{
    log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}

To get access to event metadata in function code, bind to an EventData object. You can also access the same properties by using binding expressions in the method signature. The following example shows both ways to get the same data:

#r "Microsoft.Azure.EventHubs"

using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;

public void Run(EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    TraceWriter log)
{
    log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");

    // Metadata accessed by using binding expressions
    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"SequenceNumber={sequenceNumber}");
    log.Info($"Offset={offset}");
}

To receive events in a batch, make string or EventData an array:

public static void Run(string[] eventHubMessages, TraceWriter log)
{
    foreach (var message in eventHubMessages)
    {
        log.Info($"C# function triggered to process a message: {message}");
    }
}

::: zone-end ::: zone pivot="programming-language-javascript"

The following example shows an Event Hubs trigger binding in a function.json file and a JavaScript function that uses the binding. The function reads event metadata and logs the message.

The following example shows an Event Hubs binding data in the function.json file, which is different for version 1.x of the Functions runtime compared to later versions.

Functions 2.x+

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Functions 1.x

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "path": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Here's the JavaScript code:

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

To receive events in a batch, set cardinality to many in the function.json file, as shown in the following examples.

Functions 2.x+

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Functions 1.x

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "path": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

Here's the JavaScript code:

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

::: zone-end
::: zone pivot="programming-language-powershell"

Complete PowerShell examples are pending. ::: zone-end ::: zone pivot="programming-language-python"

The following example shows an Event Hubs trigger binding in a function.json file and a Python function that uses the binding. The function reads event metadata and logs the message.

The following examples show Event Hubs binding data in the function.json file.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

Here's the Python code:

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

::: zone-end ::: zone pivot="programming-language-java"

The following example shows an Event Hubs trigger binding which logs the message body of the Event Hubs trigger.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

In the Java functions runtime library, use the EventHubTrigger annotation on parameters whose value comes from the event hub. Parameters with these annotations cause the function to run when an event arrives. This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

::: zone-end ::: zone pivot="programming-language-csharp"

Attributes

Both in-process and isolated process C# libraries use attribute to configure the trigger. C# script instead uses a function.json configuration file.

In-process

In C# class libraries, use the EventHubTriggerAttribute, which supports the following properties.

Parameters	Description
EventHubName	The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime. Can be referenced in app settings, like `%eventHubName%`
ConsumerGroup	An optional property that sets the consumer group used to subscribe to events in the hub. When omitted, the `$Default` consumer group is used.
Connection	The name of an app setting or setting collection that specifies how to connect to Event Hubs. To learn more, see Connections.

Isolated process

Use the EventHubTriggerAttribute to define a trigger on an event hub, which supports the following properties.

Parameters	Description
EventHubName	The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime. Can be referenced in app settings, like `%eventHubName%`
ConsumerGroup	An optional property that sets the consumer group used to subscribe to events in the hub. When omitted, the `$Default` consumer group is used.
Connection	The name of an app setting or setting collection that specifies how to connect to Event Hubs. To learn more, see Connections.

C# Script

function.json property	Description
type	Must be set to `eventHubTrigger`. This property is set automatically when you create the trigger in the Azure portal.
direction	Must be set to `in`. This property is set automatically when you create the trigger in the Azure portal.
name	The name of the variable that represents the event item in function code.
eventHubName	Functions 2.x and higher. The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime. Can be referenced via app settings `%eventHubName%`. In version 1.x, this property is named `path`.
consumerGroup	An optional property that sets the consumer group used to subscribe to events in the hub. If omitted, the `$Default` consumer group is used.
connection	The name of an app setting or setting collection that specifies how to connect to Event Hubs. See Connections.

::: zone-end
::: zone pivot="programming-language-java"

Annotations

In the Java functions runtime library, use the EventHubTrigger annotation, which supports the following settings:

name
dataType
eventHubName
connection
cardinality
consumerGroup

::: zone-end ::: zone pivot="programming-language-javascript,programming-language-python,programming-language-powershell"

Configuration

The following table explains the trigger configuration properties that you set in the function.json file, which differs by runtime version.

Functions 2.x+

function.json property	Description
type	Must be set to `eventHubTrigger`. This property is set automatically when you create the trigger in the Azure portal.
direction	Must be set to `in`. This property is set automatically when you create the trigger in the Azure portal.
name	The name of the variable that represents the event item in function code.
eventHubName	The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime. Can be referenced via app settings `%eventHubName%`
consumerGroup	An optional property that sets the consumer group used to subscribe to events in the hub. If omitted, the `$Default` consumer group is used.
cardinality	Set to `many` in order to enable batching. If omitted or set to `one`, a single message is passed to the function.
connection	The name of an app setting or setting collection that specifies how to connect to Event Hubs. See Connections.

Functions 1.x

function.json property	Description
type	Must be set to `eventHubTrigger`. This property is set automatically when you create the trigger in the Azure portal.
direction	Must be set to `in`. This property is set automatically when you create the trigger in the Azure portal.
name	The name of the variable that represents the event item in function code.
path	The name of the event hub. When the event hub name is also present in the connection string, that value overrides this property at runtime.
consumerGroup	An optional property that sets the consumer group used to subscribe to events in the hub. If omitted, the `$Default` consumer group is used.
cardinality	Set to `many` in order to enable batching. If omitted or set to `one`, a single message is passed to the function.
connection	The name of an app setting or setting collection that specifies how to connect to Event Hubs. See Connections.

::: zone-end

[!INCLUDE app settings to local.settings.json]

Usage

To learn more about how Event Hubs trigger and IoT Hub trigger scales, see Event Hubs trigger.

::: zone pivot="programming-language-csharp"
The parameter type supported by the Event Hubs output binding depends on the Functions runtime version, the extension package version, and the C# modality used.

Extension v5.x+

In-process C# class library functions supports the following types:

Azure.Messaging.EventHubs.EventData
String
Byte array
Plain-old CLR object (POCO)

This version of EventData drops support for the legacy Body type in favor of EventBody.

Extension v3.x+

In-process C# class library functions supports the following types:

Microsoft.Azure.EventHubs.EventData
String
Byte array
Plain-old CLR object (POCO)

Extension v5.x+

Requires you to define a custom type, or use a string.

Extension v3.x+

Requires you to define a custom type, or use a string.

Extension v5.x+

C# script functions support the following types:

Azure.Messaging.EventHubs.EventData
String
Byte array
Plain-old CLR object (POCO)

This version of EventData drops support for the legacy Body type in favor of EventBody.

Extension v3.x+

C# script functions support the following types:

Microsoft.Azure.EventHubs.EventData
String
Byte array
Plain-old CLR object (POCO)

::: zone-end ::: zone pivot="programming-language-java"
The parameter type can be one of the following:

Any native Java types such as int, String, byte[].
Nullable values using Optional.
Any POJO type.

To learn more, see the EventHubTrigger reference.

::: zone-end

Event metadata

The Event Hubs trigger provides several metadata properties. Metadata properties can be used as part of binding expressions in other bindings or as parameters in your code. The properties come from the EventData class.

Property	Type	Description
`PartitionContext`	PartitionContext	The `PartitionContext` instance.
`EnqueuedTimeUtc`	`DateTime`	The enqueued time in UTC.
`Offset`	`string`	The offset of the data relative to the event hub partition stream. The offset is a marker or identifier for an event within the Event Hubs stream. The identifier is unique within a partition of the Event Hubs stream.
`PartitionKey`	`string`	The partition to which event data should be sent.
`Properties`	`IDictionary<String,Object>`	The user properties of the event data.
`SequenceNumber`	`Int64`	The logical sequence number of the event.
`SystemProperties`	`IDictionary<String,Object>`	The system properties, including the event data.

See code examples that use these properties earlier in this article.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

functions-bindings-event-hubs-trigger.md

functions-bindings-event-hubs-trigger.md

Example

In-process

Isolated process

C# Script

Functions 2.x+

Functions 1.x

Functions 2.x+

Functions 1.x

Attributes

In-process

Isolated process

C# Script

Annotations

Configuration

Functions 2.x+

Functions 1.x

Usage

Extension v5.x+

Extension v3.x+

Extension v5.x+

Extension v3.x+

Extension v5.x+

Extension v3.x+

Event metadata

Files

functions-bindings-event-hubs-trigger.md

Latest commit

History

functions-bindings-event-hubs-trigger.md

File metadata and controls

Example

Attributes

Annotations

Configuration

Usage

Event metadata