Condividi tramite

Avvio rapido: libreria client di Archiviazione BLOB di Azure per .NET

  • Articolo

Nota

L'opzione Compila da zero mostra i passaggi da seguire durante il processo di creazione di un nuovo progetto, l'installazione di pacchetti, la scrittura del codice e l'esecuzione di un'app console di base. Questo approccio è consigliato se si vogliono comprendere tutti i dettagli relativi alla creazione di un'app che si connette all'Archiviazione BLOB di Azure. Se si preferisce automatizzare le attività di distribuzione e iniziare con un progetto completato, scegliere Inizia con un modello.

Nota

L'opzione Inizia con un modello usa Azure Developer CLI per automatizzare le attività di distribuzione e inizia con un progetto completato. Questo approccio è consigliato se si vuole esplorare il codice il più rapidamente possibile, senza eseguire le attività di configurazione. Se si preferiscono istruzioni sui passaggi da seguire per compilare l'app, scegliere Compila da zero.

Introduzione alla libreria client di Archiviazione BLOB di Azure per .NET Archiviazione BLOB di Azure è la soluzione di archiviazione di oggetti di Microsoft per il cloud ottimizzata per l'archiviazione di enormi quantità di dati non strutturati.

In questo articolo, vengono mostrati i passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.

In questo articolo si usa Azure Developer CLI per distribuire le risorse di Azure ed eseguire un'app console completa con pochi comandi.

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet) | Esempi

Questo video illustra come iniziare a usare la libreria client di Archiviazione BLOB di Azure per .NET.

I passaggi del video sono descritti anche nelle sezioni seguenti.

Prerequisiti

Configurazione

Questa sezione illustra come preparare un progetto da usare con la libreria client di Archiviazione BLOB di Azure per .NET.

Creare il progetto

Creare un'app console .NET usando l'interfaccia della riga di comando di .NET o Visual Studio 2022.

  1. Nella parte superiore di Visual Studio passare a File>Nuovo>Progetto.

  2. Nella finestra di dialogo immettere lapp console nella casella di ricerca del modello di progetto e selezionare il primo risultato. Selezionare Avanti nella parte inferiore della finestra di dialogo.

    Screenshot che mostra come creare un nuovo progetto con Visual Studio.

  3. Per Nome progettoimmettere BlobQuickstart. Lasciare i valori predefiniti per i campi rimanenti, quindi selezionare Avanti.

  4. Per Framework, verificare che sia selezionata la versione installata più recente di .NET. Scegli quindi Crea. Il nuovo progetto si apre nell'ambiente di Visual Studio.

Installare il pacchetto

Per interagire con Archiviazione BLOB di Azure, installare la libreria client di Archiviazione BLOB di Azure per .NET.

  1. In Esplora soluzionifare clic con il pulsante destro del mouse sul nodo Dipendenze del progetto. Scegliere Gestisci pacchetti NuGet.

  2. Nella finestra risultante cercare Azure.Storage.Blobs. Selezionare il risultato appropriato e selezionare Installa.

    Screenshot che mostra come aggiungere un nuovo pacchetto con Visual Studio.

Configurare il codice dell'app

Sostituire il codice iniziale nel file Program.cs in modo che corrisponda all'esempio seguente, che include le istruzioni using necessarie per questo esercizio.

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 installato, è possibile creare un account di archiviazione ed eseguire il codice di esempio con pochi comandi. È possibile eseguire il progetto nell'ambiente di sviluppo locale o in un DevContainer.

Inizializzare il modello Azure Developer CLI e distribuire le risorse

Da una directory vuota seguire questa procedura per inizializzare il modello azd, effettuare il provisioning delle risorse di Azure e iniziare a usare il codice:

  • Clonare gli asset del repository di avvio rapido da GitHub e inizializzare il modello in locale:

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

    Verranno richieste le informazioni seguenti:

    • Nome ambiente: questo valore viene usato come prefisso per tutte le risorse di Azure create da Azure Developer CLI. Il nome deve essere univoco in tutte le sottoscrizioni di Azure e deve avere una lunghezza compresa tra 3 e 24 caratteri. Il nome può contenere solo lettere minuscole e numeri.

  • Accedere ad Azure:

    azd auth login

  • Effettuare il provisioning e distribuire le risorse in Azure:

    azd up

    Verranno richieste le informazioni seguenti:

    • Sottoscrizione: sottoscrizione di Azure in cui vengono distribuite le risorse.
    • Posizione: area in cui sono distribuite le risorse.

    Il completamento della distribuzione può richiedere alcuni minuti. L'output del comando azd up include il nome dell'account di archiviazione appena creato, che sarà necessario in un secondo momento per eseguire il codice.

