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

  • Artículo

Nota:

La opción Compilar desde cero le guía paso a paso por el proceso de crear un nuevo proyecto, instalar los paquetes, escribir el código y ejecutar una aplicación de consola básica. Este enfoque se recomienda si quiere comprender todos los detalles implicados en la creación de una aplicación que se conecta a Azure Blob Storage. Si prefiere automatizar las tareas de implementación y empezar con un proyecto completado, elija Iniciar con una plantilla.

Nota:

La opción Iniciar con una plantilla usa Azure Developer CLI para automatizar las tareas de implementación y comienza con un proyecto completado. Este enfoque se recomienda si quiere explorar el código lo más rápido posible sin pasar por las tareas de configuración. Si prefiere instrucciones paso a paso para compilar la aplicación, elija Compilar desde cero.

Introducción a la biblioteca cliente de Azure Blob Storage para .NET. Azure Blob Storage es una solución de almacenamiento de objetos de Microsoft para la nube y está optimizada para el almacenamiento de cantidades enormes de datos no estructurados.

En este artículo, siga los pasos para instalar el paquete y probar el código de ejemplo para tareas básicas.

En este artículo, se usa Azure Developer CLI para implementar recursos de Azure y ejecutar una aplicación de consola completa con solo unos cuantos comandos.

Documentación de referencia de la API | Código fuente de la biblioteca | Paquete (NuGet) | Ejemplos

En este vídeo se muestra cómo empezar a usar la biblioteca cliente de Azure Blob Storage para .NET.

Los pasos del vídeo también se describen en las secciones siguientes.

Requisitos previos

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

Cree una aplicación de consola de .NET mediante la CLI de .NET o Visual Studio 2022.

  1. En la parte superior de Visual Studio, vaya a Archivo>Nuevo>proyecto....

  2. En la ventana de diálogo, escriba aplicación de consola en el cuadro de búsqueda de la plantilla de proyecto y seleccione el primer resultado. Elija Siguiente en la parte inferior del cuadro de diálogo.

    A screenshot showing how to create a new project using Visual Studio.

  3. En Nombre del proyecto, escriba BlobQuickstart. Deje los valores predeterminados para el resto de los campos y seleccione Siguiente.

  4. Para el Marco, asegúrese de que se selecciona la última versión instalada de .NET. Luego, elija Crear. El nuevo proyecto se abre en el entorno de Visual Studio.

Instalar el paquete

Para interactuar con Azure Blob Storage, instale la biblioteca cliente de Azure Blob Storage para .NET.

  1. En Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias del proyecto. Seleccione Administrar paquetes NuGet.

  2. En la ventana resultante, busque Azure.Storage.Blobs. Seleccione el resultado adecuado y haga clic en Instalar.

    A screenshot showing how to add a new package using Visual Studio.

Configuración del código de la aplicación

Reemplace el código inicial del archivo Program.cs para que coincida con el ejemplo siguiente, que incluye las instrucciones necesarias using para este ejercicio.

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

Con Azure Developer CLI instalado, puede crear una cuenta de almacenamiento y ejecutar el código de ejemplo con solo unos cuantos comandos. Puede ejecutar el proyecto en el entorno de desarrollo local o en DevContainer.

Inicialización de la plantilla de Azure Developer CLI e implementación de recursos

En un directorio vacío, siga estos pasos para inicializar la plantilla azd, aprovisionar recursos de Azure y empezar a trabajar con el código:

  • Clone los recursos del repositorio de inicio rápido de GitHub e inicialice la plantilla localmente:

    azd init --template blob-storage-quickstart-dotnet

    Se le pedirá la siguiente información:

    • Nombre del entorno: este valor se usa como prefijo para todos los recursos de Azure creados por Azure Developer CLI. El nombre debe ser único en todas las suscripciones de Azure y tener entre 3 y 24 caracteres. El nombre solo puede contener números y letras minúsculas.

  • Inicie sesión en Azure:

    azd auth login

  • Aprovisione e implemente los recursos en Azure:

    azd up

    Se le pedirá la siguiente información:

    • Suscripción: la suscripción de Azure en la que se implementan los recursos.
    • Ubicación: la región de Azure donde se implementan los recursos.

    La implementación puede tardar unos minutos en finalizar. La salida del comando azd upincluye el nombre de la cuenta de almacenamiento recién creada, que necesitará más adelante para ejecutar el código.

Ejecución del código de ejemplo

