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

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 4.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.

Service Bus extension 5.x and higher

A new version of the Service Bus bindings extension is available in preview. It introduces the ability to connect using an identity instead of a secret. For .NET applications, it also changes the types that you can bind to, replacing the types from Microsoft.ServiceBus.Messaging and Microsoft.Azure.ServiceBus with newer types from Azure.Messaging.ServiceBus.

This extension version is available as a preview NuGet package or can be added from the preview extension bundle v3 by adding the following in your host.json file:

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

To learn more, see Update your extensions.

Functions 1.x

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

host.json settings

This section describes the configuration settings available for this binding in versions 2.x and higher. Settings in the host.json file apply to all functions in a function app instance. The example host.json file below contains only the version 2.x+ settings for this binding. For more information about function app configuration settings in versions 2.x and later versions, see host.json reference for Azure Functions.

Note

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

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": true,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:05:00"
            },
            "sessionHandlerOptions": {
                "autoComplete": false,
                "messageWaitTimeout": "00:00:30",
                "maxAutoRenewDuration": "00:55:00",
                "maxConcurrentSessions": 16
            },
            "batchOptions": {
                "maxMessageCount": 1000,
                "operationTimeout": "00:01:00",
                "autoComplete": true
            }
        }
    }
}

If you have isSessionsEnabled set to true, the sessionHandlerOptions is honored. If you have isSessionsEnabled set to false, the messageHandlerOptions is honored.

Property Default Description
prefetchCount 0 Gets or sets the number of messages that the message receiver can simultaneously request.
messageHandlerOptions.maxAutoRenewDuration 00:05:00 The maximum duration within which the message lock will be renewed automatically.
messageHandlerOptions.autoComplete true Whether the trigger should automatically call complete after processing, or if the function code will manually call complete.

Setting to false is only supported in C#.

If set to true, the trigger completes the message automatically if the function execution completes successfully, and abandons the message otherwise.

When set to false, you are responsible for calling MessageReceiver methods to complete, abandon, or deadletter the message. If an exception is thrown (and none of the MessageReceiver methods are called), then the lock remains. Once the lock expires, the message is re-queued with the DeliveryCount incremented and the lock is automatically renewed.

In non-C# functions, exceptions in the function results in the runtime calls abandonAsync in the background. If no exception occurs, then completeAsync is called in the background.
messageHandlerOptions.maxConcurrentCalls 16 The maximum number of concurrent calls to the callback that the message pump should initiate per scaled instance. By default, the Functions runtime processes multiple messages concurrently.
sessionHandlerOptions.maxConcurrentSessions 2000 The maximum number of sessions that can be handled concurrently per scaled instance.
batchOptions.maxMessageCount 1000 The maximum number of messages sent to the function when triggered.
batchOptions.operationTimeout 00:01:00 A time span value expressed in hh:mm:ss.
batchOptions.autoComplete true See the above description for messageHandlerOptions.autoComplete.

Additional settings for version 5.x+

The example host.json file below contains only the settings for version 5.0.0 and higher of the Service Bus extension.

{
    "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,
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessages": 1000,
            "sessionIdleTimeout": "00:01:00"
        }
    }
}

When using service bus extension version 5.x and higher, the following global configuration settings are supported in addition to the 2.x settings in ServiceBusOptions.

Property Default Description
prefetchCount 0 Gets or sets the number of messages that the message receiver can simultaneously request.
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 This should be used in place of maxAutoRenewDuration
maxConcurrentCalls 16 The maximum number of concurrent calls to the callback that the message pump should initiate per scaled instance. By default, the Functions runtime processes multiple messages concurrently.
maxConcurrentSessions 8 The maximum number of sessions that can be handled concurrently per scaled instance.
maxMessages 1000 The maximum number of messages that will be passed to each function call. This 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.

Retry settings

In addition to the above configuration properties when using version 5.x and higher of the service bus extension, you can also configure RetryOptions from within the ServiceBusOptions. These settings determine whether a failed operation should be retried, and, if so, the amount of time to wait between retry attempts. The options also control the amount of time allowed for receiving messages and other interactions with the Service Bus service.

Property Default Description
mode Exponential The approach to use for calculating retry delays. The default exponential mode will retry 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 will retry 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.

Next steps