Azure Service Bus bindings for Azure Functions

Azure Functions integrates with Azure Service Bus via triggers and bindings. Integrating with Service Bus allows you to build functions that react to and send queue or topic messages.

Action Type
Run a function when a Service Bus queue or topic message is created Trigger
Send Azure Service Bus messages Output binding

Install extension

The extension NuGet package you install depends on the C# mode you're using in your function app:

Functions execute in the same process as the Functions host. To learn more, see Develop C# class library functions using Azure Functions.

Add the extension to your project installing this NuGet package.

The functionality of the extension varies depending on the extension version:

This version 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.

This version allows you to bind to types from Azure.Messaging.ServiceBus.

This extension version is available by installing the NuGet package, version 5.x or later.

Install bundle

The Service Bus binding is part of an extension bundle, which is specified in your host.json project file. You may need to modify this bundle to change the version of the binding, or if bundles aren't already installed. To learn more, see extension bundle.

This version 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.

You can add this version of the extension from the extension bundle v3 by adding or replacing the following code 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.

host.json settings

This section describes the configuration settings available for this binding, which depends on the runtime and extension version.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

When you set the isSessionsEnabled property or attribute on the trigger to true, the sessionHandlerOptions is honored. When you set the isSessionsEnabled property or attribute on the trigger to false, the messageHandlerOptions is honored.

Property Default Description
mode Exponential The approach to use for calculating retry delays. The default exponential mode retries attempts with a delay based on a back-off strategy where each attempt increases the wait duration before retrying. The Fixed mode retries attempts at fixed intervals with each delay having a consistent duration.
tryTimeout 00:01:00 The maximum duration to wait for an operation per attempt.
delay 00:00:00.80 The delay or back-off factor to apply between retry attempts.
maxDelay 00:01:00 The maximum delay to allow between retry attempts
maxRetries 3 The maximum number of retry attempts before considering the associated operation to have failed.
prefetchCount 0 Gets or sets the number of messages that the message receiver can simultaneously request.
transportType amqpTcp The protocol and transport that is used for communicating with Service Bus. Available options: amqpTcp, amqpWebSockets
webProxy n/a The proxy to use for communicating with Service Bus over web sockets. A proxy cannot be used with the amqpTcp transport.
autoCompleteMessages true Determines whether or not to automatically complete messages after successful execution of the function and should be used in place of the autoComplete configuration setting.
maxAutoLockRenewalDuration 00:05:00 The maximum duration within which the message lock will be renewed automatically. This setting only applies for functions that receive a single message at a time.
maxConcurrentCalls 16 The maximum number of concurrent calls to the callback that should be initiated per scaled instance. By default, the Functions runtime processes multiple messages concurrently. This setting only applies for functions that receive a single message at a time.
maxConcurrentSessions 8 The maximum number of sessions that can be handled concurrently per scaled instance. This setting only applies for functions that receive a single message at a time.
maxMessageBatchSize 1000 The maximum number of messages that will be passed to each function call. This setting only applies for functions that receive a batch of messages.
sessionIdleTimeout n/a The maximum amount of time to wait for a message to be received for the currently active session. After this time has elapsed, the processor will close the session and attempt to process another session. This setting only applies for functions that receive a single message at a time.
enableCrossEntityTransactions false Whether or not to enable transactions that span multiple entities on a Service Bus namespace.

Next steps