使用 .NET 下载 Blob

本文介绍了如何使用适用于 .NET 的 Azure 存储客户端库下载 Blob。可以将 Blob 数据下载到各种目标，包括本地文件路径、流或文本字符串。还可以打开 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 创建客户端对象。要详细了解如何创建和管理客户端对象，请参阅创建和管理与数据资源交互的客户端对象。

授权

授权机制必须具有执行下载操作所需的权限。若要使用 Microsoft Entra ID 进行授权（推荐），则需要具有 Azure RBAC 内置角色 Storage Blob Data Reader 或更高权限。若要了解详细信息，请参阅获取 Blob (REST API) 的授权指南。

下载 Blob 对象

可以使用以下任一方法来下载 Blob：

你还可以打开一个流以从 Blob 中读取数据。只有在读取该流时，才会下载 blob。可以使用以下方法之一：

下载到指定文件路径

以下示例将 blob 下载到本地文件路径。如果指定的目录不存在，则代码将引发 DirectoryNotFoundException。如果该文件已存在于 localFilePath，后续下载过程则会默认覆盖该文件。

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

下载到流中

以下示例通过创建 Stream 对象，然后将 blob 下载到该流中。如果指定的目录不存在，则代码将引发 DirectoryNotFoundException。

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

下载为字符串

以下示例假定 Blob 是文本文件，并将 Blob 下载为字符串：

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

从流中下载

以下示例通过从流中读取数据来下载 blob：

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

使用配置选项下载块 Blob

下载 blob 时，可以定义客户端库配置选项。可以对这些选项进行调整，以提高性能和可靠性。以下代码示例演示如何在调用下载方法时使用 BlobDownloadToOptions 来定义配置选项。请注意，相同的选项同样适用于 BlobDownloadOptions。

在下载时指定数据传输选项

可以在 StorageTransferOptions 中配置值，以提高数据传输操作的性能。下面的代码示例演示如何设置 StorageTransferOptions 的值，以及如何将选项作为 BlobDownloadToOptions 实例的一部分包含在内。此示例中提供的值不作为建议。若要正确优化这些值，需要考虑应用的特定需求。

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var transferOptions = new StorageTransferOptions
    {
        // Set the maximum number of parallel transfer workers
        MaximumConcurrency = 2,

        // Set the initial transfer length to 8 MiB
        InitialTransferSize = 8 * 1024 * 1024,

        // Set the maximum length of a transfer to 4 MiB
        MaximumTransferSize = 4 * 1024 * 1024
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

若要详细了解如何优化数据传输选项，请参阅上传和下载的性能优化。

在下载时指定传输验证选项

使用 CRC64 的传输验证为Azure Blob 存储提供客户端级数据完整性，使你能够验证应用程序发送的数据是否与从Azure中存储和读取的数据相同。启用后，Blob SDK 会在上传和下载操作期间计算并验证 CRC64 校验和，而服务会独立计算并验证其接收和返回的数据的 CRC64 校验和。对每个请求以及整个数据流进行验证，确保即使数据以分区方式传输（如块上传或范围读取），整个 Blob 也都能得到验证。有关更多详细信息，请参阅结构化正文格式。

可以使用 MD5 传输验证来验证应用程序发送的数据是否与服务在每个请求上收到的和返回的数据匹配。启用后，Blob SDK 会在上传和下载操作期间计算和验证 MD5 哈希，而服务独立计算并验证它处理的数据的 MD5 哈希。验证在 HTTP 请求和响应级别执行，帮助检测每个传输的数据段的损坏，例如上传期间的各个块或读取过程中的范围。

可以使用 BlobClientOptions 在客户端级别定义传输验证选项，它会将验证选项应用于从 BlobClient 实例调用的所有方法。或者，可以使用 BlobDownloadToOptions 替代方法级别的传输验证选项。下面的代码示例演示如何创建 BlobDownloadToOptions 对象并指定用于生成校验和的算法。

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

下表列出了由 StorageChecksumAlgorithm 定义的校验和算法可用选项：

名称	值	说明
自动	0	推荐。允许库选择算法。不同的库版本可能会选择不同的算法。在客户端库版本 12.28.0+ 中自动选择 StorageCrc64
无	1	没有选定的算法。不要计算或请求校验和。
MD5	2	标准 MD5 哈希算法。
StorageCrc64	3	Azure 存储自定义 64 位 CRC。

资源

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

代码示例

查看本文中的代码示例 (GitHub)

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-07-02