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

  • Artigo

Introdução à biblioteca de clientes do Armazenamento de Filas do Azure para o .NET. O Armazenamento de Filas do Azure é um serviço usado para armazenar grandes quantidades de mensagens para recuperação e processamento posteriores. Siga estas etapas para instalar o pacote e experimentar o código de exemplo para tarefas básicas.

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

Use a biblioteca de clientes do Armazenamento de Filas do Azure para .NET para:

  • Criar uma fila
  • Adicionar mensagens a uma fila
  • Espiar mensagens em uma fila
  • Atualizar uma mensagem em uma fila
  • Obter o tamanho da fila
  • Receber mensagens de uma fila
  • Excluir mensagens de uma fila
  • Excluir uma fila

Pré-requisitos

Configurando

Esta seção fornece instruções sobre como preparar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Filas do Azure para .NET.

Criar o projeto

Crie um aplicativo .NET denominado QueuesQuickstart.

  1. Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome QueuesQuickstart. Esse comando cria um projeto simples em C# do tipo "olá, mundo" com um arquivo de origem único chamado Program.cs.

    dotnet new console -n QueuesQuickstart

  2. Alterne para o diretório QueuesQuickstart recém-criado.

    cd QueuesQuickstart

Instalar os pacotes

Ainda no diretório do aplicativo, instale o pacote da biblioteca de clientes do Armazenamento de Filas do Azure para .NET usando o comando dotnet add package.

dotnet add package Azure.Storage.Queues

O pacote da biblioteca de clientes de Identidade do Azure também é necessário para conexões sem senha com os serviços do Azure.

dotnet add package Azure.Identity

Configurar o framework de aplicativos

  1. Abrir o projeto no editor escolhido
  2. Abra o arquivo Program.cs
  3. Atualize o código existente para que ele corresponda ao seguinte:
using Azure;
using Azure.Identity;
using Azure.Storage.Queues;
using Azure.Storage.Queues.Models;
using System;
using System.Threading.Tasks;

Console.WriteLine("Azure Queue Storage client library - .NET quickstart sample");

// Quickstart code goes here

Autenticar no Azure

As solicitações do aplicativo para a maioria dos serviços do Azure precisam 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 seu código.

Você também pode autorizar solicitações para serviços do Azure usando senhas, cadeias de conexão ou outras credenciais diretamente. No entanto, essa abordagem deve ser usada com cautela. Os desenvolvedores devem ser diligentes para nunca expor esses segredos em um local não seguro. Qualquer pessoa que tenha acesso à senha ou à chave secreta poderá se autenticar. 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 da Identidade do Azure para .NET. Para saber mais sobre DefaultAzureCredential, confira a Visão geral do 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.

Por exemplo, seu aplicativo pode autenticar usando suas credenciais de entrada do Visual Studio ao desenvolver localmente e, em seguida, usar uma identidade gerenciada depois de ser implantado no Azure. Nenhuma alteração de código é necessária para essa transição.

Ao desenvolver localmente, verifique se a conta de usuário que está acessando os dados da fila tem as permissões corretas. Você precisará do Colaborador de dados da fila de armazenamento para ler e gravar os dados da fila. 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 da fila de armazenamento à sua conta de usuário, que fornece acesso de leitura e gravação aos dados da fila 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.

A screenshot showing how to assign a role.

  1. Use a caixa de pesquisa para filtrar os resultados para a função desejada. Para este exemplo, pesquise o Colaborador de dados da fila de armazenamento, e selecione o resultado correspondente e, em seguida, escolha Avançar.

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

  3. 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.

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

Modelo de objeto

O armazenamento de Filas do Azure é um serviço usado para armazenar grandes quantidades de mensagens. Uma mensagem da fila pode ter até 64 KB. Uma fila pode conter milhões de mensagens, até o limite da capacidade total de uma conta de armazenamento. As filas são normalmente usadas para criar uma lista de pendências de trabalho para processamento assíncrono. O Armazenamento de Filas oferece três tipos de recursos:

  • Conta de armazenamento: todo o acesso ao Armazenamento do Azure é feito por meio de uma conta de armazenamento. Para saber mais sobre as contas de armazenamento, consulte Visão geral da conta de armazenamento
  • Fila: uma fila contém um conjunto de mensagens. Todas as mensagens devem estar em uma fila. Observe que o nome da fila deve estar em letras minúsculas. Para saber mais sobre filas de nomenclatura, confira Nomenclatura de filas e metadados.
  • Mensagem: uma mensagem, em qualquer formato, de até 64 KB. Uma mensagem pode ficar na fila por no máximo 7 dias. Para a versão 2017-07-29 ou posterior, a vida útil máxima pode ser qualquer número positivo ou -1, indicando que a mensagem não expira. Se esse parâmetro for omitido, a vida útil padrão será de sete dias.

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

