Azure Functions Queue Trigger

This document explains how to use the Queue trigger binding with Azure Functions. The Queue trigger allows you to run an Azure Function in response to new messages appearing in an Azure Storage Queue.

When to use a Queue Trigger

A Queue trigger is ideal for scenarios where you need to process items asynchronously. Common use cases include:

How it works

When a new message is added to the configured Azure Storage Queue, the Queue trigger automatically invokes your function. The function receives the message content, and upon successful completion, the message is automatically deleted from the queue. If the function fails, the message remains in the queue and will be retried (subject to queue configuration).

Prerequisites

Creating a Queue Trigger Function

1. Project Setup

If you haven't already, create a new Azure Functions project:

func init MyQueueTriggerProject --worker-runtime dotnet
cd MyQueueTriggerProject

Or for Node.js:

func init MyQueueTriggerProject --worker-runtime node

2. Add a Queue Trigger Function

Add a new function with a Queue trigger binding:

func new --template "AzureQueueStorageTrigger" --name QueueProcessor

This will create a new function named QueueProcessor with the appropriate configuration.

3. Configure the Binding

The binding configuration is typically found in a file named function.json (for Node.js, Python, Java) or defined in code attributes (for C#).

Example function.json (Node.js)

{
  "scriptFile": "index.js",
  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Example C# Function

[FunctionName("QueueProcessor")]
public static void Run([QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem, ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

The key properties are:

Tip: You can use a placeholder for the queue name (e.g., %MY_QUEUE_NAME%) and define the actual queue name in your application settings.

4. Write Function Logic

Implement the code within your function to process the message. The message content will be passed as the parameter specified in the binding (e.g., myQueueItem).

Example index.js (Node.js)

module.exports = async function (context, myQueueItem) {
    context.log('JavaScript queue trigger function processed work item', myQueueItem);
    // Your processing logic here
    context.log('Message processed successfully.');
};

5. Configure Storage Connection String

Ensure your Azure Storage connection string is configured in your application settings. For local development, this is typically in a local.settings.json file.

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "YOUR_STORAGE_CONNECTION_STRING",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet" // or "node", "python", etc.
  }
}

Replace YOUR_STORAGE_CONNECTION_STRING with your actual connection string.

Advanced Scenarios

Poison Messages

If a function consistently fails to process a message, it's considered a "poison message." The Queue trigger has built-in retry mechanisms. After a configured number of retries, the message is moved to a special "poison queue" (named like myqueue-items-poison) for manual inspection. You can configure the maximum retry count using the maxDequeueCount property in the binding configuration (e.g., in function.json).

    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "AzureWebJobsStorage",
      "maxDequeueCount": 5 // Default is 1 for some runtimes, 10 for others
    }

Batching Messages

For higher throughput scenarios, you can configure your trigger to process multiple messages in a single function invocation. This requires using specific trigger types (e.g., queueTrigger with a batch size configuration or specialized bindings for Service Bus).

Note: Queue triggers themselves do not inherently support batching of individual messages directly in the same way as Service Bus. You would typically read multiple messages within your function or use a Service Bus trigger for true batching.

Output Bindings

You can use output bindings within your queue trigger function to interact with other Azure services, such as writing to another queue, a database, or sending an email.

Example: Writing to another Queue

{
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "input-queue",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "outputQueueItem",
      "type": "queue",
      "direction": "out",
      "queueName": "output-queue",
      "connection": "AzureWebJobsStorage"
    }
module.exports = async function (context, myQueueItem) {
    context.log('Processing item:', myQueueItem);
    const processedMessage = `Processed: ${myQueueItem}`;
    context.bindings.outputQueueItem = processedMessage;
    context.log('Sent to output queue:', processedMessage);
};

Important: Ensure your storage account connection string is kept secure and is not committed directly into your code repository. Use application settings or Azure Key Vault.

By understanding and implementing the Azure Functions Queue trigger, you can build robust, scalable, and event-driven applications.