Inicio rápido: Biblioteca cliente de Azure Blob Storage v11 para .NET

Introducción a la biblioteca cliente de Azure Blob Storage v11 para .NET. Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube. Siga los pasos para instalar el paquete y probar el código de ejemplo para realizar tareas básicas. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados.

Use la biblioteca cliente de Azure Blob Storage para .NET para:

• Crear un contenedor
• Establecimiento de los permisos en un contenedor
• Crear un blob en Azure Storage
• Descargar el blob en el equipo local
• Enumerar todos los blobs de un contenedor
• Eliminación de un contenedor

Recursos adicionales:

• Documentación de referencia de API
• Código fuente de la biblioteca
• Paquete (NuGet)
• Muestras

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• El SDK de NET Core actual del sistema operativo. Asegúrese de obtener el SDK y no el entorno de ejecución.

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca de cliente de Azure Blob Storage para. NET.

Creación del proyecto

En primer lugar, cree una aplicación de .NET Core llamada blob-quickstar.

1. En una ventana de consola (por ejemplo, cmd, PowerShell o Bash), use el comando dotnet new para crear una nueva aplicación de consola con el nombre blob-quickstar. Este comando crea un sencillo proyecto "Hola mundo" de C# con un solo archivo de origen: Program.cs.

   dotnet new console -n blob-quickstart
   

2. Cambie a la carpeta blob-quicstart recién creada y compile la aplicación para comprobar que todo está bien.

   cd blob-quickstart
   

   dotnet build
   

El resultado esperado de la compilación debe parecerse a lo siguiente:

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

Instalar el paquete

Mientras sigue en el directorio de aplicaciones, instale el paquete de la biblioteca de cliente de Azure Blob Storage para .NET con el comando dotnet add package.

dotnet add package Microsoft.Azure.Storage.Blob

Instalación del marco de la aplicación

Desde el directorio del proyecto:

1. Abra el archivo Program.cs en el editor.
2. Quite la instrucción Console.WriteLine.
3. Agregue directivas using.
4. Cree un método ProcessAsync, en el que residirá el código principal para el ejemplo.
5. Llame de forma asincrónica al método ProcessAsync desde Main.

Este es el código:

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 async Task Main()
        {
            Console.WriteLine("Azure Blob Storage - .NET quickstart sample\n");

            await ProcessAsync();

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

        private static async Task ProcessAsync()
        {
        }
    }
}

Copia de las credenciales desde Azure Portal

Cuando la aplicación de ejemplo realiza una solicitud a Azure Storage, debe estar autorizada. Para autorizar una solicitud, agregue a la aplicación las credenciales de la cuenta de almacenamiento en forma de cadena de conexión. Para ver las credenciales de la cuenta de almacenamiento, siga estos pasos:

1. Acceda a Azure Portal.

2. Busque su cuenta de almacenamiento.

3. En la sección Configuración de la información general de la cuenta de almacenamiento, seleccione Claves de acceso. Aquí puede ver las claves de acceso de la cuenta, así como la cadena de conexión completa de cada clave.

4. Busque el valor de Cadena de conexión en key1 y seleccione el botón Copiar para copiar la cadena de conexión. En el paso siguiente, agregará el valor de la cadena de conexión a una variable de entorno.

   

Configuración de la cadena de conexión de almacenamiento.

Una vez que haya copiado la cadena de conexión, escríbala en una variable de entorno nueva en la máquina local que ejecuta la aplicación. Para establecer la variable de entorno, abra una ventana de consola y siga las instrucciones de su sistema operativo. Reemplace <yourconnectionstring> por la cadena de conexión real.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Después de agregar la variable de entorno en Windows, debe iniciar una nueva instancia de la ventana de comandos.

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

MacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Después de agregar la variable de entorno, reinicie todos los programas en ejecución que necesiten leer esta variable. Por ejemplo, reinicie el entorno de desarrollo o el editor antes de continuar.

Modelo de objetos

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados son datos que no cumplen un modelo de datos o definición concreta, como texto o datos binarios. Blob Storage ofrece tres tipos de recursos:

• La cuenta de almacenamiento
• Un contenedor en la cuenta de almacenamiento
• Un blob en un contenedor

En el siguiente diagrama se muestra la relación entre estos recursos.

Use las siguientes clases de .NET para interactuar con estos recursos:

• CloudStorageAccount: La clase CloudStorageAccount representa la cuenta de almacenamiento de Azure. Utilice esta clase para autorizar el acceso a Blob Storage mediante las claves de acceso de cuenta.
• CloudBlobClient: La clase CloudBlobClient proporciona un punto de acceso a Blob service en el código.
• CloudBlobContainer: La clase CloudBlobContainer representa un contenedor de blobs en el código.
• CloudBlockBlob: El objeto CloudBlockBlob representa un blob en bloques en el código. Los blobs en bloques se componen de bloques de datos que se pueden administrar de forma individual.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes acciones con la biblioteca de cliente de Azure Blob Storage para. NET:

