Use blob index tags to manage and find data with .NET

  • Article

This article shows how to use blob index tags to manage and find data using the Azure Storage client library for .NET.

Prerequisites

Set up your environment

If you don't have an existing project, this section shows you how to set up a project to work with the Azure Blob Storage client library for .NET. The steps include package installation, adding using directives, and creating an authorized client object. For details, see Get started with Azure Blob Storage and .NET.

Install packages

From your project directory, install packages for the Azure Blob Storage and Azure Identity client libraries using the dotnet add package command. The Azure.Identity package is needed for passwordless connections to Azure services.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Add using directives

Add these using directives to the top of your code file:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Some code examples in this article might require additional using directives.

Create a client object

To connect an app to Blob Storage, create an instance of BlobServiceClient. The following example shows how to create a client object using DefaultAzureCredential for authorization:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.chinacloudapi.cn"),
        new DefaultAzureCredential());

    return client;
}

You can register a service client for dependency injection in a .NET app.

You can also create client objects for specific containers or blobs. To learn more about creating and managing client objects, see Create and manage client objects that interact with data resources.

Authorization

The authorization mechanism must have the necessary permissions to work with blob index tags. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Owner or higher. To learn more, see the authorization guidance for Get Blob Tags (REST API), Set Blob Tags (REST API), or Find Blobs by Tags (REST API).

About blob index tags

Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data. This article shows you how to set, get, and find data using blob index tags.

Blob index tags aren't supported for storage accounts with hierarchical namespace enabled. To learn more about the blob index tag feature along with known issues and limitations, see Manage and find Azure Blob data with blob index tags.

Set tags

You can set index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Setting blob index tags.

You can set tags by using either of the following methods:

The following example performs this task.

public static async Task SetTags(BlobClient blobClient)
{
    Dictionary<string, string> tags = 
        new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.SetTagsAsync(tags);
}

You can delete all tags by passing an empty [Dictionary] into the SetTags or SetTagsAsync method as shown in the following example.

Dictionary<string, string> noTags = new Dictionary<string, string>();
await blobClient.SetTagsAsync(noTags);
Related articles
Manage and find Azure Blob data with blob index tags
Set Blob Tags (REST API)

Get tags

You can get index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Getting and listing blob index tags.

You can get tags by using either of the following methods:

The following example performs this task.

public static async Task GetTags(BlobClient blobClient)
{
    Response<GetBlobTagResult> tagsResponse = await blobClient.GetTagsAsync();

    foreach (KeyValuePair<string, string> tag in tagsResponse.Value.Tags)
    {
        Console.WriteLine($"{tag.Key}={tag.Value}");
    }
}

Filter and find data with blob index tags

You can use index tags to find and filter data if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Finding data using blob index tags.

Note

You can't use index tags to retrieve previous versions. Tags for previous versions aren't passed to the blob index engine. For more information, see Conditions and known issues.

You can find data by using either of the following methods:

The following example finds all blobs tagged with a date that falls between a specific range.

public static async Task FindBlobsbyTags(BlobServiceClient serviceClient)
{
    string query = @"""Date"" >= '2020-04-20' AND ""Date"" <= '2020-04-30'";

    // Find Blobs given a tags query
    Console.WriteLine("Find Blob by Tags query: " + query + Environment.NewLine);

    List<TaggedBlobItem> blobs = new List<TaggedBlobItem>();
    await foreach (TaggedBlobItem taggedBlobItem in serviceClient.FindBlobsByTagsAsync(query))
    {
        blobs.Add(taggedBlobItem);
    }

    foreach (var filteredBlob in blobs)
    {
        
        Console.WriteLine($"BlobIndex result: ContainerName= {filteredBlob.BlobContainerName}, " +
            $"BlobName= {filteredBlob.BlobName}");
    }

}

Resources

To learn more about how to use index tags to manage and find data using the Azure Blob Storage client library for .NET, see the following resources.

REST API operations

The Azure SDK for .NET contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar .NET paradigms. The client library methods for managing and using blob index tags use the following REST API operations:

Client library resources

See also

Related content

  • This article is part of the Blob Storage developer guide for .NET. To learn more, see the full list of developer guide articles at Build your .NET app.