Desenvolver para Arquivos do Azure com .NET

✔️ Aplica-se a: compartilhamentos de arquivos SMB e NFS clássicos criados com o provedor de recursos Microsoft.Storage

✖️ Não se aplica a: Compartilhamentos de arquivos criados com o provedor de recursos Microsoft.FileShares

Saiba como desenvolver aplicativos .NET que usam Arquivos do Azure para armazenar dados. Arquivos do Azure é um serviço de compartilhamento de arquivos gerenciado na nuvem. Ele fornece compartilhamentos de arquivos totalmente gerenciados que podem ser acessados por meio do protocolo SMB (Bloco de Mensagens do Servidor) padrão do setor e do NFS (Sistema de Arquivos de Rede). Arquivos do Azure também fornece uma API REST para acesso programático a compartilhamentos de arquivos.

Neste artigo, você aprenderá sobre as diferentes abordagens para desenvolver com Arquivos do Azure em .NET e como escolher a abordagem que melhor atende às necessidades do seu aplicativo. Você também aprenderá a criar um aplicativo de console básico que interage com Arquivos do Azure recursos.

Escolha uma abordagem para desenvolvimento de .NET com Arquivos do Azure

Arquivos do Azure oferece várias maneiras de .NET desenvolvedores acessarem dados e gerenciarem recursos no Arquivos do Azure. A tabela a seguir lista as abordagens, resume como elas funcionam e fornece diretrizes sobre quando usar cada abordagem:

Para obter informações gerais sobre essas abordagens, consulte Overview do desenvolvimento de aplicativos com Arquivos do Azure.

Este artigo se concentra em trabalhar com recursos Arquivos do Azure usando as seguintes abordagens:

• Trabalho com Arquivos do Azure usando System.IO: monte um compartilhamento de arquivos usando SMB ou NFS e use o namespace System.IO para trabalhar com arquivos e diretórios no compartilhamento.
• Work with Arquivos do Azure using the File Shares client library for .NET: Use a biblioteca de clientes Armazenamento do Azure File Shares para .NET para trabalhar com arquivos e diretórios em um compartilhamento de arquivos. Essa biblioteca de clientes se baseia na API FileREST.
• Gerencie os recursos de Arquivos do Azure usando as bibliotecas de gerenciamento do Armazenamento do Azure: use as bibliotecas de gerenciamento do Armazenamento do Azure para gerenciar compartilhamentos de arquivos e outros recursos em sua conta de armazenamento. As bibliotecas de gerenciamento se baseiam na API REST do provedor de recursos Armazenamento do Azure.

Pré-requisitos

• Azure assinatura – criar uma gratuitamente
• Azure conta de armazenamento – criar uma conta de armazenamento
• SDK .NET mais recente para seu sistema operacional (obtenha o SDK e não o tempo de execução)

Configure seu ambiente

Esta seção orienta você pelas etapas para preparar um aplicativo de console .NET para trabalhar com Arquivos do Azure.

Criar o projeto

Se você ainda não tiver um aplicativo .NET, crie um usando Visual Studio ou a CLI .NET. Neste artigo, os exemplos usam um aplicativo de console para simplificar.

Instalar o pacote

Se você planeja interagir com Arquivos do Azure usando o namespace System.IO, não será necessário instalar nenhum pacote adicional. O namespace System.IO está incluído no SDK do .NET. Se você planeja usar a biblioteca de clientes de Compartilhamentos de Arquivos para .NET ou a biblioteca de gerenciamento de Armazenamento do Azure para .NET, instale o pacote usando o NuGet.

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

Adicionar usando diretivas

Se você planeja usar o namespace System.IO, adicione a seguinte diretiva usando a parte superior do arquivo Program.cs:

using System.IO;

Se você planeja usar a biblioteca de clientes de Compartilhamentos de Arquivos para .NET, adicione a seguinte diretiva de uso à parte superior do arquivo Program.cs:

using Azure.Storage.Files.Shares;

Se você planeja usar a biblioteca de gerenciamento de Armazenamento do Azure para .NET, adicione a seguinte diretiva de uso à parte superior do arquivo Program.cs:

using Azure.ResourceManager;

Para usar a biblioteca de identidade Azure para conexões sem senha para serviços de Azure, adicione o seguinte usando diretiva à parte superior do arquivo Program.cs:

using Azure.Identity;

Trabalhar com Arquivos do Azure usando System.IO

As bibliotecas de E/S de arquivo padrão são a maneira mais comum de acessar e trabalhar com recursos de Arquivos do Azure. Quando você monta um compartilhamento de arquivos usando SMB ou NFS, seu sistema operacional redireciona solicitações de API para o sistema de arquivos local. Essa abordagem permite que você use bibliotecas de E/S de arquivo padrão, como System.IO, para interagir com arquivos e diretórios no compartilhamento.

