Schnellstart: Azure Blob Storage-Clientbibliothek für .NET

  • Artikel
  • 17 Minuten Lesedauer

Erfahren Sie etwas über die ersten Schritte mit der Azure Blob Storage-Clientbibliothek für .NET. Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen. Blobspeicher ist für die Speicherung großer Mengen unstrukturierter Daten optimiert.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Beispiele

Voraussetzungen

Einrichten

In diesem Abschnitt wird beschrieben, wie ein Projekt zur Verwendung mit der Azure Blob Storage-Clientbibliothek für .NET vorbereitet wird.

Erstellen des Projekts

Für die folgenden Schritte müssen Sie eine .NET-Konsolen-App mithilfe der .NET CLI oder von Visual Studio 2022 erstellen.

  1. Navigieren Sie oben in Visual Studio zu Datei>Neu>Projekt.

  2. Geben Sie im Dialogfenster in das Suchfeld der Projektvorlage den Begriff Konsolen-App ein, und wählen Sie das erste Ergebnis aus. Wählen Sie unten im Dialogfeld Weiter aus.

    Ein Screenshot zeigt, wie ein neues Projekt mithilfe von Visual Studio erstellt wird.

  3. Geben Sie als ProjektnameBlobQuickstart ein. Übernehmen Sie bei den restlichen Feldern die Standardwerte, und wählen Sie Weiter aus.

  4. Stellen Sie für das Framework sicher, dass „.NET 6.0“ ausgewählt ist. Wähle anschließend Erstellen aus. Das neue Projekt wird in der Visual Studio-Umgebung geöffnet.

Installieren des Pakets

Installieren Sie zum Interagieren mit Azure Blob Storage die Azure Blob Storage-Clientbibliothek für .NET.

  1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Abhängigkeiten Ihres Projekts. Wählen Sie NuGet-Pakete verwalten aus.

  2. Suchen Sie im daraufhin angezeigten Fenster nach Azure.Storage.Blobs. Wählen Sie das entsprechende Ergebnis und dann Installieren aus.

    Ein Screenshot zeigt, wie ein neues Paket mithilfe von Visual Studio hinzugefügt wird.

Einrichten des App-Codes

Ersetzen Sie den Startcode in der Datei Program.cs, damit er dem folgenden Beispiel entspricht, das die erforderlichen using-Anweisungen für diese Übung enthält.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Authentifizieren bei Azure und Autorisieren des Zugriffs auf Blobdaten

Anwendungsanforderungen an Azure Blob Storage müssen autorisiert werden. Die Verwendung der von der Azure Identity-Clientbibliothek bereitgestellten Klasse DefaultAzureCredential ist der empfohlene Ansatz zum Implementieren von kennwortlosen Verbindungen mit Azure-Diensten in Ihrem Code, einschließlich Blob Storage.

Sie können Anforderungen an Azure Blob Storage auch mithilfe des Kontozugriffsschlüssels autorisieren. Dieser Ansatz sollte jedoch mit Vorsicht verwendet werden. Entwickler müssen darauf achten, dass die Zugriffsschlüssel niemals an einem unsicheren Ort offengelegt werden. Jeder, der über den Zugriffsschlüssel verfügt, kann Anforderungen für das Speicherkonto autorisieren und hat somit Zugriff auf alle Daten. DefaultAzureCredential bietet verbesserte Verwaltungs- und Sicherheitsvorteile gegenüber dem Kontoschlüssel, um kennwortlose Authentifizierung zu ermöglichen. Beide Optionen werden im folgenden Beispiel veranschaulicht.

DefaultAzureCredential ist eine von der „Azure Identity“-Clientbibliothek für .NET bereitgestellte Klasse, zu der Sie mehr in der „DefaultAzureCredential“-Übersicht erfahren können. DefaultAzureCredential unterstützt mehrere Authentifizierungsmethoden und bestimmt, welche Methode zur Laufzeit verwendet werden soll. Bei diesem Ansatz kann Ihre App unterschiedliche Authentifizierungsmethoden in verschiedenen Umgebungen (lokal gegenüber Produktion) verwenden, ohne umgebungsspezifischen Code zu implementieren.

Die Reihenfolge und Speicherorte, in denen DefaultAzureCredential nach Anmeldeinformationen sucht, finden Sie in der Übersicht über die „Azure Identity“-Bibliothek.

