Azure Functions Storage queue bindings

This article explains how to configure and code Azure Storage queue bindings in Azure Functions. Azure Functions supports trigger and output bindings for Azure Storage queues.

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

Storage Queue trigger

The Azure Storage queue trigger enables you to monitor a storage queue for new messages and react to them.

The Storage queue trigger to a function use the following JSON objects in the bindings array of function.json:

{
    "name": "<Name of input parameter in function signature>",
    "queueName": "<Name of queue to poll>",
    "connection":"<Name of app setting - see below>",
    "type": "queueTrigger",
    "direction": "in"
}

connection must contain the name of an app setting that contains a storage connection string. In the Azure portal, you can configure this app setting in the Integrate tab when you create a storage account or select an existing one. To manually create this app setting, see Manage App Service settings.

Additional settings can be provided in a host.json file to further fine-tune storage queue triggers.

Handling poison queue messages

When a queue trigger function fails, Azure Functions retries that function up to five times for a given queue message, including the first try. If all five attempts fail, Functions adds a message to a Storage queue named <originalqueuename>-poison. You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

To handle poison messages manually, you can get the number of times a message has been picked up for processing by checking dequeueCount (see Queue trigger metadata).

Trigger usage

In C# functions, you bind to the input message by using a named parameter in your function signature, like <T> <name>. Where T is the data type that you want to deserialize the data into, and paramName is the name you specified in the trigger binding. In Node.js functions, you access the input blob data using context.bindings.<name>.

The queue message can be deserialized to any of the following types:

  • Object - used for JSON serialized messages. When you declare a custom input type, the runtime tries to deserialize the JSON object.
  • String
  • Byte array
  • CloudQueueMessage (C# only)

Queue trigger metadata

You can get queue metadata in your function by using these variable names:

  • expirationTime
  • insertionTime
  • nextVisibleTime
  • id
  • popReceipt
  • dequeueCount
  • queueTrigger (another way to retrieve the queue message text as a string)

See how to use the queue metadata in Trigger sample

Trigger sample

Suppose you have the following function.json, that defines a Storage queue trigger:

{
    "disabled": false,
    "bindings": [
        {
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"",
            "type": "queueTrigger",
            "direction": "in"
        }
    ]
}

See the language-specific sample that retrieves and logs queue metadata.

Trigger sample in C#

public static void Run(string myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

Trigger sample in Node.js

module.exports = function (context) {
    context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('queueTrigger =', context.bindingData.queueTrigger);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id=', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
    context.done();
};

Storage Queue output binding

The Azure Storage queue output binding enables you to write messages to a Storage queue in your function.

The Storage queue output for a function uses the following JSON objects in the bindings array of function.json:

{
  "name": "<Name of output parameter in function signature>",
    "queueName": "<Name of queue to write to>",
    "connection":"<Name of app setting - see below>",
  "type": "queue",
  "direction": "out"
}

connection must contain the name of an app setting that contains a storage connection string. In the Azure portal, the standard editor in the Integrate tab configures this app setting for you when you create a storage account or selects an existing one. To manually create this app setting, see Manage App Service settings.

Output usage

In C# functions, you write a queue message by using the named out parameter in your function signature, like out <T> <name>. In this case, T is the data type that you want to serialize the message into, and paramName is the name you specified in the output binding. In Node.js functions, you access the output using context.bindings.<name>.

You can output a queue message using any of the data types in your code:

  • Any Object: out MyCustomType paramName
    Used for JSON serialization. When you declare a custom output type, the runtime tries to serialize the object into JSON. If the output parameter is null when the function exits, the runtime creates a queue message as a null object.
  • String: out string paramName
    Used for test messages. The runtime creates message only when the string parameter is non-null when the function exits.
  • Byte array: out byte[]

These additional output types are supported a C# function:

  • CloudQueueMessage: out CloudQueueMessage
  • ICollector<T> or IAsyncCollector<T> where T is one of the supported types.

Output sample

Suppose you have the following function.json, that defines a Storage queue trigger, a Storage blob input, and a Storage blob output:

Example function.json for a storage queue output binding that uses a manual trigger and writes the input to a queue message:

{
  "bindings": [
    {
      "type": "manualTrigger",
      "direction": "in",
      "name": "input"
    },
    {
      "type": "queue",
      "name": "myQueueItem",
      "queueName": "myqueue",
      "connection": "my_storage_connection",
      "direction": "out"
    }
  ],
  "disabled": false
}

See the language-specific sample that writes an output queue message for each input queue message.

Output sample in C#

public static void Run(string input, out string myQueueItem, TraceWriter log)
{
    myQueueItem = "New message: " + input;
}

Or, to send multiple messages,

public static void Run(string input, ICollector<string> myQueueItem, TraceWriter log)
{
    myQueueItem.Add("Message 1: " + input);
    myQueueItem.Add("Message 2: " + "Some other message.");
}

Output sample in Node.js

module.exports = function(context) {
    // Define a new message for the myQueueItem output binding.
    context.bindings.myQueueItem = "new message";
    context.done();
};

Or, to send multiple messages,

module.exports = function(context) {
    // Define a message array for the myQueueItem output binding. 
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

Next steps

For an example of a function that uses aStorage queue triggers and bindings, see Create an Azure Function connected to an Azure service.

For information about other bindings and triggers for Azure Functions, see Azure Functions triggers and bindings developer reference