Sviluppare per File di Azure con .NET

Informazioni di base sullo sviluppo di applicazioni .NET che usano File di Azure per archiviare i dati. Questo articolo illustra come creare una semplice applicazione console per eseguire le operazioni seguenti con .NET e File di Azure:

• Ottenere il contenuto di un file.
• Impostare le dimensioni massime o la quota per una condivisione file.
• Creare una firma di accesso condiviso (SAS) per un file.
• Copiare un file in un altro file nello stesso account di archiviazione.
• Copiare un file in un BLOB nello stesso account di archiviazione.
• Creare uno snapshot di una condivisione file.
• Ripristinare un file da uno snapshot di condivisione.
• Usare la metrica di Archiviazione di Azure per la risoluzione dei problemi.

Per altre informazioni su File di Azure, vedere Che cos'è File di Azure?

Si applica a

Tipo di condivisione file	SMB	NFS
Condivisioni file Standard (GPv2), archiviazione con ridondanza locale/archiviazione con ridondanza della zona
Condivisioni file Standard (GPv2), archiviazione con ridondanza geografica/archiviazione con ridondanza geografica della zona
Condivisioni file Premium (FileStorage), archiviazione con ridondanza locale/archiviazione con ridondanza della zona

Informazioni sulle API .NET

File di Azure offre due ampi approcci alle applicazioni client: Server Message Block (SMB) e REST. All'interno di .NET, le API System.IO e Azure.Storage.Files.Shares astraggono questi approcci.

Creare l'applicazione console e ottenere l'assembly

È possibile usare la libreria client di File di Azure in qualsiasi tipo di app .NET. Queste app includono app cloud, Web, desktop e per dispositivi mobili di Azure. Per semplicità, in questa guida si crea un'applicazione console.

In Visual Studio creare una nuova applicazione console di Windows. La procedura seguente illustra come creare un'applicazione console in Visual Studio 2019. La procedura è simile per le altre versioni di Visual Studio.

1. Avviare Visual Studio e selezionare Crea un nuovo progetto.
2. In Crea un nuovo progetto scegliere App console (.NET Framework) per C#, quindi selezionare Avanti.
3. In Configura il nuovo progetto, immettere un nome per l'app e selezionare Crea.

Aggiungere tutti gli esempi di codice in questo articolo alla classe Program nel file Program.cs.

Usare NuGet per installare i pacchetti necessari

Fare riferimento a questi pacchetti nel progetto:

• Libreria di base di Azure per .NET: questo pacchetto è l'implementazione della pipeline client di Azure.
• Libreria client BLOB del servizio di archiviazione di Azure per .NET: questo pacchetto fornisce l'accesso a livello di codice alle risorse BLOB nell'account di archiviazione.
• Libreria client di File di Archiviazione di Azure per .NET: questo pacchetto fornisce l'accesso a livello di codice alle risorse di file nell'account di archiviazione.
• Libreria di System Configuration Manager per .NET: questo pacchetto fornisce una classe che archivia e recupera i valori in un file di configurazione.

Per ottenere i pacchetti, è possibile usare NuGet. Seguire questa procedura:

1. In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Gestisci pacchetti NuGet.

2. In Gestione pacchetti NuGet, selezionare Sfoglia. Cercare quindi e scegliere Azure.Core e quindi selezionare Installa.

   Questo passaggio installa il pacchetto e le relative dipendenze.

3. Cercare e installare i pacchetti seguenti:

   • Azure.Storage.Blobs
   • Azure.Storage.Files.Shares
   • System.Configuration.ConfigurationManager

Salvare le credenziali dell'account di archiviazione nel file App.config

A questo punto salvare le credenziali nel file App.config del progetto. In Esplora soluzioni, fare doppio clic su App.config e modificare il file in modo che sia simile all'esempio seguente.

Sostituire myaccount con il nome dell'account di archiviazione e mykey con la chiave dell'account di archiviazione.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="StorageConnectionString" 
      value="DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net" />
    <add key="StorageAccountName" value="myaccount" />
    <add key="StorageAccountKey" value="mykey" />
  </appSettings>
</configuration>

Aggiungere le direttive using

In Esplora soluzioni, aprire il file Program.cs e aggiungere le direttive using seguenti all'inizio del file.

