Développer pour Azure Files avec .NET
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 | ||
Partages de fichiers Standard (GPv2), GRS/GZRS | ||
Partages de fichiers Premium (FileStorage), LRS/ZRS |
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 :
|
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 :
|
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.
- Démarrez Visual Studio et sélectionnez Créer un projet.
- Dans Créer un projet, choisissez Application console (.NET Framework) pour C#, puis sélectionnez Suivant.
- 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 :
- Bibliothèque Azure Core pour .NET : Ce package est l’implémentation du pipeline client Azure.
- Bibliothèque de client Stockage Blob Azure pour .NET: Ce package fournit un accès par programmation aux ressources d’objets blob de votre compte de stockage.
- Bibliothèque de client Fichiers du Stockage Azure pour .NET : Ce package fournit un accès par programmation aux ressources de fichiers de votre compte de stockage.
- Bibliothèque System Configuration Manager pour .NET : Ce package fournit une classe qui stocke et récupère des valeurs dans un fichier de configuration.
Vous pouvez utiliser NuGet pour obtenir ces packages. Procédez comme suit :
Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis choisissez Gérer les packages NuGet.
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.
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>
Remarque
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.
Remarque
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 :
- Bien démarrer avec AzCopy
- Dépanner Sauvegarde Azure
- API de stockage Azure pour .NET
- API REST du service de fichiers
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.