En este momento, los recursos están implementados en Azure y el proyecto está listo para ejecutarse. Siga estos pasos para actualizar el nombre de la cuenta de almacenamiento en el código y ejecutar la aplicación de consola de ejemplo:

  • Actualizar el nombre de la cuenta de almacenamiento: vaya al directorio src y edite Program.cs. Busque el marcador de posición <storage-account-name> y reemplácelo por el nombre real de la cuenta de almacenamiento creada por el comando azd up. Guarde los cambios.
  • Ejecutar el proyecto: si usa Visual Studio, presione F5 para compilar y ejecutar el código e interactuar con la aplicación de consola. Si usa la CLI de .NET, vaya al directorio de la aplicación, compile el proyecto mediante dotnet build y ejecute la aplicación con dotnet run.
  • Observar la salida: esta aplicación crea un archivo de prueba en la carpeta de datos local y lo carga en un contenedor de la cuenta de almacenamiento. 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.

Para más información sobre cómo funciona el código de ejemplo, consulte Ejemplos de código.

Cuando haya terminado de probar el código, consulte la sección Limpieza de recursos para eliminar los recursos creados por el comando azd up.

Modelo de objetos

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados no se ciñen a ningún un modelo de datos o definición concretos, 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 el contenedor

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

Diagram of Blob storage architecture.

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

  • BlobServiceClient: La clase BlobServiceClient permite manipular recursos de Azure Storage y contenedores de blobs.
  • BlobContainerClient: La clase BlobContainerClient permite manipular contenedores de Azure Storage y sus blobs.
  • BlobClient: La clase BlobClient permite manipular los blobs de Azure Storage.

Ejemplos de código

Los fragmentos de código de muestra de las siguientes secciones demuestran cómo realizar las siguientes tareas con la biblioteca de clientes de Azure Blob Storage para .NET:

Importante

Asegúrese de que ha instalado los paquetes NuGet correctos y de que ha agregado las instrucciones mediante instrucciones para que los códigos de ejemplo funcionen, tal y como se describe en la sección de configuración.

Nota:

La plantilla de Azure Developer CLI incluye un proyecto con código de ejemplo ya implementado. En los ejemplos siguientes se proporcionan detalles para cada parte del código de ejemplo. La plantilla implementa el método de autenticación sin contraseña recomendado, como se describe en la sección Autenticación en Azure. El método de cadena de conexión se muestra como una alternativa, pero no se usa en la plantilla y no se recomienda para el código de producción.

Autenticación en Azure y autorización del acceso a datos de blobs

Las solicitudes de aplicación a Azure Blob Storage deben estar autorizadas. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure.Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código, incluido Blob Storage.

También puede autorizar las solicitudes a Azure Blob Storage mediante la clave de acceso de la cuenta. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential es una clase que proporciona la biblioteca cliente de Azure Identity para .NET, de la que puede obtener más información en la introducción a DefaultAzureCredential. DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

El orden y las ubicaciones en las que DefaultAzureCredential busca credenciales se pueden encontrar en la información general de la biblioteca de Azure Identity.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de Visual Studio cuando se desarrolla localmente. A continuación, la aplicación puede usar una identidad administrada una vez se haya implementado en Azure. No se necesitan cambios de código para esta transición.

Asignación de roles a la cuenta de usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    A screenshot showing how to assign a role.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de sesión y conexión del código de la aplicación a Azure mediante DefaultAzureCredential

Puede autorizar el acceso a los datos de la cuenta de almacenamiento mediante los siguientes pasos:

  1. En el caso del desarrollo local, asegúrese de realizar la autenticación con la misma cuenta de Microsoft Entra a la que ha asignado el rol. Puede autenticarse a través de herramientas de desarrollo populares, como la CLI de Azure o Azure PowerShell. Las herramientas de desarrollo con las que puede autenticarse varían en todos los idiomas.

    Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

    az login

  2. Para usar DefaultAzureCredential, agregue el paquete Azure.Identity a la aplicación.

    1. En Explorador de soluciones, haga clic con el botón derecho en el nodo Dependencias del proyecto. Seleccione Administrar paquetes NuGet.

    2. En la ventana resultante, busque Azure.Identity. Seleccione el resultado adecuado y haga clic en Instalar.

      A screenshot showing how to add the identity package.

  3. Actualice el código Program.cs para que coincida con el ejemplo siguiente. Cuando el código se ejecute en la estación de trabajo local durante el desarrollo, usará las credenciales de desarrollador de la herramienta clasificada por orden de prioridad en la que ha iniciado sesión para autenticarse en Azure, como la CLI de Azure o 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. Asegúrese de actualizar el nombre de la cuenta de almacenamiento en el URI de BlobServiceClient. El nombre de la cuenta de almacenamiento se puede encontrar en la página de información general de Azure Portal.

    A screenshot showing how to find the storage account name.

    Nota:

    Cuando se implementa en Azure, se puede usar este mismo código para autorizar solicitudes a Azure Storage desde una aplicación que se ejecute en Azure. Sin embargo, deberá habilitar la identidad administrada en la aplicación en Azure. A continuación, configure la cuenta almacenamiento para permitir que esa identidad administrada se conecte. Para obtener instrucciones detalladas sobre la configuración de esta conexión entre los servicios de Azure, consulte el tutorial Autenticación desde aplicaciones hospedadas en Azure.

