Compartilhar via

Guia de Início Rápido: biblioteca de clientes do Armazenamento de Blobs do Azure para .NET

  • Artigo

Observação

A opção Criar do zero orienta você passo a passo pelo processo de criação de um projeto, instalação de pacotes, escrita do código e execução de um aplicativo de console básico. Essa abordagem é recomendada se você deseja entender todos os detalhes envolvidos na criação de um aplicativo que se conecta ao Armazenamento de Blobs do Azure. Caso prefira automatizar as tarefas de implantação e começar com um projeto concluído, escolha Iniciar com um modelo.

Observação

A opção Iniciar com um modelo usa o Azure Developer CLI para automatizar tarefas de implantação e iniciar com um projeto concluído. Essa abordagem é recomendada se você deseja explorar o código o mais rápido possível sem passar pelas tarefas de instalação. Caso prefira obter instruções passo a passo para criar o aplicativo, escolha Criar do zero.

Introdução à biblioteca de clientes do Armazenamento de Blobs do Azure para .NET. O Armazenamento de Blobs do Azure é a solução de armazenamento de objetos da Microsoft para a nuvem e é otimizado para armazenar grandes quantidades de dados não estruturados.

Neste artigo, você vai seguir as etapas para instalar o pacote e testar o código de exemplo para tarefas básicas.

Neste artigo, você usará o Azure Developer CLI para implantar recursos do Azure e executar um aplicativo de console concluído com apenas alguns comandos.

Documentação de referência da API | Código-fonte da biblioteca | Pacote (NuGet) | Exemplos

Este vídeo mostra como começar a usar a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET.

As etapas no vídeo também são descritas nas seções a seguir.

Pré-requisitos

Configurando

Esta seção orienta você na preparação de um projeto para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET.

Criar o projeto

Crie um aplicativo de console .NET usando a CLI do .NET ou o Visual Studio 2022.

  1. Na parte superior do Visual Studio, navegue até Arquivo>Novo>Projeto...

  2. Na janela da caixa de diálogo, insira o aplicativo de console na caixa de pesquisa do modelo do projeto e selecione o primeiro resultado. Escolha Avançar na parte inferior do diálogo.

    Captura de tela mostrando como criar um projeto usando o Visual Studio.

  3. Em Nome do Projeto, insira BlobQuickstart. Deixe os outros campos com os valores padrão e selecione Avançar.

  4. No caso do Framework, verifique se a última versão instalada do .NET está selecionada. Em seguida, escolha Criar. O novo projeto será aberto no ambiente do Visual Studio.

Instalar o pacote

Para interagir com o Armazenamento de Blobs do Azure, instale a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET.

  1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências do projeto. Selecione Gerenciar Pacotes NuGet.

  2. Na janela resultante, pesquise por Azure.Storage.Blobs. Selecione o resultado apropriado e, em seguida, Instalar.

    Captura de tela mostrando como adicionar um novo pacote usando o Visual Studio.

Configurar o código do aplicativo

Substitua o código inicial no arquivo Program.cs para que ele corresponda ao exemplo a seguir, que inclui as instruções necessárias using para este exercício.

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Com o Azure Developer CLI instalado, você pode criar uma conta de armazenamento e executar o código de exemplo com apenas alguns comandos. Execute o projeto em seu ambiente de desenvolvimento local ou em um DevContainer.

Inicializar o modelo do Azure Developer CLI e implantar recursos

Em um diretório vazio, siga estas etapas para inicializar o modelo azd, provisionar recursos do Azure e começar a usar o código:

  • Clone os ativos do repositório de início rápido do GitHub e inicialize o modelo localmente:

    azd init --template blob-storage-quickstart-dotnet

    Você será solicitado a dar as seguintes informações:

    • Nome do ambiente: esse valor é usado como um prefixo para todos os recursos do Azure criados pelo Azure Developer CLI. O nome precisa ser exclusivo em todas as assinaturas do Azure e ter entre 3 e 24 caracteres. O nome pode conter apenas números e letras minúsculas.

  • Faça logon no Azure:

    azd auth login

  • Provisione e implante os recursos no Azure:

    azd up

    Você será solicitado a dar as seguintes informações:

    • Assinatura: a assinatura do Azure na qual seus recursos estão implantados.
    • Localização: a região do Azure em que os recursos estão implantados.

    A implantação pode levar alguns minutos para ser concluída. A saída do comando azd up inclui o nome da conta de armazenamento recém-criada, que você precisará mais tarde para executar o código.

