title	description	ms.assetid	ms.topic	ms.date	ms.devlang	ms.custom	zone_pivot_groups
Azure Service Bus output bindings for Azure Functions	Learn to send Azure Service Bus messages from Azure Functions.	daedacf0-6546-4355-a65c-50873e74f66b	reference	01/15/2024	csharp	devx-track-csharp, devx-track-python, devx-track-extended-java, devx-track-js, devx-track-ts	programming-languages-set-functions

Azure Service Bus output binding for Azure Functions

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

For information on setup and configuration details, see the overview.

::: zone pivot="programming-language-javascript,programming-language-typescript" [!INCLUDE functions-nodejs-model-tabs-description] ::: zone-end ::: zone pivot="programming-language-python" [!INCLUDE functions-bindings-python-models-intro] ::: zone-end

Example

::: zone pivot="programming-language-csharp"

[!INCLUDE functions-bindings-csharp-intro]

[!INCLUDE functions-in-process-model-retirement-note]

Isolated worker model

This code defines and initializes the ILogger:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/ServiceBus/ServiceBusReceivedMessageFunctions.cs" id="docsnippet_servicebusmessage_createlogger":::

This example shows a C# function that receives a message and writes it to a second queue:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/ServiceBus/ServiceBusReceivedMessageFunctions.cs" id="docsnippet_servicebus_readmessage":::

This example uses an HTTP trigger with an OutputType object to both send an HTTP response and write the output message.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");
            
   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

This code defines the multiple output type OutputType, which includes the Service Bus output binding definition on OutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

In-process model

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

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

Instead of using the return statement to send the message, this HTTP trigger function returns an HTTP response that is different from the output message.

[FunctionName("HttpTrigger1")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req, 
[ServiceBus("TopicOrQueueName", Connection = "ServiceBusConnection")] IAsyncCollector<string> message, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    await message.AddAsync("MyMessage");
    await message.AddAsync("MyMessage2");

    string responseMessage = "This HTTP triggered sent a message to Service Bus.";

    return new OkObjectResult(responseMessage);
}

::: zone-end ::: zone pivot="programming-language-java"

The following example shows a Java function that sends a message to a Service Bus queue myqueue when triggered by an HTTP request.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

In the Java functions runtime library, use the @QueueOutput annotation on function parameters whose value would be written to a Service Bus queue. The parameter type should be OutputBinding<T>, where T is any native Java type of a plan old Java object (POJO).

Java functions can also write to a Service Bus topic. The following example uses the @ServiceBusTopicOutput annotation to describe the configuration for the output binding.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {
        
        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
        
    }

::: zone-end
::: zone pivot="programming-language-typescript"

Model v4

The following example shows a timer triggered TypeScript function that sends a queue message every 5 minutes.

:::code language="typescript" source="~/azure-functions-nodejs-v4/ts/src/functions/serviceBusOutput1.ts" :::

To output multiple messages, return an array instead of a single object. For example:

:::code language="typescript" source="~/azure-functions-nodejs-v4/ts/src/functions/serviceBusOutput2.ts" id="displayInDocs" :::

Model v3

TypeScript samples aren't documented for model v3.

::: zone-end
::: zone pivot="programming-language-javascript"

Model v4

The following example shows a timer triggered JavaScript function that sends a queue message every 5 minutes.

:::code language="javascript" source="~/azure-functions-nodejs-v4/js/src/functions/serviceBusOutput1.js" :::

To output multiple messages, return an array instead of a single object. For example:

:::code language="javascript" source="~/azure-functions-nodejs-v4/js/src/functions/serviceBusOutput2.js" id="displayInDocs" :::

Model v3

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 = async function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
};

Here's JavaScript script code that creates multiple messages:

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

::: zone-end
::: zone pivot="programming-language-powershell"

The following example shows a Service Bus output binding in a function.json file and a PowerShell function that uses the binding.

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

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Here's the PowerShell that creates a message as the function's output.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

::: zone-end
::: zone pivot="programming-language-python"

The following example demonstrates how to write out to a Service Bus queue in Python. The example depends on whether you use the v1 or v2 Python programming model.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

v1

A Service Bus binding definition is defined in function.json where type is set to serviceBus.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "msg",
      "queueName": "outqueue"
    }
  ]
}

