使用 .NET 列出 blob

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
适用于你的操作系统的最新 .NET SDK。确保获取 SDK，而不是运行时。

设置环境

如果没有现有项目，请查看本部分，其中介绍如何设置项目来使用适用于 .NET 的 Azure Blob 存储客户端库。步骤包括安装包、添加 using 指令，以及创建已授权的客户端对象。有关详细信息，请参阅 Azure Blob 存储和 .NET 入门。

安装软件包

从项目目录中，使用 dotnet add package 命令安装 Azure Blob 存储和 Azure 标识客户端库的包。与 Azure 服务的无密码连接需要 Azure.Identity 包。

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

添加 `using` 指令

将这些 using 指令添加到代码文件的顶部：

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

本文中的某些代码示例可能需要其他 using 指令。

创建客户端对象

若要将应用连接到 Blob 存储，请创建 BlobServiceClient 的实例。以下示例演示如何使用 DefaultAzureCredential 创建客户端对象进行授权：

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

    return client;
}

可以在 .NET 应用中为依赖项注入注册服务客户端。

还可以为特定容器或 Blob 创建客户端对象。要详细了解如何创建和管理客户端对象，请参阅创建和管理与数据资源交互的客户端对象。

授权

授权机制必须具有列出 Blob 所需的权限。要使用 Microsoft Entra ID 进行授权（推荐），你需要具有 Azure RBAC 内置角色 Storage Blob Data Reader 或更高级别的角色。若要了解详细信息，请参阅列出 Blob 对象（REST API）的授权指南。

关于 blob 列出选项

在代码中列出 Blob 时，可以指定多种选项来控制 Azure 存储返回结果的方式。可以指定要在每个结果集中返回的结果数，然后检索后续结果集。可以指定一个前缀，以返回名称以该字符或字符串开头的 blob。你可以按平面列表结构或分层结构列出 Blob。分层列表会返回 Blob，就像它们是按文件夹方式组织的一样。

若要列出存储帐户中的 Blob，请调用以下任一方法：

设置返回结果数量

默认情况下，列表操作一次最多返回 5000 个结果，但你可以指定你所希望的每个列表操作返回的结果数。本文演示的示例说明了如何在页面中返回结果。要详细了解分页概念，请参阅使用适用于 .NET 的 Azure SDK 进行分页。

使用前缀筛选结果

若要筛选 blob 列表，请为 prefix 参数指定一个字符串。前缀字符串可以包含一个或多个字符。然后，Azure 存储只返回其名称以该前缀开头的 Blob。

返回元数据

可以通过为 BlobTraits 枚举指定 Metadata 值，在结果中返回 blob 元数据。

平面列表与分层列表

Azure 存储中的 Blob 以平面范式进行组织，而不是以分层范式（类似于经典文件系统）进行组织。但是，可以将 Blob 组织到虚拟目录中，以便模拟文件夹结构。虚拟目录构成 blob 名称的一部分，并由分隔符表示。

若要将 blob 组织为虚拟目录，请在 blob 名称中使用分隔符。默认分隔符是正斜杠 (/)，但你可以指定任何字符作为分隔符。

如果使用分隔符来命名 Blob，可以选择以分层方式列出 Blob。对于分层列举操作，Azure 存储会返回父对象下的任何虚拟目录和 blob。可以递归方式调用列出操作来遍历层次结构，类似于以编程方式遍历经典文件系统。

使用平面列表

默认情况下，列出操作会以平面列表形式返回 blob。在平面列表中，blob 不按虚拟目录组织。

以下示例通过使用平面列表（并指定可选段大小）列出指定容器中的blob，并将blob名称写入控制台窗口。

