Freigeben über

Hochladen eines Blobs mit .NET

  • Artikel

In diesem Artikel wird beschrieben, wie ein Blob mithilfe der Azure Storage-Clientbibliothek für .NET hochgeladen wird. Sie können Daten aus einem Dateipfad, einem Stream, einem binären Objekt oder einer Textzeichenfolge in ein Blockblob hochladen. Sie können auch einen Blobstream öffnen und in diesen schreiben oder große Blobs in Blöcken hochladen.

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 Hochladen eines Blobs verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Mitwirkender an Storage-Blobdaten. Weitere Informationen finden Sie im Autorisierungsleitfaden für Put Blob (REST API) und Put Block (REST API).

Hochladen von Daten in ein Blockblob

Sie können eine der folgenden Methoden verwenden, um Daten in ein Blockblob hochzuladen:

Bei Verwendung dieser Uploadmethoden kann die Clientbibliothek entweder Put Blob aufrufen oder eine Reihe von Put Block-Aufrufen gefolgt von Put Block List verwenden. Dieses Verhalten hängt von der Gesamtgröße des Objekts ab und davon, wie die Datenübertragungsoptionen festgelegt sind.

Verwenden Sie eine der folgenden Methoden, um einen Stream in Blob Storage zu öffnen und in diesen Stream zu schreiben:

Hochladen eines Blockblobs aus einem lokalen Dateipfad

Im folgenden Beispiel wird ein Blockblob aus einem lokalen Dateipfad hochgeladen:

public static async Task UploadFromFileAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    await blobClient.UploadAsync(localFilePath, true);
}

Hochladen eines Blockblobs aus einem Stream

Im folgenden Beispiel wird ein Blockblob hochgeladen, indem ein Stream-Objekt erstellt und der Stream hochgeladen wird.

public static async Task UploadFromStreamAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, true);
    fileStream.Close();
}

Hochladen eines Blockblobs aus einem BinaryData-Objekt

Im folgenden Beispiel wird ein Blockblob aus einem BinaryData-Objekt hochgeladen:

public static async Task UploadFromBinaryDataAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    BinaryReader reader = new BinaryReader(fileStream);

    byte[] buffer = new byte[fileStream.Length];
    reader.Read(buffer, 0, buffer.Length);
    BinaryData binaryData = new BinaryData(buffer);

    await blobClient.UploadAsync(binaryData, true);

    fileStream.Close();
}

Hochladen eines Blockblobs aus einer Zeichenfolge

Im folgenden Beispiel wird ein Blockblob aus einer Zeichenfolge hochgeladen:

public static async Task UploadFromStringAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), overwrite: true);
}

Hochladen in einen Stream in Blob Storage

Sie können einen Stream in Blob Storage öffnen und in diesen schreiben. Im folgenden Beispiel wird eine ZIP-Datei in Blob Storage erstellt, und anschließend werden Dateien in diese Datei geschrieben. Anstatt eine ZIP-Datei im lokalen Speicher zu erstellen, befindet sich immer nur eine Datei im Arbeitsspeicher.

public static async Task UploadToStreamAsync(
    BlobContainerClient containerClient,
    string localDirectoryPath)
{
    string zipFileName = Path.GetFileName(
        Path.GetDirectoryName(localDirectoryPath)) + ".zip";

    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(zipFileName);

    using (Stream stream = await blockBlobClient.OpenWriteAsync(true))
    {
        using (ZipArchive zip = new ZipArchive(stream, ZipArchiveMode.Create, leaveOpen: false))
        {
            foreach (var fileName in Directory.EnumerateFiles(localDirectoryPath))
            {
                using (var fileStream = File.OpenRead(fileName))
                {
                    var entry = zip.CreateEntry(
                        Path.GetFileName(fileName), CompressionLevel.Optimal);
                    using (var innerFile = entry.Open())
                    {
                        await fileStream.CopyToAsync(innerFile);
                    }
                }
            }
        }
    }
}

Upload eines Blockblobs mit Konfigurationsoptionen

Beim Upload eines Blobs können Sie Clientbibliotheks-Konfigurationsoptionen definieren. Diese Optionen können feiner abgestimmt werden, um die Leistung und die Zuverlässigkeit zu verbessern und die Kosten zu optimieren. Die folgenden Codebeispiele zeigen, wie Sie BlobUploadOptions verwenden, um Konfigurationsoptionen beim Aufrufen einer Uploadmethode zu definieren.

