使用 .NET 下載 Blob

• .NET
• Java
• JavaScript
• Python
• Go

本文說明如何使用適用於 .NET 的 Azure 儲存體用戶端程式庫來下載 Blob。 您可以將 Blob 資料下載到各種目的地，包括本機檔案路徑、串流或文字字串。 您也可以開啟 Blob 串流並從中讀取。

必要條件

• Azure 訂用帳戶 - 建立免費帳戶
• Azure 儲存體帳戶 - 建立儲存體帳戶
• 適用於您作業系統的最新 .NET SDK。 請務必取得 SDK，而不是執行階段。

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫。 這些步驟包括封裝安裝、新增 using 指示詞，以及建立已授權的用戶端物件。 如需詳細資訊，請參閱 開始使用 Azure Blob 儲存體和 .NET。

安裝套件

從您的專案目錄中，使用 dotnet add package 命令安裝 Azure Blob 儲存體和 Azure 身分識別客戶端程式庫的套件。 需要 Azure.Identity 套件才能對 Azure 服務進行無密碼連線。

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.windows.net"),
        new DefaultAzureCredential());

    return client;
}

您可以在 .NET 應用程式中註冊相依性插入的服務用戶端。

您也可以為特定容器或 Blob 建立客戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

授權

授權機制必須具有執行下載作業的必要權限。 針對使用 Microsoft Entra ID 的授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 Blob 資料讀者或更高的權限。 若要深入了解，請參閱取得 Blob (REST API) 的授權指導。

下載 Blob

您可以使用下列任一方法來下載 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);
}

下載至串流

下列範例下載 Blob 的方式為建立 Stream 物件，然後下載至該串流。 如果指定的目錄不存在，程式碼會擲回 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();
}

若要深入了解微調資料傳輸選項，請參閱上傳和下載的效能微調。

指定下載時的傳輸驗證選項

您可以指定傳輸驗證選項，協助確保資料已正確下載，且傳輸期間未遭到竄改。 您可以使用 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	建議使用。 允許程式庫選擇演算法。 不同的程式庫版本可能會選擇不同的演算法。
無	1	未選取演算法。 請勿計算或要求總和檢查碼。
MD5	2	標準 MD5 雜湊演算法。
StorageCrc64	3	Azure 儲存體自訂 64 位元 CRC。

資源

若要深入了解如何使用適用於 .NET 的 Azure Blob 儲存體用戶端程式庫下載 Blob，請參閱下列資源。

程式碼範例

• 檢視本文中的程式碼範例 (GitHub) (英文)

REST API 操作

適用於 .NET 的 Azure SDK 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 .NET 範例與 REST API 作業進行互動。 用來下載 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

• 取得 Blob (REST API)

用戶端程式庫資源

• 用戶端程式庫參考文件
• 用戶端程式庫原始程式碼
• 套件 (NuGet)

另請參閱

• 上傳和下載的效能微調。

相關內容

• 本文是適用於 .NET 的 Blob 儲存體開發人員指南的一部分。 若要深入了解，請參閱位於建置 .NET 應用程式的開發人員指南文章完整清單。