Execute o código de exemplo

Neste ponto, os recursos são implantados no Azure e o projeto está pronto para ser executado. Siga estas etapas para atualizar o nome da conta de armazenamento no código e executar o exemplo de aplicativo de console:

  • Atualizar o nome da conta de armazenamento: navegue até o diretório src e edite Program.cs. Localize o espaço reservado <storage-account-name> e substitua-o pelo nome real da conta de armazenamento criada pelo comando azd up. Salve as alterações.
  • Executar o projeto: se você estiver usando o Visual Studio, pressione F5 para compilar e executar o código e interagir com o aplicativo de console. Se você estiver usando a CLI do .NET, navegue até o diretório do aplicativo, compile o projeto usando dotnet build e execute o aplicativo usando o dotnet run.
  • Observar a saída: esse aplicativo cria um arquivo de teste na pasta de dados local e o carrega em um contêiner na conta de armazenamento. Em seguida, o exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos novos e antigos.

Para saber mais sobre como o código de exemplo funciona, confira Exemplos de código.

Quando terminar de testar o código, confira a seção Limpar recursos para excluir os recursos criados pelo comando azd up.

Modelo de objeto

O Armazenamento de Blobs do Azure é otimizado para armazenar grandes quantidades de dados não estruturados. Os dados não estruturados não seguem uma definição nem um modelo de dados específico, como dados de texto ou binários. O Armazenamento de Blobs oferece três tipos de recursos:

  • A conta de armazenamento
  • Um contêiner na conta de armazenamento
  • Um blob no contêiner

O diagrama a seguir mostra a relação entre esses recursos.

Diagrama da arquitetura de armazenamento de Blobs.

Use as seguintes classes .NET para interagir com esses recursos:

  • BlobServiceClient: a classe BlobServiceClient permite manipular os recursos do Armazenamento do Azure e os contêineres do blob.
  • BlobContainerClient: a classe BlobContainerClient permite manipular os contêineres do Armazenamento do Azure e seus blobs.
  • BlobClient: a classe BlobClient permite manipular os blobs do Armazenamento do Azure.

Exemplos de código

Os snippets de código de exemplo das próximas seções demonstram como executar as seguintes tarefas com a biblioteca de clientes do Armazenamento de Blobs do Azure para .NET:

Importante

Verifique se você instalou os pacotes NuGet corretos e adicionou as instruções using necessárias para que os exemplos de código funcionem, conforme descrito na seção de configuração.

Observação

O modelo do Azure Developer CLI inclui um projeto com um código de exemplo já implementado. Os exemplos a seguir fornecem detalhes de cada parte do código de exemplo. O modelo implementa o método de autenticação sem senha recomendado, conforme descrito na seção Autenticar-se no Azure. O método de cadeia de conexão é mostrado como uma alternativa, mas não é usado no modelo e não é recomendado para o código de produção.

Autenticar-se no Azure e autorizar o acesso a dados de blob

As solicitações de aplicativo para o Armazenamento de Blobs do Azure devem ser autorizadas. O uso da classe DefaultAzureCredential fornecida pela biblioteca de clientes de identidade do Azure é a abordagem recomendada para implementar conexões sem senha com os serviços do Azure no código, incluindo o Armazenamento de Blobs.

Você também pode autorizar solicitações para o Armazenamento de Blobs do Azure usando a chave de acesso da conta. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor as chaves de acesso em um local não seguro. Qualquer pessoa que tenha a chave de acesso pode autorizar solicitações na conta de armazenamento e efetivamente tem acesso a todos os dados. DefaultAzureCredential oferece benefícios aprimorados de gerenciamento e segurança sobre a chave de conta para permitir a autenticação sem senha. Ambas as opções são demonstradas no exemplo a seguir.

DefaultAzureCredential é uma classe fornecida pela biblioteca de clientes do Azure Identity para .NET. Para saber mais sobre ela, consulte a Visão geral DefaultAzureCredential. DefaultAzureCredential dá suporte a vários métodos de autenticação e determina quais métodos devem ser usados no runtime. Essa abordagem permite que seu aplicativo use diferentes métodos de autenticação em ambientes diferentes (local versus produção) sem implementar código específico do ambiente.

