Muokkaa

Jaa

Azure Service Bus bindings for Azure Functions

  • Artikkeli

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

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.

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:

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 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.
ServiceBusReceivedMessage1 The message object.

When binding to ServiceBusReceivedMessage, you can optionally also include a parameter of type ServiceBusMessageActions1,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 ServiceBusMessageActions1,2 to perform message settlement actions.

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

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

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.
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 is used only when the isSessionsEnabled property or attribute on the trigger is set to false. 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 is used only when the isSessionsEnabled property or attribute on the trigger is set to true. 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.
minMessageBatchSize1 1 The minimum number of messages desired in a batch. The minimum applies only when the function is receiving multiple messages and must be less than maxMessageBatchSize.
The minimum size isn't strictly guaranteed. A partial batch is dispatched when a full batch can't be prepared before the maxBatchWaitTime has elapsed.
maxBatchWaitTime1 00:00:30 The maximum interval that the trigger should wait to fill a batch before invoking the function. The wait time is only considered when minMessageBatchSize is larger than 1 and is ignored otherwise. If less than minMessageBatchSize messages were available before the wait time elapses, the function is invoked with a partial batch. The longest allowed wait time is 50% of the entity message lock duration, meaning the maximum allowed is 2 minutes and 30 seconds. Otherwise, you may get lock exceptions.

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.
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 session will be closed and the function will attempt to process another session.
enableCrossEntityTransactions false Whether or not to enable transactions that span multiple entities on a Service Bus namespace.

1 Using minMessageBatchSize and maxBatchWaitTime requires v5.10.0 of the Microsoft.Azure.WebJobs.Extensions.ServiceBus package, or a later version.

Next steps