Azure Service Bus bindings for Azure Functions

This article explains how to work with Azure Service Bus bindings in Azure Functions. Azure Functions supports trigger and output bindings for Service Bus queues and topics.

This is reference information for Azure Functions developers. If you're new to Azure Functions, start with the following resources:

Trigger

Use the Service Bus trigger to respond to messages from a Service Bus queue or topic.

Trigger - example

See the language-specific example:

Trigger - C# example

The following example shows a precompiled C# function that logs a Service Bus queue message.

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", AccessRights.Manage, Connection = "ServiceBusConnection")] 
    string myQueueItem, 
    TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
}

Trigger - C# script example

The following example shows a Service Bus trigger binding in a function.json file and a C# script function that uses the binding. The function logs a Service Bus queue message.

Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Here's the C# script code:

public static void Run(string myQueueItem, TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
}

Trigger - F# example

The following example shows a Service Bus trigger binding in a function.json file and an F# function that uses the binding. The function logs a Service Bus queue message.

Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Here's the F# script code:

let Run(myQueueItem: string, log: TraceWriter) =
    log.Info(sprintf "F# ServiceBus queue trigger function processed message: %s" myQueueItem)

Trigger - JavaScript example

The following example shows a Service Bus trigger binding in a function.json file and a JavaScript function that uses the binding. The function logs a Service Bus queue message.

Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Here's the JavaScript script code:

module.exports = function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.done();
};

Trigger - attributes

For precompiled C# functions, use the following attributes to configure a Service Bus trigger:

  • ServiceBusTriggerAttribute, defined in NuGet package Microsoft.Azure.WebJobs.ServiceBus

    The attribute's constructor takes the name of the queue or the topic and subscription. You can also specify the connection's access rights. If you don't specify access rights, the default is Manage. How to choose the access rights setting is explained in the Trigger - configuration section. Here's an example that shows the attribute used with a string parameter:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue")] string myQueueItem, TraceWriter log)
    {
        ...
    }
    

    You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
        string myQueueItem, TraceWriter log)
    {
        ...
    }
    

    For a complete example, see Trigger - precompiled C# example.

  • ServiceBusAccountAttribute, defined in NuGet package Microsoft.Azure.WebJobs.ServiceBus

    Provides another way to specify the Service Bus account to use. The constructor takes the name of an app setting that contains a Service Bus connection string. The attribute can be applied at the parameter, method, or class level. The following example shows class level and method level:

    [ServiceBusAccount("ClassLevelServiceBusAppSetting")]
    public static class AzureFunctions
    {
        [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
        [FunctionName("ServiceBusQueueTriggerCSharp")]
        public static void Run(
            [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
            string myQueueItem, TraceWriter log)
    {
        ...
    }
    

The Service Bus account to use is determined in the following order:

  • The ServiceBusTrigger attribute's Connection property.
  • The ServiceBusAccount attribute applied to the same parameter as the ServiceBusTrigger attribute.
  • The ServiceBusAccount attribute applied to the function.
  • The ServiceBusAccount attribute applied to the class.
  • The "AzureWebJobsServiceBus" app setting.

Trigger - configuration

The following table explains the binding configuration properties that you set in the function.json file and the ServiceBusTrigger attribute.

function.json property Attribute property Description
type n/a Must be set to "serviceBusTrigger". This property is set automatically when you create the trigger in the Azure portal.
direction n/a Must be set to "in". This property is set automatically when you create the trigger in the Azure portal.
name n/a The name of the variable that represents the queue or topic message in function code. Set to "$return" to reference the function return value.
queueName QueueName Name of the queue to monitor. Set only if monitoring a queue, not for a topic.
topicName TopicName Name of the topic to monitor. Set only if monitoring a topic, not for a queue.
subscriptionName SubscriptionName Name of the subscription to monitor. Set only if monitoring a topic, not for a queue.
connection Connection The name of an app setting that contains the Service Bus connection string to use for this binding. If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus." If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

To obtain a connection string, follow the steps shown at Obtain the management credentials. The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRights Access Access rights for the connection string. Available values are manage and listen. The default is manage, which indicates that the connection has the Manage permission. If you use a connection string that does not have the Manage permission, set accessRights to "listen". Otherwise, the Functions runtime might fail trying to do operations that require manage rights.

When you're developing locally, app settings go into the local.settings.json file.

Trigger - usage

In C# and C# script, access the queue or topic message by using a method parameter such as string paramName. In C# script, paramName is the value specified in the name property of function.json. You can use any of the following types instead of string:

  • byte[] - Useful for binary data.
  • A custom type - If the message contains JSON, Azure Functions tries to deserialize the JSON data.
  • BrokeredMessage - Gives you the deserialized message with the BrokeredMessage.GetBody() method.

In JavaScript, access the queue or topic message by using context.bindings.<name>. <name> is the value specified in the name property of function.json. The Service Bus message is passed into the function as either a string or JSON object.

Trigger - poison messages

Poison message handling can't be controlled or configured in Azure Functions. Service Bus handles poison messages itself.

Trigger - PeekLock behavior

The Functions runtime receives a message in PeekLock mode. It calls Complete on the message if the function finishes successfully, or calls Abandon if the function fails. If the function runs longer than the PeekLock timeout, the lock is automatically renewed.

Trigger - host.json properties

The host.json file contains settings that control Service Bus trigger behavior.

{
    "serviceBus": {
      "maxConcurrentCalls": 16,
      "prefetchCount": 100,
      "autoRenewTimeout": "00:05:00"
    }
}
Property Default Description
maxConcurrentCalls 16 The maximum number of concurrent calls to the callback that the message pump should initiate. By default, the Functions runtime processes multiple messages concurrently. To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCount n/a The default PrefetchCount that will be used by the underlying MessageReceiver.
autoRenewTimeout 00:05:00 The maximum duration within which the message lock will be renewed automatically.

Output

Use Azure Service Bus output binding to send queue or topic messages.

Output - example

See the language-specific example:

Output - C# example

The following example shows a precompiled C# function that sends a Service Bus queue message:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, TraceWriter log)
{
    log.Info($"C# function processed: {input.Text}");
    return input.Text;
}

Output - C# script example

The following example shows a Service Bus output binding in a function.json file and a C# script function that uses the binding. The function uses a timer trigger to send a queue message every 15 seconds.

Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Here's C# script code that creates a single message:

public static void Run(TimerInfo myTimer, TraceWriter log, out string outputSbQueue)
{
    string message = $"Service Bus queue message created at: {DateTime.Now}";
    log.Info(message); 
    outputSbQueue = message;
}

Here's C# script code that creates multiple messages:

public static void Run(TimerInfo myTimer, TraceWriter log, ICollector<string> outputSbQueue)
{
    string message = $"Service Bus queue messages created at: {DateTime.Now}";
    log.Info(message); 
    outputSbQueue.Add("1 " + message);
    outputSbQueue.Add("2 " + message);
}

Output - F# example

The following example shows a Service Bus output binding in a function.json file and an F# script function that uses the binding. The function uses a timer trigger to send a queue message every 15 seconds.

Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Here's F# script code that creates a single message:

let Run(myTimer: TimerInfo, log: TraceWriter, outputSbQueue: byref<string>) =
    let message = sprintf "Service Bus queue message created at: %s" (DateTime.Now.ToString())
    log.Info(message)
    outputSbQueue = message

Output - JavaScript example

The following example shows a Service Bus output binding in a function.json file and a JavaScript function that uses the binding. The function uses a timer trigger to send a queue message every 15 seconds.

Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Here's JavaScript script code that creates a single message:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueueMsg = message;
    context.done();
};

Here's JavaScript script code that creates multiple messages:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueueMsg = [];
    context.bindings.outputSbQueueMsg.push("1 " + message);
    context.bindings.outputSbQueueMsg.push("2 " + message);
    context.done();
};

Output - attributes

For precompiled C# functions, use the ServiceBusAttribute, which is defined in NuGet package Microsoft.Azure.WebJobs.ServiceBus.

The attribute's constructor takes the name of the queue or the topic and subscription. You can also specify the connection's access rights. How to choose the access rights setting is explained in the Output - configuration section. Here's an example that shows the attribute applied to the return value of the function:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, TraceWriter log)
{
    ...
}

You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, TraceWriter log)
{
    ...
}

