Azure Queue storage output bindings for Azure Functions

Azure Functions can create new Azure Queue storage messages by setting up an output binding.

For information on setup and configuration details, see the overview.

Example

The following example shows a C# function that creates a queue message for each HTTP request received.

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

Attributes and annotations

In C# class libraries, use the QueueAttribute.

The attribute applies to an out parameter or the return value of the function. The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

For a complete example, see Output example.

You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. For more information, see Trigger - attributes.

Configuration

The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

function.json property Attribute property Description
type n/a Must be set to queue. This property is set automatically when you create the trigger in the Azure portal.
direction n/a Must be set to out. This property is set automatically when you create the trigger in the Azure portal.
name n/a The name of the variable that represents the queue in function code. Set to $return to reference the function return value.
queueName QueueName The name of the queue.
connection Connection The name of an app setting or setting collection that specifies how to connect to Azure Queues. See Connections.

When you're developing locally, app settings go into the local.settings.json file.

Connections

The connection property is a reference to environment configuration which specifies how the app should connect to Azure Queues. It may specify:

If the configured value is both an exact match for a single setting and a prefix match for other settings, the exact match is used.

Connection string

To obtain a connection string, follow the steps shown at Manage storage account access keys.

This connection string should be stored in an application setting with a name matching the value specified by the connection property of the binding configuration.

If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

Identity-based connections

If you are using version 5.x or higher of the extension, instead of using a connection string with a secret, you can have the app use an Azure Active Directory identity. To do this, you would define settings under a common prefix which maps to the connection property in the trigger and binding configuration.

In this mode, the extension requires the following properties:

Property Environment variable template Description Example value
Queue Service URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 The data plane URI of the queue service to which you are connecting, using the HTTPS scheme. https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri can be used as an alias. If both forms are provided, the queueServiceUri form will be used. The serviceUri form cannot be used when the overall connection configuration is to be used across blobs, queues, and/or tables.

Additional properties may be set to customize the connection. See Common properties for identity-based connections.

When hosted in the Azure Functions service, identity-based connections use a managed identity. The system-assigned identity is used by default, although a user-assigned identity can be specified with the credential and clientID properties. When run in other contexts, such as local development, your developer identity is used instead, although this can be customized. See Local development with identity-based connections.

Grant permission to the identity

Whatever identity is being used must have permissions to perform the intended actions. You will need to assign a role in Azure RBAC, using either built-in or custom roles which provide those permissions.

Important

Some permissions might be exposed by the target service that are not necessary for all contexts. Where possible, adhere to the principle of least privilege, granting the identity only required privileges. For example, if the app only needs to be able to read from a data source, use a role that only has permission to read. It would be inappropriate to assign a role that also allows writing to that service, as this would be excessive permission for a read operation. Similarly, you would want to ensure the role assignment is scoped only over the resources that need to be read.

You will need to create a role assignment that provides access to your queue at runtime. Management roles like Owner are not sufficient. The following table shows built-in roles that are recommended when using the Queue Storage extension in normal operation. Your application may require additional permissions based on the code you write.

Binding type Example built-in roles
Trigger Storage Queue Data Reader, Storage Queue Data Message Processor
Output binding Storage Queue Data Contributor, Storage Queue Data Message Sender

Usage

Default

Write a single queue message by using a method parameter such as out T paramName. You can use the method return type instead of an out parameter, and T can be any of the following types:

If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

In C# and C# script, write multiple queue messages by using one of the following types:

Additional types

Apps using the 5.0.0 or higher version of the Storage extension may also use types from the Azure SDK for .NET. This version drops support for the legacy CloudQueue and CloudQueueMessage types in favor of the following types:

For examples using these types, see the GitHub repository for the extension.

Exceptions and return codes

Binding Reference
Queue Queue Error Codes
Blob, Table, Queue Storage Error Codes
Blob, Table, Queue Troubleshooting

Next steps