Desenvolvimento para o Arquivos do Azure com .NET
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.IO
Azure.Storage.Files.Shares
abstraem essas abordagens.
API | Quando usar | Observações |
---|---|---|
System.IO | Seu aplicativo:
|
A E/S de arquivo implementada com os Arquivos do Azure via SMB geralmente é a mesma de E/S com qualquer compartilhamento de arquivos de rede ou dispositivo de armazenamento local. Para obter uma introdução a vários recursos no .NET, incluindo E/S de arquivo, consulte o tutorial Aplicativo de Console. |
Azure.Storage.Files.Shares | Seu aplicativo:
|
Este artigo demonstra o uso de Azure.Storage.Files.Shares para E/S de arquivo usando a REST em vez do protocolo SMB e o gerenciamento do compartilhamento de arquivos. |
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.
- Inicie o Visual Studio e selecione Criar um projeto.
- Em Criar um novo projeto, escolha Aplicativo de Console (.NET Framework) para C#. Em seguida, selecione Avançar.
- 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:
- 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:
No Gerenciador de Soluções, clique com o botão direito do mouse no seu projeto e escolhaGerenciar Pacotes NuGet.
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.
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.
Substitua myaccount
pelo nome da sua conta de armazenamento e mykey
pela sua chave de 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>
Observação
No momento, o emulador de armazenamento Azurite não tem suporte para Arquivos do Azure. 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.
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.
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()
.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
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 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 estiver copiando um blob para um arquivo, ou um arquivo para 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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.
//-------------------------------------------------
// 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();
}
Caso você encontre algum problema, veja Solução de problemas dos Arquivos do Azure.
Próximas etapas
Para saber mais sobre os Arquivos do Azure, confira os seguintes recursos:
- Introdução ao AzCopy
- Solucionar problemas dos Arquivos do Azure
- APIs do Armazenamento do Azure para .NET
- API REST do serviço Arquivo
Para obter exemplos de código relacionados usando SDKs preteridos do .NET versão 11.x, confira os Exemplos de código usando o .NET versão 11.x.