Skip to content

Latest commit

 

History

History
261 lines (156 loc) · 12.9 KB

functions-bindings-storage-queue.md

File metadata and controls

261 lines (156 loc) · 12.9 KB
Raw
title description ms.topic ms.custom ms.date zone_pivot_groups
Azure Queue storage trigger and bindings for Azure Functions overview
Understand how to use the Azure Queue storage trigger and output binding in Azure Functions.
reference
devx-track-extended-java, devx-track-js, devx-track-python, devx-track-ts
11/11/2022
programming-languages-set-functions

Azure Queue storage trigger and bindings for Azure Functions overview

Azure Functions can run as new Azure Queue storage messages are created and can write queue messages within a function.

Action Type
Run a function as queue storage data changes Trigger
Write queue storage messages Output binding

::: zone pivot="programming-language-csharp"

Install extension

The extension NuGet package you install depends on the C# mode you're using in your function app:

Isolated worker model

Functions execute in an isolated C# worker process. To learn more, see Guide for running C# Azure Functions in an isolated worker process.

In-process model

[!INCLUDE functions-in-process-model-retirement-note]

Functions execute in the same process as the Functions host. To learn more, see Develop C# class library functions using Azure Functions.

In a variation of this model, Functions can be run using C# scripting, which is supported primarily for C# portal editing. To update existing binding extensions for C# script apps running in the portal without having to republish your function app, see Update your extensions.

The functionality of the extension varies depending on the extension version:

Extension 5.x+

This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 4.x.

[!INCLUDE functions-bindings-supports-identity-connections-note]

This version allows you to bind to types from Azure.Storage.Queues.

This extension is available by installing the Microsoft.Azure.WebJobs.Extensions.Storage.Queues NuGet package, version 5.x.

Using the .NET CLI:

dotnet add package Microsoft.Azure.WebJobs.Extensions.Storage.Queues

[!INCLUDE functions-bindings-storage-extension-v5-tables-note]

Functions 2.x+

This section describes using a class library. For C# scripting, you would need to instead install the extension bundle, version 2.x.

Working with the trigger and bindings requires that you reference the appropriate NuGet package. Install the NuGet package, version 3.x or 4.x.

Functions 1.x

[!INCLUDE functions-runtime-1x-retirement-note]

Functions 1.x apps automatically have a reference the Microsoft.Azure.WebJobs NuGet package, version 2.x.

[!INCLUDE functions-storage-sdk-version]

Extension 5.x+

[!INCLUDE functions-bindings-supports-identity-connections-note]

This version allows you to bind to types from Azure.Storage.Queues.

This version supports configuration of triggers and bindings through .NET Aspire integration.

Add the extension to your project by installing the NuGet package, version 5.x.

Using the .NET CLI:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

[!INCLUDE functions-bindings-storage-extension-v5-isolated-worker-tables-note]

Functions 2.x+

Add the extension to your project by installing the NuGet package, version 4.x.

Functions 1.x

Functions version 1.x doesn't support the isolated worker process.

::: zone-end

::: zone pivot="programming-language-javascript,programming-language-typescript,programming-language-python,programming-language-java,programming-language-powershell"

Install bundle

The Blob storage binding is part of an extension bundle, which is specified in your host.json project file. You may need to modify this bundle to change the version of the binding, or if bundles aren't already installed. To learn more, see extension bundle.

Bundle v3.x

[!INCLUDE functions-bindings-supports-identity-connections-note]

You can add this version of the extension from the preview extension bundle v3 by adding or replacing the following code in your host.json file:

[!INCLUDE functions-extension-bundles-json-v3]

To learn more, see Update your extensions.

Bundle v2.x

You can install this version of the extension in your function app by registering the extension bundle, version 2.x.

Functions 1.x

Functions 1.x apps automatically have a reference to the extension.

::: zone-end

::: zone pivot="programming-language-csharp"

Binding types

The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following:

Isolated worker model

An isolated worker process class library compiled C# function runs in a process isolated from the runtime.

In-process model

An in-process class library is a compiled C# function runs in the same process as the Functions runtime.

Choose a version to see binding type details for the mode and version.

Extension 5.x+

The Azure Queues extension supports parameter types according to the table below.

Binding scenario Parameter types
Queue trigger QueueMessage
JSON serializable types1
string
byte[]
BinaryData
Queue output (single message) QueueMessage
JSON serializable types1
string
byte[]
BinaryData
Queue output (multiple messages) QueueClient
ICollector<T> or IAsyncCollector<T> where T is one of the single message types

1 Messages containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

Functions 2.x+

Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.Storage.Queues namespace. Newer types from Azure.Storage.Queues are exclusive to Extension 5.x+.

This version of the extension supports parameter types according to the table below.

Binding scenario Parameter types
Queue trigger CloudQueueMessage
JSON serializable types1
string
byte[]
Queue output CloudQueueMessage
JSON serializable types1
string
byte[]
CloudQueue

1 Messages containing JSON data can be deserialized into known plain-old CLR object (POCO) types.

Functions 1.x

Functions 1.x exposed types from the deprecated Microsoft.WindowsAzure.Storage namespace. Newer types from Azure.Storage.Queues are exclusive to the Extension 5.x+. To use these, you will need to upgrade your application to Functions 4.x.

Extension 5.x+

The isolated worker process supports parameter types according to the tables below. Support for binding to types from Azure.Storage.Queues is in preview.

Queue trigger

[!INCLUDE functions-bindings-storage-queue-trigger-dotnet-isolated-types]

Queue output binding

[!INCLUDE functions-bindings-storage-queue-output-dotnet-isolated-types]

Functions 2.x+

Earlier versions of extensions in the isolated worker process only support binding to string types. Additional options are available to the Extension 5.x.

Functions 1.x

Functions version 1.x doesn't support the isolated worker process. To use the isolated worker model, upgrade your application to Functions 4.x.

:::zone-end

host.json settings

[!INCLUDE functions-host-json-section-intro]

Note

For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
Property Default Description
maxPollingInterval 00:01:00 The maximum interval between queue polls. The minimum interval is 00:00:00.100 (100 ms). Intervals increment up to maxPollingInterval. The default value of maxPollingInterval is 00:01:00 (1 min). maxPollingInterval must not be less than 00:00:00.100 (100 ms). In Functions 2.x and later, the data type is a TimeSpan. In Functions 1.x, it is in milliseconds.
visibilityTimeout 00:00:00 The time interval between retries when processing of a message fails.
batchSize 16 The number of queue messages that the Functions runtime retrieves simultaneously and processes in parallel. When the number being processed gets down to the newBatchThreshold, the runtime gets another batch and starts processing those messages. So the maximum number of concurrent messages being processed per function is batchSize plus newBatchThreshold. This limit applies separately to each queue-triggered function.

If you want to avoid parallel execution for messages received on one queue, you can set batchSize to 1. However, this setting eliminates concurrency as long as your function app runs only on a single virtual machine (VM). If the function app scales out to multiple VMs, each VM could run one instance of each queue-triggered function.

The maximum batchSize is 32.
maxDequeueCount 5 The number of times to try processing a message before moving it to the poison queue.
newBatchThreshold N*batchSize/2 Whenever the number of messages being processed concurrently gets down to this number, the runtime retrieves another batch.

N represents the number of vCPUs available when running on App Service or Premium Plans. Its value is 1 for the Consumption Plan.
messageEncoding base64 This setting is only available in extension bundle version 5.0.0 and higher. It represents the encoding format for messages. Valid values are base64 and none.

Next steps