Partilhar via


Programar para os Ficheiros do Azure com .NET

Aprenda as noções básicas do desenvolvimento de aplicativos .NET que usam Arquivos do Azure para armazenar dados. Este artigo mostra como criar um aplicativo de console simples para fazer o seguinte com arquivos .NET e Azure:

  • Obtenha o conteúdo de um arquivo.
  • Defina o tamanho máximo, ou quota, para uma partilha de ficheiros.
  • Crie uma assinatura de acesso compartilhado (SAS) para um arquivo.
  • Copiar um ficheiro para outro ficheiro na mesma conta de armazenamento.
  • Copiar um ficheiro para um blob na mesma conta de armazenamento.
  • Crie um instantâneo de um compartilhamento de arquivos.
  • Restaure um arquivo a partir de um instantâneo de compartilhamento.
  • Use as Métricas de Armazenamento do Azure para solucionar problemas.

Para saber mais sobre os Arquivos do Azure, consulte O que são Arquivos do Azure?

Gorjeta

Veja o repositório de amostras de código do Armazenamento do Azure

Para obter exemplos de código de Armazenamento do Azure ponto a ponto fáceis de utilizar que pode transferir e executar, veja a nossa lista de Exemplos de Armazenamento do Azure.

Aplica-se a

Tipo de partilhas de ficheiros SMB NFS
Partilhas de ficheiros Standard (GPv2), LRS/ZRS Yes No
Partilhas de ficheiros Standard (GPv2), GRS/GZRS Yes No
Partilhas de ficheiros Premium (FileStorage), LRS/ZRS Yes No

Noções sobre as APIs de .NET

O serviço Ficheiros do Azure fornece duas abordagens abrangentes no que se refere às aplicações cliente: SMB (Server Message Block) e REST. Dentro do .NET, as System.IO APIs abstraem Azure.Storage.Files.Shares essas abordagens.

API Quando utilizar o Notas
System.IO A sua candidatura:
  • Precisa ler / gravar arquivos usando SMB
  • Está em execução num dispositivo que tem acesso à sua conta do serviço Ficheiros do Azure através da porta 445
  • Não precisa de gerir qualquer definição administrativa da partilha de ficheiros
A E/S de ficheiros implementada com os Ficheiros do Azure através de SMB é geralmente a mesma que a E/S com qualquer partilha de ficheiros de rede ou dispositivo de armazenamento local. Para obter uma introdução a vários recursos do .NET, incluindo E/S de arquivo, consulte o tutorial do Aplicativo de Console.
Azure.Storage.Files.Shares A sua candidatura:
  • Não é possível acessar os Arquivos do Azure usando o SMB na porta 445 devido a restrições de firewall ou ISP
  • Precisa de funcionalidade administrativa, como a capacidade de definir a quota de uma partilha de ficheiros ou criar uma assinatura de acesso partilhado
Este artigo demonstra o uso de para E/S de Azure.Storage.Files.Shares arquivo usando REST em vez de SMB e gerenciamento do compartilhamento de arquivos.

Criar a aplicação de consola e obter a assemblagem

Você pode usar a biblioteca de cliente do Azure Files em qualquer tipo de aplicativo .NET. Esses aplicativos incluem nuvem do Azure, Web, desktop e aplicativos móveis. Neste guia, criamos um aplicativo de console para simplificar.

No Visual Studio, crie uma nova aplicação de consola do Windows. As etapas a seguir mostram como criar um aplicativo de console no Visual Studio 2019. Os passos são semelhantes aos de outras versões do Visual Studio.

  1. Inicie o Visual Studio e selecione Criar um novo projeto.
  2. Em Criar um novo projeto, escolha Aplicativo de Console (.NET Framework) para C# e selecione Avançar.
  3. Em Configurar seu novo projeto, insira um nome para o aplicativo e selecione Criar.

Adicione todos os exemplos de código neste artigo à Program classe no arquivo Program.cs .

Utilizar o NuGet para instalar os pacotes necessários

Consulte estes pacotes no seu projeto:

Você pode usar o NuGet para obter os pacotes. Siga estes passos:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse em seu projeto e escolha Gerenciar Pacotes NuGet.

  2. No Gerenciador de Pacotes NuGet, selecione Procurar. Em seguida, procure e escolha Azure.Core e, em seguida, selecione Instalar.

    Esta etapa instala o pacote e suas dependências.

  3. Procure e instale estes pacotes:

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

Salve as credenciais da sua conta de armazenamento no arquivo App.config

Em seguida, salve suas credenciais no arquivo App.config do projeto. No Gerenciador de Soluções, clique App.config duas vezes e edite o arquivo para que ele seja semelhante ao exemplo a seguir.

Substitua myaccount pelo nome da conta de armazenamento e mykey pela chave da conta de armazenamento.

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

Atualmente, o emulador de armazenamento do Azurite não oferece suporte aos Arquivos do Azure. Sua cadeia de conexão deve ter como destino uma conta de armazenamento do Azure na nuvem para trabalhar com o Azure Files.

Adicionar com diretivas

No Gerenciador de Soluções, abra o arquivo Program.cs e adicione as seguintes diretivas using à parte superior do arquivo.

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;

Aceder à partilha de ficheiros programaticamente

