Azure Service Bus bindings for Azure Functions

2025-08-18

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:

Isolated worker model
In-process model

Functions execute in an isolated C# worker process. To learn more, see Guide for running C# Azure Functions in an isolated worker process.

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

Install bundle

To be able to use this binding extension in your app, make sure that the host.json file in the root of your project contains this extensionBundle reference:

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

In this example, the version value of [4.0.0, 5.0.0) instructs the Functions host to use a bundle version that is at least 4.0.0 but less than 5.0.0, which includes all potential versions of 4.x. This notation effectively maintains your app on the latest available minor version of the v4.x extension bundle.

When possible, you should use the latest extension bundle major version and allow the runtime to automatically maintain the latest minor version. You can view the contents of the latest bundle on the extension bundles release page. For more information, see Azure Functions extension bundles.

Binding types

The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following:

Isolated worker model
In-process class library

An isolated worker process class library compiled C# function runs in a process isolated from the runtime.

Choose a version to see binding type details for the mode and version.

The Service Bus extension supports parameter types according to the table below.

Binding scenario	Parameter types
Service Bus trigger (single message)	ServiceBusReceivedMessage `string` `byte[]` JSON serializable types¹
Service Bus trigger (message batch)	`ServiceBusReceivedMessage[]` `string[]`
Service Bus trigger advanced scenarios²	ServiceBusClient ServiceBusMessageActions ServiceBusSessionMessageActions ServiceBusReceiveActions
Service Bus output (single message)	ServiceBusMessage `string` `byte[]` JSON serializable types¹
Service Bus output (multiple messages)	`ICollector<T>` or `IAsyncCollector<T>` where `T` is one of the single message types ServiceBusSender

¹ Messages containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

² Advanced scenarios include message settlement, sessions, and transactions. These types are available as separate parameters in addition to the normal trigger parameter.

Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.ServiceBus namespace. Newer types from Azure.Messaging.ServiceBus are exclusive to Extension 5.x+.

On 30 September 2026, we'll retire the Azure Service Bus SDK libraries WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus, and com.microsoft.azure.servicebus, which don't conform to Azure SDK guidelines. We'll also end support of the SBMP protocol, so you'll no longer be able to use this protocol after 30 September 2026. Migrate to the latest Azure SDK libraries, which offer critical security updates and improved capabilities, before that date.

Although the older libraries can still be used beyond 30 September 2026, they'll no longer receive official support and updates from Microsoft. For more information, see the support retirement announcement.

This version of the extension supports parameter types according to the table below.

The Service Bus extension supports parameter types according to the table below.

Binding scenario	Parameter types
Service Bus trigger (single message)	[Microsoft.Azure.ServiceBus.Message] `string` `byte[]` JSON serializable types¹
Service Bus trigger (message batch)	`ServiceBusReceivedMessage[]` `string[]`
Service Bus trigger advanced scenarios²	IMessageReceiver MessageReceiver IMessageSession
Service Bus output (single message)	Message `string` `byte[]` JSON serializable types¹
Service Bus output (multiple messages)	`ICollector<T>` or `IAsyncCollector<T>` where `T` is one of the single message types MessageSender

¹ Messages containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

² Advanced scenarios include message settlement, sessions, and transactions. These types are available as separate parameters in addition to the normal trigger parameter.

The isolated worker process supports parameter types according to the tables below.

Service Bus trigger

When you want the function to process a single message, the Service Bus trigger can bind to the following types:

Type	Description
`string`	The message as a string. Use when the message is simple text.
`byte[]`	The bytes of the message.
JSON serializable types	When an event contains JSON data, Functions tries to deserialize the JSON data into a plain-old CLR object (POCO) type.
ServiceBusReceivedMessage¹	The message object. When binding to `ServiceBusReceivedMessage`, you can optionally also include a parameter of type ServiceBusMessageActions^1,2 to perform message settlement actions.

When you want the function to process a batch of messages, the Service Bus trigger can bind to the following types:

Type	Description
`T[]` where `T` is one of the single message types	An array of events from the batch. Each entry represents one event. When binding to `ServiceBusReceivedMessage[]`, you can optionally also include a parameter of type ServiceBusMessageActions^1,2 to perform message settlement actions.

¹ To use these types, you need to reference Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 or later and the common dependencies for SDK type bindings.

² When using ServiceBusMessageActions, set the AutoCompleteMessages property of the trigger attribute to false. This prevents the runtime from attempting to complete messages after a successful function invocation.

Service Bus output binding

When you want the function to write a single message, the Service Bus output binding can bind to the following types:

Type	Description
`string`	The message as a string. Use when the message is simple text.
`byte[]`	The bytes of the message.
JSON serializable types	An object representing the message. Functions attempts to serialize a plain-old CLR object (POCO) type into JSON data.

When you want the function to write multiple messages, the Service Bus output binding can bind to the following types:

Type	Description
`T[]` where `T` is one of the single message types	An array containing multiple message. Each entry represents one message.

For other output scenarios, create and use a ServiceBusClient with other types from Azure.Messaging.ServiceBus directly. See Register Azure clients for an example of using dependency injection to create a client type from the Azure SDK.

SDK Binding Types

SDK Types for Azure Service Bus are in Preview. Follow the Python SDK Bindings for Service Bus Sample to get started with SDK Types for Service Bus in Python.

Important

Using SDK type bindings requires the Python v2 programming model.

Binding	Parameter types	Samples
ServiceBus trigger	ServiceBusReceivedMessage	`ServiceBusReceivedMessage`

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,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

The clientRetryOptions settings only apply to interactions with the Service Bus service. They don't affect retries of function executions. For more information, see Retries.

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.
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 and doesn't apply to functions receiving a batch of messages. For batches, the maximum duration is set in Service Bus at the queue or subscription level.
maxConcurrentCalls	`16`	By default, the Functions runtime processes multiple messages concurrently. This setting limits the maximum number of concurrent calls to the callback that can be initiated per-scaled-instance. When your hosting plan has more than one core per instance, the maximum nu