Eseguire il codice di esempio

A questo punto, le risorse vengono distribuite in Azure e il progetto è pronto per l'esecuzione. Seguire questa procedura per aggiornare il nome dell'account di archiviazione nel codice ed eseguire l'app console di esempio:

  • Aggiornare il nome dell'account di archiviazione: passare alla directory src e modificare Program.cs. Trovare il segnaposto <storage-account-name> e sostituirlo con il nome effettivo dell'account di archiviazione creato dal comando azd up. Salvare le modifiche.
  • Eseguire il progetto: se si usa Visual Studio, premere F5 per compilare ed eseguire il codice e interagire con l'app console. Se si usa l'interfaccia della riga di comando di .NET, passare alla directory dell'applicazione, compilare il progetto usando dotnet build ed eseguire l'applicazione usando dotnet run.
  • Osservare l'output: questa app crea un file di test nella cartella dati locale e lo carica in un contenitore nell'account di archiviazione. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.

Per altre informazioni sul funzionamento del codice di esempio, vedere Esempi di codice.

Al termine del test del codice, vedere la sezione Pulire le risorse per eliminare le risorse create dal comando azd up.

Modello a oggetti

Il servizio Archiviazione BLOB di Azure è ottimizzato per archiviare enormi quantità di dati non strutturati. I dati non strutturati non seguono una definizione o un modello di dati specifico, ad esempio dati di testo o binari. L'archiviazione BLOB offre tre tipi di risorse:

  • L'account di archiviazione
  • Un contenitore nell'account di archiviazione
  • Un oggetto BLOB in un contenitore

Il diagramma seguente mostra la relazione tra queste risorse.

Diagramma dell'architettura dell'archiviazione BLOB.

Per interagire con queste risorse, usare le classi .NET seguenti:

  • BlobServiceClient: la classe BlobServiceClient consente di modificare le risorse di Archiviazione di Azure e i contenitori BLOB.
  • BlobContainerClient: la classe BlobContainerClient consente di modificare i contenitori di Archiviazione di Azure e i relativi oggetti BLOB.
  • BlobClient: la classe BlobClient consente di modificare gli oggetti BLOB di Archiviazione di Azure.

Esempi di codice

I frammenti di codice di esempio nelle sezioni seguenti illustrano come eseguire le attività seguenti con la libreria client di Archiviazione BLOB di Azure per .NET:

Importante

Assicurarsi di aver installato i pacchetti NuGet corretti e aggiunto le istruzioni using necessarie per consentire il funzionamento degli esempi di codice, come descritto nella sezione configurazione.

Nota

Il modello Azure Developer CLI include un progetto con codice di esempio già disponibile. Negli esempi seguenti vengono forniti dettagli per ogni parte del codice di esempio. Il modello implementa il metodo di autenticazione senza password consigliato, come descritto nella sezione Eseguire l'autenticazione in Azure. Il metodo della stringa di connessione viene visualizzato come alternativa, ma non viene usato nel modello e non è consigliato per il codice di produzione.

Eseguire l'autenticazione in Azure e autorizzare l'accesso ai dati BLOB

Le richieste dell'applicazione ad Archiviazione BLOB di Azure devono essere autorizzate. L'uso della classe DefaultAzureCredential fornita dalla libreria client di identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice.

È anche possibile autorizzare le richieste all'Archiviazione BLOB di Azure usando la chiave di accesso dell'account. Tuttavia, questo approccio deve essere usato con cautela. Gli sviluppatori devono essere diligenti per non esporre mai la chiave di accesso in una posizione non sicura. Chiunque abbia la chiave di accesso può autorizzare richieste all'account di archiviazione e di fatto ha accesso a tutti i dati. DefaultAzureCredential offre maggiore sicurezza e semplicità di gestione rispetto alla chiave dell'account per consentire l'autenticazione senza password. Entrambe le opzioni sono mostrate nell'esempio seguente.

DefaultAzureCredential è una classe fornita dalla libreria client di Identità di Azure per .NET, che è possibile ottenere altre informazioni sulla panoramica di DefaultAzureCredential. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

L'ordine e le posizioni in cui DefaultAzureCredential cerca le credenziali sono disponibili nella panoramica della libreria di identità di Azure.

Ad esempio, l'app può eseguire l'autenticazione usando le credenziali di accesso di Visual Studio con durante lo sviluppo in locale. L'app può quindi usare un'identità gestita dopo la distribuzione in Azure. Per questa transizione non sono necessarie modifiche al codice.

