Herunterladen eines Blobs mit .NET

In diesem Artikel wird beschrieben, wie ein Blob mithilfe der Azure Storage-Clientbibliothek für .NET heruntergeladen wird. Sie können Blobdaten an verschiedene Ziele herunterladen, einschließlich einen lokalen Dateipfad, einen Stream oder eine Textzeichenfolge. Sie können auch einen Blobstream öffnen und daraus lesen.

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit der Azure Blob Storage-Clientbibliothek für .NET einrichten. Die Schritte umfassen die Paketinstallation, das Hinzufügen von using-Anweisungen und das Erstellen eines autorisierten Clientobjekts. Ausführlichere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage und .NET.

Installieren von Paketen

Installieren Sie in Ihrem Projektverzeichnis mithilfe des Befehls dotnet add package Pakete für die Azure Blob Storage- und Azure Identity-Clientbibliotheken. Für kennwortlose Verbindungen mit Azure-Diensten wird das Azure.Identity-Paket benötigt.

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

Fügen Sie Anweisungen vom Typ using hinzu.

Fügen Sie diese using-Anweisungen am Anfang der Codedatei hinzu:

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

Einige Codebeispiele in diesem Artikel erfordern möglicherweise zusätzliche using-Anweisungen.

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie eine Instanz von BlobServiceClient. Das folgende Beispiel zeigt, wie Sie ein Clientobjekt mithilfe von DefaultAzureCredential für die Autorisierung erstellen:

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

    return client;
}

Sie können einen Dienstclient für die Abhängigkeitsinjektion in einer .NET-App registrieren.

Sie können auch Clientobjekte für bestimmte Container oder Blobs erstellen. Weitere Informationen zum Erstellen und Verwalten von Clientobjekten finden Sie unter Erstellen und Verwalten von Clientobjekten, die mit Datenressourcen interagieren.

Autorisierung

Der Autorisierungsmechanismus muss über die erforderlichen Berechtigungen zum Ausführen eines Downloadvorgangs verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Storage-Blobdatenleser. Weitere Informationen finden Sie im Autorisierungsleitfaden für Abrufen des Blobs (REST-API).

Herunterladen eines Blobs

Sie können eine der folgenden Methoden verwenden, um ein Blob herunterzuladen:

Sie können auch einen Stream öffnen, um aus einem Blob zu lesen. Der Stream lädt das Blob nur herunter, während aus dem Stream gelesen wird. Dazu können Sie eine der folgenden Methoden verwenden:

Herunterladen in einen Dateipfad

Das folgende Beispiel lädt ein Blob in einen lokalen Dateipfad herunter. Wenn das angegebene Verzeichnis nicht vorhanden ist, gibt der Code eine DirectoryNotFoundException aus. Wenn die Datei bereits in localFilePath vorhanden ist, wird sie während nachfolgender Downloads standardmäßig überschrieben.

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

Herunterladen in einen Stream

Im folgenden Beispiel wird ein Blob heruntergeladen, indem ein Stream-Objekt erstellt und dann in diesen Stream heruntergeladen wird. Wenn das angegebene Verzeichnis nicht vorhanden ist, gibt der Code eine DirectoryNotFoundException aus.

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

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Herunterladen in eine Zeichenfolge

Im folgenden Beispiel wird davon ausgegangen, dass es sich bei dem Blob um eine Textdatei handelt, und das Blob wird in eine Zeichenfolge heruntergeladen:

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

Herunterladen aus einem Stream

Im folgenden Beispiel wird ein Blob heruntergeladen, indem aus einem Stream gelesen wird:

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

Herunterladen eines Blockblobs mit Konfigurationsoptionen

Beim Herunterladen eines Blobs können Sie Konfigurationsoptionen für die Clientbibliothek definieren. Diese Optionen können feiner abgestimmt werden, um die Leistung und Zuverlässigkeit zu verbessern. In den folgenden Codebeispielen wird gezeigt, wie Sie Konfigurationsoptionen mithilfe von BlobUploadOptions beim Aufrufen einer Downloadmethode definieren. Beachten Sie, dass dieselben Optionen für BlobDownloadOptions verfügbar sind.

Angeben von Datenübertragungsoptionen beim Download

Sie können die Werte in StorageTransferOptions konfigurieren, um die Leistung für Datenübertragungsvorgänge zu verbessern. Im folgenden Codebeispiel wird gezeigt, wie Sie Werte für StorageTransferOptions festlegen und die Optionen als Teil einer BlobDownloadToOptions-Instanz einschließen. Die in diesem Beispiel angegebenen Werte sind nicht als Empfehlungen zu verstehen. Zur ordnungsgemäßen Optimierung dieser Werte müssen die spezifischen Anforderungen Ihrer App berücksichtigt werden.

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();
}

Weitere Informationen zur Feinabstimmung von Datenübertragungsoptionen finden Sie unter Leistungsoptimierung für Uploads und Downloads.

Angeben von Optionen für die Überprüfung der Übertragung beim Download

Sie können Optionen für die Überprüfung von Übertragungen angeben, um sicherzustellen, dass Daten ordnungsgemäß heruntergeladen werden und während der Übertragung nicht manipuliert wurden. Optionen für die Überprüfung von Übertragungen können auf Clientebene mithilfe von BlobClientOptions definiert werden, das Überprüfungsoptionen auf alle Methoden anwendet, die aus einer BlobClient-Instanz aufgerufen werden.

Sie können die Optionen für die Überprüfung von Übertragungen auf Methodenebene mithilfe von BlobDownloadToOptions auch außer Kraft setzen. Im folgenden Codebeispiel wird gezeigt, wie Sie ein BlobDownloadToOptions-Objekt erstellen und einen Algorithmus zum Generieren einer Prüfsumme angeben. Die Prüfsumme wird dann vom Dienst verwendet, um die Datenintegrität des heruntergeladenen Inhalts zu überprüfen.

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();
}

Die folgende Tabelle zeigt die verfügbaren Optionen für den Prüfsummenalgorithmus, wie vom StorageChecksumAlgorithm definiert:

Name Wert BESCHREIBUNG
Automatisch 0 Empfohlen. Ermöglicht der Bibliothek die Auswahl eines Algorithmus. Unterschiedliche Bibliotheksversionen können unterschiedliche Algorithmen auswählen.
Keine 1 Kein ausgewählter Algorithmus. Vermeiden sie das Berechnen oder Anfordern von Prüfsummen.
MD5 2 Standard-MD5-Hashalgorithmus.
StorageCrc64 3 Benutzerdefinierter 64-Bit-CRC für Azure Storage.

Ressourcen

Weitere Informationen zum Herunterladen von Blobs mithilfe der Azure Blob Storage-Clientbibliothek für .NET finden Sie in den folgenden Ressourcen.

Codebeispiele

REST-API-Vorgänge

Das Azure SDK für .NET enthält Bibliotheken, die auf der zugrunde liegenden Azure-REST-API basieren, und ermöglicht Ihnen dadurch die Interaktion mit REST-API-Vorgängen über vertraute .NET-Paradigmen. Die Methoden der Clientbibliothek zum Herunterladen von Blobs verwenden den folgenden REST-API-Vorgang:

Ressourcen zur Clientbibliothek

Siehe auch

  • Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für .NET. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer .NET-App.