Azure Functions Bindings

Service Bus Triggers

Service Bus triggers are used to create Azure Functions that execute in response to messages being added to a Service Bus queue or topic.

Overview

The Service Bus trigger for Azure Functions allows your functions to react to incoming messages from Azure Service Bus queues and topics. This is a fundamental building block for creating event-driven, decoupled, and scalable applications. When a message arrives in the configured Service Bus entity, the trigger activates your function, providing the message content as input.

Trigger Types

Service Bus triggers can be configured for both:

  • Queues: A one-to-one communication mechanism.
  • Topics: A one-to-many communication mechanism where messages are delivered to multiple subscriptions.

Configuration

The Service Bus trigger is configured in the function.json file for your function. The primary configuration options include:

Property Description Required
type Must be set to serviceBusTrigger. Yes
direction Must be set to in. Yes
name The name of the parameter in your function code that will receive the Service Bus message. Yes
queueName The name of the Service Bus queue to listen to. Use either queueName or topicName and subscriptionName.
topicName The name of the Service Bus topic to listen to. Use either queueName or topicName and subscriptionName.
subscriptionName The name of the Service Bus topic subscription to listen to. Required if topicName is used.
connection The name of the application setting that contains the Service Bus connection string. Defaults to ServiceBusConnection. No
isSessionsEnabled Set to true if the queue or topic is session-enabled. Defaults to false. No
autoDeleteOnIdle The duration after which the subscription is automatically deleted when there are no active operations. Defaults to never auto-delete. No
maxConcurrentCalls The maximum number of concurrent calls to the function. Defaults to 16. No

Example function.json for a Queue Trigger

{
  "bindings": [
    {
      "name": "message",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "my-queue",
      "connection": "ServiceBusConnection"
    }
  ]
}

Example function.json for a Topic Trigger

{
  "bindings": [
    {
      "name": "message",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "my-topic",
      "subscriptionName": "my-subscription",
      "connection": "ServiceBusConnection"
    }
  ]
}

Function Code Examples

C#

using System;
using Azure.Messaging.ServiceBus;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

public static class ServiceBusQueueTrigger
{
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("my-queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message,
        ILogger log)
    {
        log.LogInformation($"C# ServiceBus queue trigger function processed message: {message.Body}");
        log.LogInformation($"Message ID: {message.MessageId}");
    }
}

JavaScript (Node.js)

module.exports = async function (context, message) {
    context.log('JavaScript ServiceBus queue trigger function processed message: ', message.body);
    context.log('Message ID: ', message.messageId);
};

Python

import logging
import azure.functions as func

def main(message: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger function processed message: %s',
                 message.get_body().decode('utf-8'))
    logging.info('Message ID: %s', message.message_id)

Message Handling

The trigger passes the Service Bus message to your function. The type of the message object depends on the language you are using:

  • C#: Azure.Messaging.ServiceBus.ServiceBusReceivedMessage
  • JavaScript: An object with properties like body, messageId, etc.
  • Python: azure.functions.ServiceBusMessage

You can access the message body, properties, and metadata through these objects.

Advanced Features

Session Support

If your Service Bus queue or topic is session-enabled, you can configure your function to process messages in session order by setting isSessionsEnabled to true in function.json. Your function will then receive a ServiceBusSessionMessage (in C#) or equivalent object that allows you to manage sessions.

Error Handling and Dead-Lettering

When your function encounters an unrecoverable error processing a message, the trigger can automatically move the message to the Service Bus dead-letter queue. This is crucial for troubleshooting and ensuring no messages are lost. Unhandled exceptions in your function typically result in the message being abandoned or completed based on retry policies.

Note: For robust error handling, consider using output bindings to explicitly send messages to a dead-letter queue or implementing custom retry logic within your function.

Message Completion and Abandonment

By default, when your function completes successfully, the Service Bus trigger will complete the message on the Service Bus. If your function throws an exception, the message will be abandoned and will become available for redelivery after a lock duration expires. You can also explicitly control message completion and abandonment using the received message object in your code.

Concurrency and Scaling

The maxConcurrentCalls property allows you to control how many messages your function can process in parallel. By default, this is set to 16. Azure Functions runtime automatically scales based on the load, but this setting provides fine-grained control over concurrency.

Related Topics