Considere a possibilidade de usar System.IO quando seu aplicativo precisar.

• Compatibilidade do aplicativo: Ideal para aplicativos de linha de negócios com código existente que já usa System.IO. Você não precisa reescrever o código para que o aplicativo funcione com um compartilhamento de arquivos Azure.
• Facilidade de uso:System.IO é bem conhecido pelos desenvolvedores e fácil de usar. Uma proposta de valor chave do Arquivos do Azure é que ele expõe APIs do sistema de arquivos nativo por meio de SMB e NFS.

Nesta seção, você aprenderá a usar System.IO para trabalhar com recursos Arquivos do Azure.

Para obter mais informações e exemplos, confira os seguintes recursos:

• Visão geral de E/S de arquivo e fluxo
• Tarefas comuns de E/S

Montar um compartilhamento de arquivos

Para usar System.IO, primeiro você deve montar um compartilhamento de arquivos. Consulte os seguintes recursos para obter diretrizes sobre como montar um compartilhamento de arquivos usando SMB ou NFS:

• Montar um compartilhamento de arquivos SMB no Windows
• Montar um compartilhamento de arquivo SMB no Linux
• Montar um compartilhamento de arquivo NFS no Linux

Neste artigo, os exemplos de código usam o seguinte caminho para se referir a um compartilhamento de arquivos SMB montado no Windows:

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

Exemplo: conectar-se a um compartilhamento de arquivos e enumerar diretórios usando System.IO

O exemplo de código a seguir mostra como se conectar a um compartilhamento de arquivos e listar os diretórios no compartilhamento:

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

Exemplo: gravar em um arquivo em um compartilhamento de arquivos usando System.IO

O exemplo de código a seguir mostra como gravar e acrescentar texto com a File classe:

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

Exemplo: bloquear um arquivo em um compartilhamento de arquivos usando System.IO

Os clientes SMB que montam compartilhamentos de arquivos podem usar mecanismos de bloqueio do sistema de arquivos para gerenciar o acesso a arquivos compartilhados.

O exemplo de código a seguir mostra como bloquear um arquivo em um compartilhamento de arquivos com o modo de compartilhamento definido como None. Esse modo de compartilhamento recusa o compartilhamento do arquivo atual até que o arquivo seja fechado.

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

Ao usar o SMB e a API FileREST, tenha em mente que a API FileREST usa concessões para gerenciar bloqueios de arquivos, enquanto o SMB usa bloqueios do sistema de arquivos gerenciados pelo sistema operacional. Para saber mais sobre como gerenciar interações de bloqueio de arquivos entre o SMB e a API FileREST, consulte Gerenciar bloqueios de arquivo.

Exemplo: Enumerar ACLs de arquivo usando System.IO

O exemplo de código a seguir mostra como enumerar ACLs (listas de controle de acesso) para um arquivo:

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

}

Trabalhar com dados Arquivos do Azure usando a biblioteca de clientes de Compartilhamentos de Arquivos para .NET

A API FileREST fornece acesso programático a Arquivos do Azure. Ele permite que você chame os pontos de extremidade HTTPS para realizar operações em compartilhamentos de arquivos, diretórios e arquivos. A API FileREST foi projetada para alta escalabilidade e recursos avançados que podem não estar disponíveis por meio de protocolos nativos. O SDK do Azure fornece bibliotecas de clientes, como a biblioteca de clientes de Compartilhamentos de Arquivos para .NET, que se baseiam na API FileREST.

Considere usar a API FileREST e a biblioteca cliente File Shares se sua aplicação exigir:

• Recursos avançados: Acessar operações e recursos que não estão disponíveis por meio de protocolos nativos.
• Integrações de nuvem personalizadas: Criar serviços personalizados de valor agregado, como backup, antivírus ou gerenciamento de dados, que interagem diretamente com o Arquivos do Azure.
• Otimização de desempenho: Aproveite as vantagens de desempenho em cenários de alta escala usando operações de plano de dados.

A API FileREST modela os Arquivos do Azure como uma hierarquia de recursos e é recomendada para operações realizadas no nível de directory ou file. Você deve preferir a API REST do provedor de recursos de armazenamento para operações executadas no nível de serviço de arquivo ou compartilhamento de arquivos.

Nesta seção, você aprenderá a usar a biblioteca de clientes Compartilhamentos de Arquivos para trabalhar com recursos de Arquivos do Azure.

Para obter mais informações e exemplos, confira os seguintes recursos:

• Biblioteca cliente de compartilhamentos de arquivos do Armazenamento do Azure para .NET
• Biblioteca de clientes de Compartilhamentos de Arquivos do Armazenamento do Azure para exemplos de .NET

Autorizar acesso e criar um cliente

