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 | ||
Partilhas de ficheiros Standard (GPv2), GRS/GZRS | ||
Partilhas de ficheiros Premium (FileStorage), LRS/ZRS |
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:
|
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:
|
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.
- Inicie o Visual Studio e selecione Criar um novo projeto.
- Em Criar um novo projeto, escolha Aplicativo de Console (.NET Framework) para C# e selecione Avançar.
- 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:
- Biblioteca principal do Azure para .NET: este pacote é a implementação do pipeline de cliente do Azure.
- Biblioteca de cliente de Blob de Armazenamento do Azure 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 do System Configuration Manager para .NET: Este pacote fornece uma classe armazenando e recuperando valores em um arquivo de configuração.
Você pode usar o NuGet para obter os pacotes. Siga estes passos:
No Gerenciador de Soluções, clique com o botão direito do mouse em seu projeto e escolha Gerenciar Pacotes NuGet.
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.
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:
- Introdução ao AzCopy
- Resolução de problemas de Ficheiros do Azure
- APIs de Armazenamento do Microsoft Azure para .NET
- API REST de Serviço de Ficheiros
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.