Schnellstart: Azure Blob Storage-Clientbibliothek für .NETQuickstart: Azure Blob storage client library for .NET

Erfahren Sie etwas über die ersten Schritte mit der Azure Blob Storage-Clientbibliothek für .NET.Get started with the Azure Blob Storage client library for .NET. Azure Blob Storage ist die Objektspeicherlösung von Microsoft für die Cloud.Azure Blob Storage is Microsoft's object storage solution for the cloud. Führen Sie die Schritte zum Installieren des Pakets aus, und testen Sie den Beispielcode für grundlegende Aufgaben.Follow steps to install the package and try out example code for basic tasks. Blobspeicher ist für die Speicherung großer Mengen unstrukturierter Daten optimiert.Blob storage is optimized for storing massive amounts of unstructured data.

Mit der Azure Blob Storage-Clientbibliothek für .NET ist Folgendes möglich:Use the Azure Blob Storage client library for .NET to:

  • Erstellen eines ContainersCreate a container
  • Festlegen von Berechtigungen für einen ContainerSet permissions on a container
  • Erstellen eines Blobs in Azure StorageCreate a blob in Azure Storage
  • Herunterladen des Blobs auf den lokalen ComputerDownload the blob to your local computer
  • Auflisten aller Blobs in einem ContainerList all of the blobs in a container
  • Löschen eines ContainersDelete a container

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | BeispieleAPI reference documentation | Library source code | Package (NuGet) | Samples

VoraussetzungenPrerequisites

EinrichtenSetting up

In diesem Abschnitt wird beschrieben, wie ein Projekt zur Verwendung mit der Azure Blob Storage-Clientbibliothek für .NET vorbereitet wird.This section walks you through preparing a project to work with the Azure Blob Storage client library for .NET.

Erstellen des ProjektsCreate the project

Erstellen Sie zunächst eine .NET Core-Anwendung mit dem Namen blob-quickstart.First, create a .NET Core application named blob-quickstart.

  1. Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen blob-quickstart.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name blob-quickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.This command creates a simple "Hello World" C# project with a single source file: Program.cs.

    dotnet new console -n blob-quickstart
    
  2. Wechseln Sie zum neu erstellten Ordner blob-quickstart, und erstellen Sie die App, um zu überprüfen, ob alles funktioniert.Switch to the newly created blob-quickstart folder and build the app to verify that all is well.

    cd blob-quickstart
    
    dotnet build
    

Die erwartete Ausgabe aus dem Build sollte etwa wie folgt aussehen:The expected output from the build should look something like this:

C:\QuickStarts\blob-quickstart> dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 44.31 ms for C:\QuickStarts\blob-quickstart\blob-quickstart.csproj.
  blob-quickstart -> C:\QuickStarts\blob-quickstart\bin\Debug\netcoreapp2.1\blob-quickstart.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:03.08

Installieren des PaketsInstall the package

Installieren Sie im Anwendungsverzeichnis mit dem Befehl dotnet add package das Palet für die Azure Blob Storage-Clientbibliothek für .NET.While still in the application directory, install the Azure Blob Storage client library for .NET package by using the dotnet add package command.

dotnet add package Microsoft.Azure.Storage.Blob

Einrichten des App-FrameworksSet up the app framework

Über das Projektverzeichnis:From the project directory:

  1. Öffnen Sie die Datei „Program.cs“ im Editor.Open the Program.cs file in your editor
  2. Entfernen Sie die Anweisung Console.WriteLine.Remove the Console.WriteLine statement
  3. Fügen Sie using-Anweisungen hinzu.Add using directives
  4. Erstellen Sie eine ProcessAsync-Methode, in der sich der Hauptcode für das Beispiel befindet.Create a ProcessAsync method where the main code for the example will reside
  5. Rufen Sie die ProcessAsync-Methode asynchron in Main auf.Asynchronously call the ProcessAsync method from Main

Der Code lautet wie folgt:Here's the code:

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Azure.Storage;
using Microsoft.Azure.Storage.Blob;

namespace blob_quickstart
{
    class Program
    {
        public static void Main()
        {
            Console.WriteLine("Azure Blob Storage - .NET quickstart sample\n");

            // Run the examples asynchronously, wait for the results before proceeding
            ProcessAsync().GetAwaiter().GetResult();

            Console.WriteLine("Press any key to exit the sample application.");
            Console.ReadLine();
        }

        private static async Task ProcessAsync()
        {
        }
    }
}

Kopieren Ihrer Anmeldeinformationen aus dem Azure-PortalCopy your credentials from the Azure portal

