Azure Blob storage bindings for Azure Functions overview

Article
06/27/2024

Azure Functions integrates with Azure Storage via triggers and bindings. Integrating with Blob storage allows you to build functions that react to changes in blob data as well as read and write values.

Action	Type
Run a function as blob storage data changes	Trigger
Read blob storage data in a function	Input binding
Allow a function to write blob storage data	Output binding

Install extension

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

Isolated worker model
In-process model

Important

Support will end for the in-process model on November 10, 2026. We highly recommend that you migrate your apps to the isolated worker model for full support.

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:

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

This version introduces the ability to connect using an identity instead of a secret. For a tutorial on configuring your function apps with managed identities, see the creating a function app with identity-based connections tutorial.

This version allows you to bind to types from Azure.Storage.Blobs. Learn more about how these new types are different from WindowsAzure.Storage and Microsoft.Azure.Storage and how to migrate to them from the Azure.Storage.Blobs Migration Guide.

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

Using the .NET CLI:

dotnet add package Microsoft.Azure.WebJobs.Extensions.Storage.Blobs --version 5.0.0

Note

Azure Blobs, Azure Queues, and Azure Tables now use separate extensions and are referenced individually. For example, to use the triggers and bindings for all three services in your .NET in-process app, you should add the following packages to your project:

Previously, the extensions shipped together as Microsoft.Azure.WebJobs.Extensions.Storage, version 4.x. This same package also has a 5.x version, which references the split packages for blobs and queues only. When upgrading your package references from older versions, you may therefore need to additionally reference the new Microsoft.Azure.WebJobs.Extensions.Tables NuGet package. Also, when referencing these newer split packages, make sure you are not referencing an older version of the combined storage package, as this will result in conflicts from two definitions of the same bindings.

Add the extension to your project by installing the Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs NuGet package, version 5.x or later.

Using the .NET CLI:

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

Note

Azure Blobs, Azure Queues, and Azure Tables now use separate extensions and are referenced individually. For example, to use the triggers and bindings for all three services in your .NET isolated-process app, you should add the following packages to your project:

Previously, the extensions shipped together as Microsoft.Azure.Functions.Worker.Extensions.Storage, version 4.x. This same package also has a 5.x version, which references the split packages for blobs and queues only. When upgrading your package references from older versions, you may therefore need to additionally reference the new Microsoft.Azure.Functions.Worker.Extensions.Tables NuGet package. Also, when referencing these newer split packages, make sure you are not referencing an older version of the combined storage package, as this will result in conflicts from two definitions of the same bindings.

If you're writing your application using F#, you must also configure this extension as part of the app's startup configuration. In the call to ConfigureFunctionsWorkerDefaults() or ConfigureFunctionsWebApplication(), add a delegate that takes an IFunctionsWorkerApplication parameter. Then within the body of that delegate, call ConfigureBlobStorageExtension() on the object:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureBlobStorageExtension() |> ignore
) |> ignore

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.

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

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

To learn more, see Update your extensions.

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
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.

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

Binding scenario	Parameter types
Blob trigger	Stream `TextReader` `string` `byte[]` BinaryData BlobClient¹ BlockBlobClient¹ PageBlobClient¹ AppendBlobClient¹ BlobBaseClient¹
Blob input (single blob)	Stream `TextReader` `string` `byte[]` BinaryData BlobClient¹ BlockBlobClient¹ PageBlobClient¹ AppendBlobClient¹ BlobBaseClient¹
Blob input (multiple blobs from a container)	`IEnumerable<T>` where `T` is one of the single blob input binding types
Blob output (single blob)	Stream `TextWriter` `string` `byte[]`
Blob output (multiple blobs)	`ICollector<T>` or `IAsyncCollector<T>` where `T` is one of the single blob output binding types

¹ The client types require the Access property of the attribute to be set to FileAccess.ReadWrite.

For examples using these types, see the GitHub repository for the extension. Learn more about types from the Azure SDK, how they are different from earlier versions, and how to migrate to them from the Azure.Storage.Blobs Migration Guide.

Earlier versions of the extension exposed types from the now deprecated Microsoft.Azure.Storage.Blob namespace. Newer types from Azure.Storage.Blobs are exclusive to extension 5.x and higher.

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

Binding	Parameter types
Blob trigger	Stream `TextReader` `string` `byte[]` ICloudBlob¹ CloudBlockBlob¹ CloudPageBlob¹ CloudAppendBlob¹
Blob input	Stream `TextReader` `string` `byte[]` ICloudBlob¹ CloudBlockBlob¹ CloudPageBlob¹ CloudAppendBlob¹
Blob output	Stream `TextWriter` `string` `byte[]`

¹ These types require the Access property of the attribute to be set to FileAccess.ReadWrite.

² IEnumerable<T> provides an enumeration of blobs in the container. Here, T can be any of the other supported types.