Diagram of Queue storage architecture

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

  • QueueServiceClient: O QueueServiceClient permite que você gerencie todas as filas em sua conta de armazenamento.
  • QueueClient: A classe QueueClient permite que você gerencie e manipule uma fila individual e as mensagens dela.
  • QueueMessage: A classe QueueMessage representa os objetos individuais retornados ao chamar ReceiveMessages em uma fila.

Exemplos de código

Estes snippets de código de exemplo mostram como realizar as seguintes ações com a biblioteca de clientes do Armazenamento de Filas do Azure para .NET:

Autorizar acesso e criar um objeto de cliente

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

Depois de autenticado, você pode criar e autorizar um objeto QueueClient usando DefaultAzureCredential para acessar dados da fila na conta de armazenamento. DefaultAzureCredential descobrirá e usará automaticamente a conta com a qual você entrou na etapa anterior.

Para autorizar o uso de DefaultAzureCredential, verifique se você adicionou a pacote Azure.Identity, conforme descrito em Instalar os pacotes. Além disso, lembre-se de adicionar uma diretiva de uso para o namespace Azure.Identity no arquivo Program.cs:

using Azure.Identity;

Em seguida, decida um nome para a fila e crie uma instância da classe QueueClient usando DefaultAzureCredential para autorização. Usaremos esse objeto cliente para criar e interagir com o recurso de fila de espera na conta de armazenamento.

Importante

Os nomes de fila podem conter apenas letras minúsculas, números e hifens e precisam começar com uma letra ou um número. Cada hífen deve ser precedido e seguido por um caractere que não seja um hífen. O nome também precisa ter entre 3 e 63 caracteres. Para obter mais informações, confira Como nomear filas e metadados.

Adicione o código a seguir no final arquivo Program.cs. Certifique-se de substituir o valor do espaço reservado <storage-account-name>:

// Create a unique name for the queue
// TODO: Replace the <storage-account-name> placeholder 
string queueName = "quickstartqueues-" + Guid.NewGuid().ToString();
string storageAccountName = "<storage-account-name>";

// Instantiate a QueueClient to create and interact with the queue
QueueClient queueClient = new QueueClient(
    new Uri($"https://{storageAccountName}.queue.core.windows.net/{queueName}"),
    new DefaultAzureCredential());

Observação

As mensagens enviadas usando a classe QueueClient devem estar em um formato que possa ser incluído em uma solicitação XML com codificação UTF-8. Opcionalmente, você pode definir a opção MessageEncoding como Base64 para lidar com mensagens sem conformidade.

Criar uma fila

Usando o objeto QueueClient, chame o método CreateAsync para criar a fila na sua conta de armazenamento.

Adicione este código no final do método Program.cs:

Console.WriteLine($"Creating queue: {queueName}");

// Create the queue
await queueClient.CreateAsync();

Adicionar mensagens a uma fila

O snippet de código a seguir adiciona mensagens à fila de maneira assíncrona chamando o método SendMessageAsync. Ele também salva um SendReceipt retornado de uma chamada SendMessageAsync. O recibo é usado para atualizar a mensagem posteriormente no programa.

Adicione este código no final do arquivo Program.cs:

Console.WriteLine("\nAdding messages to the queue...");

// Send several messages to the queue
await queueClient.SendMessageAsync("First message");
await queueClient.SendMessageAsync("Second message");

// Save the receipt so we can update this message later
SendReceipt receipt = await queueClient.SendMessageAsync("Third message");

Espiar mensagens em uma fila

Espie as mensagens na fila chamando o método PeekMessagesAsync. Esse método recupera uma ou mais mensagens do início da fila, mas não altera a visibilidade da mensagem.

Adicione este código no final do arquivo Program.cs:

Console.WriteLine("\nPeek at the messages in the queue...");

// Peek at messages in the queue
PeekedMessage[] peekedMessages = await queueClient.PeekMessagesAsync(maxMessages: 10);

foreach (PeekedMessage peekedMessage in peekedMessages)
{
    // Display the message
    Console.WriteLine($"Message: {peekedMessage.MessageText}");
}

Atualizar uma mensagem em uma fila