Die Beispielanwendung muss den Zugriff auf Ihr Speicherkonto authentifizieren.The sample application needs to authenticate access to your storage account. Fügen Sie zum Authentifizieren der Anwendung die Anmeldeinformationen für Ihr Speicherkonto in Form einer Verbindungszeichenfolge hinzu.To authenticate, add your storage account credentials to the application as a connection string. Führen Sie zum Anzeigen der Anmeldeinformationen Ihres Speicherkontos die folgenden Schritte aus:View your storage account credentials by following these steps:

  1. Navigieren Sie zum Azure-Portal.Navigate to the Azure portal.

  2. Suchen Sie nach Ihrem Speicherkonto.Locate your storage account.

  3. Wählen Sie im Abschnitt Einstellungen der Speicherkontoübersicht die Option Zugriffsschlüssel.In the Settings section of the storage account overview, select Access keys. Hier können Sie Ihre Kontozugriffsschlüssel und die vollständige Verbindungszeichenfolge für jeden Schlüssel anzeigen.Here, you can view your account access keys and the complete connection string for each key.

  4. Suchen Sie unter key1 nach dem Wert für die Verbindungszeichenfolge, und wählen Sie dann die Schaltfläche Kopieren, um die Verbindungszeichenfolge zu kopieren.Find the Connection string value under key1, and select the Copy button to copy the connection string. Der Wert der Verbindungszeichenfolge wird in einem späteren Schritt einer Umgebungsvariablen hinzugefügt.You will add the connection string value to an environment variable in the next step.

    Screenshot: Kopieren einer Verbindungszeichenfolge aus dem Azure-Portal

Konfigurieren der SpeicherverbindungszeichenfolgeConfigure your storage connection string

Schreiben Sie die Verbindungszeichenfolge nach dem Kopieren in eine neue Umgebungsvariable auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird.After you have copied your connection string, write it to a new environment variable on the local machine running the application. Öffnen Sie zum Festlegen der Umgebungsvariablen ein Konsolenfenster, und befolgen Sie die Anleitung für Ihr Betriebssystem.To set the environment variable, open a console window, and follow the instructions for your operating system. Ersetzen Sie <yourconnectionstring> durch Ihre Verbindungszeichenfolge.Replace <yourconnectionstring> with your actual connection string.

Nachdem Sie die Umgebungsvariable hinzugefügt haben, müssen Sie unter Umständen alle ausgeführten Programme neu starten, in denen die Umgebungsvariable gelesen werden muss.After you add the environment variable, you may need to restart any running programs that will need to read the environment variable. Wenn Sie beispielsweise Visual Studio als Editor verwenden, müssen Sie Visual Studio neu starten, bevor Sie das Beispiel ausführen.For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.

WindowsWindows

setx STORAGE_CONNECTION_STRING "<yourconnectionstring>"

LinuxLinux

export STORAGE_CONNECTION_STRING="<yourconnectionstring>"

macOSMacOS

export STORAGE_CONNECTION_STRING="<yourconnectionstring>"

ObjektmodellObject model

Azure Blob Storage ist für die Speicherung großer Mengen unstrukturierter Daten optimiert.Azure Blob storage is optimized for storing massive amounts of unstructured data. Unstrukturierte Daten sind Daten, die keinem bestimmten Datenmodell und keiner bestimmten Definition entsprechen (also beispielsweise Text- oder Binärdaten).Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. Blob Storage bietet drei Typen von Ressourcen:Blob storage offers three types of resources:

  • Das SpeicherkontoThe storage account.
  • Einen Container im SpeicherkontoA container in the storage account
  • Ein Blob in einem ContainerA blob in a container

Im folgenden Diagramm ist die Beziehung zwischen diesen Ressourcen dargestellt.The following diagram shows the relationship between these resources.

Diagramm der Blob Storage-Architektur

Verwenden Sie die folgenden .NET-Klassen zur Interaktion mit folgenden Ressourcen:Use the following .NET classes to interact with these resources:

  • CloudStorageAccount: Die CloudStorageAccount-Klasse stellt Ihr Azure Storage-Konto dar.CloudStorageAccount: The CloudStorageAccount class represents your Azure storage account. Verwenden Sie diese Klasse für den Zugriff auf Blob Storage mithilfe Ihrer Kontozugriffsschlüssel.Use this class to authorize access to Blob storage using your account access keys.
  • CloudBlobClient: Die CloudBlobClient-Klasse gibt einen Zugriffspunkt für den Blob-Dienst im Code an.CloudBlobClient: The CloudBlobClient class provides a point of access to the Blob service in your code.
  • CloudBlobContainer: Die CloudBlobContainer-Klasse stellt einen Blobcontainer im Code dar.CloudBlobContainer: The CloudBlobContainer class represents a blob container in your code.
  • CloudBlockBlob: Das CloudBlockBlob-Objekt stellt ein Blockblob im Code dar.CloudBlockBlob: The CloudBlockBlob object represents a block blob in your code. Blockblobs bestehen aus Datenblöcken, die einzeln verwaltet werden können.Block blobs are made up of blocks of data that can be managed individually.