The isolated worker process supports parameter types according to the tables below.

Blob trigger

The blob trigger can bind to the following types:

Type	Description
`string`	The blob content as a string. Use when the blob content is simple text.
`byte[]`	The bytes of the blob content.
JSON serializable types	When a blob contains JSON data, Functions tries to deserialize the JSON data into a plain-old CLR object (POCO) type.
Stream	(Preview¹) An input stream of the blob content.
BlobClient, BlockBlobClient, PageBlobClient, AppendBlobClient, BlobBaseClient	(Preview¹) A client connected to the blob. This offers the most control for processing the blob and can be used to write back to the blob if the connection has sufficient permission.

¹ To use these types, you need to reference Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.1.1-preview2 or later and the common dependencies for SDK type bindings.

Blob input binding

When you want the function to process a single blob, the blob input binding can bind to the following types:

Type	Description
`string`	The blob content as a string. Use when the blob content is simple text.
`byte[]`	The bytes of the blob content.
JSON serializable types	When a blob contains JSON data, Functions tries to deserialize the JSON data into a plain-old CLR object (POCO) type.
Stream	(Preview¹) An input stream of the blob content.
BlobClient, BlockBlobClient, PageBlobClient, AppendBlobClient, BlobBaseClient	(Preview¹) A client connected to the blob. This offers the most control for processing the blob and can be used to write back to it if the connection has sufficient permission.

When you want the function to process multiple blobs from a container, the blob input binding can bind to the following types:

Type Description

T[] or List<T> where T is one of the single blob input binding types An array or list of multiple blobs. Each entry represents one blob from the container. You can also bind to any interfaces implemented by these types, such as IEnumerable<T>.

BlobContainerClient (Preview¹)
A client connected to the container. This offers the most control for processing the container and can be used to write to it if the connection has sufficient permission.

The BlobPath configuration for an input binding to BlobContainerClient currently requires the presence of a blob name. It is not sufficient to provide just the container name. A placeholder value may be used and will not change the behavior. For example, setting [BlobInput("samples-workitems/placeholder.txt")] BlobContainerClient containerClient does not consider whether any placeholder.txt exists or not, and the client will work with the overall "samples-workitems" container.

Type	Description
`T[]` or `List<T>` where `T` is one of the single blob input binding types	An array or list of multiple blobs. Each entry represents one blob from the container. You can also bind to any interfaces implemented by these types, such as `IEnumerable<T>`.
BlobContainerClient	(Preview¹) A client connected to the container. This offers the most control for processing the container and can be used to write to it if the connection has sufficient permission. The `BlobPath` configuration for an input binding to BlobContainerClient currently requires the presence of a blob name. It is not sufficient to provide just the container name. A placeholder value may be used and will not change the behavior. For example, setting `[BlobInput("samples-workitems/placeholder.txt")] BlobContainerClient containerClient` does not consider whether any `placeholder.txt` exists or not, and the client will work with the overall "samples-workitems" container.

¹ To use these types, you need to reference Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 5.1.1-preview2 or later and the common dependencies for SDK type bindings.

Blob output binding

When you want the function to write to a single blob, the blob output binding can bind to the following types:

Type	Description
`string`	The blob content as a string. Use when the blob content is simple text.
`byte[]`	The bytes of the blob content.
JSON serializable types	An object representing the content of a JSON blob. Functions attempts to serialize a plain-old CLR object (POCO) type into JSON data.

When you want the function to write to multiple blobs, the blob output binding can bind to the following types:

Type	Description
`T[]` where `T` is one of the single blob output binding types	An array containing content for multiple blobs. Each entry represents the content of one blob.

For other output scenarios, create and use types from Azure.Storage.Blobs directly.

host.json settings

This section describes the function app configuration settings available for functions that use this binding. These settings only apply when using extension version 5.0.0 and higher. The example host.json file below contains only the version 2.x+ settings for this binding. For more information about function app configuration settings in versions 2.x and later versions, see host.json reference for Azure Functions.

Note

This section doesn't apply to extension versions before 5.0.0. For those earlier versions, there aren't any function app-wide configuration settings for blobs.

{
    "version": "2.0",
    "extensions": {
        "blobs": {
            "maxDegreeOfParallelism": 4,
            "poisonBlobThreshold": 1
        }
    }
}

Property	Default	Description
maxDegreeOfParallelism	8 * (the number of available cores)	The integer number of concurrent invocations allowed for all blob-triggered functions in a given function app. The minimum allowed value is 1.
poisonBlobThreshold	5	The integer number of times to try processing a message before moving it to the poison queue. The minimum allowed value is 1.

AI Skills Fest

Azure Blob storage bindings for Azure Functions overview

Install extension

Install bundle

Binding types

host.json settings

Next steps

Additional resources