using System;
using System.Configuration;
using System.IO;
using System.Threading.Tasks;
using Azure;
using Azure.Storage;
using Azure.Storage.Blobs;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;
using Azure.Storage.Sas;

Accedere alla condivisione file a livello di programmazione

Nel file Program.cs aggiungere il codice seguente per accedere alla condivisione file a livello di codice.

Il metodo seguente crea una condivisione file se non esiste già. Il metodo inizia creando un oggetto ShareClient da una stringa di connessione. L'esempio tenta quindi di scaricare un file creato in precedenza. Chiamare questo metodo da Main().

//-------------------------------------------------
// Create a file share
//-------------------------------------------------
public async Task CreateShareAsync(string shareName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a ShareClient which will be used to create and manipulate the file share
    ShareClient share = new ShareClient(connectionString, shareName);

    // Create the share if it doesn't already exist
    await share.CreateIfNotExistsAsync();

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        Console.WriteLine($"Share created: {share.Name}");

        // Get a reference to the sample directory
        ShareDirectoryClient directory = share.GetDirectoryClient("CustomLogs");

        // Create the directory if it doesn't already exist
        await directory.CreateIfNotExistsAsync();

        // Ensure that the directory exists
        if (await directory.ExistsAsync())
        {
            // Get a reference to a file object
            ShareFileClient file = directory.GetFileClient("Log1.txt");

            // Ensure that the file exists
            if (await file.ExistsAsync())
            {
                Console.WriteLine($"File exists: {file.Name}");

                // Download the file
                ShareFileDownloadInfo download = await file.DownloadAsync();

                // Save the data to a local file, overwrite if the file already exists
                using (FileStream stream = File.OpenWrite(@"downloadedLog1.txt"))
                {
                    await download.Content.CopyToAsync(stream);
                    await stream.FlushAsync();
                    stream.Close();

                    // Display where the file was saved
                    Console.WriteLine($"File downloaded: {stream.Name}");
                }
            }
        }
    }
    else
    {
        Console.WriteLine($"CreateShareAsync failed");
    }
}

Impostare la dimensione massima per una condivisione file

A partire dalla versione 5.x della libreria client di File di Azure, è possibile impostare la quota (dimensione massima) per una condivisione file. È anche possibile controllare la quantità di dati archiviata attualmente nella condivisione.

Impostare la quota per una condivisione limita le dimensioni totali dei file archiviati nella condivisione. Se le dimensioni totali dei file nella condivisione superano la quota, i client non possono aumentare le dimensioni dei file esistenti. I client non possono anche creare nuovi file, a meno che tali file non siano vuoti.

L'esempio seguente illustra come controllare l'uso corrente per una condivisione e come impostare la quota per la condivisione.

//-------------------------------------------------
// Set the maximum size of a share
//-------------------------------------------------
public async Task SetMaxShareSizeAsync(string shareName, int increaseSizeInGiB)
{
    const long ONE_GIBIBYTE = 10737420000; // Number of bytes in 1 gibibyte

    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instantiate a ShareClient which will be used to access the file share
    ShareClient share = new ShareClient(connectionString, shareName);

    // Create the share if it doesn't already exist
    await share.CreateIfNotExistsAsync();

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        // Get and display current share quota
        ShareProperties properties = await share.GetPropertiesAsync();
        Console.WriteLine($"Current share quota: {properties.QuotaInGB} GiB");

        // Get and display current usage stats for the share
        ShareStatistics stats = await share.GetStatisticsAsync();
        Console.WriteLine($"Current share usage: {stats.ShareUsageInBytes} bytes");

        // Convert current usage from bytes into GiB
        int currentGiB = (int)(stats.ShareUsageInBytes / ONE_GIBIBYTE);

        // This line sets the quota to be the current 
        // usage of the share plus the increase amount
        await share.SetQuotaAsync(currentGiB + increaseSizeInGiB);

        // Get the new quota and display it
        properties = await share.GetPropertiesAsync();
        Console.WriteLine($"New share quota: {properties.QuotaInGB} GiB");
    }
}

Generare la firma di accesso condiviso per un file o una condivisione file