CodebeispieleCode examples

Mit den Beispielcodeausschnitten wird veranschaulicht, wie folgende Vorgänge mit der Azure Blob Storage-Clientbibliothek für .NET durchgeführt werden:These example code snippets show you how to perform the following with the Azure Blob storage client library for .NET:

Authentifizieren des ClientsAuthenticate the client

Mit dem folgenden Code wird überprüft, ob die Umgebungsvariable eine Verbindungszeichenfolge enthält, die analysiert werden kann, um ein Objekt vom Typ CloudStorageAccount zu erstellen, das auf das Speicherkonto verweist.The code below checks that the environment variable contains a connection string that can be parsed to create a CloudStorageAccount object pointing to the storage account. Verwenden Sie die TryParse-Methode, um zu überprüfen, ob die Verbindungszeichenfolge gültig ist.To check that the connection string is valid, use the TryParse method. Wenn TryParse erfolgreich ist, wird die Variable storageAccount initialisiert, und true wird zurückgegeben.If TryParse is successful, it initializes the storageAccount variable and returns true.

Fügen Sie diesen in der ProcessAsync-Methode ein:Add this code inside the ProcessAsync method:

// Retrieve the connection string for use with the application. The storage 
// connection string is stored in an environment variable on the machine 
// running the application called STORAGE_CONNECTION_STRING. If the 
// environment variable is created after the application is launched in a 
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string storageConnectionString = Environment.GetEnvironmentVariable("STORAGE_CONNECTION_STRING");

// Check whether the connection string can be parsed.
CloudStorageAccount storageAccount;
if (CloudStorageAccount.TryParse(storageConnectionString, out storageAccount))
{
    // If the connection string is valid, proceed with operations against Blob
    // storage here.
    // ADD OTHER OPERATIONS HERE
}
else
{
    // Otherwise, let the user know that they need to define the environment variable.
    Console.WriteLine(
        "A connection string has not been defined in the system environment variables. " +
        "Add an environment variable named 'STORAGE_CONNECTION_STRING' with your storage " +
        "connection string as a value.");
    Console.WriteLine("Press any key to exit the application.");
    Console.ReadLine();
}

Hinweis

Um die restlichen Vorgänge in diesem Artikel auszuführen, ersetzen Sie // ADD OTHER OPERATIONS HERE im Code oben durch die in den folgenden Abschnitten verwendeten Codeausschnitte.To perform the rest of the operations in this article, replace // ADD OTHER OPERATIONS HERE in the code above with the code snippets in the following sections.

Erstellen eines ContainersCreate a container

Erstellen Sie bei der Containererstellung zuerst eine Instanz des CloudBlobClient-Objekts, das auf Blobspeicher in Ihrem Speicherkonto verweist.To create the container, first create an instance of the CloudBlobClient object, which points to Blob storage in your storage account. Erstellen Sie als Nächstes eine Instanz des CloudBlobContainer-Objekts und anschließend den Container.Next, create an instance of the CloudBlobContainer object, then create the container.

In diesem Fall wird im Code die CreateAsync-Methode aufgerufen, um den Container zu erstellen.In this case, the code calls the CreateAsync method to create the container. Ein GUID-Wert wird an den Containernamen angehängt, um sicherzustellen, dass er eindeutig ist.A GUID value is appended to the container name to ensure that it is unique. In einer Produktionsumgebung ist es häufig besser, die CreateIfNotExistsAsync-Methode nur dann zum Erstellen eines Containers zu verwenden, wenn er noch nicht vorhanden ist.In a production environment, it's often preferable to use the CreateIfNotExistsAsync method to create a container only if it does not already exist.

Wichtig

Die Containernamen müssen klein geschrieben werden.Container names must be lowercase. 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).For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.

// Create the CloudBlobClient that represents the 
// Blob storage endpoint for the storage account.
CloudBlobClient cloudBlobClient = storageAccount.CreateCloudBlobClient();