A ordem e as localizações nas quais DefaultAzureCredential procura as credenciais, podem ser encontradas na Visão geral da biblioteca de Identidade do Azure.

Por exemplo, o aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio no desenvolvimento local. Em seguida, o aplicativo pode usar uma identidade gerenciada após ser implantado no Azure. Nenhuma alteração de código é necessária para essa transição.

Atribuir funções à sua conta de usuário do Microsoft Entra

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados de blob tem as permissões corretas. Você precisará do Colaborador de Dados do Blob de Armazenamento para ler e gravar os dados de blob. Para atribuir essa função a si mesmo, você precisará receber a atribuição da função Administrador de Acesso do Usuário ou de outra função que inclua a ação Microsoft.Authorization/roleAssignments/write. É possível atribuir funções RBAC do Azure a um usuário usando o portal do Azure, a CLI do Azure ou o Azure PowerShell. Você pode saber mais sobre os escopos disponíveis para atribuições de função na página de visão geral do escopo.

Nesse cenário, você atribuirá permissões à sua conta de usuário, no escopo da conta de armazenamento, para seguir o Princípio do Privilégio Mínimo. Essa prática fornece aos usuários apenas as permissões mínimas necessárias e cria ambientes de produção mais seguros.

O exemplo a seguir atribuirá a função de Colaborador de Dados do Blob de Armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados de blob na sua conta de armazenamento.

Importante

Na maioria dos casos, levará um ou dois minutos para a atribuição de função se propagar no Azure, mas em casos raros pode levar até oito minutos. Se você receber erros de autenticação ao executar o código pela primeira vez, aguarde alguns instantes e tente novamente.

  1. No portal do Azure, localize sua conta de armazenamento usando a barra de pesquisa principal ou a navegação à esquerda.

  2. Na página de visão geral da conta de armazenamento, selecione Controle de acesso (IAM) no menu à esquerda.

  3. Na página Controle de acesso (IAM), selecione a guia Atribuições de função.

  4. Selecione + Adicionar no menu superior e, em seguida, Adicionar atribuição de função no menu suspenso resultante.

    Captura de tela mostrando como atribuir uma função.

  5. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de Dados do Blob de Armazenamento e selecione o resultado correspondente e, em seguida, escolha Avançar.

  6. Em Atribuir acesso a, selecione Usuário, grupo ou entidade de serviço e, em seguida, selecione + Selecionar membros.

  7. No diálogo, pesquise seu nome de usuário do Microsoft Entra (geralmente seu endereço de email user@domain) e escolha Selecionar na parte inferior do diálogo.

  8. Selecione Revisar + atribuir para ir para a página final e, em seguida, Revisar + atribuir novamente para concluir o processo.

Entrar e conectar o código do aplicativo ao Azure usando DefaultAzureCredential

É possível autorizar o acesso aos dados pela conta de armazenamento usando as seguintes etapas:

  1. Para desenvolvimento local, você deve estar autenticado com a mesma conta do Microsoft Entra à qual a função foi atribuída. Você pode autenticar por meio de ferramentas de desenvolvimento populares, como a CLI do Azure ou o Azure PowerShell. As ferramentas de desenvolvimento com as quais você pode autenticar variam entre os idiomas.

    Entre no Azure por meio da CLI do Azure usando o seguinte comando:

    az login

  2. Para usar DefaultAzureCredential, adicione o pacote Azure.Identity ao aplicativo.

    1. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó Dependências do projeto. Selecione Gerenciar Pacotes NuGet.

    2. Na janela resultante, pesquise por Azure.Identity. Selecione o resultado apropriado e, em seguida, Instalar.

      Uma captura de tela mostrando como adicionar o pacote de identidade.

  3. Atualize o código Program.cs para que ele corresponda ao exemplo a seguir. Quando o código for executado na estação de trabalho local durante o desenvolvimento, ele usará as credenciais do desenvolvedor da ferramenta priorizada na qual você está conectado para autenticação no Azure, como a CLI do Azure ou o Visual Studio.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Atualize o nome da conta de armazenamento no URI do BlobServiceClient. O nome da conta de armazenamento pode ser encontrado na página de visão geral do portal do Azure.

    Uma captura de tela mostrando como localizar o nome da conta de armazenamento.

    Observação

    Quando implantado no Azure, esse mesmo código pode ser usado para autorizar solicitações para o Armazenamento do Azure de um aplicativo em execução no Azure. No entanto, você precisará habilitar a identidade gerenciada em seu aplicativo no Azure. Em seguida, configure a conta de armazenamento para permitir que essa identidade gerenciada se conecte. Para obter instruções detalhadas sobre como configurar essa conexão entre os serviços do Azure, consulte o tutorial Autenticação de aplicativos hospedados no Azure.