A partire dalla versione 5.x della libreria client di File di Azure, è possibile generare una firma di accesso condiviso (SAS) per una condivisione file o per un singolo file.

Il metodo di esempio seguente restituisce una firma di accesso condiviso in un file nella condivisione specificata.

//-------------------------------------------------
// Create a SAS URI for a file
//-------------------------------------------------
public Uri GetFileSasUri(string shareName, string filePath, DateTime expiration, ShareFileSasPermissions permissions)
{
    // Get the account details from app settings
    string accountName = ConfigurationManager.AppSettings["StorageAccountName"];
    string accountKey = ConfigurationManager.AppSettings["StorageAccountKey"];

    ShareSasBuilder fileSAS = new ShareSasBuilder()
    {
        ShareName = shareName,
        FilePath = filePath,

        // Specify an Azure file resource
        Resource = "f",

        // Expires in 24 hours
        ExpiresOn = expiration
    };

    // Set the permissions for the SAS
    fileSAS.SetPermissions(permissions);

    // Create a SharedKeyCredential that we can use to sign the SAS token
    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);

    // Build a SAS URI
    UriBuilder fileSasUri = new UriBuilder($"https://{accountName}.file.core.windows.net/{fileSAS.ShareName}/{fileSAS.FilePath}");
    fileSasUri.Query = fileSAS.ToSasQueryParameters(credential).ToString();

    // Return the URI
    return fileSasUri.Uri;
}

Per altre informazioni sulla creazione e l'uso delle firme di accesso condiviso, vedere Funzionamento di una firma di accesso condiviso.

Copiare i file

A partire dalla versione 5.x della libreria client di File di Azure, è possibile copiare un file in un altro file, un file in un BLOB o un BLOB in un file.

È anche possibile usare AzCopy per copiare un file in un altro o per copiare un BLOB in un file o in altro modo. Vedere Introduzione ad AzCopy.

Copiare un file in un altro file

Nell'esempio seguente viene copiato un file in un altro file nella stessa condivisione. È possibile usare l'autenticazione con chiave condivisa per eseguire la copia perché questa operazione copia i file all'interno dello stesso account di archiviazione.

//-------------------------------------------------
// Copy file within a directory
//-------------------------------------------------
public async Task CopyFileAsync(string shareName, string sourceFilePath, string destFilePath)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Get a reference to the file we created previously
    ShareFileClient sourceFile = new ShareFileClient(connectionString, shareName, sourceFilePath);

    // Ensure that the source file exists
    if (await sourceFile.ExistsAsync())
    {
        // Get a reference to the destination file
        ShareFileClient destFile = new ShareFileClient(connectionString, shareName, destFilePath);

        // Start the copy operation
        await destFile.StartCopyAsync(sourceFile.Uri);

        if (await destFile.ExistsAsync())
        {
            Console.WriteLine($"{sourceFile.Uri} copied to {destFile.Uri}");
        }
    }
}

Copiare un file in un BLOB

Nell'esempio seguente viene creato un file che viene copiato in un BLOB nello stesso account di archiviazione. L'esempio crea una firma di accesso condiviso per il file di origine, che il servizio usa per autorizzare l'accesso al file di origine durante l'operazione di copia.

//-------------------------------------------------
// Copy a file from a share to a blob
//-------------------------------------------------
public async Task CopyFileToBlobAsync(string shareName, string sourceFilePath, string containerName, string blobName)
{
    // Get a file SAS from the method created ealier
    Uri fileSasUri = GetFileSasUri(shareName, sourceFilePath, DateTime.UtcNow.AddHours(24), ShareFileSasPermissions.Read);

    // Get a reference to the file we created previously
    ShareFileClient sourceFile = new ShareFileClient(fileSasUri);

    // Ensure that the source file exists
    if (await sourceFile.ExistsAsync())
    {
        // Get the connection string from app settings
        string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

        // Get a reference to the destination container
        BlobContainerClient container = new BlobContainerClient(connectionString, containerName);

        // Create the container if it doesn't already exist
        await container.CreateIfNotExistsAsync();

        BlobClient destBlob = container.GetBlobClient(blobName);

        await destBlob.StartCopyFromUriAsync(sourceFile.Uri);

        if (await destBlob.ExistsAsync())
        {
            Console.WriteLine($"File {sourceFile.Name} copied to blob {destBlob.Name}");
        }
    }
}

