Queue Storage Queue Trigger for Azure Functions (PowerShell)

This document provides detailed information about using the Queue Storage trigger binding for Azure Functions written in PowerShell. This trigger automatically invokes your function when a new message is added to a specified Azure Queue Storage queue.

Overview

The Queue Storage trigger is a serverless event-driven mechanism. When a new message appears in your Azure Queue Storage, the trigger activates, and your PowerShell function is executed with the message content as input.

Configuration

To configure the Queue Storage trigger, you define a binding in your function.json file.

function.json Example

{
  "bindings": [
    {
      "name": "message",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Binding Properties

Property Description Required
name The name of the variable in your PowerShell script that will hold the queue message. Yes
type Must be queueTrigger for this binding. Yes
direction Must be in for a trigger. Yes
queueName The name of the Azure Queue Storage queue to monitor. Yes
connection The name of the application setting that contains the Azure Queue Storage connection string. Defaults to AzureWebJobsStorage. No
catchUpOnFirstInboundCall Boolean value. If true, the function will process all available messages in the queue on the first inbound call after deployment or restart, even if the queue has been idle. Defaults to false. No
newQueueMessageThreshold Specifies the threshold for the number of new queue messages that will trigger an execution. Defaults to 1. No

PowerShell Script Example

Your PowerShell script will receive the queue message content in the variable specified by the name property in function.json.

run.ps1 Example

param($message)

Write-Host "PowerShell queue trigger function processed message:"
Write-Host $message.MessageContent

# Access message properties if available (e.g., from Blob or HTTP triggers)
# For a simple queue trigger, $message.MessageContent usually contains the raw message string.

# Example: Convert message content to JSON object if it's JSON formatted
try {
    $jsonContent = ConvertFrom-Json -InputObject $message.MessageContent -ErrorAction Stop
    Write-Host "Parsed JSON content:"
    $jsonContent | Format-List
} catch {
    Write-Host "Message content is not valid JSON."
}

# Example: Simulating work
Start-Sleep -Seconds 2

Write-Host "Function execution completed."

Message Object

When a message is received, it's passed to your script as an object. For a Queue Storage trigger, the primary content is usually accessed via the MessageContent property.

Note: The structure of the $message object might vary slightly depending on the Azure Functions runtime version and other bindings used. For a basic queue trigger, expect MessageContent to hold the string payload of the queue message.

Advanced Scenarios

Handling Large Messages

If your queue messages are large, consider using a pattern where the queue message contains a reference (e.g., a URL or blob name) to the actual data stored in Azure Blob Storage. Your function can then retrieve the data from Blob Storage.

Poison Queue Handling

Azure Functions automatically handles retries for queue messages. If a function fails to process a message multiple times, the message can be moved to a "poison queue" for manual inspection. You can configure the maximum retry count via the host.json file.

Batch Processing

For higher throughput, you can configure the trigger to receive messages in batches. This is typically done in host.json.

{
  "version": "2.0",
  "extensions": {
    "queues": {
      "maxPollingInterval": "00:00:00",
      "batchSize": 16,
      "newBatchThreshold": 4,
      "messageHandlerSettings": {
        "maxConcurrentCalls": 16,
        "maxDequeueCount": 5,
        "visibilityTimeout": "00:01:00",
        "processMessagesWaitTimeout": "00:00:10",
        "storageClientSideTimeout": "00:00:05"
      }
    }
  }
}

When batching is enabled, your PowerShell script will receive an array of messages.

Connection Strings

Ensure that the application setting specified in the connection property (e.g., AzureWebJobsStorage) is correctly configured in your Azure Function App's application settings with a valid connection string for your Azure Storage account.

Important: Never hardcode connection strings directly in your function code or function.json. Always use application settings.

Deployment

You can deploy your Azure Functions project, including PowerShell functions, using various methods like Azure CLI, Azure PowerShell, Visual Studio Code with Azure Functions extension, or CI/CD pipelines.

See Also