Criar um contêiner

Crie um contêiner em sua conta de armazenamento chamando o método CreateBlobContainerAsync no objeto blobServiceClient. Neste exemplo, o código acrescenta um valor GUID ao nome do contêiner para garantir que ele seja exclusivo.

Adicione o seguinte código ao final do arquivo Program.cs:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Para saber mais sobre como criar um contêiner e explorar mais exemplos de código, confira Criar um contêiner de blob com .NET.

Importante

Os nomes de contêiner devem estar em minúsculas. Para saber mais sobre como nomear contêineres e blobs, veja Nomenclatura e referência de contêineres, blobs e metadados.

Carregar um blob para um contêiner

Carregue um blob em um contêiner usando UploadAsync. O código de exemplo cria um arquivo de texto no diretório data local para carregá-lo no contêiner.

Adicione o seguinte código ao final do arquivo Program.cs:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Para saber mais sobre o carregamento de blobs, e para explorar mais exemplos de código, confira Carregar um blob com .NET.

Listar os blobs de um contêiner

Liste os blobs no contêiner chamando o método GetBlobsAsync.

Adicione o seguinte código ao final do arquivo Program.cs:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Para saber mais sobre a listagem de blobs, e para explorar mais exemplos de código, confira Listagem de blobs com .NET.

Baixar um blob

Baixe o blob que criamos anteriormente chamando o método DownloadToAsync. O código de exemplo acrescenta a cadeia de caracteres “DOWNLOADED” ao nome do arquivo para que você possa ver os dois arquivos no sistema de arquivos local.

Adicione o seguinte código ao final do arquivo Program.cs:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Para saber mais sobre o download de blobs, e para explorar mais exemplos de código, confira Baixar um blob com .NET.

Excluir um contêiner

O código a seguir limpa os recursos que o aplicativo criou excluindo o contêiner usando DeleteAsync. O código de exemplo também exclui os arquivos locais criados pelo aplicativo.

O aplicativo pausa a entrada do usuário chamando Console.ReadLine antes de excluir o blob, o contêiner e os arquivos locais. Essa é uma boa oportunidade de verificar se os recursos foram criados corretamente antes de serem excluídos.

Adicione o seguinte código ao final do arquivo Program.cs:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Para saber mais sobre como excluir um contêiner e explorar mais exemplos de código, confira Excluir e restaurar um contêiner de blob com .NET.

O código concluído

Depois que você concluir essas etapas, o código do arquivo Program.cs será parecido com o seguinte:

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Executar o código

Este aplicativo cria um arquivo de teste na pasta dados local e o carrega no Armazenamento de Blobs. Em seguida, o exemplo lista os blobs no contêiner e baixa o arquivo com um novo nome para que você possa comparar os arquivos novos e antigos.

Se você estiver usando o Visual Studio, pressione F5 para criar e executar o código e interagir com o aplicativo de console. Se você estiver usando a CLI do .NET, navegue até seu diretório de aplicativo e compile e execute o aplicativo.

dotnet build

dotnet run

A saída do aplicativo é semelhante ao seguinte exemplo (os valores do GUID foram omitidos para facilitar a leitura):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de iniciar o processo de limpeza, verifique se os dois arquivos estão na pasta data. Você pode abri-los e observar se eles são idênticos.

Limpar os recursos

Depois de verificar os arquivos e concluir o teste, pressione a tecla ENTER para excluir os arquivos de teste e o contêiner criado na conta de armazenamento. Use também a CLI do Azure para excluir recursos.

Ao terminar o início rápido, limpe os recursos criados executando o seguinte comando:

azd down

Você será solicitado a confirmar a exclusão dos recursos. Insira y para confirmar.

Próxima etapa

Exemplos de Armazenamento do Azure e guias de desenvolvedor para .NET