Azure IoT Hub bindings for Azure Functions

This set of articles explains how to work with Azure Functions bindings for IoT Hub. The IoT Hub support is based on the Azure Event Hubs Binding.

Important

While the following code samples use the Event Hub API, the given syntax is applicable for IoT Hub functions.

Action Type
Respond to events sent to an IoT hub event stream. Trigger
Write events to an IoT event stream Output binding

Add to your Functions app

Functions 2.x and higher

Working with the trigger and bindings requires that you reference the appropriate package. The NuGet package is used for .NET class libraries while the extension bundle is used for all other application types.

Language Add by... Remarks
C# Installing the NuGet package, version 3.x
C# Script, Java, JavaScript, Python, PowerShell Registering the extension bundle The Azure Tools extension is recommended to use with Visual Studio Code.
C# Script (online-only in Azure portal) Adding a binding To update existing binding extensions without having to republish your function app, see Update your extensions.

Event Hubs extension 5.x and higher

A new version of the Event Hubs bindings extension is available now available. It introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial. For .NET applications, it also changes the types that you can bind to, replacing the types from Microsoft.Azure.EventHubs with newer types from Azure.Messaging.EventHubs.

This extension version is available by installing the NuGet package, version 5.x, or it can be added from the extension bundle v3 by adding the following in your host.json file:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.3.0, 4.0.0)"
  }
}

To learn more, see Update your extensions.

Functions 1.x

Functions 1.x apps automatically have a reference the Microsoft.Azure.WebJobs NuGet package, version 2.x.

host.json settings

The host.json file contains settings that control behavior for the Event Hubs trigger. The configuration is different depending on the Azure Functions version.

Functions 2.x and higher

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            },
            "initialOffsetOptions": {
                "type": "fromStart",
                "enqueuedTimeUtc": ""
            }
        }
    }
}  
Property Default Description
batchCheckpointFrequency 1 The number of event batches to process before creating an EventHub cursor checkpoint.
eventProcessorOptions/maxBatchSize 10 The maximum event count received per receive loop.
eventProcessorOptions/prefetchCount 300 The default pre-fetch count used by the underlying EventProcessorHost. The minimum allowed value is 10.
initialOffsetOptions/type1 fromStart The location in the event stream from which to start processing when a checkpoint doesn't exist in storage. Options are fromStart , fromEnd or fromEnqueuedTime. fromEnd processes new events that were enqueued after the function app started running. Applies to all partitions. For more information, see the EventProcessorOptions documentation.
initialOffsetOptions/enqueuedTimeUtc1 N/A Specifies the enqueued time of the event in the stream from which to start processing. When initialOffsetOptions/type is configured as fromEnqueuedTime, this setting is mandatory. Supports time in any format supported by DateTime.Parse(), such as 2020-10-26T20:31Z. For clarity, you should also specify a timezone. When timezone isn't specified, Functions assumes the local timezone of the machine running the function app, which is UTC when running on Azure. For more information, see the EventProcessorOptions documentation.

1 Support for initialOffsetOptions begins with EventHubs v4.2.0.

Note

For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.

Functions 1.x

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
Property Default Description
maxBatchSize 64 The maximum event count received per receive loop.
prefetchCount n/a The default pre-fetch that will be used by the underlying EventProcessorHost.
batchCheckpointFrequency 1 The number of event batches to process before creating an EventHub cursor checkpoint.

Note

For a reference of host.json in Azure Functions 1.x, see host.json reference for Azure Functions 1.x.

Next steps