For a complete example, see Output - precompiled C# example.

You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. For more information, see Trigger - attributes.

Output - configuration

The following table explains the binding configuration properties that you set in the function.json file and the ServiceBus attribute.

function.json property Attribute property Description
type n/a Must be set to "serviceBus". This property is set automatically when you create the trigger in the Azure portal.
direction n/a Must be set to "out". This property is set automatically when you create the trigger in the Azure portal.
name n/a The name of the variable that represents the queue or topic in function code. Set to "$return" to reference the function return value.
queueName QueueName Name of the queue. Set only if sending queue messages, not for a topic.
topicName TopicName Name of the topic to monitor. Set only if sending topic messages, not for a queue.
subscriptionName SubscriptionName Name of the subscription to monitor. Set only if sending topic messages, not for a queue.
connection Connection The name of an app setting that contains the Service Bus connection string to use for this binding. If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus." If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

To obtain a connection string, follow the steps shown at Obtain the management credentials. The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRights Access Access rights for the connection string. Available values are "manage" and "listen". The default is "manage", which indicates that the connection has Manage permissions. If you use a connection string that does not have Manage permissions, set accessRights to "listen". Otherwise, the Functions runtime might fail trying to do operations that require manage rights.

When you're developing locally, app settings go into the local.settings.json file.

Output - usage

In C# and C# script, access the queue or topic by using a method parameter such as out string paramName. In C# script, paramName is the value specified in the name property of function.json. You can use any of the following parameter types:

  • out T paramName - T can be any JSON-serializable type. If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message.

For creating multiple messages in a C# or C# script function, you can use ICollector<T> or IAsyncCollector<T>. A message is created when you call the Add method.

In JavaScript, access the queue or topic by using context.bindings.<name>. <name> is the value specified in the name property of function.json. You can assign a string, a byte array, or a Javascript object (deserialized into JSON) to context.binding.<name>.

Next steps