• Autenticar el cliente
• Creación de un contenedor
• Establecimiento de los permisos en un contenedor
• Carga de los blobs en un contenedor
• Enumeración de los blobs de un contenedor
• Descarga de los blobs
• Eliminación de un contenedor

Autenticar el cliente

El código siguiente comprueba que la variable de entorno contiene una cadena de conexión que se pueda analizar para crear un objeto CloudStorageAccount que señala a la cuenta de almacenamiento. Para comprobar que la cadena de conexión es válida, use el método TryParse. Si TryParse es correcto, inicializa la variable storageAccount y devuelve true.

Agregue este código dentro del método ProcessAsync:

// 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 AZURE_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("AZURE_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 'AZURE_STORAGE_CONNECTION_STRING' with your storage " +
        "connection string as a value.");
    Console.WriteLine("Press any key to exit the application.");
    Console.ReadLine();
}

Crear un contenedor

Para crear el contenedor, en primer lugar cree una instancia del objeto CloudBlobClient que apunte a Blob Storage en la cuenta de almacenamiento. Cree una instancia del objeto CloudBlobContainer y, después, cree el contenedor.

En este caso, el código llama al método CreateAsync para crear el contenedor. Un valor de GUID se anexa al nombre de contenedor para asegurarse de que sea único. En un entorno de producción, a menudo es preferible utilizar el método CreateIfNotExistsAsync para crear un contenedor solo si no existe.

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

Establecimiento de los permisos en un contenedor

Establezca los permisos en el contenedor para que sus blobs sean públicos. Si un blob es público, cualquier cliente puede acceder de forma anónima.

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

Carga de los blobs en un contenedor

El fragmento de código siguiente obtiene una referencia a un objeto CloudBlockBlob mediante una llamada al método GetBlockBlobReference en el contenedor creado en la sección anterior. Luego carga el archivo local seleccionado en el blob mediante una llamada al método UploadFromFileAsync. Esta operación crea el blob si no existe y lo sobrescribe, en caso de que ya exista.

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

Enumerar los blobs de un contenedor

Enumera los blobs del contenedor mediante el método ListBlobsSegmentedAsync. En este caso, solo se ha agregado un blob al contenedor, por lo que la operación de enumeración devuelve simplemente dicho blob.

Si hay demasiados blobs para que se devuelvan en una sola llamada (de manera predeterminada más de 5000), el método ListBlobsSegmentedAsync devuelve un segmento del conjunto total de resultados y un token de continuación. Para recuperar el siguiente segmento de blobs, proporciónelo en el token de continuación devuelto por la llamada anterior, etc. hasta que el token de continuación es nulo. Un token de continuación nulo indica que se han recuperado todos los blobs. El código muestra cómo utilizar el token de continuación para los procedimientos recomendados.

// 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.

Descargar blobs

Descargue el blob creado anteriormente en el sistema de archivos local con el método DownloadToFileAsync. El código de ejemplo agrega el sufijo "_DOWNLOADED" al nombre del blob para que pueda ver ambos archivos en el sistema de archivos local.

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

Eliminación de un contenedor

El código siguiente limpia los recursos que creó; para ello, elimina todo el contenedor con CloudBlobContainer.DeleteAsync. Si lo desea, también puede eliminar los archivos locales.

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

Ejecución del código

Esta aplicación crea un archivo de prueba en la carpeta Mis documentos local y lo carga en Blob Storage. Después, en el ejemplo se enumeran los blobs del contenedor y se descarga el archivo con un nombre nuevo para que pueda comparar los archivos antiguo y nuevo.

Vaya al directorio de la aplicación y compile y ejecute la aplicación.

dotnet build

dotnet run

La salida de la aplicación es similar a la del ejemplo siguiente:

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.

Al presionar la tecla Entrar, la aplicación elimina el contenedor de almacenamiento y los archivos. Antes de eliminarlos, compruebe si la carpeta Mis documentos contiene los dos archivos. Puede abrirlos y ver que son idénticos. Copie la dirección URL del blob de la ventana de la consola y péguela en un explorador para ver el contenido del blob.

Después de haber comprobado los archivos, presione cualquier tecla para finalizar la demostración y eliminar los archivos de prueba.

Pasos siguientes

En esta guía de inicio rápido, ha aprendido a cargar, descargar y enumerar blobs mediante .NET.

Para aprender a crear una aplicación web que cargue una imagen en Blob Storage, diríjase a:

• Para más información sobre .NET Core, consulte Get started with .NET in 10 minutes (Introducción a .NET en 10 minutos).
• Para explorar una aplicación de ejemplo que puede implementar desde Visual Studio para Windows, consulte el artículo .NET Photo Gallery Web Application Sample with Azure Blob Storage (Ejemplo de aplicación web de galería fotográfica .NET con Azure Blob Storage).