Microsoft.Azure.WebJobs.Extensions.Storage.Blobs 5.3.0-beta.1

Azure WebJobs Storage Blobs client library for .NET

This extension provides functionality for accessing Azure Storage Blobs in Azure Functions within the process.

Getting started

Install the package

Install the Storage Blobs extension with NuGet:

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

Prerequisites

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az storage account create --name <your-resource-name> --resource-group <your-resource-group-name> --location westus --sku Standard_LRS

Authenticate the client

In order for the extension to access Blobs, you will need the connection string which can be found in the Azure Portal or by using the Azure CLI snippet below.

az storage account show-connection-string -g <your-resource-group-name> -n <your-resource-name>

The connection string can be supplied through AzureWebJobsStorage app setting.

Key concepts

Using Blob trigger

The Blob storage trigger starts a function when a new or updated blob is detected. The blob contents are provided as input to the function.

Please follow the tutorial to learn about triggering an Azure Function when a blob is modified.

Listening strategies

Blob trigger offers handful of strategies when it comes to listening to blob creation and modification. The strategy can be customized by specifying Source property of the BlobTrigger (see examples below).

Default strategy

By default blob trigger uses polling which works as a hybrid between inspecting Azure Storage analytics logging and running periodic container scans. Blobs are scanned in groups of 10,000 at a time with a continuation token used between intervals.

Azure Storage analytics logging is not enabled by default, see Azure Storage analytics logging for how to enable it.

This strategy is not recommended for high-scale applications or scenarios that require low latency.

Event grid

Blob storage events can be used to listen for changes. This strategy requires additional setup.

This strategy is recommended for high-scale applications.

Using Blob binding

The input binding allows you to read blob storage data as input to an Azure Function. The output binding allows you to modify and delete blob storage data in an Azure Function.

Please follow the input binding tutorial and output binding tutorial to learn about using this extension for accessing Blobs.

Examples

Reacting to blob change

Default strategy

public static class BlobFunction_ReactToBlobChange
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob")] Stream blobStream,
        ILogger logger)
    {
        using var blobStreamReader = new StreamReader(blobStream);
        logger.LogInformation("Blob sample-container/sample-blob has been updated with content: {content}", blobStreamReader.ReadToEnd());
    }
}

Event Grid strategy

public static class BlobFunction_ReactToBlobChange_EventGrid
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob", Source = BlobTriggerSource.EventGrid)] Stream blobStream,
        ILogger logger)
    {
        using var blobStreamReader = new StreamReader(blobStream);
        logger.LogInformation("Blob sample-container/sample-blob has been updated with content: {content}", blobStreamReader.ReadToEnd());
    }
}

Reading from stream

public static class BlobFunction_ReadStream
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob-1")] Stream blobStream1,
        [Blob("sample-container/sample-blob-2", FileAccess.Read)] Stream blobStream2,
        ILogger logger)
    {
        using var blobStreamReader1 = new StreamReader(blobStream1);
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated with content: {content}", blobStreamReader1.ReadToEnd());
        using var blobStreamReader2 = new StreamReader(blobStream2);
        logger.LogInformation("Blob sample-container/sample-blob-2 has content: {content}", blobStreamReader2.ReadToEnd());
    }
}

Writing to stream

public static class BlobFunction_WriteStream
{
    [FunctionName("BlobFunction")]
    public static async Task Run(
        [BlobTrigger("sample-container/sample-blob-1")] Stream blobStream1,
        [Blob("sample-container/sample-blob-2", FileAccess.Write)] Stream blobStream2,
        ILogger logger)
    {
        await blobStream1.CopyToAsync(blobStream2);
        logger.LogInformation("Blob sample-container/sample-blob-1 has been copied to sample-container/sample-blob-2");
    }
}

Binding to string

public static class BlobFunction_String
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob-1")] string blobContent1,
        [Blob("sample-container/sample-blob-2")] string blobContent2,
        ILogger logger)
    {
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated with content: {content}", blobContent1);
        logger.LogInformation("Blob sample-container/sample-blob-2 has content: {content}", blobContent2);
    }
}

Writing string to blob

public static class BlobFunction_String_Write
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob-1")] string blobContent1,
        [Blob("sample-container/sample-blob-2")] out string blobContent2,
        ILogger logger)
    {
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated with content: {content}", blobContent1);
        blobContent2 = blobContent1;
        logger.LogInformation("Blob sample-container/sample-blob-1 has been copied to sample-container/sample-blob-2");
    }
}