Assegnare ruoli all'account utente di Microsoft Entra

Quando si sviluppa in locale, assicurarsi che l'account utente che accede ai dati BLOB disponga delle autorizzazioni corrette. Per leggere e scrivere dati BLOB, è necessario disporre del ruolo Collaboratore ai dati dei BLOB di archiviazione. Per assegnare a se stessi questo ruolo, è necessario assegnare il ruolo Amministratore accesso utenti o un altro ruolo che include l'azione Microsoft.Authorization/roleAssignments/write. È possibile assegnare ruoli controllo degli accessi in base al ruolo di Azure a un utente usando il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per altre informazioni sugli ambiti disponibili per le assegnazioni di ruolo, vedere la pagina panoramica dell'ambito.

In questo scenario si assegneranno le autorizzazioni all'account utente con ambito all'account utente, per seguire il principio dei privilegi minimi. Questa procedura offre agli utenti solo le autorizzazioni minime necessarie e crea ambienti di produzione più sicuri.

L'esempio seguente assegnerà il ruolo Collaboratore ai dati dei BLOB di archiviazione all'account utente, che fornisce l'accesso in lettura e scrittura ai dati BLOB nell'account di archiviazione.

Importante

Nella maggior parte dei casi, la propagazione dell'assegnazione di ruolo in Azure richiederà almeno due minuti, ma in rari casi può richiedere fino a otto minuti. Se si ricevono errori di autenticazione quando si esegue il codice per la prima volta, attendere alcuni istanti e riprovare.

  1. Nel portale di Azure, individuare l'account di archiviazione usando la barra di ricerca principale o lo spostamento a sinistra.

  2. Nella pagina di panoramica dell'account di archiviazione selezionare Controllo di accesso (IAM) dal menu a sinistra.

  3. Nella pagina Controllo di accesso (IAM), selezionare la scheda Assegnazioni di ruolo.

  4. Selezionare + Aggiungi dal menu in alto e quindi Aggiungi assegnazione di ruolo dal menu a discesa risultante.

    Screenshot che mostra come assegnare un ruolo.

  5. Usare la casella di ricerca per filtrare i risultati in base al ruolo desiderato. Per questo esempio, cercare Collaboratore ai dati dei BLOB di archiviazione e selezionare il risultato corrispondente, quindi scegliere Avanti.

  6. In Assegna accesso a selezionare Utente, gruppo o entità servizio e quindi scegliere + Seleziona membri.

  7. Nella finestra di dialogo cercare il nome utente di Microsoft Entra (in genere l'indirizzo di posta elettronica user@domain) e quindi scegliere Selezionare nella parte inferiore della finestra di dialogo.

  8. Selezionare Rivedi e assegna per passare alla pagina finale e quindi Rivedi e assegna di nuovo per completare il processo.

Accedere e connettere il codice dell'app ad Azure usando DefaultAzureCredential

È possibile autorizzare l'accesso ai dati nell'account di archiviazione seguendo questa procedura:

  1. Per lo sviluppo in locale, assicurarsi di essere autenticati con lo stesso account Microsoft Entra a cui è stato assegnato il ruolo. È possibile eseguire l'autenticazione tramite strumenti di sviluppo diffusi, ad esempio l'interfaccia della riga di comando di Azure o Azure PowerShell. Gli strumenti di sviluppo con cui è possibile eseguire l'autenticazione variano a seconda dei linguaggi.

    Accedere ad Azure tramite l'interfaccia della riga di comando di Azure usando il comando seguente:

    az login

  2. Per usare DefaultAzureCredential, aggiungere il pacchetto Azure.Identity all'applicazione.

    1. In Esplora soluzionifare clic con il pulsante destro del mouse sul nodo Dipendenze del progetto. Scegliere Gestisci pacchetti NuGet.

    2. Nella finestra risultante cercare Azure.Identity. Selezionare il risultato appropriato e selezionare Installa.

      Screenshot che mostra come aggiungere il pacchetto identity.

  3. Aggiornare il codice Program.cs in modo che corrisponda all'esempio seguente. Quando il codice viene eseguito nella workstation locale durante lo sviluppo, userà le credenziali per sviluppatori dello strumento con priorità a cui si è connessi per l'autenticazione in Azure, ad esempio l'interfaccia della riga di comando di 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. Assicurarsi di aggiornare il nome dell'account di archiviazione nell'URI dell'oggetto BlobServiceClient. Il nome dell'account di archiviazione è disponibile nella pagina di panoramica del portale di Azure.

    Uno screenshot che mostra come trovare il nome dell'account di archiviazione.

    Nota

    Quando viene distribuito in Azure, questo stesso codice può essere usato per autorizzare le richieste ad Archiviazione di Azure da un'applicazione in esecuzione in Azure. È tuttavia necessario abilitare l'identità gestita nell'app in Azure. Configurare quindi l'account di archiviazione per consentire la connessione a tale identità gestita. Per istruzioni dettagliate sulla configurazione di questa connessione tra i servizi di Azure, vedere l'esercitazione Autenticazione dalle app ospitate in Azure.

Creazione di un contenitore

Creare un nuovo contenitore nell'account di archiviazione chiamando il metodo CreateBlobContainerAsync sull'oggetto blobServiceClient. In questo esempio il codice aggiunge un valore GUID al nome del contenitore per assicurarsi che sia univoco.

Aggiungere il codice seguente alla fine del file 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);