È possibile copiare un BLOB in un file nello stesso modo. Se l'oggetto di origine è un BLOB, creare una firma di accesso condiviso per autorizzare l'accesso al BLOB durante l'operazione di copia.

Snapshot di condivisione

A partire dalla versione 8.5 della libreria client di File di Azure, è possibile creare uno snapshot di condivisione. nonché elencare, esplorare ed eliminare snapshot di condivisione. Dopo la creazione, gli snapshot di condivisione sono di sola lettura.

Creare snapshot di condivisione

L'esempio seguente crea uno snapshot di condivisione file.

//-------------------------------------------------
// Create a share snapshot
//-------------------------------------------------
public async Task CreateShareSnapshotAsync(string shareName)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);

    // Instantiate a ShareClient which will be used to access the file share
    ShareClient share = shareServiceClient.GetShareClient(shareName);

    // Ensure that the share exists
    if (await share.ExistsAsync())
    {
        // Create a snapshot
        ShareSnapshotInfo snapshotInfo = await share.CreateSnapshotAsync();
        Console.WriteLine($"Snapshot created: {snapshotInfo.Snapshot}");
    }
}

Elencare gli snapshot di condivisione

Nell'esempio seguente vengono elencati gli snapshot di una condivisione.

//-------------------------------------------------
// List the snapshots on a share
//-------------------------------------------------
public void ListShareSnapshots()
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);

    // Display each share and the snapshots on each share
    foreach (ShareItem item in shareServiceClient.GetShares(ShareTraits.All, ShareStates.Snapshots))
    {
        if (null != item.Snapshot)
        {
            Console.WriteLine($"Share: {item.Name}\tSnapshot: {item.Snapshot}");
        }
    }
}

Elencare file e directory all'interno di snapshot di condivisione

L'esempio seguente consente di esplorare file e directory all'interno degli snapshot di condivisione.

//-------------------------------------------------
// List the snapshots on a share
//-------------------------------------------------
public void ListSnapshotContents(string shareName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    Console.WriteLine($"Share: {share.Name}");

    // Get as ShareClient that points to a snapshot
    ShareClient snapshot = share.WithSnapshot(snapshotTime);

    // Get the root directory in the snapshot share
    ShareDirectoryClient rootDir = snapshot.GetRootDirectoryClient();

    // Recursively list the directory tree
    ListDirTree(rootDir);
}

//-------------------------------------------------
// Recursively list a directory tree
//-------------------------------------------------
public void ListDirTree(ShareDirectoryClient dir)
{
    // List the files and directories in the snapshot
    foreach (ShareFileItem item in dir.GetFilesAndDirectories())
    {
        if (item.IsDirectory)
        {
            Console.WriteLine($"Directory: {item.Name}");
            ShareDirectoryClient subDir = dir.GetSubdirectoryClient(item.Name);
            ListDirTree(subDir);
        }
        else
        {
            Console.WriteLine($"File: {dir.Name}\\{item.Name}");
        }
    }
}

Ripristinare condivisioni file o file da snapshot di condivisione

L'acquisizione di uno snapshot di una condivisione file consente di recuperare singoli file o l'intera condivisione file.

È possibile ripristinare un file da uno snapshot di condivisione file eseguendo una query sugli snapshot di condivisione di una condivisione file. È quindi possibile recuperare un file appartenente a uno snapshot di condivisione specifico. Usare tale versione per leggere o ripristinare direttamente il file.

//-------------------------------------------------
// Restore file from snapshot
//-------------------------------------------------
public async Task RestoreFileFromSnapshot(string shareName, string directoryName, string fileName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    // Get as ShareClient that points to a snapshot
    ShareClient snapshot = share.WithSnapshot(snapshotTime);

    // Get a ShareDirectoryClient, then a ShareFileClient to the snapshot file
    ShareDirectoryClient snapshotDir = snapshot.GetDirectoryClient(directoryName);
    ShareFileClient snapshotFile = snapshotDir.GetFileClient(fileName);

    // Get a ShareDirectoryClient, then a ShareFileClient to the live file
    ShareDirectoryClient liveDir = share.GetDirectoryClient(directoryName);
    ShareFileClient liveFile = liveDir.GetFileClient(fileName);

    // Restore the file from the snapshot
    ShareFileCopyInfo copyInfo = await liveFile.StartCopyAsync(snapshotFile.Uri);

    // Display the status of the operation
    Console.WriteLine($"Restore status: {copyInfo.CopyStatus}");
}

