Azure Functions Queue Storage Trigger (C#)

This document details how to use the Queue Storage trigger for Azure Functions written in C#.

Overview

The Queue Storage trigger starts a Function when a message is added to a specific Azure Queue Storage queue. This is a common pattern for processing asynchronous tasks, handling work queues, and decoupling services.

Trigger Configuration

The Queue Storage trigger is configured using an attribute in your C# function code or through the function.json file.

C# Attribute Configuration

The most common way to define a Queue Storage trigger in C# is by using the QueueTrigger attribute.

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

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

            // Your processing logic here
            // For example, parse the message, interact with other services, etc.
        }
    }
}

Attribute Parameters

• queueName: The name of the Queue Storage queue to monitor. In the example above, it's "myqueue-items".
• Connection: The name of the application setting that contains the connection string to your Azure Storage account. The default is "AzureWebJobsStorage", which is typically configured in your local.settings.json or Azure Function App settings.

function.json Configuration

Alternatively, you can configure the trigger declaratively in the function.json file. This is less common for C# code-first development but is useful for other languages or when using certain deployment methods.

{
  "scriptFile": "__init__.py", // For Python, adjust for C# if needed or rely on attribute
  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Note: When using C# attributes, the function.json is generated automatically. If you are manually creating function.json, ensure the name property matches the parameter name in your C# method.

Input Binding

The message content from the queue is passed as the input to your function. The type of the input parameter can be:

• string: For plain text messages.
• byte[]: For binary data.
• POCO (Plain Old C# Object): If your messages are JSON-serialized, you can bind directly to a C# class. The runtime will automatically deserialize the JSON.

POCO Deserialization Example

Define a C# class that matches the structure of your queued messages.

public class MyQueueMessage
{
    public string Id { get; set; }
    public string Data { get; set; }
}

Update your function signature to accept this POCO:

using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public static class QueueProcessor
    {
        [FunctionName("ProcessQueueMessagePOCO")]
        public static void Run(
            [QueueTrigger("myqueue-items-json", Connection = "AzureWebJobsStorage")] MyQueueMessage myQueueItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed message ID: {myQueueItem.Id}");
            log.LogInformation($"Data: {myQueueItem.Data}");
        }
    }
}

Function Execution and Message Handling

When a message is successfully processed by your function, it is automatically deleted from the queue.

If your function throws an unhandled exception:

• The message remains in the queue.
• After a configurable number of retries (controlled by maxDequeueCount in the host configuration), the message will be moved to the associated poison queue (e.g., myqueue-items-poison) for manual inspection.

Queue Properties and Deletion

The trigger automatically handles the visibility timeout and deletion of messages. You do not need to manually manage this for successful executions. For advanced scenarios where you need more control, consider using the Queue Storage SDK directly within your function.

Connection String Configuration

Ensure your Azure Storage connection string is correctly configured. For local development, this is typically done in the local.settings.json file under the Values section:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "DefaultEndpointsProtocol=https;AccountName=YOUR_STORAGE_ACCOUNT_NAME;AccountKey=YOUR_STORAGE_ACCOUNT_KEY;EndpointSuffix=core.windows.net",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet"
  }
}

In Azure, you configure this in the Function App's "Configuration" settings.

Best Practices

• Idempotency: Design your functions to be idempotent. If a message is processed multiple times due to retries, the outcome should be the same.
• Error Handling: Implement robust error handling. Log errors clearly and consider moving problematic messages to a dead-letter queue or a dedicated error handling process.
• Message Size: Queue Storage messages have a size limit (64 KB). For larger data, consider storing the data in Blob Storage and passing a reference in the queue message.
• Connection String Security: Never hardcode connection strings. Use environment variables or application settings.