Développer pour Azure Files avec .NET

  • Article

Découvrez les bases du développement d’applications .NET qui utilisent Azure Files pour stocker des données. Cet article explique comment créer une application console simple pour effectuer les opérations suivantes avec .NET et Azure Files :

  • Obtenir le contenu d’un fichier
  • Définir la taille maximale, ou quota, pour un partage de fichiers.
  • Créer une signature d’accès partagé (SAP) pour un fichier.
  • Copier un fichier dans un autre fichier au sein du même compte de stockage
  • Copier un fichier dans un objet blob au sein du même compte de stockage.
  • Créer un instantané d’un partage de fichiers.
  • Restaurer un fichier à partir d’un instantané de partage de fichiers.
  • Utiliser Azure Storage Metrics pour la résolution des problèmes

Pour en savoir plus sur Azure Files, consultez Qu’est-ce qu’Azure Files ?.

Conseil

Consultez le référentiel d’exemples de code de Stockage Azure

Pour des exemples de code Stockage Azure de bout en bout faciles à utiliser que vous pouvez télécharger et exécuter, consultez notre liste Exemples Stockage Azure.

S’applique à

Type de partage de fichiers SMB NFS
Partages de fichiers Standard (GPv2), LRS/ZRS Oui Non
Partages de fichiers Standard (GPv2), GRS/GZRS Oui Non
Partages de fichiers Premium (FileStorage), LRS/ZRS Oui Non

Compréhension des API .NET

Azure Files fournit deux grandes approches pour les applications clientes : Server Message Block (SMB) et REST. Dans .NET, l’abstraction de ces approches est fournie par les API System.IO et Azure.Storage.Files.Shares.

API Quand l’utiliser Notes
System.IO Votre application :
  • Doit lire/écrire des fichiers à l’aide de SMB.
  • Est en cours d’exécution sur un périphérique qui a accès via le port 445 à votre compte Azure Files
  • N’a pas besoin de gérer les paramètres d’administration du partage de fichiers
 Les E/S de fichiers implémentées avec Azure Files sur SMB sont généralement similaires aux E/S avec un partage de fichiers réseau ou un périphérique de stockage local. Pour découvrir une présentation de certaines fonctionnalités de .NET, notamment des E/S de fichiers, consultez le tutoriel Application console.
Azure.Storage.Files.Shares Votre application :
  • Ne peut pas accéder à Azure Files à l’aide de SMB sur le port 445 en raison des contraintes de pare-feu ou d’ISP.
  • Nécessite une fonctionnalité d’administration, telle que la capacité de définir le quota d’un partage de fichier ou de créer une signature d’accès partagé
 Cet article décrit l’utilisation de Azure.Storage.Files.Shares pour les E/S de fichiers utilisant REST plutôt que SMB et la gestion du partage de fichiers.

Création de l’application console et obtention de l’assembly

Vous pouvez utiliser la bibliothèque de client Azure Files dans n’importe quel type d’application .NET. Ces applications incluent les applications cloud Azure, web, de bureau et mobiles. Dans ce guide, nous allons créer une application console pour rester simple.

Dans Visual Studio, créez une application de console Windows. Les étapes suivantes vous montrent comment créer une application console dans Visual Studio 2019. Les étapes sont semblables pour d’autres versions de Visual Studio.

  1. Démarrez Visual Studio et sélectionnez Créer un projet.
  2. Dans Créer un projet, choisissez Application console (.NET Framework) pour C#, puis sélectionnez Suivant.
  3. Dans Configurer votre nouveau projet, entrez un nom pour l’application, puis sélectionnez Créer.

Ajoutez tous les exemples de code de cet article à la classe Program dans le fichier Program.cs.

Utiliser NuGet pour installer les packages requis

Reportez-vous à ces packages dans votre projet :

Vous pouvez utiliser NuGet pour obtenir ces packages. Procédez comme suit :

  1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis choisissez Gérer les packages NuGet.

  2. Dans le Gestionnaire de package NuGet, sélectionnez Parcourir. Ensuite, recherchez et choisissez Azure.Core, puis sélectionnez Installer.

    Cette étape installe le package et ses dépendances.

  3. Recherchez et installez ces packages :

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

Enregistrer les informations d’identification de votre compte de stockage dans le fichier App.config

Enregistrez ensuite vos informations d’identification dans le fichier App.config de votre projet. Dans l’Explorateur de solutions, double-cliquez sur App.config, puis modifiez le fichier afin qu’il soit similaire à l’exemple suivant.

Remplacez myaccount par le nom de votre compte de stockage et mykey par la clé de votre compte de stockage.

<?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>

Notes

L’émulateur de stockage Azurite ne prend actuellement pas en charge Azure Files. Votre chaîne de connexion doit cibler un compte de stockage Azure dans le cloud pour fonctionner avec Azure Files.

Ajouter des directives d’utilisation

Dans l’Explorateur de solutions, ouvrez le fichier Program.cs, puis ajoutez les directives using suivantes en haut du fichier.

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;

Accès au partage de fichiers par programmation

Dans le fichier Program.cs, ajoutez le code suivant pour accéder au partage de fichiers programmatiquement.

