Azure Functions: Queue Trigger Binding (C#)

This document details how to use the Azure Queue Storage trigger binding for Azure Functions in C#. This binding allows your function to be invoked automatically when a new message is added to a specified Azure Storage Queue.

Overview

The queue trigger allows you to build event-driven applications that respond to messages in an Azure Storage Queue. When a message appears in the queue, the trigger invokes your function with the message content. This is a powerful pattern for decoupling services and processing tasks asynchronously.

How it Works

The queue trigger works by continuously polling a specific Azure Storage Queue. When a message is detected, it's processed by the trigger and then passed as an input to your C# function. By default, the message is deleted from the queue after successful processing. If your function fails, the message can be made visible again for retry.

Configuration

To configure a queue trigger, you'll use the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package and apply the QueueTrigger attribute to a method parameter in your function class.

The QueueTrigger Attribute

The QueueTrigger attribute takes the following parameters:

• queueName: The name of the Azure Storage Queue to monitor.
• Connection (optional): The name of an app setting that contains the connection string to your Azure Storage Account. If omitted, the default AzureWebJobsStorage connection string is used.

Example Function

Here's a basic example of a C# Azure Function that uses a queue trigger:

// Ensure you have the Microsoft.Azure.WebJobs.Extensions.Storage NuGet package installed.
// Add this using statement to your file:
// using Microsoft.Azure.WebJobs;

public static class QueueTriggerFunction
{
    [FunctionName("QueueTriggerCSharp")]
    public static void Run(
        [QueueTrigger("my-queue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        // You can also bind to a specific type if your messages are JSON serialized.
        // For example: [QueueTrigger("my-queue-items", Connection = "AzureWebJobsStorage")] MyDataModel myQueueItem,
        ILogger log)
    {
        log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");

        // Your processing logic here.
        // If the function execution completes without throwing an exception,
        // the message will be automatically deleted from the queue.
    }

    // Example of a custom data model for JSON messages
    // public class MyDataModel
    // {
    //     public string Id { get; set; }
    //     public string Message { get; set; }
    // }
}

Input Binding Types

The QueueTrigger attribute can bind to various types. The most common ones are:

• string: For plain text messages.
• byte[]: For binary messages.
• Poco (Plain Old CLR Object): If your queue messages are JSON serialized, you can bind directly to a C# object. The runtime will automatically deserialize the JSON into your object.
• CloudQueueMessage: For more control over the message, including message ID, insertion time, and expiration time.

Binding to JSON Objects

When your queue messages are JSON, you can define a C# class and bind to it:

public class Order
{
    public string OrderId { get; set; }
    public string Item { get; set; }
    public int Quantity { get; set; }
}

public static class QueueJsonTriggerFunction
{
    [FunctionName("QueueJsonTriggerCSharp")]
    public static void Run(
        [QueueTrigger("orders", Connection = "AzureWebJobsStorage")] Order order,
        ILogger log)
    {
        log.LogInformation($"Processing order: {order.OrderId}");
        log.LogInformation($"Item: {order.Item}, Quantity: {order.Quantity}");
    }
}

Error Handling and Retries

By default, if your queue-triggered function throws an unhandled exception, the message is not deleted from the queue and will become visible again after a visibility timeout. This allows the function to retry processing the message.

For more robust error handling, you can:

• Use poison queues: Configure the `maxDequeueCount` property in function.json (or via attributes in C#) to move messages to a separate "poison" queue after a certain number of failed attempts.
• Implement custom retry logic: Catch exceptions within your function and log them, or use external mechanisms for retrying.

Connection Strings

Connection strings for Azure Storage Accounts are typically stored in application settings. The default setting name is AzureWebJobsStorage. You can override this by specifying the Connection property in the QueueTrigger attribute.

Example local.settings.json

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

Best Practices

• Keep your queue messages small and focused.
• Ensure your function is idempotent, meaning it can be executed multiple times with the same input without changing the result.
• Use poison queues for messages that repeatedly fail to process.
• Monitor your queue length and function execution logs for any issues.

For advanced scenarios, refer to the official Azure Functions documentation for queue triggers.