No arquivo Program.cs, adicione o seguinte código para acessar o compartilhamento de arquivos programaticamente.

O método a seguir cria um compartilhamento de arquivos se ele ainda não existir. O método começa criando um objeto ShareClient a partir de uma cadeia de conexão. Em seguida, o exemplo tenta baixar um arquivo que criamos anteriormente. Chame esse método 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");
    }
}

Definir o tamanho máximo para uma partilha de ficheiros

A partir da versão 5.x da biblioteca de cliente de Arquivos do Azure, você pode definir a cota (tamanho máximo) para um compartilhamento de arquivos. De igual modo, pode verificar a quantidade de dados atualmente armazenada na partilha.

Definir a cota para um compartilhamento limita o tamanho total dos arquivos armazenados no compartilhamento. Se o tamanho total dos arquivos no compartilhamento exceder a cota, os clientes não poderão aumentar o tamanho dos arquivos existentes. Os clientes também não podem criar novos arquivos, a menos que esses arquivos estejam vazios.

O exemplo abaixo mostra como verificar a utilização atual para uma partilha e como configurar a quota para a partilha.

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

Gerar uma assinatura de acesso partilhado para um ficheiro ou partilha de ficheiros

A partir da versão 5.x da biblioteca de cliente dos Arquivos do Azure, você pode gerar uma assinatura de acesso compartilhado (SAS) para um compartilhamento de arquivos ou para um arquivo individual.

O método de exemplo a seguir retorna uma SAS em um arquivo no compartilhamento 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 obter mais informações sobre como criar e usar assinaturas de acesso compartilhado, consulte Como funciona uma assinatura de acesso compartilhado.

Copiar ficheiros

A partir da versão 5.x da biblioteca de cliente de Arquivos do Azure, você pode copiar um arquivo para outro arquivo, um arquivo para um blob ou um blob para um arquivo.

Você também pode usar o AzCopy para copiar um arquivo para outro ou para copiar um blob para um arquivo ou vice-versa. Consulte Introdução ao AzCopy.

Nota

Se você estiver copiando um blob para um arquivo ou um arquivo para um blob, deverá usar uma assinatura de acesso compartilhado (SAS) para autorizar o acesso ao objeto de origem, mesmo que esteja copiando dentro da mesma conta de armazenamento.

Copiar um ficheiro para outro ficheiro

O exemplo seguinte copia um ficheiro para outro ficheiro na mesma partilha. Você pode usar a autenticação de chave compartilhada para fazer a cópia porque essa operação copia arquivos dentro da mesma conta de armazenamento.

//-------------------------------------------------
// 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 um ficheiro para um blob

O exemplo seguinte cria um ficheiro e copia-o para um blob na mesma conta do Storage. O exemplo cria um SAS para o ficheiro de origem, que o serviço utiliza para autorizar o acesso ao ficheiro de origem durante a operação de cópia.

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

Pode copiar um blob para um ficheiro da mesma forma. Se o objeto de origem for um blob, crie um SAS para autorizar o acesso a esse blob durante a operação de cópia.

Compartilhar instantâneos

A partir da versão 8.5 da biblioteca de cliente do Azure Files, você pode criar um instantâneo de compartilhamento. Também pode listar, procurar ou eliminar instantâneos de partilha. Depois de criados, os instantâneos de compartilhamento são somente leitura.

Criar instantâneos de partilha

O exemplo seguinte cria um instantâneo de partilha de ficheiros.

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

Listar instantâneos de partilha

O exemplo a seguir lista os instantâneos em um compartilhamento.

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

Listar arquivos e diretórios em instantâneos de compartilhamento

O exemplo a seguir navega por arquivos e diretórios em instantâneos de compartilhamento.

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

Restaurar compartilhamentos de arquivos ou arquivos de instantâneos de compartilhamento

Tirar um instantâneo de um compartilhamento de arquivos permite que você recupere arquivos individuais ou todo o compartilhamento de arquivos.

Pode restaurar um ficheiro de um instantâneo de partilha de ficheiros através da consulta dos instantâneos de partilha de uma partilha de ficheiros. Em seguida, você pode recuperar um arquivo que pertence a um instantâneo de compartilhamento específico. Use essa versão para ler diretamente ou restaurar o arquivo.

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

Eliminar instantâneos de partilha

O exemplo seguinte elimina um instantâneo de partilha de ficheiros.

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

Solucionar problemas de Arquivos do Azure usando métricas

O Azure Storage Analytics dá suporte a métricas para Arquivos do Azure. Com os dados de métricas, pode rastrear pedidos e diagnosticar problemas.

Você pode habilitar métricas para Arquivos do Azure no portal do Azure. Você também pode habilitar métricas programaticamente chamando a operação Definir Propriedades do Serviço de Arquivo com a API REST ou um de seus análogos na biblioteca de cliente do Azure Files.

O exemplo de código a seguir mostra como usar a biblioteca de cliente .NET para habilitar métricas para Arquivos do Azure.

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

Se você encontrar algum problema, consulte Solucionar problemas de arquivos do Azure.

Próximos passos

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

Para exemplos de código relacionados usando SDKs do .NET versão 11.x preteridos, consulte Exemplos de código usando o .NET versão 11.x.