Per altre informazioni sulla creazione di un contenitore e per esplorare altri esempi di codice, vedere Creare un contenitore BLOB con .NET.

Importante

I nomi dei contenitori devono essere in minuscolo. Per altre informazioni sulla denominazione di contenitori e BLOB, vedere Naming and Referencing Containers, Blobs, and Metadata (Assegnazione di nome e riferimento a contenitori, BLOB e metadati).

Caricare un BLOB in un contenitore

Caricare un BLOB in un contenitore usando UploadAsync. Il codice di esempio crea un file di testo nella directory dati locale da caricare nel contenitore.

Aggiungere il codice seguente alla fine del file 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);

Per altre informazioni sul caricamento di BLOB e per esplorare altri esempi di codice, vedere Caricare un BLOB con .NET.

Elencare BLOB in un contenitore

Elencare i BLOB nel contenitore chiamando il metodo GetBlobsAsync.

Aggiungere il codice seguente alla fine del file Program.cs:

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

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

Per altre informazioni sull'elenco dei BLOB e per esplorare altri esempi di codice, vedere Elencare i BLOB con .NET.

Scaricare un BLOB

Scaricare il BLOB creato in precedenza chiamando il metodo DownloadToAsync. Il codice di esempio aggiunge la stringa "DOWNLOADED" al nome del file in modo che sia possibile visualizzare entrambi i file nel file system locale.

Aggiungere il codice seguente alla fine del file 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);

Per altre informazioni sul download di BLOB e per esplorare altri esempi di codice, vedere Scaricare un BLOB con .NET.

Eliminare un contenitore

Il codice seguente elimina le risorse create dall'app eliminando il contenitore usando DeleteAsync. L'esempio di codice elimina anche i file locali creati dall'app.

L'app viene sospesa per l'input dell'utente chiamando Console.ReadLine prima dell'eliminazione di BLOB, contenitore e file locali. Si tratta di una valida opportunità per verificare che le risorse siano state create correttamente, prima che vengano eliminate.

Aggiungere il codice seguente alla fine del file 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");

Per altre informazioni sull'eliminazione di un contenitore e per esplorare altri esempi di codice, vedere Eliminare e ripristinare un contenitore BLOB con .NET.

Codice completato

Dopo aver completato questi passaggi, il codice nel file Program.cs dovrebbe essere simile al seguente:

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

Eseguire il codice

Questa app crea un file di test nella cartella data locale e lo carica nell'archiviazione BLOB. L'esempio elenca quindi i BLOB presenti nel contenitore e scarica il file con un nuovo nome per consentire il confronto tra i nuovi file e quelli precedenti.

Se si usa Visual Studio, premere F5 per compilare ed eseguire il codice e interagire con l'app console. Se si usa l'interfaccia della riga di comando di .NET, passare alla directory dell'applicazione, quindi compilare ed eseguire l'applicazione.

dotnet build

dotnet run

L'output dell'app è simile all'esempio seguente (i valori GUID omessi per la leggibilità):

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

Prima di iniziare il processo di pulizia, controllare che nella cartella dati siano presenti due file. È possibile aprirli e verificare che sono identici.

Pulire le risorse

Dopo aver verificato i file e aver completato il test, premere INVIO per eliminare i file di test insieme al contenitore creato nell'account di archiviazione. È anche possibile usare l'interfaccia della riga di comando di Azure per eliminare le risorse.

Al termine dell'avvio rapido, è possibile pulire le risorse create eseguendo il comando seguente:

azd down

Verrà richiesto di confermare l'eliminazione delle risorse. Immettere y per confermare.

Passaggio successivo

Esempi e guide per sviluppatori di Archiviazione di Azure per .NET