Eliminare snapshot di condivisione

L'esempio seguente elimina uno snapshot di condivisione file.

//-------------------------------------------------
// Delete a snapshot
//-------------------------------------------------
public async Task DeleteSnapshotAsync(string shareName, string snapshotTime)
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Get a ShareClient
    ShareClient share = shareService.GetShareClient(shareName);

    // Get a ShareClient that points to a snapshot
    ShareClient snapshotShare = share.WithSnapshot(snapshotTime);

    try
    {
        // Delete the snapshot
        await snapshotShare.DeleteIfExistsAsync();
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine($"Exception: {ex.Message}");
        Console.WriteLine($"Error code: {ex.Status}\t{ex.ErrorCode}");
    }
}

Risolvere i problemi di File di Azure usando le metriche

Analisi archiviazione di Azure supporta le metriche per File di Azure. Grazie ai dati di metrica, è possibile monitorare le richieste e diagnosticare i problemi.

È possibile abilitare le metriche per File di Azure dal portale di Azure. È anche possibile abilitare le metriche a livello di codice chiamando l'operazione di Impostare le proprietà del servizio file con l'API REST o una delle relative analogie nella libreria client di File di Azure.

L'esempio di codice seguente illustra come usare la libreria client .NET per abilitare le metriche per File di Azure.

//-------------------------------------------------
// Use metrics
//-------------------------------------------------
public async Task UseMetricsAsync()
{
    // Get the connection string from app settings
    string connectionString = ConfigurationManager.AppSettings["StorageConnectionString"];

    // Instatiate a ShareServiceClient
    ShareServiceClient shareService = new ShareServiceClient(connectionString);

    // Set metrics properties for File service
    await shareService.SetPropertiesAsync(new ShareServiceProperties()
    {
        // Set hour metrics
        HourMetrics = new ShareMetrics()
        {
            Enabled = true,
            IncludeApis = true,
            Version = "1.0",

            RetentionPolicy = new ShareRetentionPolicy()
            {
                Enabled = true,
                Days = 14
            }
        },

        // Set minute metrics
        MinuteMetrics = new ShareMetrics()
        {
            Enabled = true,
            IncludeApis = true,
            Version = "1.0",

            RetentionPolicy = new ShareRetentionPolicy()
            {
                Enabled = true,
                Days = 7
            }
        }
    });

    // Read the metrics properties we just set
    ShareServiceProperties serviceProperties = await shareService.GetPropertiesAsync();

    // Display the properties
    Console.WriteLine();
    Console.WriteLine($"HourMetrics.InludeApis: {serviceProperties.HourMetrics.IncludeApis}");
    Console.WriteLine($"HourMetrics.RetentionPolicy.Days: {serviceProperties.HourMetrics.RetentionPolicy.Days}");
    Console.WriteLine($"HourMetrics.Version: {serviceProperties.HourMetrics.Version}");
    Console.WriteLine();
    Console.WriteLine($"MinuteMetrics.InludeApis: {serviceProperties.MinuteMetrics.IncludeApis}");
    Console.WriteLine($"MinuteMetrics.RetentionPolicy.Days: {serviceProperties.MinuteMetrics.RetentionPolicy.Days}");
    Console.WriteLine($"MinuteMetrics.Version: {serviceProperties.MinuteMetrics.Version}");
    Console.WriteLine();
}

Se si verificano problemi, vedere Risolvere i problemi relativi a File di Azure.

Passaggi successivi

Per altre informazioni su File di Azure, vedere le risorse seguenti:

• Introduzione ad AzCopy
• Risolvere i problemi relativi ad Azure AD
• API di Archiviazione di Azure per .NET
• API REST del servizio file

Per esempi di codice correlati che usano SDK .NET versione 11.x deprecata, vedere Esempi di codice con .NET versione 11.x.