使用 .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 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 内置角色“存储 Blob 数据读取者”或更高级别的角色。 若要了解详细信息，请参阅获取 Blob (REST API) 的授权指南。

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

• DownloadTo
• DownloadToAsync
• DownloadContent -DownloadContentAsync

你还可以打开一个流来读取 Blob。 流只在被读取时下载 Blob。 可以使用以下方法之一：

• OpenRead
• OpenReadAsync

以下示例将 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 时，可以定义客户端库配置选项。 可以对这些选项进行调整，以提高性能和可靠性。 以下代码示例演示如何在调用下载方法时使用 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();
}

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

可以指定传输验证选项，以帮助确保正确下载数据并且在传输过程中未被篡改。 可以使用 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 定义的校验和算法的可用选项：

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

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

Azure SDK for .NET 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 .NET 范例与 REST API 操作进行交互。 用于下载 blob 的客户端库方法使用以下 REST API 操作：

• 获取 Blob (REST API)

• 客户端库参考文档
• 客户端库源代码
• 包 (NuGet)

• 上传和下载的性能优化。

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