In _init_.py, you can write out a message to the queue by passing a value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

::: zone-end
::: zone pivot="programming-language-csharp"

Attributes

Both in-process and isolated worker process C# libraries use attributes to define the output binding. C# script instead uses a function.json configuration file as described in the C# scripting guide.

Isolated worker model

In C# class libraries, use the ServiceBusOutputAttribute to define the queue or topic written to by the output.

The following table explains the properties you can set using the attribute:

Property	Description
EntityType	Sets the entity type as either `Queue` for sending messages to a queue or `Topic` when sending messages to a topic.
QueueOrTopicName	Name of the topic or queue to send messages to. Use `EntityType` to set the destination type.
Connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.

In-process model

In C# class libraries, use the ServiceBusAttribute.

The following table explains the properties you can set using the attribute:

Property	Description
QueueName	Name of the queue. Set only if sending queue messages, not for a topic.
TopicName	Name of the topic. Set only if sending topic messages, not for a queue.
Connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.
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 doesn't have the Manage permission, set `accessRights` to "listen". Otherwise, the Functions runtime might fail trying to do operations that require manage rights. In Azure Functions version 2.x and higher, this property isn't available because the latest version of the Service Bus SDK doesn't support manage operations.

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, ILogger log)
{
    ...
}

You can set the Connection property to specify the name of an app setting that contains the Service Bus connection string to use, as shown in the following example:

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

For a complete example, see 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 Attributes in the trigger reference.

::: zone-end

::: zone pivot="programming-language-python"

Decorators

Applies only to the Python v2 programming model.

For Python v2 functions defined using a decorator, the following properties on the service_bus_topic_output:

Property	Description
`arg_name`	The name of the variable that represents the queue or topic message in function code.
`queue_name`	Name of the queue. Set only if sending queue messages, not for a topic.
`topic_name`	Name of the topic. Set only if sending topic messages, not for a queue.
`connection`	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.

For Python functions defined by using function.json, see the Configuration section. ::: zone-end

::: zone pivot="programming-language-java"

Annotations

The ServiceBusQueueOutput and ServiceBusTopicOutput annotations are available to write a message as a function output. The parameter decorated with these annotations must be declared as an OutputBinding<T> where T is the type corresponding to the message's type.

[!INCLUDE app settings to local.settings.json]

::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-powershell,programming-language-python"

Configuration

::: zone-end

::: zone pivot="programming-language-python" Applies only to the Python v1 programming model.

::: zone-end ::: zone pivot="programming-language-javascript,programming-language-typescript"

Model v4

The following table explains the properties that you can set on the options object passed to the output.serviceBusQueue() method.

Property	Description
queueName	Name of the queue.
connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.

The following table explains the properties that you can set on the options object passed to the output.serviceBusTopic() method.

Property	Description
topicName	Name of the topic.
connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.

Model v3

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

Property	Description
type	Must be set to `serviceBus`. This property is set automatically when you create the trigger in the Azure portal.
direction	Must be set to `out`. This property is set automatically when you create the trigger in the Azure portal.
name	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	Name of the queue. Set only if sending queue messages, not for a topic.
topicName	Name of the topic. Set only if sending topic messages, not for a queue.
connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.

[!INCLUDE app settings to local.settings.json]

::: zone-end
::: zone pivot="programming-language-powershell,programming-language-python"

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

function.json property	Description
type	Must be set to `serviceBus`. This property is set automatically when you create the trigger in the Azure portal.
direction	Must be set to `out`. This property is set automatically when you create the trigger in the Azure portal.
name	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	Name of the queue. Set only if sending queue messages, not for a topic.
topicName	Name of the topic. Set only if sending topic messages, not for a queue.
connection	The name of an app setting or setting collection that specifies how to connect to Service Bus. See Connections.
accessRights (v1 only)	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 doesn't have the Manage permission, set `accessRights` to "listen". Otherwise, the Functions runtime might fail trying to do operations that require manage rights. In Azure Functions version 2.x and higher, this property isn't available because the latest version of the Service Bus SDK doesn't support manage operations.

[!INCLUDE app settings to local.settings.json]