Binding to byte array

public static class BlobFunction_ByteArray
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob-1")] byte[] blobContent1,
        [Blob("sample-container/sample-blob-2")] byte[] blobContent2,
        ILogger logger)
    {
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated with content: {content}", Encoding.UTF8.GetString(blobContent1));
        logger.LogInformation("Blob sample-container/sample-blob-2 has content: {content}", Encoding.UTF8.GetString(blobContent2));
    }
}

Writing byte array to blob

public static class BlobFunction_ByteArray_Write
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob-1")] byte[] blobContent1,
        [Blob("sample-container/sample-blob-2")] out byte[] blobContent2,
        ILogger logger)
    {
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated with content: {content}", Encoding.UTF8.GetString(blobContent1));
        blobContent2 = blobContent1;
        logger.LogInformation("Blob sample-container/sample-blob-1 has been copied to sample-container/sample-blob-2");
    }
}

Binding to TextReader and TextWriter

public static class BlobFunction_TextReader_TextWriter
{
    [FunctionName("BlobFunction")]
    public static async Task Run(
        [BlobTrigger("sample-container/sample-blob-1")] TextReader blobContentReader1,
        [Blob("sample-container/sample-blob-2")] TextWriter blobContentWriter2,
        ILogger logger)
    {
        while (blobContentReader1.Peek() >= 0)
        {
            await blobContentWriter2.WriteLineAsync(await blobContentReader1.ReadLineAsync());
        }
        logger.LogInformation("Blob sample-container/sample-blob-1 has been copied to sample-container/sample-blob-2");
    }
}

Binding to Azure Storage Blob SDK types

public static class BlobFunction_BlobClient
{
    [FunctionName("BlobFunction")]
    public static async Task Run(
        [BlobTrigger("sample-container/sample-blob-1")] BlobClient blobClient1,
        [Blob("sample-container/sample-blob-2")] BlobClient blobClient2,
        ILogger logger)
    {
        BlobProperties blobProperties1 = await blobClient1.GetPropertiesAsync();
        logger.LogInformation("Blob sample-container/sample-blob-1 has been updated on: {datetime}", blobProperties1.LastModified);
        BlobProperties blobProperties2 = await blobClient2.GetPropertiesAsync();
        logger.LogInformation("Blob sample-container/sample-blob-2 has been updated on: {datetime}", blobProperties2.LastModified);
    }
}

Accessing Blob container

public static class BlobFunction_AccessContainer
{
    [FunctionName("BlobFunction")]
    public static async Task Run(
        [BlobTrigger("sample-container/sample-blob")] Stream blobStream,
        [Blob("sample-container")] BlobContainerClient blobContainerClient,
        ILogger logger)
    {
        logger.LogInformation("Blobs within container:");
        await foreach (BlobItem blobItem in blobContainerClient.GetBlobsAsync())
        {
            logger.LogInformation(blobItem.Name);
        }
    }
}

Enumerating blobs in container

public static class BlobFunction_EnumerateBlobs_Stream
{
    [FunctionName("BlobFunction")]
    public static async Task Run(
        [BlobTrigger("sample-container/sample-blob")] Stream blobStream,
        [Blob("sample-container")] IEnumerable<Stream> blobs,
        ILogger logger)
    {
        logger.LogInformation("Blobs contents within container:");
        foreach (Stream content in blobs)
        {
            using var blobStreamReader = new StreamReader(content);
            logger.LogInformation(await blobStreamReader.ReadToEndAsync());
        }
    }
}

public static class BlobFunction_EnumerateBlobs_BlobClient
{
    [FunctionName("BlobFunction")]
    public static void Run(
        [BlobTrigger("sample-container/sample-blob")] Stream blobStream,
        [Blob("sample-container")] IEnumerable<BlobClient> blobs,
        ILogger logger)
    {
        logger.LogInformation("Blobs within container:");
        foreach (BlobClient blob in blobs)
        {
            logger.LogInformation(blob.Name);
        }
    }
}

Configuring the extension

Please refer to sample functions app.

Troubleshooting

Please refer to Monitor Azure Functions for troubleshooting guidance.

Next steps

Read the introduction to Azure Function or creating an Azure Function guide.

Contributing

See the Storage CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.