Ihre App kann sich beispielsweise mit Ihren Visual Studio-Anmeldeinformationen authentifizieren, wenn Sie lokal entwickeln. Dann kann Ihre App eine verwaltete Identität verwenden, nachdem sie in Azure bereitgestellt wurde. Für diesen Übergang sind keine Änderungen am Code erforderlich.

Zuweisen von Rollen zu Ihrem Azure AD-Benutzerkonto

Stellen Sie beim lokalen Entwickeln sicher, dass das Benutzerkonto, das auf Blobdaten zugreift, die richtigen Berechtigungen hat. Sie benötigen die Berechtigung Mitwirkender an Storage-Blobdaten zum Lesen und Schreiben von Blobdaten. Um sich selbst diese Rolle zuweisen zu können, benötigen Sie die Rolle Benutzerzugriffsadministrator oder eine andere Rolle, die die Aktion Microsoft.Authorization/roleAssignments/write enthält. Sie können einem Benutzer Azure RBAC-Rollen über das Azure-Portal, die Azure CLI oder mit Azure PowerShell zuweisen. Weitere Informationen zu den verfügbaren Bereichen für Rollenzuweisungen finden Sie auf der Seite Bereichsübersicht.

In diesem Szenario weisen Sie Ihrem Benutzerkonto Berechtigungen zu, die auf das Speicherkonto zugeschnitten sind, um dem Prinzip der geringsten Rechte zu folgen. Auf diese Weise erhalten Benutzer nur die erforderlichen Mindestberechtigungen, und es entstehen sicherere Produktionsumgebungen.

Im folgenden Beispiel wird Ihrem Benutzerkonto die Rolle Mitwirkender an Storage-Blobdaten zugewiesen, die sowohl Lese- als auch Schreibzugriff auf Blobdaten in Ihrem Speicherkonto ermöglicht.

Wichtig

In den meisten Fällen dauert es eine oder zwei Minute(n), bis die Rollenzuweisung in Azure weitergegeben wird. In seltenen Fällen kann es aber bis zu acht Minuten dauern. Wenn bei der ersten Ausführung Ihres Codes Authentifizierungsfehler auftreten, warten Sie einige Momente, und versuchen Sie es dann erneut.

  1. Suchen Sie im Azure-Portal Ihr Speicherkonto mithilfe der Hauptsuchleiste oder der linken Navigationsleiste.

  2. Wählen Sie auf der Übersichtsseite des Speicherkontos im linken Menü die Option Zugriffssteuerung (IAM) aus.

  3. Wählen Sie auf der Seite Zugriffssteuerung (IAM) die Registerkarte Rollenzuweisungen aus.

  4. Wählen Sie im oberen Menü + Hinzufügen und aus dem dann angezeigten Dropdownmenü die Option Rollenzuweisung hinzufügen aus.

    Ein Screenshot zeigt, wie eine Rolle zugewiesen wird.

  5. Über das Suchfeld können Sie die Ergebnisse für die gewünschte Rolle filtern. Suchen Sie in diesem Beispiel nach Mitwirkender an Speicherblobdaten, wählen Sie das entsprechende Ergebnis und dann Weiter aus.

  6. Wählen Sie unter Zugriff zuweisen zu die Option Benutzer, Gruppe oder Dienstprinzipal und dann die Option + Mitglieder auswählen aus.

  7. Suchen Sie im Dialogfeld nach Ihrem Azure AD-Benutzernamen (normalerweise Ihre E-Mail-Adresse benutzer@domäne), und wählen Sie unten im Dialogfeld Auswählen aus.

  8. Wählen Sie Überprüfen und zuweisen aus, um zur letzten Seite zu gelangen, und wählen Sie erneut Überprüfen und zuweisen aus, um den Vorgang abzuschließen.

Anmelden und Verbinden ihres App-Codes mit Azure mithilfe von „DefaultAzureCredential“

