Scaricare un BLOB con .NET

  • Articolo

Questo articolo illustra come scaricare un BLOB usando la libreria client di Archiviazione di Azure per .NET. È possibile scaricare dati BLOB in varie destinazioni, tra cui un percorso di file locale, un flusso o una stringa di testo. È anche possibile aprire un flusso BLOB e leggerlo.

Prerequisiti

Configurazione dell'ambiente

Se non si ha un progetto esistente, questa sezione spiega come configurare un progetto per l'uso con la libreria client di Archiviazione BLOB di Azure per .NET. I passaggi includono l'installazione del pacchetto, l'aggiunta di direttive using e la creazione di un oggetto client autorizzato. Per informazioni dettagliate, vedere Introduzione ad Archiviazione BLOB di Azure e .NET.

Installare i pacchetti

Nella directory del progetto installare i pacchetti per le librerie client di Archiviazione BLOB di Azure e Azure Identity usando il comando dotnet add package. Il pacchetto Azure.Identity è necessario per le connessioni senza password ai servizi di Azure.

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

Aggiungere le direttive using

Aggiungere queste direttive using all'inizio del file del codice:

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

Alcuni esempi di codice in questo articolo potrebbero richiedere direttive using aggiuntive.

Creare un oggetto client

Per connettere un'app ad Archiviazione BLOB, creare un'istanza di BlobServiceClient. Nell'esempio seguente viene illustrato come creare un oggetto client usando DefaultAzureCredential per l'autorizzazione:

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

    return client;
}

È possibile registrare un client del servizio per l'inserimento delle dipendenze in un'app .NET.

È anche possibile creare oggetti client per contenitori o BLOB specifici. Per altre informazioni sulla creazione e la gestione di oggetti client, vedere Creare e gestire oggetti client che interagiscono con le risorse dati.

Autorizzazione

Il meccanismo di autorizzazione deve disporre delle autorizzazioni necessarie per eseguire un'operazione di download. Per l'autorizzazione con Microsoft Entra ID (scelta consigliata), è necessario disporre del ruolo predefinito Controllo degli accessi in base al ruolo di Azure Lettore dei dati del BLOB di archiviazione o ruolo superiore. Per altre informazioni, vedere le indicazioni sulle autorizzazioni per Get Blob (API REST).

Scaricare un BLOB

Per scaricare un BLOB, è possibile utilizzare uno o più dei metodi seguenti:

È anche possibile aprire un flusso perl eggere da un BLOB. Il flusso scarica solo il BLOB durante la lettura. È possibile usare uno dei metodi seguenti:

Scaricare in un percorso di file

L'esempio seguente scarica un BLOB in un percorso di file locale. Se la directory specificata non esiste, il codice genera un'eccezione DirectoryNotFoundException. Se il file esiste già in localFilePath, viene sovrascritto per impostazione predefinita durante i download successivi.

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

Scaricare in un flusso

L'esempio seguente scarica un BLOB creando un oggetto Flusso e quindi scaricandolo in tale flusso. Se la directory specificata non esiste, il codice genera un'eccezione DirectoryNotFoundException.

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

    await blobClient.DownloadToAsync(fileStream);

    fileStream.Close();
}

Scaricare in una stringa

L'esempio seguente presuppone che il BLOB sia un file di testo e scarica il BLOB in una stringa:

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

Scaricare da un flusso

L'esempio seguente scarica un BLOB leggendo da un flusso:

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

Scaricare un BLOB in blocchi con le opzioni di configurazione

È possibile definire le opzioni di configurazione della libreria client durante il download di un BLOB. Queste opzioni possono essere ottimizzate per migliorare le prestazioni e l'affidabilità. Gli esempi di codice seguenti illustrano come usare BlobDownloadToOptions per definire le opzioni di configurazione quando si chiama un metodo di download. Si noti che le stesse opzioni sono disponibili per BlobDownloadOptions.

Specificare le opzioni di trasferimento dei dati al download

È possibile configurare i valori in StorageTransferOptions per migliorare le prestazioni per le operazioni di trasferimento dei dati. Nell'esempio di codice seguente viene illustrato come impostare i valori per StorageTransferOptions e includere le opzioni come parte di un'istanza di BlobDownloadToOptions. I valori forniti in questo esempio non sono necessariamente quelli consigliati. Per ottimizzare correttamente questi valori, è necessario considerare le esigenze specifiche dell'app.

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

Per altre informazioni sull'ottimizzazione delle opzioni di trasferimento dei dati, vedere Ottimizzazione delle prestazioni per caricamenti e download.

Specificare le opzioni di convalida del trasferimento al download

È possibile specificare le opzioni di convalida del trasferimento per assicurarsi che i dati vengano scaricati correttamente e che non siano manomessi durante il transito. Le opzioni di convalida del trasferimento possono essere definite a livello di client usando BlobClientOptions, che applica le opzioni di convalida a tutti i metodi chiamati da un'istanza BlobClient.

È anche possibile eseguire l'override delle opzioni di convalida del trasferimento a livello di metodo usando BlobDownloadToOptions. Nell'esempio di codice seguente viene illustrato come creare un oggetto BlobDownloadToOptions e specificare un algoritmo per la generazione di un checksum. Il checksum viene quindi usato dal servizio per verificare l'integrità dei dati del contenuto scaricato.

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

La tabella seguente illustra le opzioni disponibili per l'algoritmo checksum, come definito da StorageChecksumAlgorithm:

Nome valore Descrizione
Automatico 0 Requisiti consigliati. Consente alla libreria di scegliere un algoritmo. Diverse versioni della libreria possono scegliere algoritmi diversi.
None 1 Nessun algoritmo selezionato. Non vengono calcolati o richiesti checksum.
MD5 2 Algoritmo hash MD5 standard.
StorageCrc64 3 CRC personalizzato di Archiviazione di Azure a 64 bit.

Risorse

Per altre informazioni su come scaricare i BLOB tramite la libreria client di Archiviazione BLOB di Azure per .NET, vedere le risorse seguenti.

Esempi di codice

Operazioni dell'API REST

Azure SDK per .NET contiene librerie basate sull'API REST di Azure, che consentono di interagire con le operazioni dell'API REST tramite paradigmi .NET noti. I metodi della libreria client per scaricare i BLOB usano l'operazione API REST seguente:

Risorse della libreria client

Vedi anche

Contenuto correlato

  • Questo articolo fa parte della Guida per sviluppatori di Archiviazione BLOB per .NET. Per altre informazioni, vedere l’elenco completo degli articoli della Guida per sviluppatori inCreare la propria app .NET.