// Create a container called 'quickstartblobs' and 
// append a GUID value to it to make the name unique.
CloudBlobContainer cloudBlobContainer = 
    cloudBlobClient.GetContainerReference("quickstartblobs" + 
        Guid.NewGuid().ToString());
await cloudBlobContainer.CreateAsync();

Festlegen von Berechtigungen für einen ContainerSet permissions on a container

Legen Sie Berechtigungen für den Container fest, sodass alle Blobs im Container öffentlich sind.Set permissions on the container so that any blobs in the container are public. Wenn ein Blob öffentlich ist, kann darauf über jeden Client anonym zugegriffen werden.If a blob is public, it can be accessed anonymously by any client.

// Set the permissions so the blobs are public.
BlobContainerPermissions permissions = new BlobContainerPermissions
{
    PublicAccess = BlobContainerPublicAccessType.Blob
};
await cloudBlobContainer.SetPermissionsAsync(permissions);

Hochladen von Blobs in einen ContainerUpload blobs to a container

Im folgenden Codeausschnitt wird ein Verweis auf ein CloudBlockBlob-Objekt abgerufen, indem die GetBlockBlobReference-Methode für den Container aufgerufen wird, der im vorherigen Abschnitt erstellt wurde.The following code snippet gets a reference to a CloudBlockBlob object by calling the GetBlockBlobReference method on the container created in the previous section. Anschließend wird die ausgewählte lokale Datei in das Blob hochgeladen, indem die UploadFromFileAsync-Methode aufgerufen wird.It then uploads the selected local file to the blob by calling the UploadFromFileAsync method. Mit dieser Methode wird das Blob erstellt, falls es nicht vorhanden ist, oder überschrieben, sofern es bereits vorhanden ist.This method creates the blob if it doesn't already exist, and overwrites it if it does.

// Create a file in your local MyDocuments folder to upload to a blob.
string localPath = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
string localFileName = "QuickStart_" + Guid.NewGuid().ToString() + ".txt";
string sourceFile = Path.Combine(localPath, localFileName);
// Write text to the file.
File.WriteAllText(sourceFile, "Hello, World!");

Console.WriteLine("Temp file = {0}", sourceFile);
Console.WriteLine("Uploading to Blob storage as blob '{0}'", localFileName);

// Get a reference to the blob address, then upload the file to the blob.
// Use the value of localFileName for the blob name.
CloudBlockBlob cloudBlockBlob = cloudBlobContainer.GetBlockBlobReference(localFileName);
await cloudBlockBlob.UploadFromFileAsync(sourceFile);

Auflisten der Blobs in einem ContainerList the blobs in a container

Listen Sie die Blobs im Container mithilfe der ListBlobsSegmentedAsync-Methode auf.List the blobs in the container by using the ListBlobsSegmentedAsync method. In diesem Fall wurde dem Container nur ein Blob hinzugefügt, sodass beim Auflisten auch nur ein Blob zurückgegeben wird.In this case, only one blob has been added to the container, so the listing operation returns just that one blob.

Falls die Anzahl von zurückzugebenden Blobs für einen Aufruf zu hoch ist (standardmäßig > 5000), gibt die ListBlobsSegmentedAsync-Methode ein Segment des gesamten Resultsets und ein Fortsetzungstoken zurück.If there are too many blobs to return in one call (by default, more than 5000), then the ListBlobsSegmentedAsync method returns a segment of the total result set and a continuation token. Zum Abrufen des nächsten Blobsegments geben Sie das vom vorherigen Aufruf zurückgegebene Fortsetzungstoken an und fahren damit fort, bis das Fortsetzungstoken null ist.To retrieve the next segment of blobs, you provide in the continuation token returned by the previous call, and so on, until the continuation token is null. Ein Fortsetzungstoken von „null“ gibt an, dass alle Blobs abgerufen wurden.A null continuation token indicates that all of the blobs have been retrieved. Im Code wird angezeigt, wie Sie das Fortsetzungstoken im Rahmen der bewährten Methoden einsetzen.The code shows how to use the continuation token for the sake of best practices.

// List the blobs in the container.
Console.WriteLine("List blobs in container.");
BlobContinuationToken blobContinuationToken = null;
do
{
    var results = await cloudBlobContainer.ListBlobsSegmentedAsync(null, blobContinuationToken);
    // Get the value of the continuation token returned by the listing call.
    blobContinuationToken = results.ContinuationToken;
    foreach (IListBlobItem item in results.Results)
    {
        Console.WriteLine(item.Uri);
    }
} while (blobContinuationToken != null); // Loop while the continuation token is not null.