Atualize o conteúdo de uma mensagem chamando o método UpdateMessageAsync. Esse método pode alterar o conteúdo e o tempo limite da visibilidade de uma mensagem. O conteúdo da mensagem precisa ser uma cadeia de caracteres codificada em UTF-8 com até 64 KB. Junto com o novo conteúdo da mensagem, transmita os valores do SendReceipt que foi salvo anteriormente no código. Os valores de SendReceipt identificam a mensagem a ser atualizada.

Console.WriteLine("\nUpdating the third message in the queue...");

// Update a message using the saved receipt from sending the message
await queueClient.UpdateMessageAsync(receipt.MessageId, receipt.PopReceipt, "Third message has been updated");

Obter o tamanho da fila

Você pode obter uma estimativa do número de mensagens em uma fila. O método GetProperties retorna propriedades de fila, incluindo a contagem de mensagens. A ApproximateMessagesCount propriedade contém o número aproximado de mensagens na fila. Esse número não é menor do que o número real de mensagens na fila, mas pode ser maior.

Adicione este código no final do arquivo Program.cs:

QueueProperties properties = queueClient.GetProperties();

// Retrieve the cached approximate message count
int cachedMessagesCount = properties.ApproximateMessagesCount;

// Display number of messages
Console.WriteLine($"Number of messages in queue: {cachedMessagesCount}");

Receber mensagens de uma fila

Baixe as mensagens adicionadas anteriormente chamando o método ReceiveMessagesAsync.

Adicione este código no final do arquivo Program.cs:

Console.WriteLine("\nReceiving messages from the queue...");

// Get messages from the queue
QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 10);

Opcionalmente, você pode especificar um valor para maxMessages, que é o número de mensagens a serem recuperadas da fila de espera. O padrão é 1 mensagem e o máximo é de 32 mensagens. Você também pode especificar um valor para o visibilityTimeout, o que ocultará as mensagens de outras operações durante o período do tempo limite. O padrão é 30 segundos.

Excluir mensagens de uma fila

Exclua as mensagens da fila depois que elas forem processadas. Nesse caso, o processamento só exibe a mensagem no console.

O aplicativo pausa a entrada do usuário chamando Console.ReadLine antes de processar e excluir as mensagens. Verifique no portal do Azure se os recursos foram criados corretamente antes de serem excluídos. As mensagens que não forem explicitamente excluídas acabarão se tornando novamente visíveis na fila de espera para obterem mais uma chance de processamento.

Adicione este código no final do arquivo Program.cs:

Console.WriteLine("\nPress Enter key to 'process' messages and delete them from the queue...");
Console.ReadLine();

// Process and delete messages from the queue
foreach (QueueMessage message in messages)
{
    // "Process" the message
    Console.WriteLine($"Message: {message.MessageText}");

    // Let the service know we're finished with
    // the message and it can be safely deleted.
    await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
}

Excluir uma fila

O código a seguir limpa os recursos que o aplicativo criou ao excluir a fila usando o método DeleteAsync.

Adicione este código no final do arquivo Program.cs:

Console.WriteLine("\nPress Enter key to delete the queue...");
Console.ReadLine();

// Clean up
Console.WriteLine($"Deleting queue: {queueClient.Name}");
await queueClient.DeleteAsync();

Console.WriteLine("Done");

Executar o código

Esse aplicativo cria e adiciona três mensagens a uma fila do Azure. O código lista as mensagens na fila e, em seguida, recupera essas mensagens e as exclui, antes de excluir a fila.

Na janela do console, 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:

Azure Queue Storage client library - .NET quickstart sample

Creating queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2

Adding messages to the queue...

Peek at the messages in the queue...
Message: First message
Message: Second message
Message: Third message

Updating the third message in the queue...

Receiving messages from the queue...

Press Enter key to 'process' messages and delete them from the queue...

Message: First message
Message: Second message
Message: Third message has been updated

Press Enter key to delete the queue...

Deleting queue: quickstartqueues-5c72da2c-30cc-4f09-b05c-a95d9da52af2
Done

Quando o aplicativo pausar antes de receber mensagens, verifique sua conta de armazenamento no portal do Azure. Verifique se as mensagens estão na fila.

Pressione a tecla Enter para receber e excluir as mensagens. Quando solicitado, pressione a tecla Enter novamente para excluir a fila e concluir a demonstração.

Próximas etapas

Neste início rápido, você aprendeu a criar uma fila e adicionar mensagens a ela usando o código .NET assíncrono. Em seguida, você aprendeu a espiar, recuperar e excluir mensagens. Por fim, você aprendeu a excluir uma fila de mensagens.

Para obter tutoriais, amostras, inícios rápidos e outros tipos de documentação, visite:

Azure para desenvolvedores .NET e .NET Core