La méthode suivante crée un partage de fichiers, s’il n’en existe pas déjà un. La méthode commence par créer un objet ShareClient à partir d’une chaîne de connexion. L’exemple tente ensuite de télécharger un fichier que nous avons créé précédemment. Appelez cette méthode à partir de 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");
    }
}

Définition de la taille maximale d’un partage de fichiers

À compter de la version 5.x de la bibliothèque de client Azure Files, vous pouvez définir le quota (taille maximale) d’un partage de fichiers. Vous pouvez également vérifier la quantité de données actuellement stockée sur le partage.

Le fait de définir le quota pour un partage limite la taille totale des fichiers stockés sur ce partage. Si la taille totale des fichiers sur le partage dépasse le quota, les clients ne peuvent pas augmenter la taille des fichiers existants. Les clients ne peuvent pas non plus créer de nouveaux fichiers, sauf si ces fichiers sont vides.

L’exemple ci-dessous illustre comment vérifier l’utilisation actuelle pour un partage et comment définir le quota pour le partage.

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

Génération d’une signature d’accès partagé pour un fichier ou partage de fichiers

À compter de la version 5.x de la bibliothèque de client Azure Files, vous pouvez générer une signature d’accès partagé (SAP) pour un partage de fichiers ou un fichier individuel.

L’exemple de méthode suivant retourne une signature d’accès partagé sur un fichier du partage spécifié.

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

Pour plus d’informations sur la création et l’utilisation de signatures d’accès partagé, consultez Fonctionnement d’une signature d’accès partagé.

Copie des fichiers

À compter de la version 5.x de la bibliothèque de client Azure Files, vous pouvez copier un fichier dans un autre fichier, un fichier dans un objet blob ou un objet blob dans un fichier.

Vous pouvez également utiliser AzCopy pour copier un fichier dans un autre ou pour copier un objet blob dans un fichier, ou inversement. Consultez Bien démarrer avec AzCopy.

Notes

Si vous copiez un objet blob dans un fichier ou un fichier dans un objet blob, vous devez utiliser une signature d’accès partagé (SAP) pour autoriser l’accès à l’objet source, même si vous effectuez la copie dans le même compte de stockage.

Copier un fichier dans un autre

L’exemple suivant copie un fichier dans un autre fichier au sein du même partage. Vous pouvez utiliser l’Authentification par clé partagée pour effectuer la copie car cette opération copie des fichiers dans le même compte de stockage.

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

Copier un fichier dans un objet blob

L’exemple ci-dessous crée un fichier et le copie dans un objet blob au sein du même compte de stockage. L’exemple crée une SAP pour le fichier source, que le service utilise pour autoriser l’accès au fichier source pendant l’opération de copie.

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

Vous pouvez copier un objet blob dans un fichier de la même façon. Si l’objet source est un objet blob, créez une SAP pour authentifier l’accès à cet objet blob pendant l’opération de copie.

Instantanés de partage

À compter de la version 8.5 de la bibliothèque de client Azure Files, vous pouvez créer un instantané de partage. Vous pouvez également répertorier ou parcourir des instantanés de partage et les supprimer. Une fois créés, les instantanés de partage sont en lecture seule.

Créer des instantanés de partage

L’exemple suivant permet de créer un instantané de partage de fichier.

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

Répertorier les instantanés de partage

L’exemple suivant liste les instantanés présents sur un partage.

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

Lister les fichiers et les répertoires figurant dans des instantanés de partage

L’exemple suivant parcourt les fichiers et les répertoires figurant dans des instantanés de partage.

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

Restaurer des partages de fichiers ou des fichiers à partir d’instantanés de partage

Prendre un instantané d’un partage de fichiers vous permet de récupérer des fichiers ou l’intégralité du partage de fichiers.

Vous pouvez restaurer un fichier à partir d’un instantané de partage de fichiers en interrogeant les instantanés de partage d’un partage de fichiers. Vous pouvez ensuite récupérer un fichier qui appartient à un instantané de partage particulier. Utilisez cette version pour restaurer ou pour lire directement le fichier.

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

Supprimer des instantanés de partage

L’exemple suivant permet de supprimer un instantané de partage de fichier.

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

Résoudre les problèmes liés à Azure Files à l’aide de métriques

Azure Storage Analytics prend en charge les métriques pour Azure Files. Avec les données de métriques, vous pouvez suivre les demandes et diagnostiquer les problèmes.

Vous pouvez activer les métriques pour Azure Files par le biais du Portail Azure. Vous pouvez également activer les métriques par programmation en appelant l’opération Définition des propriétés du service Fichier avec l’API REST ou l’un de ses équivalents dans la bibliothèque de client Azure Files.

L’exemple de code suivant montre comment utiliser la bibliothèque de client .NET afin d’activer les métriques pour Azure Files.

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

Si vous rencontrez des problèmes, consultez Résoudre les problèmes liés à Azure Files.

Étapes suivantes

Pour plus d’informations sur Azure Files, consultez les ressources suivantes :

Vidéos et articles conceptuels

Outils pris en charge pour le stockage de fichiers

Informations de référence

Pour obtenir des exemples de code associés utilisant des Kits de développement logiciel (SDK) .NET version 11.x dépréciés, consultez l’article Exemples de code utilisant .NET version 11.x.