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 | ||
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. No .NET, as System.IO
APIs e Azure.Storage.Files.Shares
abstraem estas abordagens.
API | Quando utilizar | Notas |
---|---|---|
System.IO | A sua aplicação:
|
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:
|
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.
- Inicie o Visual Studio e selecione Criar um novo projeto.
- Em Criar um novo projeto, selecione Aplicação de Consola (.NET Framework) para C#e, em seguida, selecione Seguinte.
- 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:
- Biblioteca principal do Azure para .NET: este pacote é a implementação do pipeline de cliente do Azure.
- Biblioteca de cliente do Blob de Armazenamento do Azure para .NET: este pacote fornece acesso programático aos recursos de blobs na sua conta de armazenamento.
- Biblioteca de cliente dos Ficheiros de Armazenamento do Azure para .NET: este pacote fornece acesso programático aos recursos de ficheiros na sua conta de armazenamento.
- Biblioteca de Configuration Manager do sistema para .NET: este pacote fornece uma classe que armazena e recupera valores num ficheiro de configuração.
Pode utilizar o NuGet para obter os pacotes. Siga estes passos:
No Explorador de Soluções, clique com o botão direito do rato no projeto e selecione Gerir Pacotes NuGet.
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.
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
- Azure Files: a frictionless cloud SMB file system for Windows and Linux (Ficheiros do Azure: um sistema de ficheiros SMB na cloud sem incómodos para Windows e Linux)
- Utilizar os Ficheiros do Azure com o Linux
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.