Para conectar um aplicativo ao Arquivos do Azure, crie um objeto ShareClient. Esse objeto é o ponto de partida para trabalhar com recursos Arquivos do Azure. Os exemplos de código a seguir mostram como criar um ShareClient objeto usando diferentes mecanismos de autorização.

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 saber mais sobre cada um desses mecanismos de autorização, consulte Escolher como autorizar o acesso aos dados do arquivo.

Exemplo: copiar arquivos usando a biblioteca de clientes Compartilhamentos de Arquivos

Você pode copiar arquivos em um compartilhamento de arquivos ou entre compartilhamentos de arquivos usando o seguinte método:

• StartCopyAsync

Você pode copiar um arquivo para um blob de destino usando o seguinte método de um BlobClient objeto:

• StartCopyFromUriAsync

O exemplo de código a seguir mostra como copiar um arquivo para um arquivo em outro compartilhamento de arquivos:

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);

Exemplo: alugar um arquivo usando a biblioteca de clientes de Compartilhamentos de Arquivos

Uma concessão cria um bloqueio em um arquivo gerenciado por Azure por meio de uma ID de concessão. A concessão fornece um mecanismo para coordenar o acesso a arquivos em vários clientes em um sistema distribuído. Uma concessão em um arquivo fornece acesso exclusivo de gravação e exclusão. Para saber mais sobre estados e ações de locação, consulte Arquivo de Locação.

O exemplo de código a seguir mostra como criar um cliente de concessão, adquirir uma concessão de duração infinita em um arquivo e liberar a concessão:

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

Ao usar o SMB e a API FileREST, tenha em mente que a API FileREST usa concessões para gerenciar bloqueios de arquivos, enquanto o SMB usa bloqueios do sistema de arquivos gerenciados pelo sistema operacional. Para saber mais sobre como gerenciar interações de bloqueio de arquivos entre o SMB e a API FileREST, consulte Gerenciar bloqueios de arquivo.

Exemplo: criar e listar instantâneos de compartilhamento usando a biblioteca de clientes Compartilhamentos de Arquivos

Os instantâneos de compartilhamento são cópias somente leitura de um compartilhamento de arquivos em um momento. Você pode criar um instantâneo de um compartilhamento de arquivos e, em seguida, usar o instantâneo para acessar os dados no compartilhamento no momento em que o instantâneo foi criado. Você também pode listar todos os instantâneos em um compartilhamento de arquivos e excluir instantâneos de compartilhamento.

O exemplo de código a seguir mostra como criar um instantâneo de compartilhamento, listar os instantâneos em um compartilhamento de arquivos e percorrer a árvore de diretório em um instantâneo de compartilhamento:

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

Gerenciar recursos Arquivos do Azure usando as bibliotecas de gerenciamento de Armazenamento do Azure

As bibliotecas de gerenciamento de Armazenamento do Azure são criadas na API REST do provedor de recursos Armazenamento do Azure. O provedor de recursos Armazenamento do Azure é um serviço baseado em Azure Resource Manager e dá suporte a métodos declarativos (modelos) e imperativos (chamada direta à API). A API REST do provedor de recursos Armazenamento do Azure fornece acesso programático a recursos Armazenamento do Azure, incluindo compartilhamentos de arquivos. O SDK do Azure fornece bibliotecas de gerenciamento que se baseiam na API REST do provedor de recursos Armazenamento do Azure.

As bibliotecas de gerenciamento são recomendadas para operações executadas no nível do serviço de arquivo ou do compartilhamento de arquivos. Nesta seção, você aprenderá a usar as bibliotecas de gerenciamento de Armazenamento do Azure para gerenciar Arquivos do Azure recursos.

Exemplo: criar um compartilhamento de arquivos usando a biblioteca de gerenciamento de Armazenamento do Azure

O exemplo de código a seguir mostra como criar um objeto ArmClient de nível superior, registrar o provedor de recursos de armazenamento com uma assinatura e criar um compartilhamento de arquivos usando a biblioteca de gerenciamento de Armazenamento do Azure:

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;

Você pode configurar as propriedades de compartilhamento de arquivos usando a classe FileShareData . O exemplo anterior mostra como definir a ShareQuota propriedade.

Exemplo: listar compartilhamentos de arquivos e instantâneos usando a biblioteca de gerenciamento de Armazenamento do Azure

O exemplo de código a seguir mostra como listar compartilhamentos de arquivos e instantâneos em uma conta de armazenamento:

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

Conteúdo relacionado

Para obter mais informações sobre como desenvolver com Arquivos do Azure, consulte os seguintes recursos:

• Overview do desenvolvimento de aplicativos com Arquivos do Azure
• Nomeando e referenciando compartilhamentos, diretórios, arquivos e metadados
• Gerenciar bloqueios de arquivo
• Operações em diretórios
• Operações em arquivos