Herunterladen von BlobsDownload blobs

Laden Sie das zuvor erstellte Blob mithilfe der DownloadToFileAsync-Methode in das lokale Dateisystem herunter.Download the blob created previously to your local file system by using the DownloadToFileAsync method. Im Beispielcode wird das Suffix „_DOWNLOADED“ an den Blobnamen angefügt, damit beide Dateien im lokalen Dateisystem angezeigt werden können.The example code adds a suffix of "_DOWNLOADED" to the blob name so that you can see both files in local file system.

// Download the blob to a local file, using the reference created earlier.
// Append the string "_DOWNLOADED" before the .txt extension so that you 
// can see both files in MyDocuments.
string destinationFile = sourceFile.Replace(".txt", "_DOWNLOADED.txt");
Console.WriteLine("Downloading blob to {0}", destinationFile);
await cloudBlockBlob.DownloadToFileAsync(destinationFile, FileMode.Create);

Löschen eines ContainersDelete a container

Im folgenden Code werden die mit der App erstellten Ressourcen bereinigt, indem der gesamte Container mithilfe von CloudBlobContainer.DeleteAsync gelöscht wird.The following code cleans up the resources the app created by deleting the entire container using CloudBlobContainer.DeleteAsync. Sie können bei Bedarf auch die lokalen Dateien löschen.You can also delete the local files if you like.

Console.WriteLine("Press the 'Enter' key to delete the example files, " +
    "example container, and exit the application.");
Console.ReadLine();
// Clean up resources. This includes the container and the two temp files.
Console.WriteLine("Deleting the container");
if (cloudBlobContainer != null)
{
    await cloudBlobContainer.DeleteIfExistsAsync();
}
Console.WriteLine("Deleting the source, and downloaded files");
File.Delete(sourceFile);
File.Delete(destinationFile);

Ausführen des CodesRun the code

Mit dieser App wird in Ihrem lokalen Ordner MyDocuments eine Testdatei erstellt und in Blob Storage hochgeladen.This app creates a test file in your local MyDocuments folder and uploads it to Blob storage. 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.The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.

Wenn Sie Visual Studio als Editor verwenden, können Sie F5 drücken, um die Ausführung zu starten.If you are using Visual Studio as your editor, you can press F5 to run.

Navigieren Sie andernfalls zu Ihrem Anwendungsverzeichnis, und erstellen dann die Anwendung, und führen Sie sie aus.Otherwise, navigate to your application directory, then build and run the application.

dotnet build
dotnet run

Die Ausgabe der Beispielanwendung ähnelt dem folgenden Beispiel:The output of the example application is similar to the following example:

Azure Blob storage - .NET Quickstart example

Created container 'quickstartblobs33c90d2a-eabd-4236-958b-5cc5949e731f'

Temp file = C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926-a9da-96
97c748f4db.txt
Uploading to Blob storage as blob 'QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f
4db.txt'

Listing blobs in container.
https://storagesamples.blob.core.windows.net/quickstartblobs33c90d2a-eabd-4236-
958b-5cc5949e731f/QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f4db.txt

Downloading blob to C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926
-a9da-9697c748f4db_DOWNLOADED.txt

Press any key to delete the example files and example container.

Wenn Sie die EINGABETASTE drücken, löscht die Anwendung den Speichercontainer und die Dateien.When you press the Enter key, the application deletes the storage container and the files. Überprüfen Sie den Ordner MyDocuments vor dem Löschen auf die beiden Dateien.Before you delete them, check your MyDocuments folder for the two files. Sie können sie öffnen und sich vergewissern, dass sie identisch sind.You can open them and observe that they are identical. Kopieren Sie die Blob-URL aus dem Konsolenfenster, und fügen Sie sie in einen Browser ein, um den Blobinhalt anzuzeigen.Copy the blob's URL from the console window and paste it into a browser to view the contents of the blob.

Nachdem Sie die Dateien erfolgreich überprüft haben, drücken Sie eine beliebige Taste, um die Demo zu beenden und die Testdateien zu löschen.After you've verified the files, hit any key to finish the demo and delete the test files.

Nächste SchritteNext steps

In dieser Schnellstartanleitung wurde beschrieben, wie Sie Blobs per .NET hochladen, herunterladen und auflisten.In this quickstart, you learned how to upload, download, and list blobs using .NET.

Informationen zum Erstellen einer Web-App, die ein Bild in Blob Storage hochlädt, finden Sie hier:To learn how to create a web app that uploads an image to Blob storage, continue to: