Desarrollo para Azure Files con .NET

Aprenda a desarrollar aplicaciones .NET que usan Azure Files para almacenar datos. Azure Files es un servicio de recurso compartido de archivos administrado en la nube. Proporciona recursos compartidos de archivos totalmente administrados a los que se puede acceder a través de los protocolos estándar del bloque de mensajes del servidor (SMB) y del sistema de archivos de red (NFS). Azure Files también proporciona una API REST para el acceso mediante programación a los recursos compartidos de archivos.

En este artículo, obtendrá información sobre los distintos enfoques para desarrollar con Azure Files en .NET y cómo elegir el enfoque que mejor se adapte a las necesidades de la aplicación. También aprenderá a crear una aplicación de consola básica que interactúe con los recursos de Azure Files.

Se aplica a

Modelo de administración	Modelo de facturación	Nivel multimedia	Redundancia	Pequeñas y Medianas Empresas (PYME)	NFS
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Local (LRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Zona (ZRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	Geo (GRS)
Microsoft.Storage	Aprovisionado v2	HDD (estándar)	GeoZone (GZRS)
Microsoft.Storage	Aprovisionado v1	SSD (Premium)	Local (LRS)
Microsoft.Storage	Aprovisionado v1	SSD (Premium)	Zona (ZRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Local (LRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Zona (ZRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	Geo (GRS)
Microsoft.Storage	Pago por uso	HDD (estándar)	GeoZone (GZRS)

Acerca del desarrollo de aplicaciones .NET con Azure Files

Azure Files ofrece varias maneras para que los desarrolladores de .NET accedan a los datos y administren recursos en Azure Files. En la tabla siguiente se enumeran los enfoques, se resume cómo funcionan y se proporcionan instrucciones sobre cuándo usar cada enfoque:

Para obtener información general sobre estos enfoques, consulte Introducción al desarrollo de aplicaciones con Azure Files.

Este artículo se centra en trabajar con recursos de Azure Files mediante los siguientes enfoques:

• Trabajar con Azure Files mediante System.IO: monte un recurso compartido de archivos mediante SMB o NFS y use el System.IO espacio de nombres para trabajar con archivos y directorios en el recurso compartido.
• Trabajar con Azure Files mediante la biblioteca cliente de recursos compartidos de archivos para .NET: use la biblioteca cliente de recursos compartidos de archivos de Azure Storage para .NET para trabajar con archivos y directorios en un recurso compartido de archivos. Esta biblioteca cliente se basa en la API FileREST.
• Administración de recursos de Azure Files mediante las bibliotecas de administración de Azure Storage: use las bibliotecas de administración de Azure Storage para administrar recursos compartidos de archivos y otros recursos de la cuenta de almacenamiento. Las bibliotecas de administración se basan en la API REST del proveedor de recursos de Azure Storage.

Prerrequisitos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• SDK de .NET más reciente para el sistema operativo (obtenga el SDK y no el entorno de ejecución)

Configuración del entorno

En esta sección se describen los pasos necesarios para preparar una aplicación de consola de .NET para trabajar con Azure Files.

Creación del proyecto

Si aún no tiene una aplicación .NET, cree una mediante Visual Studio o la CLI de .NET. En este artículo, creamos una aplicación de consola para simplificar.

Instalación del paquete

Si planea interactuar con Azure Files mediante el System.IO espacio de nombres, no es necesario instalar paquetes adicionales. El System.IO espacio de nombres se incluye con el SDK de .NET. Si tiene previsto usar la biblioteca cliente de recursos compartidos de archivos para .NET o la biblioteca de administración de Azure Storage para .NET, instale el paquete mediante NuGet.

dotnet add package Azure.Storage.Files.Shares
dotnet add package Azure.ResourceManager.Storage
dotnet add package Azure.Identity

Adición de directivas using

Si tiene previsto usar el System.IO espacio de nombres, agregue la siguiente directiva using al principio del archivo Program.cs:

using System.IO;

Si planea usar la biblioteca cliente de recursos compartidos de archivos para .NET, agregue la siguiente directiva using a la parte superior del archivo de Program.cs:

using Azure.Storage.Files.Shares;

Si tiene previsto usar la biblioteca de administración de Azure Storage para .NET, agregue la siguiente directiva using a la parte superior del archivo de Program.cs:

using Azure.ResourceManager;

Para usar la biblioteca de identidades de Azure para las conexiones sin contraseña a los servicios de Azure, agregue la siguiente directiva using a la parte superior del archivo de Program.cs:

using Azure.Identity;

Uso de Azure Files con System.IO

Las bibliotecas de E/S de archivos estándar son la forma más común de acceder a los recursos de Azure Files y trabajar con ellos. Al montar un recurso compartido de archivos mediante SMB o NFS, el sistema operativo redirige las solicitudes de API para el sistema de archivos local. Este enfoque permite usar bibliotecas de E/S de archivos estándar, como System.IO, para interactuar con archivos y directorios en el recurso compartido.

Considere la posibilidad de usar System.IO cuando la aplicación requiera:

• Compatibilidad de aplicaciones: Ideal para aplicaciones de línea de negocio con código existente que ya usa System.IO. No es necesario volver a escribir código para que la aplicación funcione con un recurso compartido de archivos de Azure.
• Facilidad de uso:System.IO es bien conocido por los desarrolladores y fácil de usar. Una propuesta de valor clave de Azure Files es que expone las API nativas del sistema de archivos a través de SMB y NFS.

En esta sección, aprenderá a usar System.IO para trabajar con recursos de Azure Files.

Para obtener más información y ejemplos, consulte los recursos siguientes:

• Información general de E/S de archivos y secuencias
• Tareas comunes de E/S

Montar un recurso compartido de archivos

Para usar System.IO, primero debe montar un recurso compartido de archivos. Consulte los siguientes recursos para obtener instrucciones sobre cómo montar un recurso compartido de archivos mediante SMB o NFS:

• Montar un recurso compartido de archivos SMB en Windows
• Montaje de un recurso compartido de archivos SMB en Linux
• Montaje de un recurso compartido de archivos NFS en Linux

En este artículo, usamos la siguiente ruta de acceso para hacer referencia a un recurso compartido de archivos SMB montado en Windows:

string fileSharePath = @"Z:\file-share";

Ejemplo: Conexión a un recurso compartido de archivos y enumeración de directorios mediante System.IO

En el ejemplo de código siguiente se muestra cómo conectarse a un recurso compartido de archivos y enumerar los directorios del recurso compartido:

using System.IO;

string fileSharePath = @"Z:\file-share";

EnumerateDirectories(@"Z:\file-share");

static void EnumerateDirectories(string path)
{
    try
    {
        List<string> dirs = new List<string>(Directory.EnumerateDirectories(path));

        foreach (var dir in dirs)
        {
            Console.WriteLine($"{dir.Substring(dir.LastIndexOf(Path.DirectorySeparatorChar) + 1)}");
        }
        Console.WriteLine($"{dirs.Count} directories found.");
    }
    catch (UnauthorizedAccessException ex)
    {
        Console.WriteLine(ex.Message);
    }
    catch (PathTooLongException ex)
    {
        Console.WriteLine(ex.Message);
    }
}

Ejemplo: Escribir en un archivo de una compartición de archivos mediante System.IO

En el ejemplo de código siguiente se muestra cómo escribir y anexar texto con la File clase :

using System.IO;

string fileSharePath = @"Z:\file-share";

WriteToFile(fileSharePath, "test.txt");

static void WriteToFile(string fileSharePath, string fileName)
{
    string textToWrite = "First line" + Environment.NewLine;
    string filePath = Path.Combine(fileSharePath, fileName);
    
    File.WriteAllText(filePath, textToWrite);

    string[] textToAppend = { "Second line", "Third line" };
    File.AppendAllLines(filePath, textToAppend);
}

Ejemplo: Bloqueo de un archivo en un recurso compartido de archivos mediante System.IO

Los clientes SMB que montan recursos compartidos de archivos pueden usar mecanismos de bloqueo del sistema de archivos para administrar el acceso a archivos compartidos.

En el siguiente ejemplo de código se muestra cómo bloquear un archivo en una compartición de archivos con el modo de recurso compartido establecido en None. Este modo de recurso compartido rechaza el uso compartido del archivo actual hasta que se cierra el archivo.

using System.IO;

string fileSharePath = @"Z:\file-share";

LockFile(Path.Combine(fileSharePath, "test.txt"));

static void LockFile(string filePath)
{
    try
    {
        using (FileStream fs = new FileStream(filePath, FileMode.Open, FileAccess.ReadWrite, FileShare.None))
        {
            Console.WriteLine("File locked.");

            // Do something with file, press Enter to close the stream and release the lock
            Console.ReadLine();

            fs.Close();
            Console.WriteLine("File closed.");
        }
    }
    catch (IOException ex)
    {
        Console.WriteLine(ex.Message);
    }
}

Al usar SMB y la API FileREST, tenga en cuenta que la API FileREST usa concesiones para administrar bloqueos de archivos, mientras que SMB usa bloqueos del sistema de archivos administrados por el sistema operativo. Para obtener más información sobre cómo administrar las interacciones de bloqueo de archivos entre SMB y la API FileREST, consulte Administración de bloqueos de archivos.

Ejemplo: Enumerar ACL de archivo mediante System.IO

En el ejemplo de código siguiente se muestra cómo enumerar listas de control de acceso (ACL) para un archivo:

using System.IO;
using System.Security.AccessControl;

string fileSharePath = @"Z:\file-share";
string fileName = "test.txt";
string filePath = Path.Combine(fileSharePath, fileName);

EnumerateFileACLs(filePath);

static void EnumerateFileACLs(string filePath)
{
    FileInfo fileInfo = new FileInfo(filePath);

    // For directories, use DirectorySecurity instead of FileSecurity
    FileSecurity fSecurity = FileSystemAclExtensions.GetAccessControl(fileInfo);

    // List all access rules for the file
    foreach (FileSystemAccessRule rule in fSecurity.GetAccessRules(true, true, typeof(System.Security.Principal.NTAccount)))
    {
        Console.WriteLine($"Identity: {rule.IdentityReference.Value}");
        Console.WriteLine($"Access Control Type: {rule.AccessControlType}");
        Console.WriteLine($"File System Rights: {rule.FileSystemRights}");
        Console.WriteLine();
    }

}

Trabajar con datos de Azure Files mediante la biblioteca cliente de recursos compartidos de archivos para .NET

La API FileREST proporciona acceso mediante programación a Azure Files. Permite llamar a puntos de conexión HTTPS para realizar operaciones en comparticiones de archivos, directorios y archivos. La API FileREST está diseñada para alta escalabilidad y características avanzadas que podrían no estar disponibles a través de protocolos nativos. El SDK de Azure proporciona bibliotecas cliente, como la biblioteca cliente de recursos compartidos de archivos para .NET, que se basan en la API FileREST.

Considere la posibilidad de usar la API FileREST y la biblioteca cliente del recurso compartido de archivos si la aplicación requiere:

• Características avanzadas: Acceso a las operaciones y características que no están disponibles a través de protocolos nativos.
• Integraciones en la nube personalizadas: Cree servicios personalizados de valor agregado, como copia de seguridad, antivirus o administración de datos, que interactúan directamente con Azure Files.
• Optimización del rendimiento: Beneficiarse de las ventajas de rendimiento en escenarios a gran escala mediante operaciones de plano de datos.

La API FileREST modela Azure Files como una jerarquía de recursos y se recomienda para las operaciones que se realizan en el nivel de directorio o archivo . Debe preferir la API REST del proveedor de recursos de almacenamiento para las operaciones que se realizan en el nivel de servicio de archivos o recurso compartido de archivos .

En esta sección, aprenderá a usar la biblioteca cliente de recursos compartidos de archivos para trabajar con recursos de Azure Files.

Para obtener más información y ejemplos, consulte los recursos siguientes:

• Biblioteca cliente de recursos compartidos de archivos de Azure Storage para .NET
• Biblioteca cliente de recursos compartidos de archivos de Azure Storage para ejemplos de .NET

Autorización del acceso y creación de un cliente

Para conectar una aplicación a Azure Files, cree un ShareClient objeto . Este objeto es el punto de partida para trabajar con recursos de Azure Files. En los ejemplos de código siguientes se muestra cómo crear un ShareClient objeto mediante distintos mecanismos de autorización.

using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

// ...

string accountName = "<account-name>";
string shareName = "<share-name>";

ShareClientOptions options = new()
{
    AllowSourceTrailingDot = true,
    AllowTrailingDot = true,
    ShareTokenIntent = ShareTokenIntent.Backup,
};
ShareClient shareClient = new(
   new Uri($"https://{accountName}.file.core.windows.net/{shareName}"),
   new DefaultAzureCredential(),
   options);

ShareDirectoryClient directoryClient = shareClient.GetDirectoryClient("sample-directory");

string accountName = "<account-name>";
string accountKey = "<account-key>";
string shareName = "<share-name>";

StorageSharedKeyCredential sharedKeyCredential = 
    new StorageSharedKeyCredential(accountName, accountKey);

ShareClient shareClient = new ShareClient(
    new Uri($"https://{accountName}.file.core.windows.net/{shareName}"),
    sharedKeyCredential);

string connectionString = "<connection-string>";
string shareName = "<share-name>";

ShareClient shareClient = new ShareClient(connectionString, shareName);

Para obtener más información sobre cada uno de estos mecanismos de autorización, consulte Elección de cómo autorizar el acceso a los datos de archivos.

Ejemplo: Copia de archivos usando biblioteca cliente de comparticiones de archivos

Puede copiar archivos dentro de un recurso compartido de archivos o entre recursos compartidos de archivos mediante el método siguiente:

• StartCopyAsync

Puede copiar un archivo en un blob de destino mediante el método siguiente desde un BlobClient objeto :

• StartCopyFromUriAsync

En el ejemplo de código siguiente se muestra cómo copiar un archivo en un archivo de otro recurso compartido de archivos:

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

string accountName = "<account-name>";
string srcShareName = "src-file-share";
string destShareName = "dest-file-share";
string srcFilePath = "src/path/to/file";
string destFilePath = "dest/path/to/file";

TokenCredential tokenCredential = new DefaultAzureCredential();

ShareClientOptions options = new()
{
    ShareTokenIntent = ShareTokenIntent.Backup,
};

ShareFileClient srcShareFileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{srcShareName}/{srcFilePath}"),
    tokenCredential,
    options);

ShareFileClient destShareFileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{destShareName}/{destFilePath}"),
    tokenCredential,
    options);

// Copy the file from the source share to the destination share

await destShareFileClient.StartCopyAsync(srcShareFileClient.Uri);

Ejemplo: concesión de un archivo mediante la biblioteca cliente de recursos compartidos de archivos

Una concesión crea un bloqueo en un archivo administrado por Azure mediante un identificador de concesión. La concesión proporciona un mecanismo para coordinar el acceso a los archivos en varios clientes de un sistema distribuido. Una concesión en un archivo proporciona acceso exclusivo de escritura y eliminación. Para más información sobre los estados de concesión y las acciones, consulte Archivo de concesión.

En el ejemplo de código siguiente se muestra cómo crear un cliente de concesión, adquirir una concesión de duración infinita en un archivo y liberar la concesión:

using Azure.Core;
using Azure.Identity;
using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;
using Azure.Storage.Files.Shares.Specialized;

string accountName = "<account-name>";
string shareName = "sample-file-share";
string filePath = "path/to/file";

TokenCredential tokenCredential = new DefaultAzureCredential();

ShareClientOptions options = new()
{
    ShareTokenIntent = ShareTokenIntent.Backup,
};

ShareFileClient fileClient = new(
    new Uri($"https://{accountName}.file.core.windows.net/{shareName}/{filePath}"),
    tokenCredential,
    options);

ShareLeaseClient leaseClient = fileClient.GetShareLeaseClient();

// Acquire a lease on the source file
await leaseClient.AcquireAsync(duration: ShareLeaseClient.InfiniteLeaseDuration);

// Do something with the file

// Release the lease
await leaseClient.ReleaseAsync();

Al usar SMB y la API FileREST, tenga en cuenta que la API FileREST usa concesiones para administrar bloqueos de archivos, mientras que SMB usa bloqueos del sistema de archivos administrados por el sistema operativo. Para obtener más información sobre cómo administrar las interacciones de bloqueo de archivos entre SMB y la API FileREST, consulte Administración de bloqueos de archivos.

Ejemplo: Crear y enumerar instantáneas de recurso compartido mediante la biblioteca cliente de recursos compartidos de archivos

Las instantáneas de recurso compartido son copias de solo lectura de un recurso compartido de archivos en un momento dado. Puede crear una instantánea de un recurso compartido de archivos y, a continuación, usar la instantánea para acceder a los datos del recurso compartido en el momento en que se creó la instantánea. También puede enumerar todas las instantáneas de un recurso compartido de archivos y eliminar instantáneas de recurso compartido.

En el ejemplo de código siguiente se muestra cómo crear una instantánea de recurso compartido, enumerar las instantáneas de un recurso compartido de archivos y recorrer el árbol de directorios en una instantánea de recurso compartido:

using Azure.Storage.Files.Shares;
using Azure.Storage.Files.Shares.Models;

string connectionString = "<connection-string>";

ShareServiceClient shareServiceClient = new ShareServiceClient(connectionString);
ShareClient shareClient = shareServiceClient.GetShareClient("sample-file-share");

// Create a snapshot

ShareSnapshotInfo snapshotInfo = await shareClient.CreateSnapshotAsync();
Console.WriteLine($"Snapshot created: {snapshotInfo.Snapshot}");

// List snapshots in a share

await foreach (ShareItem shareItem in shareServiceClient.GetSharesAsync(ShareTraits.All, ShareStates.Snapshots))
{
    if (shareItem.Snapshot != null)
    {
        Console.WriteLine($"Share: {shareItem.Name} (Snapshot: {shareItem.Snapshot})");
    }
}

// List directories and files in a share snapshot

string snapshotTimestamp = snapshotInfo.Snapshot.ToString();
ShareClient shareSnapshot = shareClient.WithSnapshot(snapshotTimestamp);
ShareDirectoryClient rootDir = shareSnapshot.GetRootDirectoryClient();

await ListDirectoryTreeAsync(rootDir);

static async Task ListDirectoryTreeAsync(ShareDirectoryClient directory)
{
    await foreach (ShareFileItem fileItem in directory.GetFilesAndDirectoriesAsync())
    {
        if (fileItem.IsDirectory)
        {
            Console.WriteLine($"Directory: {fileItem.Name}");
            await ListDirectoryTreeAsync(directory.GetSubdirectoryClient(fileItem.Name));
        }
        else
        {
            Console.WriteLine($"File: {fileItem.Name}");
        }
    }
}

Administración de recursos de Azure Files mediante las bibliotecas de administración de Azure Storage

Las bibliotecas de administración de Azure Storage se basan en la API REST del proveedor de recursos de Azure Storage. El proveedor de recursos de Azure Storage es un servicio basado en Azure Resource Manager y admite métodos declarativos (plantillas) e imperativos (llamada a API directa). La API REST del proveedor de recursos de Azure Storage proporciona acceso mediante programación a los recursos de Azure Storage, incluidos los recursos compartidos de archivos. El SDK de Azure proporciona bibliotecas de administración que se basan en la API REST del proveedor de recursos de Azure Storage.

Las bibliotecas de administración se recomiendan para las operaciones que se realizan en el servicio de archivos o en el nivel de recurso compartido de archivos . En esta sección, aprenderá a usar las bibliotecas de administración de Azure Storage para administrar recursos de Azure Files.

Ejemplo: Creación de un recurso compartido de archivos mediante la biblioteca de administración de Azure Storage

En el ejemplo de código siguiente se muestra cómo crear un objeto de nivel ArmClient superior, registrar el proveedor de recursos storage con una suscripción y crear un recurso compartido de archivos mediante la biblioteca de administración de Azure Storage:

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.Storage;

ArmClient armClient = new ArmClient(new DefaultAzureCredential());

// Create a resource identifier, then get the subscription resource
ResourceIdentifier resourceIdentifier = new($"/subscriptions/<subscription-id>");
SubscriptionResource subscription = armClient.GetSubscriptionResource(resourceIdentifier);

ResourceProviderResource resourceProvider =
    await subscription.GetResourceProviderAsync("Microsoft.Storage");

// Check the registration state of the resource provider and register, if needed
if (resourceProvider.Data.RegistrationState == "NotRegistered")
    resourceProvider.Register();

// Get a resource group
ResourceGroupResource resourceGroup = await subscription.GetResourceGroupAsync("<resource-group-name>");

// Get a collection of storage account resources
StorageAccountCollection accountCollection = resourceGroup.GetStorageAccounts();

// Get a specific storage account resource
StorageAccountResource storageAccount = await accountCollection.GetAsync("<storage-account-name>");

// Get a file service resource for the storage account
FileServiceResource fileService = storageAccount.GetFileService();

// Create a new file share (or update if it already exists)
ArmOperation <FileShareResource> fileShareOperation = await fileService
    .GetFileShares()
    .CreateOrUpdateAsync(WaitUntil.Completed, "sample-file-share", new FileShareData()
    {
        ShareQuota = 1024,
        // Add file share properties here
    });

// Get the file share resource
FileShareResource fileShare = fileShareOperation.Value;

Puede configurar las propiedades del recurso compartido de archivos mediante la clase FileShareData . En el ejemplo anterior se muestra cómo establecer la ShareQuota propiedad .

Ejemplo: enumerar los recursos compartidos e instantáneas de archivos mediante la biblioteca de administración de Azure Storage

En el ejemplo de código siguiente se muestra cómo enumerar los recursos compartidos de archivos y las instantáneas en una cuenta de almacenamiento:

// Iterate over a collection of file shares and list them along with any snapshots
string expand = "snapshots";
await foreach (FileShareResource shareResource in fileService.GetFileShares().GetAllAsync(expand: expand))
{
    // Call operations on the file share resource

    // For this demo, print out the resource name and snapshot information
    FileShareData resourceData = shareResource.Data;
    Console.WriteLine($"Resource name: {resourceData.Name}");
    if (resourceData.SnapshotOn.HasValue)
    {
        Console.WriteLine($"Snapshot: {resourceData.SnapshotOn}");
    }
}

Contenido relacionado

Para más información sobre el desarrollo con Azure Files, consulte los siguientes recursos:

• Introducción al desarrollo de aplicaciones con Azure Files
• Asignar nombres y hacer referencia a recursos compartidos, directorios, archivos y metadatos
• Administrar bloqueos de archivos
• Operaciones en directorios
• Operaciones en archivos