Compartir vía

Descarga de un blob con .NET

  • Artículo

En este artículo se muestra cómo descargar un blob con la biblioteca cliente de Azure Storage para .NET. Puede descargar datos de blob en varios destinos, incluyendo una ruta de acceso de archivo local, una secuencia o una cadena de texto. También puede abrir una secuencia de blobs y leerla.

Requisitos previos

Configurar el entorno

Si no tiene un proyecto existente, esta sección le muestra cómo configurar un proyecto para que funcione con la biblioteca de clientes Azure Blob Storage para .NET. Los pasos incluyen la instalación del paquete, la adición de directivas using y la creación de un objeto cliente autorizado. Para más información, consulte Introducción a Azure Blob Storage y .NET.

Instalar paquetes

En el directorio del proyecto, instale los paquetes para las bibliotecas cliente de Azure Blob Storage y Azure Identity mediante el comando dotnet add package. El paquete Azure.Identity es necesario para las conexiones sin contraseña a los servicios de Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Agregue directivas using.

Agregue estas directivas using al principio del archivo de código:

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

Algunos ejemplos de código de este artículo pueden requerir directivas using adicionales.

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Puede registrar un cliente de servicio para la inserción de dependencias en una aplicación .NET.

También puede crear objetos de cliente para contenedores o blobs específicos. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Authorization

El mecanismo de autorización debe tener los permisos necesarios para realizar una operación de descarga. Para la autorización con Microsoft Entra ID (recomendado) se necesita el rol integrado de RBAC de Azure de Lector de datos de Storage Blob o superior. Para obtener más información, consulte la guía de autorización de Obtener blobs (API de REST).

Descarga de un blob

Puede usar cualquiera de los métodos siguientes para descargar un blob:

También puede abrir una secuencia para leer desde un blob. La secuencia solo descarga el blob a medida que se lea la secuencia. Puede usar cualquiera de los métodos siguientes:

Descarga en una ruta de acceso de archivo

En el ejemplo siguiente se descarga un blob en una ruta de acceso de archivo local. Si el directorio especificado no existe, el código produce una excepción DirectoryNotFoundException. Si el archivo ya existe en localFilePath, se sobrescribirá de forma predeterminada durante las descargas posteriores.

public static async Task DownloadBlobToFileAsync(
    BlobClient blobClient,
    string localFilePath)
{
    await blobClient.DownloadToAsync(localFilePath);
}

Descarga en una secuencia

En el ejemplo siguiente se descarga un blob mediante la creación de un objeto un Stream y, a continuación, la descarga en esa secuencia. Si el directorio especificado no existe, el código produce una excepción DirectoryNotFoundException.

public static async Task DownloadBlobToStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Descarga en una cadena

En el ejemplo siguiente se supone que el blob es un archivo de texto y descarga el blob en una cadena:

public static async Task DownloadBlobToStringAsync(BlobClient blobClient)
{
    BlobDownloadResult downloadResult = await blobClient.DownloadContentAsync();
    string blobContents = downloadResult.Content.ToString();
}

Descarga desde una secuencia

En el ejemplo siguiente se descarga un blob mediante la lectura desde una secuencia:

public static async Task DownloadBlobFromStreamAsync(
    BlobClient blobClient,
    string localFilePath)
{
    using (var stream = await blobClient.OpenReadAsync())
    {
        FileStream fileStream = File.OpenWrite(localFilePath);
        await stream.CopyToAsync(fileStream);
    }
}

Descargar un blob en bloques con opciones de configuración

Puede definir las opciones de configuración de la biblioteca cliente al descargar un blob. Estas opciones se pueden ajustar para mejorar el rendimiento y la confiabilidad. En los ejemplos de código siguientes se muestra cómo usar BlobDownloadToOptions para definir opciones de configuración al llamar a un método de descarga. Tenga en cuenta que las mismas opciones están disponibles para BlobDownloadOptions.

Especificar opciones de transferencia de datos al descargar

Puede configurar los valores de StorageTransferOptions para mejorar el rendimiento de las operaciones de transferencia de datos. En el ejemplo de código siguiente se muestra cómo establecer valores para StorageTransferOptions e incluir las opciones como parte de una instancia de BlobDownloadToOptions. Los valores proporcionados en este ejemplo no están diseñados para ser una recomendación. Para ajustar correctamente estos valores, debe tener en cuenta las necesidades específicas de la aplicación.

public static async Task DownloadBlobWithTransferOptionsAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

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

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferOptions = transferOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

Para obtener más información sobre cómo ajustar las opciones de transferencia de datos, consulte Ajuste del rendimiento para cargas y descargas.

Especificar las opciones de validación de transferencia en la descarga

Puede especificar las opciones de validación de transferencia para ayudar a garantizar que los datos se descargan correctamente y no se han alterado durante el tránsito. Las opciones de validación de transferencia se pueden definir en el nivel de cliente mediante BlobClientOptions, que aplica opciones de validación a todos los métodos a los que se llama desde una instancia de BlobClient.

También puede invalidar las opciones de validación de transferencia en el nivel de método mediante BlobDownloadToOptions. En el ejemplo de código siguiente se muestra cómo crear un objeto BlobDownloadToOptions y especificar un algoritmo para generar una suma de comprobación. A continuación, el servicio usa la suma de comprobación para comprobar la integridad de los datos del contenido descargado.

public static async Task DownloadBlobWithChecksumAsync(
    BlobClient blobClient,
    string localFilePath)
{
    FileStream fileStream = File.OpenWrite(localFilePath);

    var validationOptions = new DownloadTransferValidationOptions
    {
        AutoValidateChecksum = true,
        ChecksumAlgorithm = StorageChecksumAlgorithm.Auto
    };

    BlobDownloadToOptions downloadOptions = new BlobDownloadToOptions()
    {
        TransferValidation = validationOptions
    };

    await blobClient.DownloadToAsync(fileStream, downloadOptions);

    fileStream.Close();
}

En la tabla siguiente se muestran las opciones disponibles para el algoritmo de suma de comprobación, tal y como se define en StorageChecksumAlgorithm:

Nombre valor Descripción
Auto 0 Se recomienda su uso. Permite que la biblioteca elija un algoritmo. Diferentes versiones de biblioteca pueden elegir algoritmos diferentes.
None 1 No hay ningún algoritmo seleccionado. No calcule ni solicite sumas de comprobación.
MD5 2 Algoritmo hash MD5 estándar.
StorageCrc64 3 CRC de 64 bits personalizado de Azure Storage.

Recursos

Para más información sobre cómo descargar blobs con la biblioteca cliente de Azure Blob Storage para .NET, consulte los recursos siguientes.

Ejemplos de código

Operaciones de API REST

El SDK de Azure para .NET contiene bibliotecas que se crean a partir de la API REST de Azure, lo que le permite interactuar con las operaciones de API REST a través de paradigmas conocidos de .NET. Los métodos de la biblioteca cliente para descargar blobs usan la siguiente operación de API de REST:

Recursos de la biblioteca cliente

Consulte también

Contenido relacionado

  • Este artículo forma parte de la guía para desarrolladores de Blob Storage para .NET. Para obtener más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación .NET.