private static async Task ListBlobsFlatListing(BlobContainerClient blobContainerClient, 
                                               int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = blobContainerClient.GetBlobsAsync()
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobItem> blobPage in resultSegment)
        {
            foreach (BlobItem blobItem in blobPage.Values)
            {
                Console.WriteLine("Blob name: {0}", blobItem.Name);
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

示例输出类似于：

Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

注意

所显示的示例输出假定你有一个带平面命名空间的存储帐户。如果你为存储账户启用了分层命名空间功能，目录就不是虚拟的。相反，它们是具体的、独立的物体。因此，目录会在列表中显示为零长度 Blob。

使用分层命名空间时，如需了解另一种列出选项，请参阅列出目录内容 (Azure Data Lake Storage)。

使用分层列表

以分层方式调用列出操作时，Azure 存储将返回位于层次结构第一级别的虚拟目录和 Blob。

若要以分层方式列出 blob，请调用 BlobContainerClient.GetBlobsByHierarchy 或 BlobContainerClient.GetBlobsByHierarchyAsync 方法。

以下示例通过层级列表列出指定容器中的blob，并指定可选的段大小，并将blob名称写入控制台窗口。

private static async Task ListBlobsHierarchicalListing(BlobContainerClient container, 
                                                       string prefix, 
                                                       int? segmentSize)
{
    try
    {
        // Call the listing operation and return pages of the specified size.
        var resultSegment = container.GetBlobsByHierarchyAsync(prefix:prefix, delimiter:"/")
            .AsPages(default, segmentSize);

        // Enumerate the blobs returned for each page.
        await foreach (Page<BlobHierarchyItem> blobPage in resultSegment)
        {
            // A hierarchical listing may return both virtual directories and blobs.
            foreach (BlobHierarchyItem blobhierarchyItem in blobPage.Values)
            {
                if (blobhierarchyItem.IsPrefix)
                {
                    // Write out the prefix of the virtual directory.
                    Console.WriteLine("Virtual directory prefix: {0}", blobhierarchyItem.Prefix);

                    // Call recursively with the prefix to traverse the virtual directory.
                    await ListBlobsHierarchicalListing(container, blobhierarchyItem.Prefix, null);
                }
                else
                {
                    // Write out the name of the blob.
                    Console.WriteLine("Blob name: {0}", blobhierarchyItem.Blob.Name);
                }
            }

            Console.WriteLine();
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

示例输出类似于：

Virtual directory prefix: FolderA/
Blob name: FolderA/blob1.txt
Blob name: FolderA/blob2.txt
Blob name: FolderA/blob3.txt

Virtual directory prefix: FolderA/FolderB/
Blob name: FolderA/FolderB/blob1.txt
Blob name: FolderA/FolderB/blob2.txt
Blob name: FolderA/FolderB/blob3.txt

Virtual directory prefix: FolderA/FolderB/FolderC/
Blob name: FolderA/FolderB/FolderC/blob1.txt
Blob name: FolderA/FolderB/FolderC/blob2.txt
Blob name: FolderA/FolderB/FolderC/blob3.txt

注意

Blob 快照无法在分层列出操作中列出。

列出 Blob 的版本或快照

若要列出 blob 版本或快照，请在“版本”或“快照”字段中指定 BlobStates 参数。该服务返回从最旧到最新的版本和快照。

下面的代码示例演示如何列出 blob 版本。

private static void ListBlobVersions(BlobContainerClient blobContainerClient, 
                                           string blobName)
{
    try
    {
        // Call the listing operation, specifying that blob versions are returned.
        // Use the blob name as the prefix. 
        var blobVersions = blobContainerClient.GetBlobs
            (BlobTraits.None, BlobStates.Version, prefix: blobName)
            .OrderByDescending(version => version.VersionId).Where(blob => blob.Name == blobName);

        // Construct the URI for each blob version.
        foreach (var version in blobVersions)
        {
            BlobUriBuilder blobUriBuilder = new BlobUriBuilder(blobContainerClient.Uri)
            {
                BlobName = version.Name,
                VersionId = version.VersionId
            };

            if ((bool)version.IsLatestVersion.GetValueOrDefault())
            {
                Console.WriteLine("Current version: {0}", blobUriBuilder);
            }
            else
            {
                Console.WriteLine("Previous version: {0}", blobUriBuilder);
            }
        }
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine(e.Message);
        Console.ReadLine();
        throw;
    }
}

以 Apache Arrow 格式列出 Blob（预览）

Important

Apache Arrow格式的blob列表目前处于预览阶段。此场景需要 Azure Blob 存储客户端库的 .NET 测试版（预览Azure.Storage.Blobs版，例如 12.30.0-beta.1 或更高版本）。预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。有些功能可能不被支持，或者功能受限。有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

该功能基于现有 List Blobs API。它没有使用默认的 XML，而是使用紧凑的列状 Apache Arrow 格式作为线路上的响应格式。你可以通过在容器列表调用中设置一个选项来启用它。 .NET SDK 在幕后解码 Apache Arrow，但仍然返回相同的BlobItem对象。这种方法在枚举大型容器时提高了列表吞吐量并减少客户端 CPU。它保留了应用程序所依赖的响应合同。

Warning

在启用层级命名空间（Azure Data Lake Storage）的存储账户上，不支持Apache Arrow格式的blob列表。

要请求Apache Arrow格式的结果，将GetBlobsOptions的ResponseFormat属性设置为StorageResponseFormat.Arrow，然后将选项传递给接受 GetBlobsOptions的BlobContainerClient.GetBlobs超载。使用 Apache Arrow 输出时，你还可以设置 StartFrom 和 EndBefore 属性来控制返回路径的范围。

以下示例列出容器中的blobs，并请求以Apache Arrow格式获取结果：

using Azure.Storage;
using Azure.Storage.Blobs.Models;

GetBlobsOptions options = new GetBlobsOptions
{
    Prefix = "FolderA/",
    ResponseFormat = StorageResponseFormat.Arrow
};

foreach (BlobItem blobItem in containerClient.GetBlobs(options))
{
    Console.WriteLine("Blob name: " + blobItem.Name);
}

资源

若要详细了解如何使用适用于 .NET 的 Azure Blob 存储客户端库列出 Blob，请参阅以下资源。

REST API 操作

Azure SDK for .NET 包含基于 Azure REST API 构建的库。通过使用这些库，你可以通过熟悉的 .NET 范式与 REST API 操作交互。用于列出 blob 的客户端库方法使用以下 REST API 操作：

列出 Blob (REST API)

客户端库资源

另请参阅

本文是适用于 .NET 的 Blob 存储开发人员指南的一部分。若要了解详细信息，请参阅生成 .NET 应用中的开发人员指南文章的完整列表。

Last updated on 2026-09-04