Sie können den Zugriff auf Daten in Ihrem Speicherkonto mithilfe der folgenden Schritte autorisieren:

  1. Vergewissern Sie sich, dass Sie mit dem Azure AD-Konto authentifiziert sind, dem Sie die Rolle zugewiesen haben. Dann können Sie sich über die Azure-Befehlszeilenschnittstelle (Azure CLI), Visual Studio oder Azure PowerShell authentifizieren.

    Melden Sie sich mit dem folgenden Befehl über die Azure-Befehlszeilenschnittstelle bei Azure an:

    az login

  2. Um DefaultAzureCredential verwenden zu können, fügen Sie Ihrer Anwendung das Paket Azure.Identity hinzu.

    1. Klicken Sie in Projektmappen-Explorer mit der rechten Maustaste auf den Knoten Abhängigkeiten Ihres Projekts. Wählen Sie NuGet-Pakete verwalten aus.

    2. Suchen Sie im daraufhin angezeigten Fenster nach Azure.Identity. Wählen Sie das entsprechende Ergebnis und dann Installieren aus.

      Ein Screenshot zeigt, wie das Identitätspaket hinzugefügt wird.

  3. Aktualisieren Sie Ihren Program.cs-Code, damit er mit dem folgenden Beispiel übereinstimmt. Wenn der Code während der Entwicklung auf Ihrer lokalen Arbeitsstation ausgeführt wird, verwendet er die Entwickleranmeldeinformationen des priorisierten Tools, bei dem Sie angemeldet sind, um sich bei Azure zu authentifizieren, z. B. Azure CLI oder Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Stellen Sie sicher, dass Sie den Namen des Speicherkontos im URI Ihres BlobServiceClient aktualisieren. Den Name des Speicherkontos finden Sie auf der Übersichtsseite des Azure-Portals.

    Screenshot: Ermitteln des Namens des Speicherkontos.

    Hinweis

    Bei der Bereitstellung in Azure kann derselbe Code verwendet werden, um Anforderungen an Azure Storage aus einer in Azure ausgeführten Anwendung zu autorisieren. Sie müssen jedoch die verwaltete Identität für Ihre App in Azure aktivieren. Konfigurieren Sie dann Ihr Speicherkonto, um dieser verwalteten Identität das Herstellen einer Verbindung zu ermöglichen. Ausführliche Anleitungen zum Konfigurieren dieser Verbindung zwischen Azure-Diensten finden Sie im Tutorial Auth from Azure-hosted apps (Autorisieren aus von Azure gehosteten Apps).

Objektmodell

Azure Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert. Unstrukturierte Daten entsprechen keinem bestimmten Datenmodell und keiner bestimmten Definition (also beispielsweise Text- oder Binärdaten). Blob Storage bietet drei Typen von Ressourcen:

  • Das Speicherkonto
  • Einen Container im Speicherkonto
  • Ein Blob im Container

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.

Diagramm der Blob Storage-Architektur.

Verwenden Sie die folgenden .NET-Klassen zur Interaktion mit folgenden Ressourcen:

  • BlobServiceClient: Die BlobServiceClient-Klasse ermöglicht Ihnen, Azure Storage-Ressourcen und Blobcontainer zu bearbeiten.
  • BlobContainerClient: Die BlobContainerClient-Klasse ermöglicht Ihnen, Azure Storage-Container und deren Blobs zu bearbeiten.
  • BlobClient: Die BlobClient-Klasse ermöglicht Ihnen, Azure Storage-Blobs zu bearbeiten.

Codebeispiele

Die Beispielcodeschnipsel in den folgenden Abschnitten veranschaulichen, wie grundlegende Datenvorgänge mit der Azure Blob Storage-Clientbibliothek für .NET ausgeführt werden.

Wichtig

Stellen Sie sicher, dass Sie die richtigen NuGet-Pakete installiert und die erforderlichen Verwendungsanweisungen hinzugefügt haben, damit die Codebeispiele so funktionieren, wie es im Abschnitt Einrichten beschrieben wird.

  • Azure.Identity (wenn Sie den kennwortlosen Ansatz verwenden)
  • Azure.Storage.Blobs

Erstellen eines Containers

Legen Sie einen Namen für den neuen Container fest. Der folgende Code hängt einen GUID-Wert an den Containernamen an, damit dieser eindeutig ist.

Wichtig

Die Containernamen müssen klein geschrieben werden. Weitere Informationen zum Benennen von Containern und Blobs finden Sie unter Naming and Referencing Containers, Blobs, and Metadata (Benennen von Containern, Blobs und Metadaten und Verweisen auf diese).

Sie können die Methode CreateBlobContainerAsync für den blobServiceClient aufrufen, um in Ihrem Speicherkonto einen Container zu erstellen.

Fügen Sie diesen Code am Ende der Klasse Program.cs hinzu:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Weitere Informationen zum Erstellen eines Containers und weitere Codebeispiele zum Erkunden finden Sie unter Erstellen eines Blobcontainers mit .NET.

Hochladen eines Blobs in einen Container

