Desarrollo para Azure Files con .NET
Aprenda los conceptos básicos de desarrollar aplicaciones .NET que usen Azure Files para almacenar datos. En este artículo se muestra cómo crear una aplicación de consola simple para hacer lo siguiente con .NET y Azure Files:
- Obtenga el contenido de un archivo.
- Establezca la cuota o tamaño máximo para un recurso compartido de archivos.
- Cree una firma de acceso compartido (SAS) para un archivo.
- Copie un archivo en otro en la misma cuenta de almacenamiento.
- Copie un archivo en un blob en la misma cuenta de almacenamiento.
- Cree una instantánea de un recurso compartido de archivos.
- Restaure un archivo desde una instantánea de recurso compartido.
- Use las métricas de Azure Storage para solucionar problemas.
Para obtener más información acerca de Azure Files, consulte ¿Qué es Azure Files?.
Sugerencia
Extraer del repositorio ejemplos de código de Azure Storage
Para encontrar ejemplos de código de Azure Storage de un extremo a otro y fáciles de usar que se pueden descargar y ejecutar, consulte nuestra lista de ejemplos de Azure Storage.
Se aplica a
Tipo de recurso compartido de archivos | SMB | NFS |
---|---|---|
Recursos compartidos de archivos Estándar (GPv2), LRS/ZRS | ||
Recursos compartidos de archivos Estándar (GPv2), GRS/GZRS | ||
Recursos compartidos de archivos Premium (FileStorage), LRS/ZRS |
Descripción de las API de .NET
Azure Files proporciona dos enfoques generales para las aplicaciones cliente: bloque de mensajes del servidor (SMB) y REST. Dentro de. NET, las API System.IO
y Azure.Storage.Files.Shares
extraen estos métodos.
API | Cuándo se usa | Notas |
---|---|---|
System.IO | Su aplicación:
|
La E/S de archivos de Azure Files a través de SMB normalmente es igual que la E/S con cualquier recurso compartido de red o dispositivo de almacenamiento local. Para obtener una introducción a una serie de características en .NET, incluida la E/S de archivos, consulte Aplicación de consola. |
Azure.Storage.Files.Shares | Su aplicación:
|
Este artículo muestra el uso de Azure.Storage.Files.Shares para la E/S de archivos con REST (en lugar de SMB) y la administración del recurso compartido de archivos. |
Creación de la aplicación de consola y obtención del ensamblado
Puede usar la biblioteca cliente de Azure Files en cualquier tipo de aplicación .NET. Estas aplicaciones incluyen la nube de Azure, la Web, el escritorio y aplicaciones móviles. En esta guía, creamos una aplicación de consola para hacerlo más sencillo.
En Visual Studio, cree una nueva aplicación de consola de Windows. Los siguientes pasos muestran cómo crear una aplicación de consola en Visual Studio 2019. Los pasos son similares en otras versiones de Visual Studio.
- Inicie Visual Studio y seleccione Crear un proyecto.
- En Crear un proyecto, elija Aplicación de consola (.NET Framework) para C# y seleccione Siguiente.
- En Configure su nuevo proyecto, escriba un nombre para la app y seleccione Crear.
Agregue todos los ejemplos de código en este artículo a la clase Program
en el archivo Program.cs.
Uso de NuGet para instalar los paquetes necesarios
Consulte estos paquetes en el proyecto:
- Biblioteca de Azure Core para .NET: este paquete es la implementación de la canalización de clientes de Azure.
- Biblioteca cliente de blob de Azure Storage para .NET: Este paquete proporciona acceso mediante programación a los recursos de blob de la cuenta de almacenamiento.
- Biblioteca cliente de archivos de Azure Storage para .NET: Este paquete proporciona acceso mediante programación a los recursos de archivo de la cuenta de almacenamiento.
- Biblioteca de Configuration Manager del sistema para .NET: este paquete proporciona una clase que almacena y recupera valores en un archivo de configuración.
Puede usar NuGet para obtener los paquetes. Siga estos pasos:
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Administrar paquetes de NuGet.
En Administrador de paquetes NuGet, seleccione Examinar. A continuación, busque y elija Azure.Core, y, después, seleccione Instalar.
En este paso se instala el paquete y sus dependencias.
Busque e instale estos paquetes:
- Azure.Storage.Blobs
- Azure.Storage.Files.Shares
- System.Configuration.ConfigurationManager
Guardar las credenciales de la cuenta de almacenamiento en el archivo app.config
A continuación, guardará las credenciales en el archivo App.config del proyecto. En el Explorador de soluciones, haga doble clic en App.config
y edite el archivo para que sea similar al ejemplo siguiente.
Reemplace myaccount
por el nombre de la cuenta de almacenamiento y mykey
por la clave de la cuenta de almacenamiento.
<?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>
Nota:
El emulador de almacenamiento de Azurite no admite actualmente Azure Files. La cadena de conexión debe hacer referencia a una cuenta de Azure Storage en la nube para trabajar con Azure Files.
Adición de directivas using
En el Explorador de soluciones, abra el archivo Program.cs y agregue lo siguiente mediante directivas al principio del archivo.
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;
Obtener acceso al recurso compartido de archivos mediante programación
En el archivo Program.cs, agregue el código siguiente para obtener acceso al recurso compartido de archivos mediante programación.
El método siguiente crea un recurso compartido de archivos si aún no existe. El método se inicia creando un objeto ShareClient a partir de una cadena de conexión. A continuación, en el ejemplo se intenta descargar un archivo que creamos anteriormente. Llame a este método desde 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");
}
}
Establecer el tamaño máximo para un recurso compartido de archivos
A partir de la versión 5.x de la biblioteca cliente de Azure Files, se puede establecer la cuota (tamaño máximo) de un recurso compartido de archivos. También puede comprobar cuántos datos se almacenan actualmente en el recurso compartido.
Al establecer la cuota para un recurso compartido, se limita el tamaño total de los archivos almacenados en el recurso compartido. Si el tamaño total de los archivos del recurso compartido supera la cuota, los clientes no pueden aumentar el tamaño de los archivos existentes. Los clientes tampoco pueden crear archivos nuevos, a menos que estén vacíos.
En el ejemplo siguiente se muestra cómo comprobar el uso actual de un recurso compartido y cómo establecer la cuota para el recurso compartido.
//-------------------------------------------------
// 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");
}
}
Generar una firma de acceso compartido para un archivo o recurso compartido de archivos
A partir de la versión 5.x de la biblioteca cliente de Azure Files, puede generar una firma de acceso compartido (SAS) para un recurso compartido de archivos o para un archivo individual.
El método de ejemplo siguiente devuelve una SAS en un archivo del recurso compartido especificado.
//-------------------------------------------------
// 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;
}
Para más información sobre la creación y el uso de firmas de acceso compartido, consulte Funcionamiento de una firma de acceso compartido.
Copiar archivos
A partir de la versión 5.x de la biblioteca cliente de Azure Files, puede copiar un archivo en otro, un archivo en un blob o un blob en un archivo.
También puede usar AzCopy para copiar un archivo en otro o para copiar un blob en un archivo o viceversa. Consulte Introducción a AzCopy.
Nota:
Si va a copiar un blob en un archivo o un archivo en un blob, debe usar una firma de acceso compartido (SAS) para autorizar el acceso al objeto de origen, incluso si está copiando dentro de la misma cuenta de almacenamiento.
Copiar un archivo en otro
En el ejemplo siguiente se copia un archivo en otro en el mismo recurso compartido. Puede usar la autenticación de clave compartida para realizar la copia porque en esta operación se copian archivos de la misma cuenta de almacenamiento.
//-------------------------------------------------
// 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}");
}
}
}
Copiar un archivo en un blob
En el ejemplo siguiente se crea un archivo y se copia en un blob de la misma cuenta de almacenamiento. El ejemplo crea una SAS para el archivo de origen, que el servicio usa para autorizar el acceso al archivo de origen durante la operación de 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}");
}
}
}
Puede copiar un blob en un archivo de la misma manera. Si el objeto de origen es un blob, cree una SAS para autorizar el acceso a dicho blob durante la operación de copia.
Instantáneas de recursos compartido
A partir de la versión 8.5 de la biblioteca cliente de Azure Files, se puede crear una instantánea de recurso compartido. Las instantáneas de recursos compartidos también se pueden enumerar, explorar y eliminar. Una vez creadas, las instantáneas de recursos compartidos son de solo lectura.
Creación de instantáneas de recurso compartido
En el siguiente ejemplo se crea una instantánea de recurso compartido.
//-------------------------------------------------
// 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}");
}
}
Enumerar instantáneas del recurso compartido
En el ejemplo siguiente se enumeran las instantáneas de un recurso compartido.
//-------------------------------------------------
// 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}");
}
}
}
Enumeración de archivos y directorios en instantáneas de recursos compartidos
En el ejemplo siguiente se examinan los archivos y directorios de instantáneas de recursos compartidos.
//-------------------------------------------------
// 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}");
}
}
}
Restauración de recursos compartidos de archivos o archivos desde instantáneas de recursos compartidos
La toma de una instantánea de un recurso compartido de archivos permite recuperar archivos individuales o todo el recurso compartido de archivos.
Para restaurar un archivo de una instantánea del recurso compartido de archivos, consulte las instantáneas de recursos compartidos de un recurso compartido de archivos. Después, puede recuperar un archivo que pertenezca a una instantánea de recurso compartido determinada. Use esa versión para leer directamente el archivo o restaurarlo.
//-------------------------------------------------
// 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}");
}
Eliminación de instantáneas de recursos compartidos
En el siguiente ejemplo se elimina una instantánea de recurso compartido.
//-------------------------------------------------
// 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}");
}
}
Solución de problemas de Azure Files mediante métricas
Azure Storage Analytics admite métricas para Azure Files. Con los datos de las métricas, es posible seguir paso a paso las solicitudes y diagnosticar problemas.
Puede habilitar las métricas para Azure Files mediante Azure Portal. La métrica también se puede habilitar mediante programación. Para ello, hay que llamar a la operación Set File Service Properties con la API de REST o una de sus análogas de la biblioteca cliente de Azure Files.
En el siguiente ejemplo de código se muestra cómo usar la biblioteca cliente de .NET a fin de habilitar las métricas para 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 encuentra algún problema, consulte Solución de problemas de Azure Files.
Pasos siguientes
Para más información acerca de Azure Files, consulte los siguientes recursos:
- Introducción a AzCopy
- Solucionar problemas de Azure Files
- API de Azure Storage para .NET
- File Service REST API (API de REST de File Service)
Para obtener ejemplos de código relacionados con los SDK de .NET versión 11.x en desuso, consulte Ejemplos de código con la versión 11.x de .NET.