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

Richten Sie Ihre Umgebung ein

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 die integrierte Azure RBAC-Rolle Storage Blob Data Reader oder höher. Weitere Informationen finden Sie in der Anleitung zur Autorisierung für Get Blob (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:

In einen Dateipfad herunterladen

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

In einen Stream herunterladen

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

In eine Zeichenfolge herunterladen

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

Die Übertragungsprüfung mit CRC64-NVME bietet datenintegrität auf Clientebene für Azure Blob Storage, sodass Sie überprüfen können, ob die von Ihrer Anwendung gesendeten Daten die gleichen Daten sind, die von Azure gespeichert und gelesen werden. Wenn diese Option aktiviert ist, berechnet und überprüft das Blob SDK CRC64-NVME Prüfsummen während Upload- und Downloadvorgängen, während der Dienst CRC64-NVME Prüfsummen für die empfangenen und zurückgegebenen Daten unabhängig berechnet und überprüft. Die Überprüfung erfolgt für jede Anforderung und über den vollständigen Datenstrom hinweg, um sicherzustellen, dass das gesamte Blob auch dann überprüft wird, wenn Daten in Partitionen übertragen werden, z. B. Blockuploads oder Bereichslesevorgänge. Weitere Informationen finden Sie unter "Strukturiertes Textformat ".

Die Übertragungsüberprüfung mit MD5 ist verfügbar, um zu überprüfen, ob die von Ihrer Anwendung gesendeten Daten den empfangenen und von dem Dienst zurückgegebenen Daten auf jeder Anforderung entsprechen. Wenn diese Option aktiviert ist, berechnet und überprüft das Blob SDK MD5-Hashes während Upload- und Downloadvorgängen, während der Dienst MD5-Hashes für die verarbeiteten Daten unabhängig berechnet und überprüft. Die Überprüfung erfolgt auf HTTP-Anforderungs- und Antwortebene und hilft dabei, Beschädigungen für jedes übertragene Datensegment zu erkennen, z. B. einzelne Blöcke während Uploads oder Bereiche während der Lesevorgänge.

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. Alternativ können Sie übertragungsvalidierungsoptionen auf Methodenebene mithilfe von BlobDownloadToOptions überschreiben. Im folgenden Codebeispiel wird gezeigt, wie Sie ein BlobDownloadToOptions-Objekt erstellen und einen Algorithmus zum Generieren einer Prüfsumme angeben.

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. Auto wählt StorageCrc64 in Clientbibliotheksversionen 12.28.0+ aus.
Keine 1 Kein ausgewählter Algorithmus. Vermeiden sie das Berechnen oder Anfordern von Prüfsummen.
MD5 2 Standard-MD5-Hash-Algorithmus.
StorageCrc64 3 Azure Storage benutzerdefiniertes CRC64-NVME.

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

Zugehöriger Inhalt

  • 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.
  • Last updated on