Fügen Sie den folgenden Code am Ende der Klasse Program.cs hinzu:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Der Codeschnipsel führt die folgenden Schritte aus:

  1. Erstellen einer Textdatei im lokalen Verzeichnis data
  2. Abrufen eines Verweises auf ein BlobClient-Objekt durch Aufrufen der GetBlobClient-Methode für den Container aus dem Abschnitt Erstellen eines Containers
  3. Hochladen der lokalen Textdatei in das Blob durch Aufrufen der UploadAsync-Methode. Mit dieser Methode wird das Blob erstellt, falls es nicht vorhanden ist, oder überschrieben, sofern es bereits vorhanden ist.

Weitere Informationen zum Hochladen von Blobs und weitere Codebeispiele zum Erkunden finden Sie unter Hochladen eines Blobs mit .NET.

Listet Blobs in einem Container auf.

Listen Sie die Blobs im Container auf, indem Sie die GetBlobsAsync-Methode aufrufen. In diesem Fall wurde dem Container nur ein Blob hinzugefügt, sodass beim Auflisten auch nur ein Blob zurückgegeben wird.

Fügen Sie den folgenden Code am Ende der Klasse Program.cs hinzu:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Weitere Informationen zum Auflisten von Blobs und weitere Codebeispiele zum Erkunden finden Sie unter Auflisten von Blobs mit .NET.

Herunterladen eines Blobs

Laden Sie das zuvor erstellte Blob herunter, indem Sie die DownloadToAsync-Methode aufrufen. Im Beispielcode wird das Suffix „DOWNLOADED“ an den Dateinamen angefügt, damit beide Dateien im lokalen Dateisystem angezeigt werden können.

Fügen Sie den folgenden Code am Ende der Klasse Program.cs hinzu:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Weitere Informationen zum Herunterladen von Blobs und weitere Codebeispiele zum Erkunden finden Sie unter Herunterladen eines Blobs mit .NET.

Löschen eines Containers

Im folgenden Code werden die von der App erstellten Ressourcen bereinigt, indem der gesamte Container mithilfe von DeleteAsync gelöscht wird. Außerdem werden die von der App erstellten lokalen Dateien gelöscht.

Die App wird unterbrochen, um auf Benutzereingaben zu warten, indem Console.ReadLine aufgerufen wird, bevor Blob, Container und lokale Dateien gelöscht werden. Dies ist eine gute Möglichkeit, um zu überprüfen, ob die Ressourcen tatsächlich ordnungsgemäß erstellt wurden, bevor sie gelöscht werden.

Fügen Sie den folgenden Code am Ende der Klasse Program.cs hinzu:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Weitere Informationen zum Löschen eines Containers und weitere Codebeispiele zum Erkunden finden Sie unter Löschen und Wiederherstellen eines Blobcontainers mit .NET.

Der vollständige Code

Nach Abschluss dieser Schritte sollte der Code in Ihrer Datei Program.cs jetzt ähnlich wie im folgenden Beispiel aussehen:

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

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Ausführen des Codes

Mit dieser App wird in Ihrem lokalen Ordner data eine Testdatei erstellt und in Blob Storage hochgeladen. Anschließend werden im Beispiel die Blobs im Container aufgelistet, und die Datei wird mit einem neuen Namen heruntergeladen, damit Sie die alte und neue Datei vergleichen können.

Wenn Sie Visual Studio verwenden, drücken Sie F5, um den Code zu erstellen, ihn auszuführen und mit der Konsolen-App zu interagieren. Wenn Sie die .NET CLI verwenden, navigieren Sie zu Ihrem Anwendungsverzeichnis, erstellen Sie die Anwendung, und führen Sie sie aus.

dotnet build

dotnet run

Die Ausgabe der App sieht etwa wie das folgende Beispiel aus:

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobs60c70d78-8d93-43ae-954d-8322058cfd64/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Listing blobs...
        quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31.txt

Downloading blob to
        ./data/quickstart2fe6c5b4-7918-46cb-96f4-8c4c5cb2fd31DOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Überprüfen Sie den Ordner data vor dem Start der Bereinigung auf die beiden Dateien. Sie können sie öffnen und sich vergewissern, dass sie identisch sind.

Nachdem Sie die Dateien erfolgreich überprüft haben, drücken Sie die EINGABETASTE, um die Testdateien zu löschen und die Demo zu beenden.

Nächste Schritte

In dieser Schnellstartanleitung wurde beschrieben, wie Sie Blobs per .NET hochladen, herunterladen und auflisten.

Weitere Beispiel-Apps für Blob Storage finden Sie unter:

Beispiele für die Azure Blob Storage-Bibliothek für .NET