::: zone-end

See the Example section for complete examples.

Usage

::: zone pivot="programming-language-csharp"

All C# modalities and extension versions support the following output parameter types:

Type	Description
System.String	Use when the message to write is simple text. When the parameter value is null when the function exits, Functions doesn't create a message.
byte[]	Use for writing binary data messages. When the parameter value is null when the function exits, Functions doesn't create a message.
Object	When a message contains JSON, Functions serializes the object into a JSON message payload. When the parameter value is null when the function exits, Functions creates a message with a null object.

Messaging-specific parameter types contain extra message metadata and aren't compatible with JSON serialization. As a result, it isn't possible to use ServiceBusMessage with the output binding in the isolated model. The specific types supported by the output binding depend on the Functions runtime version, the extension package version, and the C# modality used.

Extension v5.x

Use the ServiceBusMessage type when sending messages with metadata. Parameters are defined as return type attributes. Use an ICollector<T> or IAsyncCollector<T> to write multiple messages. A message is created when you call the Add method.

When the parameter value is null when the function exits, Functions doesn't create a message.

[!INCLUDE functions-service-bus-account-attribute]

Functions 2.x and higher

Use the Message type when sending messages with metadata. Parameters are defined as return type attributes. Use an ICollector<T> or IAsyncCollector<T> to write multiple messages. A message is created when you call the Add method.

[!INCLUDE service-bus-track-0-and-1-sdk-support-retirement]

When the parameter value is null when the function exits, Functions doesn't create a message.

[!INCLUDE functions-service-bus-account-attribute]

Functions 1.x

Use the BrokeredMessage type when sending messages with metadata. Parameters are defined as return type attributes. When the parameter value is null when the function exits, Functions doesn't create a message.

[!INCLUDE functions-service-bus-account-attribute]

Extension 5.x and higher

[!INCLUDE functions-bindings-service-bus-output-dotnet-isolated-types]

Functions 2.x and higher

Earlier versions of this extension in the isolated worker process only support binding to messaging-specific types. More options are available to Extension 5.x and higher

Functions 1.x

Functions version 1.x doesn't support isolated worker process. To use the isolated worker model, upgrade your application to Functions 4.x.

::: zone-end

In Azure Functions 1.x, the runtime creates the queue if it doesn't exist and you have set accessRights to manage. In Azure Functions version 2.x and higher, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function fails.

::: zone pivot="programming-language-java" Use the Azure Service Bus SDK rather than the built-in output binding. ::: zone-end
::: zone pivot="programming-language-javascript,programming-language-typescript"

Model v4

Access the output message by returning the value directly or using context.extraOutputs.set().

Model v3

Access the output message by using context.bindings.<name> where <name> is the value specified in the name property of function.json.

::: zone-end
::: zone pivot="programming-language-powershell"
Output to the Service Bus is available via the Push-OutputBinding cmdlet where you pass arguments that match the name designated by binding's name parameter in the function.json file. ::: zone-end
::: zone pivot="programming-language-python"
Use the Azure Service Bus SDK rather than the built-in output binding. ::: zone-end
For a complete example, see the examples section.

[!INCLUDE functions-service-bus-connections]

Exceptions and return codes

Binding	Reference
Service Bus	Service Bus Error Codes
Service Bus	Service Bus Limits

Next steps

Run a function when a Service Bus queue or topic message is created (Trigger)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

functions-bindings-service-bus-output.md

functions-bindings-service-bus-output.md

Azure Service Bus output binding for Azure Functions

Example

Isolated worker model

In-process model

Model v4

Model v3

Model v4

Model v3

v2

v1

Attributes

Isolated worker model

In-process model

Decorators

Annotations

Configuration

Model v4

Model v3

Usage

Extension v5.x

Functions 2.x and higher

Functions 1.x

Extension 5.x and higher

Functions 2.x and higher

Functions 1.x

Model v4

Model v3

Exceptions and return codes

Next steps

Files

functions-bindings-service-bus-output.md

Latest commit

History

functions-bindings-service-bus-output.md

File metadata and controls

Azure Service Bus output binding for Azure Functions

Example

Attributes

Decorators

Annotations

Configuration

Usage

Exceptions and return codes

Next steps