Creación de un contenedor

Cree un nuevo contenedor en su cuenta de almacenamiento llamando al método CreateBlobContainerAsync en el objeto blobServiceClient. En este ejemplo, el código añade un valor GUID al nombre del contenedor para asegurarse de que es único.

Agregue el siguiente código al final del archivo Program.cs:

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

Para obtener más información sobre cómo crear un contenedor y explorar más ejemplos de código, consulte Creación de un contenedor de blobs con .NET.

Importante

Los nombres de contenedor deben estar en minúsculas. Para más información acerca de los contenedores de nomenclatura y los blobs, consulte Naming and Referencing Containers, Blobs, and Metadata (Asignación de nombres y realización de referencias a contenedores, blobs y metadatos).

Carga de un blob en un contenedor

Cargue un blob en un contenedor mediante UploadAsync. El código del ejemplo crea un archivo de texto en el directorio local de datos para cargarlo en el contenedor.

Agregue el siguiente código al final del archivo Program.cs:

// 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, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Para obtener más información sobre cómo cargar blobs y explorar más ejemplos de código, consulte Carga de un blob con .NET.

Listado de blobs de un contenedor

Enumere los blobs en el contenedor llamando al método GetBlobsAsync.

Agregue el siguiente código al final del archivo Program.cs:

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

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

Para obtener más información sobre cómo enumerar blobs y explorar más ejemplos de código, consulte Enumeración de blobs con .NET.

Descarga de un blob

Descargue el blob que creamos anteriormente llamando al método DownloadToAsync. El código del ejemplo añade la cadena "DESCARGADO" al nombre del archivo para que pueda ver ambos archivos en el sistema de archivos local.

Agregue el siguiente código al final del archivo Program.cs:

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

Para obtener más información sobre cómo descargar blobs y explorar más ejemplos de código, consulte Descarga de un blob con .NET.

Eliminación de un contenedor

El código siguiente limpia los recursos que creó; para ello, elimina el contenedor con DeleteAsync. El ejemplo de código también elimina los archivos locales creados por la aplicación.

La aplicación se detiene para la entrada del usuario mediante una llamada a Console.ReadLine antes de eliminar el blob, el contenedor y los archivos locales. Esta es una buena oportunidad para verificar que los recursos se han creado correctamente antes de eliminarlos.

Agregue el siguiente código al final del archivo Program.cs:

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

Para obtener más información sobre cómo eliminar un contenedor y explorar más ejemplos de código, consulte Eliminación y restauración de un contenedor de blobs con .NET.

Código completo

Después de completar estos pasos, el código del archivo Program.cs ahora debe ser similar al siguiente:

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

Ejecución del código

Esta aplicación crea un archivo de prueba en la carpeta data 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.

Si usa Visual Studio, presione F5 para compilar y ejecutar el código e interactuar con la aplicación de consola. Si está usando la CLI de .NET, vaya hasta el directorio de la aplicación y, a continuación, compile y ejecute la aplicación.

dotnet build

dotnet run

La salida de la aplicación es similar al ejemplo siguiente (se omiten los valores GUID para mejorar la legibilidad):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

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

Antes de comenzar el proceso de limpieza, compruebe que los dos archivos están en la carpeta data. Puede abrirlos y comprobar que son idénticos.

Limpieza de recursos

Después de comprobar los archivos y finalizar las pruebas, presione la tecla Entrar para eliminar los archivos de prueba junto con el contenedor que creó en la cuenta de almacenamiento. También puede usar la CLI de Azure para eliminar recursos.

Cuando haya terminado con el inicio rápido, puede limpiar los recursos que creó con el siguiente comando:

azd down

Se le pedirá que confirme la eliminación de los recursos. Escriba y para confirmar.

Pasos siguientes

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

Para ver las aplicaciones de ejemplo de Blob Storage, siga estos pasos:

Ejemplos de biblioteca de Azure Blob Storage para .NET