title	description	ms.topic	ms.date	ms.devlang	ms.custom	zone_pivot_groups
Azure Queue storage output binding for Azure Functions	Learn to create Azure Queue storage messages in Azure Functions.	reference	03/06/2023	csharp, java, javascript, powershell, python	devx-track-csharp, cc996988-fb4f-47, devx-track-python, devx-track-extended-java, devx-track-js	programming-languages-set-functions-lang-workers

Azure Queue storage output bindings for Azure Functions

Azure Functions can create new Azure Queue storage messages by setting up an output binding.

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

::: zone pivot="programming-language-python" Azure Functions supports two programming models for Python. The way that you define your bindings depends on your chosen programming model.

v2

The Python v2 programming model lets you define bindings using decorators directly in your Python function code. For more information, see the Python developer guide.

v1

The Python v1 programming model requires you to define bindings in a separate function.json file in the function folder. For more information, see the Python developer guide.

This article supports both programming models.

Important

The Python v2 programming model is currently in preview. ::: zone-end

Example

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

[!INCLUDE functions-bindings-csharp-intro]

In-process

The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Isolated process

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Queue/QueueFunction.cs" id="docsnippet_queue_output_binding" :::

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

The following example shows a Java function that creates a queue message for when triggered by an HTTP request.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

In the Java functions runtime library, use the @QueueOutput annotation on parameters whose value would be written to Queue storage. The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

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

The following example shows an HTTP trigger binding in a function.json file and a JavaScript function that uses the binding. The function creates a queue item for each HTTP request received.

Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

The configuration section explains these properties.

Here's the JavaScript code:

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

You can send multiple messages at once by defining a message array for the myQueueItem output binding. The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = async function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
};

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

The following code examples demonstrate how to output a queue message from an HTTP-triggered function. The configuration section with the type of queue defines the output binding.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Using this binding configuration, a PowerShell function can create a queue message using Push-OutputBinding. In this example, a message is created from a query string or body parameter.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

To send multiple messages at once, define a message array and use Push-OutputBinding to send messages to the Queue output binding.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

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

The following example demonstrates how to output single and multiple values to storage queues. The configuration needed for function.json is the same either way. 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.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)
    
    msg.set(input_msg)
    
    logging.info(f'name: {name}')
    return 'OK'

v1

A Storage queue binding is defined in function.json where type is set to queue.

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

To set an individual message on the queue, you pass a single 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'

To create multiple messages on the queue, declare a parameter as the appropriate list type and pass an array of values (that match the list type) to the set method.

import azure.functions as func
import typing

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

    msg.set(['one', 'two'])

    return 'OK'

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

Attributes

The attribute that defines an output binding in C# libraries depends on the mode in which the C# class library runs.

In-process

In C# class libraries, use the QueueAttribute. C# script instead uses a function.json configuration file as described in the C# scripting guide.

The attribute applies to an out parameter or the return value of the function. The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

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

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

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

Isolated process

When running in an isolated worker process, you use the QueueOutputAttribute, which takes the name of the queue, as shown in the following example:

:::code language="csharp" source="~/azure-functions-dotnet-worker/samples/Extensions/Queue/QueueFunction.cs" id="docsnippet_queue_trigger" :::

Only returned variables are supported when running in an isolated worker process. Output parameters can't be used.

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

Property	Description
`arg_name`	The name of the variable that represents the queue in function code.
`queue_name`	The name of the queue.
`connection`	The name of an app setting or setting collection that specifies how to connect to Azure Queues. See Connections.

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

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

Annotations

The QueueOutput annotation allows you to write a message as the output of a function. The following example shows an HTTP-triggered function that creates a queue message.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}

Property	Description
`name`	Declares the parameter name in the function signature. When the function is triggered, this parameter's value has the contents of the queue message.
`queueName`	Declares the queue name in the storage account.
`connection`	Points to the storage account connection string.

The parameter associated with the QueueOutput annotation is typed as an OutputBinding<T> instance. ::: zone-end
::: zone pivot="programming-language-javascript,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-powershell,programming-language-python"

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

function.json property	Description
type	Must be set to `queue`. 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 in function code. Set to `$return` to reference the function return value.
queueName	The name of the queue.
connection	The name of an app setting or setting collection that specifies how to connect to Azure Queues. See Connections.

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

::: zone-end

See the Example section for complete examples.

Usage

::: zone pivot="programming-language-csharp"
The usage of the Queue output binding depends on the extension package version and the C# modality used in your function app, which can be one of the following:

In-process

An in-process class library is a compiled C# function runs in the same process as the Functions runtime.

Isolated process

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

Choose a version to see usage details for the mode and version.

Extension 5.x+

Write a single queue message by using a method parameter such as out T paramName. You can use the method return type instead of an out parameter, and T can be any of the following types:

An object serializable as JSON
string
byte[]
QueueMessage

For examples using these types, see the GitHub repository for the extension.

You can write multiple messages to the queue by using one of the following types:

ICollector<T> or IAsyncCollector<T>
QueueClient

For examples using QueueMessage and QueueClient, see the GitHub repository for the extension.

[!INCLUDE functions-bindings-storage-attribute]

Extension 2.x+

Write a single queue message by using a method parameter such as out T paramName. You can use the method return type instead of an out parameter, and T can be any of the following types:

An object serializable as JSON
string
byte[]
CloudQueueMessage

If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

You can write multiple messages to the queue by using one of the following types:

ICollector<T> or IAsyncCollector<T>
CloudQueue

[!INCLUDE functions-bindings-storage-attribute]

Extension 5.x+

[!INCLUDE functions-bindings-storage-queue-output-dotnet-isolated-types]

Extension 2.x+

Isolated worker process currently only supports binding to string parameters.

::: zone-end

::: zone pivot="programming-language-java" There are two options for writing to a queue from a function by using the QueueOutput annotation:

Return value: By applying the annotation to the function itself, the return value of the function is written to the queue.
Imperative: To explicitly set the message value, apply the annotation to a specific parameter of the type OutputBinding<T>, where T is a POJO or any native Java type. With this configuration, passing a value to the setValue method writes the value to the queue.

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

The output queue item is available via context.bindings.<NAME> where <NAME> matches the name defined in function.json. You can use a string or a JSON-serializable object for the queue item payload.

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

Output to the queue message is available via Push-OutputBinding 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"

There are two options for writing from your function to the configured queue:

Return value: Set the name property in function.json to $return. With this configuration, the function's return value is persisted as a Queue storage message.
Imperative: Pass a value to the set method of the parameter declared as an Out type. The value passed to set is persisted as a Queue storage message.

::: zone-end

[!INCLUDE functions-storage-queue-connections]

Exceptions and return codes

Binding	Reference
Queue	Queue Error Codes
Blob, Table, Queue	Storage Error Codes
Blob, Table, Queue	Troubleshooting

Next steps

Run a function as queue storage data changes (Trigger)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

functions-bindings-storage-queue-output.md

functions-bindings-storage-queue-output.md

Azure Queue storage output bindings for Azure Functions

v2

v1

Example

In-process

Isolated process

v2

v1

Attributes

In-process

Isolated process

Decorators

Annotations

Configuration

Usage

In-process

Isolated process

Extension 5.x+

Extension 2.x+

Extension 5.x+

Extension 2.x+

Exceptions and return codes

Next steps

Files

functions-bindings-storage-queue-output.md

Latest commit

History

functions-bindings-storage-queue-output.md

File metadata and controls

Azure Queue storage output bindings for Azure Functions

Example

Attributes

Decorators

Annotations

Configuration

Usage

Exceptions and return codes

Next steps