Programar para os Ficheiros do Azure com .NET

Aprenda as noções básicas sobre o desenvolvimento de aplicações .NET que utilizam Ficheiros do Azure para armazenar dados. Este artigo mostra como criar uma aplicação de consola simples para fazer o seguinte com .NET e Ficheiros do Azure:

  • Obtenha o conteúdo de um ficheiro.
  • Defina o tamanho máximo, ou quota, para uma partilha de ficheiros.
  • Crie uma assinatura de acesso partilhado (SAS) para um ficheiro.
  • 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 uma partilha de ficheiros.
  • Restaurar um ficheiro a partir de um instantâneo de partilha.
  • Utilize as Métricas de Armazenamento do Azure para resolução de problemas.

Para saber mais sobre Ficheiros do Azure, consulte O que é Ficheiros do Azure?

Dica

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. No .NET, as System.IO APIs e Azure.Storage.Files.Shares abstraem estas abordagens.

API Quando utilizar Notas
System.IO A sua aplicação:
  • Precisa de ler/escrever ficheiros com o 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 ficheiro implementada com Ficheiros do Azure através de SMB é geralmente igual à E/S com qualquer partilha de ficheiros de rede ou dispositivo de armazenamento local. Para obter uma introdução a várias funcionalidades no .NET, incluindo E/S de ficheiros, veja o tutorial Aplicação de Consola .
Azure.Storage.Files.Shares A sua aplicação:
  • Não é possível aceder ao Ficheiros do Azure com 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 a utilização de para E/S de Azure.Storage.Files.Shares ficheiros com REST em vez de SMB e gestão da partilha de ficheiros.

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

Pode utilizar a biblioteca de cliente Ficheiros do Azure em qualquer tipo de aplicação .NET. Estas aplicações incluem a cloud, a Web, o ambiente de trabalho e as aplicações móveis do Azure. Neste guia, vamos criar uma aplicação de consola para simplificar.

No Visual Studio, crie uma nova aplicação de consola do Windows. Os passos seguintes mostram-lhe como criar uma aplicação de consola 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, selecione Aplicação de Consola (.NET Framework) para C#e, em seguida, selecione Seguinte.
  3. Em Configurar o novo projeto, introduza um nome para a aplicação e selecione Criar.

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

Utilizar o NuGet para instalar os pacotes necessários

Veja estes pacotes no seu projeto:

Pode utilizar o NuGet para obter os pacotes. Siga estes passos:

  1. No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Gerir Pacotes NuGet.

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

    Este passo instala o pacote e as respetivas dependências.

  3. Procure e instale estes pacotes:

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

Guardar as credenciais da conta de armazenamento no ficheiro de App.config

Em seguida, guarde as suas credenciais no ficheiro App.config do projeto. No Explorador de Soluções, faça duplo clique App.config e edite o ficheiro para que seja semelhante ao exemplo seguinte.

Substitua pelo myaccount 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 suporta Ficheiros do Azure. A cadeia de ligação tem de visar uma conta de armazenamento do Azure na cloud para trabalhar com Ficheiros do Azure.

Adicionar com diretivas

Em Explorador de Soluções, abra o ficheiro Program.cs e adicione as seguintes diretivas de utilização à parte superior do ficheiro.

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 ficheiro Program.cs , adicione o seguinte código para aceder à partilha de ficheiros programaticamente.

O método seguinte cria uma partilha de ficheiros, caso ainda não exista. O método começa por criar um objeto ShareClient a partir de uma cadeia de ligação. Em seguida, o exemplo tenta transferir um ficheiro que criámos anteriormente. Chame este 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 Ficheiros do Azure, pode definir a quota (tamanho máximo) para uma partilha de ficheiros. De igual modo, pode verificar a quantidade de dados atualmente armazenada na partilha.

Definir a quota de uma partilha limita o tamanho total dos ficheiros armazenados na partilha. Se o tamanho total dos ficheiros na partilha exceder a quota, os clientes não poderão aumentar o tamanho dos ficheiros existentes. Os clientes também não podem criar novos ficheiros, a menos que esses ficheiros 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 Ficheiros do Azure, pode gerar uma assinatura de acesso partilhado (SAS) para uma partilha de ficheiros ou para um ficheiro individual.

O seguinte método de exemplo devolve uma SAS num ficheiro na partilha especificada.

//-------------------------------------------------
// 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 utilizar assinaturas de acesso partilhado, consulte Como funciona uma assinatura de acesso partilhado.

Copiar ficheiros

A partir da versão 5.x da biblioteca de cliente do Ficheiros do Azure, pode copiar um ficheiro para outro ficheiro, um ficheiro para um blob ou um blob para um ficheiro.

Também pode utilizar o AzCopy para copiar um ficheiro para outro ou para copiar um blob para um ficheiro ou para o contrário. Veja Introdução ao AzCopy.

Nota

Se estiver a copiar um blob para um ficheiro ou um ficheiro para um blob, tem de utilizar uma assinatura de acesso partilhado (SAS) para autorizar o acesso ao objeto de origem, mesmo se estiver a copiar dentro da mesma conta de armazenamento.

Copiar um ficheiro para outro ficheiro

O exemplo seguinte copia um ficheiro para outro ficheiro na mesma partilha. Pode utilizar a autenticação de Chave Partilhada para fazer a cópia porque esta operação copia ficheiros na 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 de armazenamento. 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.

Partilhar instantâneos

A partir da versão 8.5 da biblioteca de cliente Ficheiros do Azure, pode criar um instantâneo de partilha. Também pode listar, procurar ou eliminar instantâneos de partilha. Uma vez criados, os instantâneos de partilha são só de 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 seguinte lista os instantâneos numa partilha.

//-------------------------------------------------
// 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 ficheiros e diretórios em instantâneos de partilha

O exemplo seguinte procura ficheiros e diretórios em instantâneos de partilha.

//-------------------------------------------------
// 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 partilhas de ficheiros ou ficheiros a partir de instantâneos de partilha

Tirar um instantâneo de uma partilha de ficheiros permite-lhe recuperar ficheiros individuais ou toda a partilha de ficheiros.

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, pode obter um ficheiro que pertence a um instantâneo de partilha específico. Utilize essa versão para ler ou restaurar diretamente o ficheiro.

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

Resolver problemas Ficheiros do Azure com métricas

O Azure Análise de Armazenamento suporta métricas para Ficheiros do Azure. Com os dados de métricas, pode rastrear pedidos e diagnosticar problemas.

Pode ativar as métricas para Ficheiros do Azure a partir do portal do Azure. Também pode ativar as métricas através de programação ao chamar a operação Definir Propriedades do Serviço de Ficheiros com a API REST ou um dos respetivos analógicos na biblioteca de cliente do Ficheiros do Azure.

O exemplo de código seguinte mostra como utilizar a biblioteca de cliente .NET para ativar métricas para Ficheiros 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 encontrar problemas, veja Resolver problemas Ficheiros do Azure.

Passos seguintes

Para obter mais informações sobre Ficheiros do Azure, veja os seguintes recursos:

Artigos e vídeos concetuais

Suporte de ferramentas para o Armazenamento de ficheiros

Referência

Para exemplos de código relacionados com SDKs de .NET preteridos versão 11.x, veja Exemplos de código com a versão 11.x do .NET.