| ms.service | azure-functions | |
|---|---|---|
| ms.topic | include | |
| ms.date | 02/21/2020 | |
| author | v1212 | |
| ms.author | wujia | |
| ms.custom |
|
::: zone pivot="programming-language-csharp"
The extension NuGet package you install depends on the C# mode you're using in your function app:
Functions execute in an isolated C# worker process. To learn more, see Guide for running C# Azure Functions in an isolated worker process.
[!INCLUDE functions-in-process-model-retirement-note]
Functions execute in the same process as the Functions host. To learn more, see Develop C# class library functions using Azure Functions.
In a variation of this model, Functions can be run using C# scripting, which is supported primarily for C# portal editing. To update existing binding extensions for C# script apps running in the portal without having to republish your function app, see Update your extensions.
The functionality of the extension varies depending on the extension version:
This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 4.x.
[!INCLUDE functions-bindings-supports-identity-connections-note]
This version uses the newer Event Hubs binding type Azure.Messaging.EventHubs.EventData.
This extension version is available by installing the NuGet package, version 6.x.
This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 3.x or later.
[!INCLUDE functions-bindings-supports-identity-connections-note]
This version uses the newer Event Hubs binding type Azure.Messaging.EventHubs.EventData.
This extension version is available by installing the NuGet package, version 5.x.
This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 2.x.
Supports the original Event Hubs binding parameter type of Microsoft.Azure.EventHubs.EventData.
Add the extension to your project by installing the NuGet package, version 3.x or 4.x.
[!INCLUDE functions-runtime-1x-retirement-note]
Version 1.x of the Functions runtime doesn't require an extension.
[!INCLUDE functions-bindings-supports-identity-connections-note]
This version supports configuration of triggers and bindings through .NET Aspire integration.
Add the extension to your project by installing the NuGet package, version 6.x.
[!INCLUDE functions-bindings-supports-identity-connections-note]
This version supports configuration of triggers and bindings through .NET Aspire integration.
Add the extension to your project by installing the NuGet package, version 5.x.
Add the extension to your project by installing the NuGet package, version 4.x.
Version 1.x of the Functions runtime doesn't support running in an isolated worker process.
::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-python,programming-language-java,programming-language-powershell"
[!INCLUDE functions-install-extension-bundle]
::: zone-end
::: zone pivot="programming-language-csharp"
The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following options:
An isolated worker process class library compiled C# function runs in a process isolated from the runtime.
An in-process class library is a compiled C# function runs in the same process as the Functions runtime.
Choose a version to see binding type details for the mode and version.
[!INCLUDE functions-event-hubs-extensionv5-inproc]
[!INCLUDE functions-event-hubs-extensionv5-inproc]
Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.EventHubs namespace. Newer types from Azure.Messaging.EventHubs are exclusive to Extension v5.x+.
This version of the extension supports parameter types according to the table below.
| Binding scenario | Parameter types |
|---|---|
| Event Hubs trigger (single message) | Microsoft.Azure.EventHubs.EventData JSON serializable types1 stringbyte[] |
| Event Hubs trigger (batch) | EventData[]string[] |
| Event Hubs output | Microsoft.Azure.EventHubs.EventData JSON serializable types1 stringbyte[] |
1 Events containing JSON data can be deserialized into known plain-old CLR object (POCO) types.
Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.EventHubs namespace. Newer types from Azure.Messaging.EventHubs are exclusive to Extension v5.x+.
This version of the extension supports parameter types according to the table below.
| Binding scenario | Parameter types |
|---|---|
| Event Hubs trigger (single event) | Microsoft.Azure.EventHubs.EventData JSON serializable types1 stringbyte[] |
| Event Hubs trigger (batch of events) | EventData[]string[] |
| Event Hubs output | Microsoft.Azure.EventHubs.EventData JSON serializable types1 stringbyte[] |
1 Events containing JSON data can be deserialized into known plain-old CLR object (POCO) types.
[!INCLUDE functions-event-hubs-extensionv5-isolated]
[!INCLUDE functions-event-hubs-extensionv5-isolated]
Earlier versions of the extension in the isolated worker process only support binding to strings and JSON serializable types. More options are available to Extension v5.x+.
Functions version 1.x doesn't support the isolated worker process. To use the isolated worker model, upgrade your application to Functions 4.x.
::: zone-end
::: zone pivot="programming-language-python"
SDK Types for Azure EventHub are in Preview. Follow the Python SDK Bindings for EventHub Sample to get started with SDK Types for Event Hubs in Python.
Important
Using SDK type bindings requires the Python v2 programming model.
| Binding | Parameter types | Samples |
|---|---|---|
| EventHub trigger | EventData | EventData |
:::zone-end
The host.json file contains settings that control behavior for the Event Hubs trigger. The configuration is different depending on the extension version.
{
"version": "2.0",
"extensions": {
"eventHubs": {
"maxEventBatchSize" : 100,
"minEventBatchSize" : 25,
"maxWaitTime" : "00:05:00",
"batchCheckpointFrequency" : 1,
"prefetchCount" : 300,
"transportType" : "amqpWebSockets",
"webProxy" : "https://proxyserver:8080",
"customEndpointAddress" : "amqps://company.gateway.local",
"targetUnprocessedEventThreshold" : 75,
"initialOffsetOptions" : {
"type" : "fromStart",
"enqueuedTimeUtc" : ""
},
"clientRetryOptions":{
"mode" : "exponential",
"tryTimeout" : "00:01:00",
"delay" : "00:00:00.80",
"maximumDelay" : "00:01:00",
"maximumRetries" : 3
}
}
}
} | Property | Default | Description |
|---|---|---|
| maxEventBatchSize2 | 100 | The maximum number of events included in a batch for a single invocation. Must be at least 1. |
| minEventBatchSize1 | 1 | The minimum number of events desired in a batch. The minimum applies only when the function is receiving multiple events and must be less than maxEventBatchSize.The minimum size isn't strictly guaranteed. A partial batch is dispatched when a full batch can't be prepared before the maxWaitTime has elapsed. Partial batches are also likely for the first invocation of the function after scaling takes place. |
| maxWaitTime1 | 00:01:00 | The maximum interval that the trigger should wait to fill a batch before invoking the function. The wait time is only considered when minEventBatchSize is larger than 1 and is otherwise ignored. If less than minEventBatchSize events were available before the wait time elapses, the function is invoked with a partial batch. The longest allowed wait time is 10 minutes.NOTE: This interval is not a strict guarantee for the exact timing on which the function is invoked. There is a small margin of error due to timer precision. When scaling takes place, the first invocation with a partial batch may occur more quickly or may take up to twice the configured wait time. |
| batchCheckpointFrequency | 1 | The number of batches to process before creating a checkpoint for the event hub. NOTE: Setting this value above 1 for hosting plans supported by target based scaling can cause incorrect scaling behavior. The platform calculates unprocessed queue size as "current position - checkpointed position", which may incorrectly indicate unprocessed messages when batches have been processed but not yet checkpointed, preventing proper scale-in when no messages remain. |
| prefetchCount | 300 | The number of events that is eagerly requested from Event Hubs and held in a local cache to allow reads to avoid waiting on a network operation |
| transportType | amqpTcp | The protocol and transport that is used for communicating with Event Hubs. Available options: amqpTcp, amqpWebSockets |
| webProxy | null | The proxy to use for communicating with Event Hubs over web sockets. A proxy cannot be used with the amqpTcp transport. |
| customEndpointAddress | null | The address to use when establishing a connection to Event Hubs, allowing network requests to be routed through an application gateway or other path needed for the host environment. The fully qualified namespace for the event hub is still needed when a custom endpoint address is used, and it must be specified explicitly or via the connection string. |
| targetUnprocessedEventThreshold1 | null | The desired number of unprocessed events per function instance. The threshold is used in target-based scaling to override the default scaling threshold inferred from the maxEventBatchSize option. When set, the total unprocessed event count is divided by this value to determine the number of function instances needed. The instance count is rounded up to a number that creates a balanced partition distribution. |
| initialOffsetOptions/type | fromStart | The location in the event stream to start processing when a checkpoint does not exist in storage. Applies to all partitions. For more information, see the OffsetType documentation. Available options: fromStart, fromEnd, fromEnqueuedTime |
| initialOffsetOptions/enqueuedTimeUtc | null | 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. |
| clientRetryOptions/mode | exponential | The approach to use for calculating retry delays. Exponential mode retries attempts with a delay based on a back-off strategy where each attempt will increase the duration that it waits before retrying. The fixed mode retries attempts at fixed intervals with each delay having a consistent duration. Available options: exponential, fixed |
| clientRetryOptions/tryTimeout | 00:01:00 | The maximum duration to wait for an Event Hubs operation to complete, per attempt. |
| clientRetryOptions/delay | 00:00:00.80 | The delay or back-off factor to apply between retry attempts. |
| clientRetryOptions/maximumDelay | 00:00:01 | The maximum delay to allow between retry attempts. |
| clientRetryOptions/maximumRetries | 3 | The maximum number of retry attempts before considering the associated operation to have failed. |
1 Using minEventBatchSize and maxWaitTime requires v5.3.0 of the Microsoft.Azure.WebJobs.Extensions.EventHubs package, or a later version.
2 The default maxEventBatchSize changed in v6.0.0 of the Microsoft.Azure.WebJobs.Extensions.EventHubs package. In earlier versions, this was 10.
The clientRetryOptions are used to retry operations between the Functions host and Event Hubs (such as fetching events and sending events). Refer to guidance on Azure Functions error handling and retries for information on applying retry policies to individual functions.
For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.
{
"version": "2.0",
"extensions": {
"eventHubs": {
"batchCheckpointFrequency": 1,
"eventProcessorOptions": {
"maxBatchSize": 256,
"prefetchCount": 512
},
"initialOffsetOptions": {
"type": "fromStart",
"enqueuedTimeUtc": ""
}
}
}
} | Property | Default | Description |
|---|---|---|
| batchCheckpointFrequency | 1 | The number of event batches to process before creating an Event Hubs cursor checkpoint. NOTE: Setting this value above 1 for hosting plans supported by target based scaling can cause incorrect scaling behavior. The platform calculates unprocessed queue size as "current position - checkpointed position", which may incorrectly indicate unprocessed messages when batches have been processed but not yet checkpointed, preventing proper scale-in when no messages remain. |
| eventProcessorOptions/maxBatchSize | 10 | The maximum event count received per receive loop. |
| eventProcessorOptions/prefetchCount | 300 | The default prefetch 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 | null | 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.
For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.
{
"eventHub": {
"maxBatchSize": 64,
"prefetchCount": 256,
"batchCheckpointFrequency": 1
}
}| Property | Default | Description |
|---|---|---|
| maxBatchSize | 64 | The maximum event count received per receive loop. |
| prefetchCount | 300 | The default prefetch that will be used by the underlying EventProcessorHost. |
| batchCheckpointFrequency | 1 | The number of event batches to process before creating an Event Hubs cursor checkpoint. NOTE: Setting this value above 1 for hosting plans supported by target based scaling can cause incorrect scaling behavior. The platform calculates unprocessed queue size as "current position - checkpointed position", which may incorrectly indicate unprocessed messages when batches have been processed but not yet checkpointed, preventing proper scale-in when no messages remain. |
For a reference of host.json in Azure Functions 1.x, see host.json reference for Azure Functions 1.x.