O POWER BI É PARA VOCÊ

Aprenda o básico do desenvolvimento de aplicativos .NET que usam os Arquivos do Azure para armazenar dados. Este artigo mostra como criar um aplicativo de console simples para fazer o seguinte com o .NET e os Arquivos do Azure:

• Obtenha o conteúdo de um arquivo.
• Definia o tamanho máximo, ou a cota, para um compartilhamento de arquivos.
• Crie uma assinatura de acesso compartilhado (SAS) para um arquivo.
• Copie um arquivo em outro arquivo na mesma conta de armazenamento.
• Copie um arquivo em um blob na mesma conta de armazenamento.
• Crie um instantâneo de um compartilhamento de arquivos.
• Restaurar um arquivo de um instantâneo de compartilhamento.
• Use métricas de armazenamento do Azure para solucionar problemas.

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

 Dica

Confira o repositório de exemplos de código do Armazenamento do Azure

Para exemplos de código fácil de usar ponta a ponta do Armazenamento do Azure que você pode baixar e executar, consulte nossa lista de Exemplos de Armazenamento do Azure.

Aplica-se a

Tipo de compartilhamento de arquivos	SMB	NFS
Compartilhamentos de arquivos padrão (GPv2), LRS/ZRS
Compartilhamentos de arquivos padrão (GPv2), GRS/GZRS
Compartilhamento de arquivos premium (FileStorage), LRS/ZRS

Compreendendo as APIs do .NET

Os Arquivos do Azure fornecem duas abordagens amplas para aplicativos cliente: protocolo SMB e REST. No .NET, as APIs System.IOAzure.Storage.Files.Shares abstraem essas abordagens.

Criar o aplicativo do console e obter o assembly

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

No Visual Studio, crie um novo aplicativo de console do Windows. As etapas a seguir mostram como criar um aplicativo de console no Visual Studio 2019. As etapas são semelhantes em outras versões do Visual Studio.

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

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

Use o NuGet para instalar os pacotes necessários

Consulte estes pacotes em seu projeto:

• SDK do NET do Azure v12
• SDK do NET do Azure v11

• Biblioteca principal do Azure para .NET: este pacote é a implementação do pipeline do cliente do Azure.
• Biblioteca de cliente do Azure Storage Blob para .NET: este pacote fornece acesso programático a recursos de blob em sua conta de armazenamento.
• Biblioteca de cliente de arquivos de armazenamento do Azure para .NET: este pacote fornece acesso programático a recursos de arquivo em sua conta de armazenamento.
• Biblioteca de Configuration Manager do sistema para .NET: este pacote fornece uma classe que armazena e recupera valores em um arquivo de configuração.

Você pode usar NuGet para obter os pacotes. Siga estas etapas:

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

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

   Essa etapa instala o pacote e suas dependências.

3. Pesquise e instale esses pacotes:

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

Salve suas credenciais da conta de armazenamento no arquivo App.config

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

• SDK do NET do Azure v12
• SDK do NET do Azure v11

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

XMLCopiar

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

 Observação

O emulador de armazenamento do Azure não tem suporte para Arquivos do Azure no momento. Sua cadeia de conexão deve ter como destino uma conta de armazenamento do Azure na nuvem para funcionar com os Arquivos do Azure.

Adicionar diretivas using

No Gerenciador de Soluções, abra o arquivo Program.cs e adicione o seguinte usando as diretivas do tipo do arquivo.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

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;

Acessar o compartilhamento de arquivos programaticamente

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

• SDK do NET do Azure v12
• SDK do NET do Azure v11

O método a seguir criará 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, a amostra tenta baixar um arquivo que criamos anteriormente. Chame esse método em Main().

C#Copiar

//-------------------------------------------------
// 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 de um compartilhamento de arquivos

A partir da versão 5.x da biblioteca de cliente dos Arquivos do Azure, você pode definir a cota (tamanho máximo) de um compartilhamento de arquivos. Você também pode verificar a quantidade de dados atualmente armazenada no compartilhamento.

Definir a cota de 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 a seguir mostra como verificar o uso atual de um compartilhamento e como definir a cota para o compartilhamento.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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 compartilhado para um arquivo ou compartilhamento de arquivos

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.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

O método de exemplo a seguir retorna uma SAS em um arquivo no compartilhamento especificado.

C#Copiar

//-------------------------------------------------
// 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 saber mais sobre como criar e usar assinaturas de acesso compartilhado, veja Como assinaturas de acesso compartilhado funcionam.

Copiar arquivos

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

Você também pode usar AzCopy para copiar um arquivo para outro, ou para copiar um blob para um arquivo, ou o contrário. Confira Introdução ao AzCopy.

 Observação

Se você estiver copiando um blob em um arquivo, ou um arquivo em um blob, use uma assinatura de acesso compartilhado (SAS) para autorizar o acesso ao objeto de origem, mesmo se estiver copiando dentro da mesma conta de armazenamento.

Copiar um arquivo para outro arquivo

O exemplo a seguir copia um arquivo em outro arquivo no mesmo compartilhamento. Você pode usar a autenticação de Chave Compartilhada para fazer a cópia porque esta operação copia arquivos dentro da mesma conta de armazenamento.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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 arquivo em um blob

O exemplo a seguir cria um arquivo e o copia em um blob dentro da mesma conta de armazenamento. O exemplo cria uma SAS para o arquivo de origem, que o serviço usa para autorizar o acesso ao arquivo de origem durante a operação de cópia.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

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

Você pode copiar um blob em um arquivo da mesma maneira. Se o objeto de origem for um blob, crie uma SAS para autorizar o acesso ao blob durante a operação de cópia.

Instantâneos de compartilhamento

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

Criar instantâneos de compartilhamento

O exemplo a seguir cria um instantâneo de compartilhamento de arquivos.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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 compartilhamento

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

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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 procura arquivos e diretórios em instantâneos de compartilhamento.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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 a recuperação de arquivos individuais ou de todo o compartilhamento de arquivo.

Você pode restaurar um arquivo de um instantâneo de compartilhamento de arquivo consultando os instantâneos de compartilhamento de um compartilhamento de arquivos. 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.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

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

Excluir instantâneos de compartilhamento

O exemplo a seguir exclui um instantâneo de compartilhamento de arquivos.

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

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

A Análise de Armazenamento do Azure dá suporte a métricas para os Arquivos do Azure. Com dados de métricas, você pode rastrear solicitações e diagnosticar problemas.

É possível habilitar métricas para os Arquivos do Azure por meio do portal do Azure. Você também pode habilitar métricas programaticamente ao chamar a operação Definir Propriedades de Serviço do Arquivo com a API REST ou uma operação semelhante na biblioteca do cliente dos Arquivos do Azure.

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

• SDK do NET do Azure v12
• SDK do NET do Azure v11

C#Copiar

//-------------------------------------------------
// 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, poderá consultar Solucionar problemas de Arquivos do Azure no Windows.