Angeben von Datenübertragungsoptionen beim Upload

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 BlobUploadOptions-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 UploadWithTransferOptionsAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

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

    var uploadOptions = new BlobUploadOptions()
    {
        TransferOptions = transferOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

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

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

Sie können Optionen für die Überprüfung von Übertragungen angeben, um sicherzustellen, dass Daten ordnungsgemäß hochgeladen 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 von einer BlobClient-Instanz aufgerufen werden.

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

public static async Task UploadWithChecksumAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlobClient blobClient = containerClient.GetBlobClient(fileName);

    var validationOptions = new UploadTransferValidationOptions
    {
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    var uploadOptions = new BlobUploadOptions()
    {
        TransferValidation = validationOptions
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Die folgende Tabelle zeigt die verfügbaren Optionen für den Prüfsummenalgorithmus, wie im 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.

Hinweis

Wenn die in der Anforderung angegebene Prüfsumme nicht mit der vom Dienst berechneten Prüfsumme übereinstimmt, schlägt der Uploadvorgang fehl. Der Vorgang wird nicht wiederholt, wenn eine Standardwiebelrichtlinie verwendet wird. In .NET wird ein RequestFailedException mit Statuscode 400 und dem Fehlercode Md5Mismatch oder Crc64Mismatchausgelöst, je nachdem, welcher Algorithmus verwendet wird.

Hochladen mit Indextags

Blobindextags kategorisieren Daten in Ihrem Speicherkonto mithilfe von Schlüssel-Wert-Tagattributen. Diese Tags werden automatisch indiziert und als durchsuchbarer mehrdimensionaler Index verfügbar gemacht, um Daten einfach finden zu können. Sie können Tags zu einer BlobUploadOptions-Instanz hinzufügen und diese Instanz an die UploadAsync-Methode übergeben.

Im folgenden Beispiel wird ein Blockblob mit Indextags hochgeladen:

public static async Task UploadBlobWithTagsAsync(
    BlobContainerClient containerClient,
    string blobName)
{
    BlobClient blobClient = containerClient.GetBlobClient(blobName);
    string blobContents = "Sample blob data";

    BlobUploadOptions options = new BlobUploadOptions();
    options.Tags = new Dictionary<string, string>
    {
        { "Sealed", "false" },
        { "Content", "image" },
        { "Date", "2020-04-20" }
    };

    await blobClient.UploadAsync(BinaryData.FromString(blobContents), options);
}

Festlegen der Zugriffsebene eines Blobs während des Uploads

Beim Upload können Sie die Zugriffsebene eines Blobs festlegen, indem Sie die Klasse BlobUploadOptions verwenden. Im folgenden Codebeispiel wird gezeigt, wie die Zugriffsebene beim Upload eines Blobs festgelegt wird:

public static async Task UploadWithAccessTierAsync(
    BlobContainerClient containerClient,
    string localFilePath)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient(fileName);

    var uploadOptions = new BlobUploadOptions()
    {
        AccessTier = AccessTier.Cool
    };

    FileStream fileStream = File.OpenRead(localFilePath);
    await blockBlobClient.UploadAsync(fileStream, uploadOptions);
    fileStream.Close();
}

Das Festlegen der Zugriffsebene ist nur für Blockblobs zulässig. Sie können die Zugriffsebene für ein Blockblob auf Hot, Cool, Cold oder Archive festlegen. Um die Zugriffsebene auf Cold festzulegen, müssen Sie mindestens die Version 12.15.0 der Clientbibliothek verwenden.

Weitere Informationen zu Zugriffsebenen finden Sie unter Übersicht über Zugriffsebenen.

Hochladen eines Blockblobs durch Stagingblöcke und Commit

Sie können die Aufteilung der Uploads in Blöcke besser kontrollieren, indem Sie einzelne Datenblöcke manuell bereitstellen. Wenn alle Blöcke, aus denen ein Blob besteht, bereitgestellt wurden, können Sie sie in Blob Storage committen. Sie können diesen Ansatz verwenden, um die Leistung zu verbessern, indem Sie Blöcke parallel hochladen.

public static async Task UploadBlocksAsync(
    BlobContainerClient blobContainerClient,
    string localFilePath,
    int blockSize)
{
    string fileName = Path.GetFileName(localFilePath);
    BlockBlobClient blobClient = blobContainerClient.GetBlockBlobClient(fileName);

    FileStream fileStream = File.OpenRead(localFilePath);
    ArrayList blockIDArrayList = new ArrayList();
    byte[] buffer;

    var bytesLeft = (fileStream.Length - fileStream.Position);

    while (bytesLeft > 0)
    {
        if (bytesLeft >= blockSize)
        {
            buffer = new byte[blockSize];
            await fileStream.ReadAsync(buffer, 0, blockSize);
        }
        else
        {
            buffer = new byte[bytesLeft];
            await fileStream.ReadAsync(buffer, 0, Convert.ToInt32(bytesLeft));
            bytesLeft = (fileStream.Length - fileStream.Position);
        }

        using (var stream = new MemoryStream(buffer))
        {
            string blockID = Convert.ToBase64String(
                Encoding.UTF8.GetBytes(Guid.NewGuid().ToString()));

            blockIDArrayList.Add(blockID);
            await blobClient.StageBlockAsync(blockID, stream);
        }
        bytesLeft = (fileStream.Length - fileStream.Position);
    }

    string[] blockIDArray = (string[])blockIDArrayList.ToArray(typeof(string));

    await blobClient.CommitBlockListAsync(blockIDArray);
}

Ressourcen

Weitere Informationen zum Hochladen 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 Clientbibliotheksmethoden zum Hochladen von Blobs verwenden die folgenden REST-API-Vorgänge:

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.